A pure TypeScript reader for FlatCityBuf,
a cloud-optimized binary encoding of CityJSON. It
reads a .fcb file from a URL over HTTP range requests, from a Blob/File
in the browser, from a local path in Node, or from an in-memory Uint8Array,
and answers spatial and attribute queries by fetching only the index and the
matching features. No WebAssembly, one runtime dependency (flatbuffers), the
same code in Node and the browser.
Status: reading only — there is no writer here (only the Rust and C++
implementations produce .fcb files) — and this reader is less settled than
those two. It passes all 14 shared conformance cases against the Rust reader's
own output, but JavaScript has no FlatBuffers verifier, so input files must be
trusted: framing is bounds-checked, the tables inside are not. Attribute
queries also carry three deliberate divergences from the Rust reader (a
fourth, Byte signedness, was resolved upstream). All of it
is spelled out, with citations, in the
TypeScript guide.
Requires Node ≥ 22.12 for the Node entry point, and is ESM only — import
it, do not require it.
npm install @cityjson/flatcitybuf
import { FcbReader, toCityJSONFeature } from '@cityjson/flatcitybuf'
const reader = await FcbReader.fromUrl('https://example.com/city.fcb')
const hits = await reader.select({
spatial: { kind: 'bbox', value: [minX, minY, maxX, maxY] },
where: [{ field: 'b3_h_dak_50p', operator: 'Gt', value: 20 }],
limit: 50,
})
console.log(hits.featuresCount) // total matches, not the page size
for await (const feature of hits) {
console.log(feature.id, toCityJSONFeature(feature, reader.header))
}
Reading a local file in Node lives behind the separate ./node subpath, so the
package root never imports node:* and stays usable in a browser — see
Entry points in the guide. Upgrading from the old WebAssembly binding? The
guide has the full API mapping.
MIT. See LICENSE.