topojson-client

topojson-client is the reference JavaScript library for working with TopoJSON, the compact topology-preserving alternative to GeoJSON created by Mike Bostock. It converts TopoJSON objects back into standard GeoJSON Features and FeatureCollections so they can be rendered with tools like d3.geoPath, while also providing shape-merging (to dissolve interior borders between adjacent polygons, such as states into a country outline), mesh extraction (for efficiently stroking shared boundaries only once), neighbor detection, and coordinate quantization utilities.

Because TopoJSON encodes shared boundaries as arcs referenced by multiple geometries rather than duplicating coordinates, files are dramatically smaller than equivalent GeoJSON — often 80% or more — which makes topojson-client a common companion to D3-based choropleths, boundary maps, and any browser application that needs to ship geographic topology efficiently and reconstitute it on the client.

What You Get

• feature() to convert a TopoJSON object or GeometryCollection back into a GeoJSON Feature or FeatureCollection
• merge() / mergeArcs() to dissolve interior borders and union adjacent Polygon/MultiPolygon objects into a single MultiPolygon
• mesh() / meshArcs() to extract a deduplicated MultiLineString of arcs for efficient boundary stroking, with an optional filter for interior-vs-exterior borders
• neighbors() to compute the adjacency list between a set of topology objects
• bbox(), quantize(), transform()/untransform() for bounding boxes and delta-encoded coordinate quantization
• CLI tools topo2geo, topomerge, and topoquantize for converting and manipulating TopoJSON files from the command line

Common Use Cases

• Rendering choropleth maps and administrative boundaries with D3’s d3.geoPath after converting TopoJSON to GeoJSON with feature()
• Producing a single country/region outline from many adjacent state or district polygons via merge()
• Drawing map borders efficiently by stroking a mesh() once instead of every shared edge from every adjacent polygon
• Preprocessing large geographic datasets on the command line with topo2geo/topoquantize before bundling them for a web app

Under The Hood

Architecture — The library is organized as one small ES module per operation (feature.js, merge.js, mesh.js, neighbors.js, quantize.js, transform.js, bbox.js) re-exported from a single src/index.js barrel, with no shared class or mutable global state; each function takes a TopoJSON topology object plus its own arguments and returns plain GeoJSON/TopoJSON data. feature.js exposes an internal object() walker that resolves TopoJSON arc indices into coordinate arrays via a transform() closure and reverses negative (backward-traversed) arc indices; merge.js and mesh.js both build on a shared stitch.js routine that joins raw arc fragments into closed rings or open lines using start/end-point dictionaries (fragmentByStart/fragmentByEnd), and merge.js additionally groups adjacent polygons via a Polygon-by-arc adjacency map before computing which grouped ring has the largest planar area to select the true exterior. Tech Stack — Pure JavaScript (ES2015 modules) with zero runtime dependencies for the library itself; the three CLI binaries in bin/ depend only on commander@2 for argument parsing and stream topology JSON from stdin/file through Node’s fs and readline. The build uses Rollup (rollup.config.js) to produce UMD/ESM bundles for browser, AMD, and CommonJS consumption, published to npm and unpkg/jsDelivr as dist/topojson-client.js. Code Quality — Tests live under test/*-test.js using tape, covering feature, merge, mesh, neighbors, quantize, bbox, and the topo2geo CLI (10 test files against real GeoJSON/TopoJSON fixtures in test/geojson and test/topojson), and eslint:recommended is enforced as part of the test script; the source itself favors terse, single-purpose functions with minimal inline documentation (relying on the README’s API reference instead), and there is no TypeScript — types are implicit from usage. API Design — The API is deliberately small and composable: every transform accepts a topology first and either an object/array/filter after, mirroring D3’s functional style, so feature, merge, and mesh can be reached for immediately after import * as topojson from "topojson-client" with no configuration or setup step; the tradeoff is that consumers must already understand TopoJSON’s arc/transform model to interpret arguments like arc filters or quantization transforms correctly.