@ferrybig/cgeodata-reader 0.0.0-stage → 0.1.0

package/dist/cache.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A least-recently-used cache bounded by the byte size of what it holds,
+ * not by entry count: decoded chunks range from a few hundred bytes to
+ * several megabytes (5.4 MB for the largest on a worldwide build), so
+ * only a byte budget answers "how much memory does the reader need".
+ *
+ * A `Map` iterates in insertion order, so re-inserting an entry on every
+ * hit keeps the least recently used one first, where eviction takes it.
+ */
+export declare class ByteBudgetCache<V> {
+    private readonly entries;
+    private totalBytes;
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+    /** Bytes currently held. */
+    get size(): number;
+    get(key: number): V | undefined;
+    /** Caches `value` as `bytes` bytes, evicting least recently used entries
+     * to stay within budget. A value bigger than the whole budget isn't
+     * cached at all, rather than emptying the cache for it. */
+    set(key: number, value: V, bytes: number): void;
+    delete(key: number): void;
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,60 @@
+/**
+ * A least-recently-used cache bounded by the byte size of what it holds,
+ * not by entry count: decoded chunks range from a few hundred bytes to
+ * several megabytes (5.4 MB for the largest on a worldwide build), so
+ * only a byte budget answers "how much memory does the reader need".
+ *
+ * A `Map` iterates in insertion order, so re-inserting an entry on every
+ * hit keeps the least recently used one first, where eviction takes it.
+ */
+export class ByteBudgetCache {
+    entries = new Map();
+    totalBytes = 0;
+    maxBytes;
+    constructor(maxBytes) {
+        if (!(maxBytes >= 0)) {
+            throw new RangeError(`cache size must be a non-negative number of bytes, not ${maxBytes}`);
+        }
+        this.maxBytes = maxBytes;
+    }
+    /** Bytes currently held. */
+    get size() {
+        return this.totalBytes;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    /** Caches `value` as `bytes` bytes, evicting least recently used entries
+     * to stay within budget. A value bigger than the whole budget isn't
+     * cached at all, rather than emptying the cache for it. */
+    set(key, value, bytes) {
+        this.delete(key);
+        if (bytes > this.maxBytes)
+            return;
+        this.entries.set(key, { value, bytes });
+        this.totalBytes += bytes;
+        for (const [oldest, { bytes: oldBytes }] of this.entries) {
+            if (this.totalBytes <= this.maxBytes)
+                break;
+            this.entries.delete(oldest);
+            this.totalBytes -= oldBytes;
+        }
+    }
+    delete(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return;
+        this.entries.delete(key);
+        this.totalBytes -= entry.bytes;
+    }
+    clear() {
+        this.entries.clear();
+        this.totalBytes = 0;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cellBounds.d.ts

@@ -0,0 +1,19 @@
+/** A lat/lon rectangle, half-open like the rest of the format (Section
+ * 2.3): `minLat <= lat < maxLat`, `minLon <= lon < maxLon`. */
+export interface BoundingBox {
+    /** Southern edge, included. */
+    minLat: number;
+    /** Northern edge, excluded. */
+    maxLat: number;
+    /** Western edge, included. */
+    minLon: number;
+    /** Eastern edge, excluded. */
+    maxLon: number;
+}
+/** The lat/lon extent of chunk (c, r) in a W x H grid (Section 6.1). */
+export declare function chunkBoundingBox(c: number, r: number, width: number, height: number): BoundingBox;
+/** The lat/lon extent of cell (cellX, cellY) at the given depth within a
+ * chunk (Section 8.1: cell (0, 0) is the chunk's own south-west corner). */
+export declare function cellBoundingBox(chunkBox: BoundingBox, cellX: number, cellY: number, depth: number): BoundingBox;
+/** Whether `box` contains the point, by the half-open rule above. */
+export declare function boundingBoxContains(box: BoundingBox, lat: number, lon: number): boolean;

package/dist/cellBounds.js

@@ -0,0 +1,36 @@
+/** The lat/lon extent of chunk (c, r) in a W x H grid (Section 6.1). */
+export function chunkBoundingBox(c, r, width, height) {
+    const lonWidth = 360 / width;
+    const latHeight = 180 / height;
+    const minLon = -180 + c * lonWidth;
+    const minLat = -90 + r * latHeight;
+    return {
+        minLon,
+        maxLon: minLon + lonWidth,
+        minLat,
+        maxLat: minLat + latHeight,
+    };
+}
+/** The lat/lon extent of cell (cellX, cellY) at the given depth within a
+ * chunk (Section 8.1: cell (0, 0) is the chunk's own south-west corner). */
+export function cellBoundingBox(chunkBox, cellX, cellY, depth) {
+    const cellsPerSide = 2 ** depth;
+    const lonWidth = (chunkBox.maxLon - chunkBox.minLon) / cellsPerSide;
+    const latHeight = (chunkBox.maxLat - chunkBox.minLat) / cellsPerSide;
+    const minLon = chunkBox.minLon + cellX * lonWidth;
+    const minLat = chunkBox.minLat + cellY * latHeight;
+    return {
+        minLon,
+        maxLon: minLon + lonWidth,
+        minLat,
+        maxLat: minLat + latHeight,
+    };
+}
+/** Whether `box` contains the point, by the half-open rule above. */
+export function boundingBoxContains(box, lat, lon) {
+    return (lat >= box.minLat &&
+        lat < box.maxLat &&
+        lon >= box.minLon &&
+        lon < box.maxLon);
+}
+//# sourceMappingURL=cellBounds.js.map

package/dist/chunk.d.ts

@@ -0,0 +1,34 @@
+/** One chunk's records (Section 8), decoded: record `j` is the cell
+ * `codes[j]` at depth `depths[j]`, attributed to
+ * `palette[paletteIndices[j] - 1]` (or to no place for index 0). */
+export interface ChunkRecords {
+    /** Global place ids referenced by this chunk, indexed 0..P-1. */
+    palette: number[];
+    /** Stored Morton codes, chunk-local, strictly increasing. Typed arrays
+     * rather than plain ones for this and the other per-record fields: a
+     * big chunk holds over a million records, and parsing and holding them
+     * as boxed JS arrays costs several times as much. 32 bits, as every
+     * code is below 4^`MAX_SUPPORTED_DEPTH`. */
+    codes: Uint32Array;
+    /** Each record's depth in the chunk's quadtree, 0 to `max_depth`. */
+    depths: Uint8Array;
+    /** Local palette index per record: 0 = "no place", k = palette[k-1].
+     * As wide as the file stores them (Section 8.3's S), rounding 3 bytes
+     * up to a `Uint32Array`. */
+    paletteIndices: Uint8Array | Uint16Array | Uint32Array;
+}
+/**
+ * The deepest `max_depth` this reader supports, though the format allows
+ * up to 26: every code is then below 4^16 = 2^32, so a decoded chunk
+ * holds its codes in 32 bits. Deeper files aren't worth reading in
+ * place: one chunk is one zlib block that a lookup inflates whole, and
+ * at depth 16 a chunk already spans up to 4^16 cells, so a lookup could
+ * inflate gigabytes. Finer cells should come from a bigger chunk grid
+ * (`width_exp`, `height_exp`) instead (binary-format.md Section 10).
+ */
+export declare const MAX_SUPPORTED_DEPTH = 16;
+/** Parses one already-inflated chunk block (Section 8.2, or Section 8.6's
+ * layout for a `version` 0 file) and checks the cheap Section 8.5
+ * invariants a reader can verify without external context (place ids
+ * are validated by the caller, which has the place table). */
+export declare function parseChunk(buf: Uint8Array, maxDepth: number, version: number): ChunkRecords;

package/dist/chunk.js

@@ -0,0 +1,269 @@
+import { decodeChunkCodes, WASM_MIN_RECORDS } from "./chunkDecoder.js";
+import { CGeoDataFormatError } from "./errors.js";
+import { readDeltaVarintList, readDeltaVarints32Into, readVarint, } from "./varint.js";
+/**
+ * The deepest `max_depth` this reader supports, though the format allows
+ * up to 26: every code is then below 4^16 = 2^32, so a decoded chunk
+ * holds its codes in 32 bits. Deeper files aren't worth reading in
+ * place: one chunk is one zlib block that a lookup inflates whole, and
+ * at depth 16 a chunk already spans up to 4^16 cells, so a lookup could
+ * inflate gigabytes. Finer cells should come from a bigger chunk grid
+ * (`width_exp`, `height_exp`) instead (binary-format.md Section 10).
+ */
+export const MAX_SUPPORTED_DEPTH = 16;
+/** The index width S from Section 8.3's table. */
+function paletteIndexWidth(paletteCount) {
+    if (paletteCount <= 255)
+        return 1;
+    if (paletteCount <= 65535)
+        return 2;
+    if (paletteCount <= 2 ** 24 - 1)
+        return 3;
+    return 4;
+}
+/** Whether typed arrays here are little-endian, as the file's integers
+ * are (true on every mainstream platform), so 2- and 4-byte palette
+ * indices can be copied in rather than assembled byte by byte. */
+const LITTLE_ENDIAN = new Uint8Array(Uint16Array.of(1).buffer)[0] === 1;
+/** `n` unsigned `width`-byte little-endian integers (Section 8.3's
+ * palette indices) from `buf` at `offset`, in the narrowest typed array
+ * that holds `width` bytes. Always a copy, so the inflated block can be
+ * freed. */
+function readLittleEndian(buf, offset, width, n) {
+    switch (width) {
+        case 1:
+            // Not `buf.slice()`: the block is a Buffer, whose `slice` returns
+            // a view.
+            return new Uint8Array(buf.subarray(offset, offset + n));
+        case 2: {
+            const out = new Uint16Array(n);
+            if (LITTLE_ENDIAN) {
+                new Uint8Array(out.buffer).set(buf.subarray(offset, offset + 2 * n));
+                return out;
+            }
+            for (let i = 0, b = offset; i < n; i++, b += 2)
+                out[i] = buf[b] | (buf[b + 1] << 8);
+            return out;
+        }
+        case 3: {
+            const out = new Uint32Array(n);
+            for (let i = 0, b = offset; i < n; i++, b += 3) {
+                out[i] = buf[b] | (buf[b + 1] << 8) | (buf[b + 2] << 16);
+            }
+            return out;
+        }
+        default: {
+            const out = new Uint32Array(n);
+            if (LITTLE_ENDIAN) {
+                new Uint8Array(out.buffer).set(buf.subarray(offset, offset + 4 * n));
+                return out;
+            }
+            for (let i = 0, b = offset; i < n; i++, b += 4) {
+                out[i] =
+                    buf[b] |
+                        (buf[b + 1] << 8) |
+                        (buf[b + 2] << 16) |
+                        (buf[b + 3] << 24);
+            }
+            return out;
+        }
+    }
+}
+/** Whether the power of two `span` divides `value`, both below 2^53: a
+ * bitwise check while they fit in 31 bits (max_depth 15 and under), else
+ * a double modulo, which is exact but several times slower. */
+function isMultipleOf(value, span) {
+    return value < 0x80000000 ? (value & (span - 1)) === 0 : value % span === 0;
+}
+/** Parses one already-inflated chunk block (Section 8.2, or Section 8.6's
+ * layout for a `version` 0 file) and checks the cheap Section 8.5
+ * invariants a reader can verify without external context (place ids
+ * are validated by the caller, which has the place table). */
+export function parseChunk(buf, maxDepth, version) {
+    if (maxDepth > MAX_SUPPORTED_DEPTH) {
+        throw new RangeError(`max_depth ${maxDepth} is past the ${MAX_SUPPORTED_DEPTH} this reader supports`);
+    }
+    let offset = 0;
+    const { value: paletteCount, bytesRead: b1 } = readVarint(buf, offset);
+    offset += b1;
+    const { values: palette, bytesRead: b2 } = readDeltaVarintList(buf, offset, paletteCount);
+    offset += b2;
+    const { value: recordCount, bytesRead: b3 } = readVarint(buf, offset);
+    offset += b3;
+    if (version !== 0) {
+        return parseRecords(buf, offset, palette, recordCount, maxDepth);
+    }
+    const { value: codesLength, bytesRead: b4 } = readVarint(buf, offset);
+    offset += b4;
+    // Every code takes at least one byte, so a count the block can't hold
+    // fails here instead of allocating for it.
+    if (offset + recordCount > buf.length) {
+        throw new CGeoDataFormatError("chunk codes run past end of block");
+    }
+    const codesStart = offset;
+    const indexWidth = paletteIndexWidth(paletteCount);
+    const depthsStart = codesStart + codesLength;
+    if (recordCount >= WASM_MIN_RECORDS &&
+        paletteCount < 2 ** 32 &&
+        depthsStart + recordCount * (1 + indexWidth) === buf.length) {
+        // The fast path (./chunkDecoder.ts) for a block whose size adds up;
+        // a declined block falls through to be parsed below.
+        const codes = decodeChunkCodes(buf, codesStart, codesLength, recordCount, maxDepth, paletteCount, indexWidth);
+        if (codes) {
+            return {
+                palette,
+                codes,
+                depths: new Uint8Array(buf.subarray(depthsStart, depthsStart + recordCount)),
+                paletteIndices: readLittleEndian(buf, depthsStart + recordCount, indexWidth, recordCount),
+            };
+        }
+    }
+    const codes = new Uint32Array(recordCount);
+    const codesBytesRead = readDeltaVarints32Into(buf, codesStart, codes) - codesStart;
+    if (codesBytesRead !== codesLength) {
+        throw new CGeoDataFormatError(`chunk codes_length mismatch: header says ${codesLength}, decoding consumed ${codesBytesRead}`);
+    }
+    offset = codesStart + codesLength;
+    if (offset + recordCount > buf.length) {
+        throw new CGeoDataFormatError("chunk depths array runs past end of block");
+    }
+    // A copy, not a view, so the inflated block can be freed. Not
+    // `buf.slice()`: the block is a Buffer, whose `slice` returns a view.
+    const depths = new Uint8Array(buf.subarray(offset, offset + recordCount));
+    offset += recordCount;
+    const indicesBytes = recordCount * indexWidth;
+    if (offset + indicesBytes > buf.length) {
+        throw new CGeoDataFormatError("chunk palette_indices array runs past end of block");
+    }
+    const paletteIndices = readLittleEndian(buf, offset, indexWidth, recordCount);
+    offset += indicesBytes;
+    if (offset !== buf.length) {
+        throw new CGeoDataFormatError("chunk block has trailing bytes after palette_indices");
+    }
+    // span[d]: how many max-depth cells a depth-d record covers, 4^(D-d).
+    // A stored code is valid for depth d exactly when its low 2 x (D-d) bits
+    // are zero, i.e. when span[d] divides it -- exact in doubles, since codes
+    // and spans are both below 2^53.
+    const span = [];
+    for (let d = 0; d <= maxDepth; d++)
+        span.push(4 ** (maxDepth - d));
+    const maxCode = 4 ** maxDepth;
+    for (let j = 0; j < recordCount; j++) {
+        const depth = depths[j];
+        const code = codes[j];
+        if (depth > maxDepth) {
+            throw new CGeoDataFormatError(`record ${j} has depth ${depth} > max_depth ${maxDepth}`);
+        }
+        if (!isMultipleOf(code, span[depth])) {
+            throw new CGeoDataFormatError(`record ${j}'s code is not a valid stored code for depth ${depth}`);
+        }
+        if (code >= maxCode) {
+            throw new CGeoDataFormatError(`record ${j}'s code ${code} is not less than 4^max_depth`);
+        }
+        if (paletteIndices[j] > paletteCount) {
+            throw new CGeoDataFormatError(`record ${j} has palette index ${paletteIndices[j]} > P (${paletteCount})`);
+        }
+        if (j > 0) {
+            const prevCode = codes[j - 1];
+            if (!(prevCode < code)) {
+                throw new CGeoDataFormatError(`chunk codes are not strictly increasing at record ${j}`);
+            }
+            if (prevCode + span[depths[j - 1]] > code) {
+                throw new CGeoDataFormatError(`record ${j - 1} overlaps record ${j}`);
+            }
+        }
+    }
+    return { palette, codes, depths, paletteIndices };
+}
+/** The rest of a chunk block from its `depths` on (Section 8.2): the
+ * records tile the chunk from code 0, so each code is where the record
+ * before it ends (Section 8.4). */
+function parseRecords(buf, offset, palette, recordCount, maxDepth) {
+    const paletteCount = palette.length;
+    const indexWidth = paletteIndexWidth(paletteCount);
+    const end = offset + recordCount * (1 + indexWidth);
+    if (end > buf.length) {
+        throw new CGeoDataFormatError("chunk depths and palette_indices run past end of block");
+    }
+    if (end !== buf.length) {
+        throw new CGeoDataFormatError("chunk block has trailing bytes after palette_indices");
+    }
+    // A copy, not a view, so the inflated block can be freed. Not
+    // `buf.slice()`: the block is a Buffer, whose `slice` returns a view.
+    const depths = new Uint8Array(buf.subarray(offset, offset + recordCount));
+    const paletteIndices = readLittleEndian(buf, offset + recordCount, indexWidth, recordCount);
+    const codes = new Uint32Array(recordCount);
+    if (!deriveCodes(depths, maxDepth, codes)) {
+        throw recordError(depths, maxDepth);
+    }
+    let maxIndex = 0;
+    for (let j = 0; j < recordCount; j++) {
+        const k = paletteIndices[j];
+        if (k > maxIndex)
+            maxIndex = k;
+    }
+    if (maxIndex > paletteCount) {
+        const j = paletteIndices.findIndex((k) => k > paletteCount);
+        throw new CGeoDataFormatError(`record ${j} has palette index ${paletteIndices[j]} > P (${paletteCount})`);
+    }
+    return { palette, codes, depths, paletteIndices };
+}
+/** Fills `codes` with each record's code (Section 8.4), or returns false
+ * when a record breaks invariant 1, 2 or 3 of Section 8.5, for
+ * `recordError` to say which. In integers while every code and span fits
+ * in 31 bits (max_depth 15 and under), else in doubles. */
+function deriveCodes(depths, maxDepth, codes) {
+    const n = depths.length;
+    // span[d]: how many max-depth cells a depth-d record covers, 4^(D-d);
+    // 0 past max_depth.
+    if (maxDepth <= 15) {
+        const span = new Int32Array(256);
+        for (let d = 0; d <= maxDepth; d++)
+            span[d] = 1 << (2 * (maxDepth - d));
+        const maxCode = 1 << (2 * maxDepth);
+        let code = 0;
+        for (let j = 0; j < n; j++) {
+            const size = span[depths[j]];
+            if (size === 0 || (code & (size - 1)) !== 0 || code >= maxCode) {
+                return false;
+            }
+            codes[j] = code;
+            code += size;
+        }
+        return code <= maxCode;
+    }
+    const span = new Float64Array(256);
+    for (let d = 0; d <= maxDepth; d++)
+        span[d] = 4 ** (maxDepth - d);
+    const maxCode = 4 ** maxDepth;
+    let code = 0;
+    for (let j = 0; j < n; j++) {
+        const size = span[depths[j]];
+        if (size === 0 || code % size !== 0 || code >= maxCode)
+            return false;
+        codes[j] = code;
+        code += size;
+    }
+    return code <= maxCode;
+}
+/** The error for the first record `deriveCodes` refused. */
+function recordError(depths, maxDepth) {
+    const maxCode = 4 ** maxDepth;
+    let code = 0;
+    for (let j = 0; j < depths.length; j++) {
+        const depth = depths[j];
+        if (depth > maxDepth) {
+            return new CGeoDataFormatError(`record ${j} has depth ${depth} > max_depth ${maxDepth}`);
+        }
+        if (code >= maxCode) {
+            return new CGeoDataFormatError(`record ${j} starts past the end of the chunk`);
+        }
+        const size = 4 ** (maxDepth - depth);
+        if (code % size !== 0) {
+            return new CGeoDataFormatError(`record ${j} at code ${code} is not aligned to its depth ${depth}`);
+        }
+        code += size;
+    }
+    return new CGeoDataFormatError(`record ${depths.length - 1} runs past the end of the chunk`);
+}
+//# sourceMappingURL=chunk.js.map

package/dist/chunkDecoder.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `parseChunk`'s fast path for a version 0 file, whose chunks store their
+ * codes (binary-format.md Section 8.6): wasm/chunkDecoder.wat, a
+ * WebAssembly SIMD decoder for those codes that checks every invariant
+ * `parseChunk` does. A version 1 chunk has no codes to decode. It only
+ * ever accepts or declines a block: a declined one --
+ * malformed, or valid but unusual -- is parsed again in JavaScript,
+ * which throws the error or returns the records. Platforms without
+ * WebAssembly SIMD (or that forbid compiling it, such as a page whose
+ * CSP lacks `'wasm-unsafe-eval'`) always take the JavaScript path.
+ *
+ * Memory: one instance, its memory grown to the largest block decoded
+ * so far (3.3 MB for world.bin's largest chunk), kept between
+ * decodes so a burst of them reuses it -- allocating WebAssembly memory
+ * costs 25-100 µs -- and dropped once no decode has used it for
+ * `IDLE_RELEASE_MS`, so an idle reader holds none.
+ */
+/** Below this many records the JavaScript parser is as fast: on
+ * world.bin the fast path is level at 16-32 records, 2x faster at 128,
+ * and 5-6x faster from 4096 up. */
+export declare const WASM_MIN_RECORDS = 64;
+/** Turns the fast path off (or back on), for tests and benchmarks that
+ * compare it against the JavaScript parser. */
+export declare function useWasmChunkDecoder(on: boolean): void;
+/** How many bytes of WebAssembly memory the fast path holds right now:
+ * 0 while idle. */
+export declare function wasmChunkDecoderBytes(): number;
+/** Whether this platform runs the fast path. */
+export declare function wasmChunkDecoderAvailable(): boolean;
+/**
+ * The codes of the version 0 chunk block `buf` (Section 8.6), whose
+ * codes start at `codesStart`, checked against every Section 8.5 invariant `parseChunk`
+ * checks -- or undefined when the fast path declined it or isn't
+ * available, and the caller should parse the block in JavaScript. The
+ * caller has checked that the block is exactly as long as its counts
+ * say, that `maxDepth` is at most 16 (`parseChunk` refuses more) and
+ * `paletteCount` below 2^32.
+ */
+export declare function decodeChunkCodes(buf: Uint8Array, codesStart: number, codesLength: number, recordCount: number, maxDepth: number, paletteCount: number, indexWidth: number): Uint32Array | undefined;

package/dist/chunkDecoder.js

@@ -0,0 +1,116 @@
+import { CHUNK_DECODER_WASM } from "./chunkDecoderWasm.js";
+/**
+ * `parseChunk`'s fast path for a version 0 file, whose chunks store their
+ * codes (binary-format.md Section 8.6): wasm/chunkDecoder.wat, a
+ * WebAssembly SIMD decoder for those codes that checks every invariant
+ * `parseChunk` does. A version 1 chunk has no codes to decode. It only
+ * ever accepts or declines a block: a declined one --
+ * malformed, or valid but unusual -- is parsed again in JavaScript,
+ * which throws the error or returns the records. Platforms without
+ * WebAssembly SIMD (or that forbid compiling it, such as a page whose
+ * CSP lacks `'wasm-unsafe-eval'`) always take the JavaScript path.
+ *
+ * Memory: one instance, its memory grown to the largest block decoded
+ * so far (3.3 MB for world.bin's largest chunk), kept between
+ * decodes so a burst of them reuses it -- allocating WebAssembly memory
+ * costs 25-100 µs -- and dropped once no decode has used it for
+ * `IDLE_RELEASE_MS`, so an idle reader holds none.
+ */
+/** Below this many records the JavaScript parser is as fast: on
+ * world.bin the fast path is level at 16-32 records, 2x faster at 128,
+ * and 5-6x faster from 4096 up. */
+export const WASM_MIN_RECORDS = 64;
+/** How long the instance outlives its last decode. */
+const IDLE_RELEASE_MS = 1000;
+const PAGE_BYTES = 65536;
+/** The compiled module; null once compiling failed. */
+let compiled;
+let instance;
+let releaseTimer;
+let enabled = true;
+/** Turns the fast path off (or back on), for tests and benchmarks that
+ * compare it against the JavaScript parser. */
+export function useWasmChunkDecoder(on) {
+    enabled = on;
+    if (!on)
+        release();
+}
+/** How many bytes of WebAssembly memory the fast path holds right now:
+ * 0 while idle. */
+export function wasmChunkDecoderBytes() {
+    return instance?.memory.buffer.byteLength ?? 0;
+}
+/** Whether this platform runs the fast path. */
+export function wasmChunkDecoderAvailable() {
+    return enabled && getInstance() !== undefined;
+}
+function getInstance() {
+    if (instance)
+        return instance;
+    if (compiled === undefined) {
+        try {
+            // Throws a ReferenceError where there's no WebAssembly at all.
+            compiled = new WebAssembly.Module(Uint8Array.from(atob(CHUNK_DECODER_WASM), (c) => c.charCodeAt(0)));
+        }
+        catch {
+            compiled = null;
+        }
+    }
+    if (compiled === null)
+        return undefined;
+    const exports = new WebAssembly.Instance(compiled).exports;
+    instance = {
+        memory: exports.memory,
+        parse: exports.parse,
+    };
+    return instance;
+}
+function release() {
+    instance = undefined;
+    if (releaseTimer !== undefined)
+        clearTimeout(releaseTimer);
+    releaseTimer = undefined;
+}
+function releaseWhenIdle() {
+    if (releaseTimer !== undefined)
+        clearTimeout(releaseTimer);
+    releaseTimer = setTimeout(release, IDLE_RELEASE_MS);
+    // Node.js: don't keep the process alive just to free this.
+    releaseTimer.unref?.();
+}
+/**
+ * The codes of the version 0 chunk block `buf` (Section 8.6), whose
+ * codes start at `codesStart`, checked against every Section 8.5 invariant `parseChunk`
+ * checks -- or undefined when the fast path declined it or isn't
+ * available, and the caller should parse the block in JavaScript. The
+ * caller has checked that the block is exactly as long as its counts
+ * say, that `maxDepth` is at most 16 (`parseChunk` refuses more) and
+ * `paletteCount` below 2^32.
+ */
+export function decodeChunkCodes(buf, codesStart, codesLength, recordCount, maxDepth, paletteCount, indexWidth) {
+    if (!enabled)
+        return undefined;
+    const decoder = getInstance();
+    if (!decoder)
+        return undefined;
+    const blockBytes = buf.length - codesStart;
+    // 16 bytes of slack past the block: a 3-byte index is read as 4.
+    const out = Math.ceil((blockBytes + 16) / 16) * 16;
+    const needed = out + 4 * recordCount;
+    const { memory } = decoder;
+    if (memory.buffer.byteLength < needed) {
+        try {
+            memory.grow(Math.ceil((needed - memory.buffer.byteLength) / PAGE_BYTES));
+        }
+        catch {
+            return undefined; // out of memory: leave it to the JavaScript path
+        }
+    }
+    new Uint8Array(memory.buffer, 0, blockBytes).set(buf.subarray(codesStart));
+    const ok = decoder.parse(codesLength, recordCount, maxDepth, paletteCount, indexWidth, out);
+    releaseWhenIdle();
+    if (!ok)
+        return undefined;
+    return new Uint32Array(memory.buffer, out, recordCount).slice();
+}
+//# sourceMappingURL=chunkDecoder.js.map

package/dist/chunkDecoderWasm.d.ts

@@ -0,0 +1,2 @@
+/** chunkDecoder.wat's compiled module (1553 bytes), base64. */
+export declare const CHUNK_DECODER_WASM = "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";

package/dist/chunkDecoderWasm.js

@@ -0,0 +1,4 @@
+// Generated by `npm run build:wasm -w reader` from wasm/chunkDecoder.wat; do not edit.
+/** chunkDecoder.wat's compiled module (1553 bytes), base64. */
+export const CHUNK_DECODER_WASM = "AGFzbQEAAAABCwFgBn9/f39/fwF/AwIBAAUDAQABBxICBm1lbW9yeQIABXBhcnNlAAAK3AsB2QsEAn8FfgR/FHtCASACQQF0rYYhCSAC/Q8hEQJAA0AgBiABTw0BAkAgBkUNACAGQRBqIAFLDQAgB0EQaiAASw0AIAf9AAQAIRIgEv1kDQAgACAGav0ABAAhEyATIBH9KP1TBEBBAA8LIBEgE/1xIRMgESAAIAZqQQFr/QAEAP1xIRQgEyAU/VBBD/0P/Sj9Uw0AIBL9DAEEEED///////////////8gFP0O/Sb9UwRAQQAPC/0MAAMPP////////////////yAT/Q4hFf0MAAAAAAADDz///////////yAT/Q4hFv0MAAAAAAAAAAAAAw8//////yAT/Q4hF/0MAAAAAAAAAAAAAAAAAAMPPyAT/Q4hGCAVIBb9DQAQARECEgMTBBQFFQYWBxchGSAVIBb9DQgYCRkKGgsbDBwNHQ4eDx8hGiAXIBj9DQAQARECEgMTBBQFFQYWBxchGyAXIBj9DQgYCRkKGgsbDBwNHQ4eDx8hHCAZIBv9DQABEBECAxITBAUUFQYHFhchFSAZIBv9DQgJGBkKCxobDA0cHQ4PHh8hFiAaIBz9DQABEBECAxITBAUUFQYHFhchFyAaIBz9DQgJGBkKCxobDA0cHQ4PHh8hGCAS/YkBIR0gEv2KASEeIB0gHf0MAAAAAAAAAAAAAAAAAAAAAP0NEBAAAQIDBAUGBwgJCgsMDf2OASEdIB4gHv0MAAAAAAAAAAAAAAAAAAAAAP0NEBAAAQIDBAUGBwgJCgsMDf2OASEeIB0gHf0MAAAAAAAAAAAAAAAAAAAAAP0NEBAQEAABAgMEBQYHCAkKC/2OASEdIB4gHv0MAAAAAAAAAAAAAAAAAAAAAP0NEBAQEAABAgMEBQYHCAkKC/2OASEeIB0gHf0MAAAAAAAAAAAAAAAAAAAAAP0NEBAQEBAQEBAAAQIDBAUGB/2OASEdIB4gHv0MAAAAAAAAAAAAAAAAAAAAAP0NEBAQEBAQEBAAAQIDBAUGB/2OASEeIAggHf0ZByAe/RkHaq18IQogCiAJWgRAQQAPCyAIp/0RIR8gHyAd/akB/a4BISAgHyAd/aoB/a4BISEgHyAd/RkH/RH9rgEhHyAfIB79qQH9rgEhIiAfIB79qgH9rgEhIyAgIBX9TiAhIBb9Tv1QICIgF/1OICMgGP1O/VD9UP1TBEBBAA8LIAUgIP0LBAAgBSAh/QsEECAFICL9CwQgIAUgI/0LBDAgCiEIIAdBEGohByAFQcAAaiEFIAZBEGohBgwBCyAHIABPBEBBAA8LIActAAAhDSAHQQFqIQcgDUH/AHGtIQtCByEMAkADQCANQYABcUUNASAMQiNRBEBBAA8LIAcgAE8EQEEADwsgBy0AACENIAdBAWohByANRQRAQQAPCyALIA1B/wBxrSAMhoQhCyAMQgd8IQwMAAsLIAggC3whCiAKIAlaBEBBAA8LIAAgBmotAAAhDiAOIAJLBEBBAA8LQgAgCkIBIAIgDmtBAXSthkIBfYNSBEBBAA8LIAYEQCAAIAZqQQFrLQAAIQ4gCEIBIAIgDmtBAXSthnwgClYEQEEADwsLIAUgCqc2AgAgCiEIIAVBBGohBSAGQQFqIQYMAAsLIAcgAEcEQEEADwsgACABaiEPIA8gASAEbGohECAEQQFGBEACQANAIA9BEGogEEsNASAkIA/9AAQA/XkhJCAPQRBqIQ8MAAsLICQgA/0P/Sj9UwRAQQAPCwJAA0AgDyAQTw0BIA8tAAAgA0sEQEEADwsgD0EBaiEPDAALC0EBDwsgBEECRgRAAkADQCAPQRBqIBBLDQEgJCAP/QAEAP2ZASEkIA9BEGohDwwACwsgJCAD/RD9Mv1TBEBBAA8LAkADQCAPIBBPDQEgDy8BACADSwRAQQAPCyAPQQJqIQ8MAAsLQQEPCwJAA0AgDyAQTw0BIA8oAgAhDSAEQQNGBEAgDUH///8HcSENCyANIANLBEBBAA8LIA8gBGohDwwACwtBAQs=";
+//# sourceMappingURL=chunkDecoderWasm.js.map

package/dist/cli/buildLocateIndex.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from "./shared.ts";
+export declare const buildLocateIndexCmd: Command;

package/dist/cli/buildLocateIndex.js

@@ -0,0 +1,46 @@
+import { writeFileSync } from "node:fs";
+import { buildLocateIndex } from "../locateIndex.js";
+import { EXIT_OK, openReader, parse, UsageError, } from "./shared.js";
+export const buildLocateIndexCmd = {
+    name: "build-locate-index",
+    summary: "build a place location index for a .bin file",
+    usage: `usage: cgeodata build-locate-index <file.bin> [--output <index.bin>]
+
+Computes a representative cell for every place in <file.bin> and writes
+the result as a locate index to <index.bin> (or stdout when --output is
+omitted). Written next to <file.bin> as <file>.locate-index.bin,
+\`cgeodata locate\` and \`search --locate\` (and any CGeoDataReader opened
+from that path) use it automatically; elsewhere, pass it with
+\`locate --index\`. Turns a locate from a scan of every chunk into a
+read of one entry.
+
+  --output F  write to F instead of stdout`,
+    async run(argv) {
+        const { values, positionals } = parse(argv, {
+            output: { type: "string" },
+        });
+        const [file, ...extra] = positionals;
+        if (extra.length > 0)
+            throw new UsageError(`unexpected argument ${JSON.stringify(extra[0])}`);
+        const reader = await openReader(file);
+        const { countries, regions, cities } = reader.placeCounts;
+        process.stderr.write(`building locate index over ${countries + regions + cities} places...\n`);
+        const t0 = performance.now();
+        let bytes;
+        try {
+            bytes = await buildLocateIndex(reader);
+        }
+        finally {
+            await reader.close();
+        }
+        process.stderr.write(`done in ${((performance.now() - t0) / 1000).toFixed(1)} s, ${(bytes.length / 1024 / 1024).toFixed(1)} MiB\n`);
+        if (values.output !== undefined) {
+            writeFileSync(values.output, bytes);
+        }
+        else {
+            process.stdout.write(bytes);
+        }
+        return EXIT_OK;
+    },
+};
+//# sourceMappingURL=buildLocateIndex.js.map