@ferrybig/cgeodata-reader 0.0.0-stage → 0.1.1

package/dist/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Errors the reader throws because of the data it was given, as opposed to
+ * how it was called: a caller's invalid argument (a latitude out of range,
+ * a place id this file doesn't have) is a plain `RangeError`, and anything
+ * else is a bug.
+ *
+ * ```ts
+ * try {
+ * 	reader = CGeoDataReader.open(path);
+ * } catch (error) {
+ * 	if (error instanceof CGeoDataVersionError) {
+ * 		// written by a newer compressor: upgrade the reader
+ * 	} else if (error instanceof CGeoDataFormatError) {
+ * 		// truncated or corrupt download: fetch the file again
+ * 	} else throw error;
+ * }
+ * ```
+ */
+export class CGeoDataError extends Error {
+    /** "CGeoDataError", and each subclass its own name. */
+    name = "CGeoDataError";
+}
+/** A `.bin` file, or a search or locate index, is malformed or truncated:
+ * it breaks a rule of binary-format.md, so nothing read from it can be
+ * trusted. */
+export class CGeoDataFormatError extends CGeoDataError {
+    /** "CGeoDataFormatError" */
+    name = "CGeoDataFormatError";
+}
+/** The file is a CGEODATA file (or index) of a format version this reader
+ * doesn't know -- most likely written by a newer compressor. */
+export class CGeoDataVersionError extends CGeoDataFormatError {
+    /** "CGeoDataVersionError" */
+    name = "CGeoDataVersionError";
+    /** The version number the file declares. */
+    version;
+    constructor(message, version) {
+        super(message);
+        this.version = version;
+    }
+}
+/** The file is valid, but uses something this reader doesn't support: a
+ * `max_depth` past 16 (see `MAX_SUPPORTED_DEPTH`). Rebuild it with a
+ * bigger chunk grid instead of deeper chunks. */
+export class CGeoDataUnsupportedError extends CGeoDataFormatError {
+    /** "CGeoDataUnsupportedError" */
+    name = "CGeoDataUnsupportedError";
+}
+/** A search or locate index is well formed, but was built from a different
+ * `.bin` file than the one it's being used with (or an older build of the
+ * same one). Rebuild the index, or delete it to work without one. */
+export class CGeoDataIndexMismatchError extends CGeoDataError {
+    /** "CGeoDataIndexMismatchError" */
+    name = "CGeoDataIndexMismatchError";
+}
+//# sourceMappingURL=errors.js.map

package/dist/format.d.ts

@@ -0,0 +1,22 @@
+/**
+ * binary-format.md at the byte level: the codecs and parsers the reader is
+ * built from, for tools that write or inspect CGEODATA files (the
+ * compressor uses them). They follow the format, not a stable API, and
+ * may change when it does; `CGeoDataReader` is the interface for reading.
+ *
+ * @module @ferrybig/cgeodata-reader/format
+ */
+export { type BoundingBox, cellBoundingBox, chunkBoundingBox, } from "./cellBounds.ts";
+export { type ChunkRecords, MAX_SUPPORTED_DEPTH, parseChunk, } from "./chunk.ts";
+export { readHeaderAndDirectory } from "./container.ts";
+export { type CGeoDataDirectory, parseDirectory } from "./directory.ts";
+export { type CGeoDataHeader, parseHeader } from "./header.ts";
+export { type Inflater, inflateBlock, inflateCeiling, streamInflater, } from "./inflate.ts";
+export { decodeLocateEntry, encodeLocateEntry, type LocateCell, type LocateGrid, locateEntryWidth, } from "./locateIndex.ts";
+export { lowBits, mortonDecode, mortonEncode, shiftRight } from "./morton.ts";
+export { type PlaceTableInfo, parsePlaceTable, type ResolvedPlace, readNameBlock, readNameEntry, resolveIdentifier, } from "./placeTable.ts";
+export { decodeRangeCodedRecords, encodeRangeCodedRecords, type RangeCodedRecords, } from "./rangeChunk.ts";
+export { containsTokenRun, EXACT_SPELLING_BONUS, foldDiacritics, LEVEL_BONUS, type Needle, nameMatchQuality, placeMatchQuality, prepareNeedle, QUALITY_EXACT, QUALITY_MAX, QUALITY_SUBSTRING, QUALITY_WHOLE_WORD, tokenize, tokenizeFolded, } from "./relevance.ts";
+export { fnv1a32, foldSymbols, trigramListIndex, trigramListIndices, } from "./searchIndex.ts";
+export { toSource } from "./source.ts";
+export { IncompleteBufferError, readDeltaVarintList, readDeltaVarints32Into, readDeltaVarintsInto, readVarint, readVarintList, type VarintListResult, type VarintResult, writeVarint, } from "./varint.ts";

package/dist/format.js

@@ -0,0 +1,23 @@
+/**
+ * binary-format.md at the byte level: the codecs and parsers the reader is
+ * built from, for tools that write or inspect CGEODATA files (the
+ * compressor uses them). They follow the format, not a stable API, and
+ * may change when it does; `CGeoDataReader` is the interface for reading.
+ *
+ * @module @ferrybig/cgeodata-reader/format
+ */
+export { cellBoundingBox, chunkBoundingBox, } from "./cellBounds.js";
+export { MAX_SUPPORTED_DEPTH, parseChunk, } from "./chunk.js";
+export { readHeaderAndDirectory } from "./container.js";
+export { parseDirectory } from "./directory.js";
+export { parseHeader } from "./header.js";
+export { inflateBlock, inflateCeiling, streamInflater, } from "./inflate.js";
+export { decodeLocateEntry, encodeLocateEntry, locateEntryWidth, } from "./locateIndex.js";
+export { lowBits, mortonDecode, mortonEncode, shiftRight } from "./morton.js";
+export { parsePlaceTable, readNameBlock, readNameEntry, resolveIdentifier, } from "./placeTable.js";
+export { decodeRangeCodedRecords, encodeRangeCodedRecords, } from "./rangeChunk.js";
+export { containsTokenRun, EXACT_SPELLING_BONUS, foldDiacritics, LEVEL_BONUS, nameMatchQuality, placeMatchQuality, prepareNeedle, QUALITY_EXACT, QUALITY_MAX, QUALITY_SUBSTRING, QUALITY_WHOLE_WORD, tokenize, tokenizeFolded, } from "./relevance.js";
+export { fnv1a32, foldSymbols, trigramListIndex, trigramListIndices, } from "./searchIndex.js";
+export { toSource } from "./source.js";
+export { IncompleteBufferError, readDeltaVarintList, readDeltaVarints32Into, readDeltaVarintsInto, readVarint, readVarintList, writeVarint, } from "./varint.js";
+//# sourceMappingURL=format.js.map

package/dist/header.d.ts

@@ -0,0 +1,30 @@
+/** A file's header (Section 5). */
+export interface CGeoDataHeader {
+    /** Format version: 2 (range-coded chunks, Section 8.7), 1 (zlib
+     * chunks), or 0 for files written before chunks dropped their codes
+     * (Section 8.6). This reader reads all three. */
+    version: number;
+    /** The data's attribution notice, as given when the file was built.
+     * Show it wherever results are shown. */
+    attribution: string;
+    /** The chunk grid is 2^widthExp chunks wide... */
+    widthExp: number;
+    /** ...and 2^heightExp chunks high (Section 6.1). */
+    heightExp: number;
+    /** How many times a chunk's quadtree can split (Section 8.1): a chunk
+     * is at most 2^maxDepth cells across. */
+    maxDepth: number;
+    /** 2^keyframeExp names per name block (Section 7.3); 0 for one block. */
+    keyframeExp: number;
+    /** W = 2^widthExp */
+    width: number;
+    /** H = 2^heightExp */
+    height: number;
+    /** Byte length of the header, i.e. where the directory begins. */
+    headerLength: number;
+}
+/** Parses Section 5's header from a buffer that starts at the file's first
+ * byte. Throws IncompleteBufferError if `buf` is too short to tell (the
+ * caller should retry with more bytes), or a plain Error for a genuine
+ * format problem. */
+export declare function parseHeader(buf: Uint8Array): CGeoDataHeader;

package/dist/header.js

@@ -0,0 +1,69 @@
+import { CGeoDataFormatError, CGeoDataVersionError } from "./errors.js";
+import { IncompleteBufferError, readVarint } from "./varint.js";
+const utf8 = new TextDecoder();
+// "CGEODATA"
+const SIGNATURE = Uint8Array.from([
+    0x43, 0x47, 0x45, 0x4f, 0x44, 0x41, 0x54, 0x41,
+]);
+/** Parses Section 5's header from a buffer that starts at the file's first
+ * byte. Throws IncompleteBufferError if `buf` is too short to tell (the
+ * caller should retry with more bytes), or a plain Error for a genuine
+ * format problem. */
+export function parseHeader(buf) {
+    if (buf.length < SIGNATURE.length) {
+        throw new IncompleteBufferError("buffer too short for the CGEODATA signature");
+    }
+    for (let i = 0; i < SIGNATURE.length; i++) {
+        if (buf[i] !== SIGNATURE[i]) {
+            throw new CGeoDataFormatError("not a CGEODATA file: signature mismatch");
+        }
+    }
+    let offset = SIGNATURE.length;
+    const version = readVarint(buf, offset);
+    offset += version.bytesRead;
+    if (version.value > 2) {
+        throw new CGeoDataVersionError(`unsupported CGEODATA version ${version.value}`, version.value);
+    }
+    const attrLen = readVarint(buf, offset);
+    offset += attrLen.bytesRead;
+    const attrEnd = offset + attrLen.value;
+    if (attrEnd + 4 > buf.length) {
+        throw new IncompleteBufferError("buffer too short for attribution + fixed header fields");
+    }
+    const attribution = utf8.decode(buf.subarray(offset, attrEnd));
+    offset = attrEnd;
+    const widthExp = buf[offset];
+    const heightExp = buf[offset + 1];
+    const maxDepth = buf[offset + 2];
+    const keyframeExp = buf[offset + 3];
+    offset += 4;
+    if (maxDepth > 26) {
+        throw new CGeoDataFormatError(`max_depth ${maxDepth} exceeds the maximum of 26`);
+    }
+    if (widthExp > 15) {
+        throw new CGeoDataFormatError(`width_exp ${widthExp} exceeds the maximum of 15`);
+    }
+    if (heightExp > 15) {
+        throw new CGeoDataFormatError(`height_exp ${heightExp} exceeds the maximum of 15`);
+    }
+    // The only other u8 of the header, and the only one that was left
+    // unchecked: a place count is below 2^53 (Section 3.2), so a block of
+    // 2^53 names or more can never be anything but malformed -- and an
+    // unchecked value renders as nonsense ("keyframe 255 (5.8e+76 names per
+    // block)" from `cgeodata info`).
+    if (keyframeExp > 52) {
+        throw new CGeoDataFormatError(`keyframe_exp ${keyframeExp} exceeds the maximum of 52`);
+    }
+    return {
+        version: version.value,
+        attribution,
+        widthExp,
+        heightExp,
+        maxDepth,
+        keyframeExp,
+        width: 2 ** widthExp,
+        height: 2 ** heightExp,
+        headerLength: offset,
+    };
+}
+//# sourceMappingURL=header.js.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CGEODATA reader: resolves a latitude/longitude to the country, region
+ * and city containing it, from a CGEODATA file (see binary-format.md).
+ *
+ * This entry point is platform-neutral. On Node.js, open files with
+ * `openFile()` from `./node`; anywhere else, hand `CGeoDataReader.open()`
+ * the file's bytes or a `Blob`. Search and locate indexes, and their
+ * builders, are in `./indexes`; the format's low-level codecs, for tools
+ * that write or inspect files, in `./format`.
+ *
+ * @module @ferrybig/cgeodata-reader
+ */
+export { type BoundingBox, boundingBoxContains } from "./cellBounds.ts";
+export type { ChunkRecords } from "./chunk.ts";
+export type { CGeoDataDirectory } from "./directory.ts";
+export { CGeoDataError, CGeoDataFormatError, CGeoDataIndexMismatchError, CGeoDataUnsupportedError, CGeoDataVersionError, } from "./errors.ts";
+export type { CGeoDataHeader } from "./header.ts";
+export { type Inflater, streamInflater } from "./inflate.ts";
+export { CGeoDataReader, type ChunkRecord, DEFAULT_CACHE_BYTES, type IndexOption, type Location, type OpenOptions, type Place, type PlaceCounts, type PlaceFilter, type PlaceIdResult, type PlaceIds, type PlaceLevel, type PlaceRef, type QueryResult, type SearchOptions, } from "./reader.ts";
+export { BlobSource, type ByteSource, BytesSource, type SourceInput, } from "./source.ts";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * CGEODATA reader: resolves a latitude/longitude to the country, region
+ * and city containing it, from a CGEODATA file (see binary-format.md).
+ *
+ * This entry point is platform-neutral. On Node.js, open files with
+ * `openFile()` from `./node`; anywhere else, hand `CGeoDataReader.open()`
+ * the file's bytes or a `Blob`. Search and locate indexes, and their
+ * builders, are in `./indexes`; the format's low-level codecs, for tools
+ * that write or inspect files, in `./format`.
+ *
+ * @module @ferrybig/cgeodata-reader
+ */
+export { boundingBoxContains } from "./cellBounds.js";
+export { CGeoDataError, CGeoDataFormatError, CGeoDataIndexMismatchError, CGeoDataUnsupportedError, CGeoDataVersionError, } from "./errors.js";
+export { streamInflater } from "./inflate.js";
+export { CGeoDataReader, DEFAULT_CACHE_BYTES, } from "./reader.js";
+export { BlobSource, BytesSource, } from "./source.js";
+//# sourceMappingURL=index.js.map

package/dist/indexes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The sidecar indexes (binary-format.md Appendices B and C): building
+ * them from a `.bin` file, and opening them yourself -- to share one
+ * index between several readers, say. A reader opened with `openFile()`
+ * already finds the ones next to its file; elsewhere,
+ * `OpenOptions.searchIndex` / `locateIndex` take an index's bytes.
+ *
+ * @module @ferrybig/cgeodata-reader/indexes
+ */
+export { type BuildLocateIndexOptions, buildLocateIndex, LocateIndex, } from "./locateIndex.ts";
+export { buildSearchIndex, DEFAULT_SEARCH_INDEX_OPTIONS, SearchIndex, type SearchIndexOptions, } from "./searchIndex.ts";

package/dist/indexes.js

@@ -0,0 +1,12 @@
+/**
+ * The sidecar indexes (binary-format.md Appendices B and C): building
+ * them from a `.bin` file, and opening them yourself -- to share one
+ * index between several readers, say. A reader opened with `openFile()`
+ * already finds the ones next to its file; elsewhere,
+ * `OpenOptions.searchIndex` / `locateIndex` take an index's bytes.
+ *
+ * @module @ferrybig/cgeodata-reader/indexes
+ */
+export { buildLocateIndex, LocateIndex, } from "./locateIndex.js";
+export { buildSearchIndex, DEFAULT_SEARCH_INDEX_OPTIONS, SearchIndex, } from "./searchIndex.js";
+//# sourceMappingURL=indexes.js.map

package/dist/inflate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Decompresses one zlib stream (RFC 1950, binary-format.md Section 4),
+ * refusing to produce more than `maxOutputLength` bytes. May answer
+ * synchronously: Node's inflater does for small blocks, where handing the
+ * work to a thread costs more than doing it.
+ */
+export type Inflater = (compressed: Uint8Array, maxOutputLength: number) => Uint8Array | Promise<Uint8Array>;
+/** The most a block of `compressedLength` bytes may inflate to. */
+export declare function inflateCeiling(compressedLength: number): number;
+/**
+ * The platform-neutral inflater: the web's `DecompressionStream`, which
+ * browsers, Deno, Bun and Node.js all have. On Node.js, `./node.ts`'s
+ * zlib inflater is several times faster for small blocks.
+ */
+export declare const streamInflater: Inflater;
+/** Inflates one compressed block (Section 4) with `inflater`, under the
+ * size ceiling above. Anything the inflater rejects -- a corrupt stream,
+ * or one that would inflate past the ceiling -- is the file's fault, so
+ * it surfaces as a `CGeoDataFormatError` with the inflater's own error as
+ * its `cause`. */
+export declare function inflateBlock(inflater: Inflater, compressed: Uint8Array): Promise<Uint8Array>;

package/dist/inflate.js

@@ -0,0 +1,61 @@
+import { CGeoDataFormatError } from "./errors.js";
+// Section 11: readers MUST bound the inflated size of every compressed
+// block, to defend against decompression bombs. zlib's documented
+// worst-case expansion ratio is on the order of 1032:1; we round up and add
+// a floor so tiny legitimate blocks are never starved.
+const MAX_EXPANSION_RATIO = 1100;
+const MIN_OUTPUT_CEILING = 1 << 20; // 1 MiB
+/** The most a block of `compressedLength` bytes may inflate to. */
+export function inflateCeiling(compressedLength) {
+    return Math.max(MIN_OUTPUT_CEILING, compressedLength * MAX_EXPANSION_RATIO);
+}
+/**
+ * The platform-neutral inflater: the web's `DecompressionStream`, which
+ * browsers, Deno, Bun and Node.js all have. On Node.js, `./node.ts`'s
+ * zlib inflater is several times faster for small blocks.
+ */
+export const streamInflater = async (compressed, maxOutputLength) => {
+    const stream = new DecompressionStream("deflate");
+    const writer = stream.writable.getWriter();
+    // Not awaited: the readable side below is what drains it, and a corrupt
+    // stream surfaces there (writer.closed's rejection is the same error).
+    writer.write(compressed).catch(() => { });
+    writer.close().catch(() => { });
+    const reader = stream.readable.getReader();
+    const parts = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > maxOutputLength) {
+            await reader.cancel();
+            throw new RangeError(`inflates past ${maxOutputLength} bytes, the limit for its size`);
+        }
+        parts.push(value);
+    }
+    if (parts.length === 1)
+        return parts[0];
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+};
+/** Inflates one compressed block (Section 4) with `inflater`, under the
+ * size ceiling above. Anything the inflater rejects -- a corrupt stream,
+ * or one that would inflate past the ceiling -- is the file's fault, so
+ * it surfaces as a `CGeoDataFormatError` with the inflater's own error as
+ * its `cause`. */
+export async function inflateBlock(inflater, compressed) {
+    try {
+        return await inflater(compressed, inflateCeiling(compressed.length));
+    }
+    catch (error) {
+        throw new CGeoDataFormatError(`compressed block does not inflate: ${error.message}`, { cause: error });
+    }
+}
+//# sourceMappingURL=inflate.js.map

package/dist/locateIndex.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Place location index (Appendix C of binary-format.md): a sidecar file
+ * that stores one representative cell per place, so that
+ * `CGeoDataReader.locate()` is a single read of a few bytes instead of a
+ * scan through every chunk.
+ *
+ * The file is CGEODATA kind 2: the 8-byte "CGEODATA" signature and a
+ * `version` varint (kind × 16 + version = 33), then an FNV-1a 64-bit
+ * checksum over the source's header, directory and place table, the
+ * entry width, the place count, one fixed-width entry per place id, and
+ * one area byte per place id. Entries are raw, so an entry is found by
+ * multiplying its id by the entry width.
+ *
+ * The representative cell and area of a place are defined in Section
+ * C.3, and `locate()` without an index computes exactly the same ones by
+ * scanning (`computeLocateCell`). The index is only a precomputed copy of
+ * them.
+ */
+import type { CGeoDataHeader } from "./header.ts";
+import type { CGeoDataReader } from "./reader.ts";
+import { type SourceInput } from "./source.ts";
+/** The header fields a locate entry's layout depends on. */
+export type LocateGrid = Pick<CGeoDataHeader, "widthExp" | "heightExp" | "maxDepth">;
+/** One cell as an index entry names it (Section C.2): a cell of a chunk,
+ * addressed like a chunk record (Section 8.4) -- `code` is the stored
+ * `2 × max_depth`-bit Morton code, `depth` the cell's depth. */
+export interface LocateCell {
+    /** The chunk the cell is in (Section 6.1). */
+    chunkIndex: number;
+    /** The cell's stored Morton code within its chunk (Section 8.1). */
+    code: number;
+    /** The cell's depth in the chunk's quadtree. */
+    depth: number;
+}
+/** `ceil((width_exp + height_exp + 2 × max_depth + 1) / 8)`: enough bytes
+ * for a depth-`max_depth` cell plus its marker bit. */
+export declare function locateEntryWidth(grid: LocateGrid): number;
+/** The entry for `cell`, or `0` ("no geometry") for null. */
+export declare function encodeLocateEntry(cell: LocateCell | null, grid: LocateGrid): number;
+/** Inverse of `encodeLocateEntry`: null for `0`, and an error for a value
+ * whose marker bit doesn't sit at a valid depth. */
+export declare function decodeLocateEntry(value: number, grid: LocateGrid): LocateCell | null;
+/**
+ * Record cells in global full-precision cell coordinates -- Section 9's
+ * `gx`/`gy` grid, `W × 2^D` columns by `H × 2^D` rows. Cell `i` covers
+ * columns `gx[i] .. gx[i] + 2^(D - depth[i]) - 1` and the same run of
+ * rows from `gy[i]`.
+ */
+export interface CellList {
+    gx: Uint32Array;
+    gy: Uint32Array;
+    depth: Uint8Array;
+}
+/**
+ * The representative cell of Section C.3 for the cells `start .. end - 1`
+ * of `cells`: the full-precision cell nearest to the per-axis weighted
+ * median of the cells' centres, among the cells themselves. Returned in
+ * global full-precision coordinates; undefined for an empty range.
+ */
+export declare function representativeCell(cells: CellList, start: number, end: number, header: CGeoDataHeader): {
+    gx: number;
+    gy: number;
+} | undefined;
+/** A place's representative cell and area byte (Section C.3). */
+export interface PlaceLocation {
+    /** The representative cell. */
+    cell: LocateCell;
+    /** The area byte; never 0, since a place with a cell has an area. */
+    area: number;
+}
+/**
+ * Section C.3 for one place, straight from the chunks: collects the cells
+ * of every record attributed to `id` or a place under it, then picks the
+ * representative cell and totals the area. This is what `locate()` does
+ * without an index, and it reads every non-empty chunk.
+ */
+export declare function computeLocateCell(reader: CGeoDataReader, id: number): Promise<PlaceLocation | null>;
+/** Tuning for `buildLocateIndex`; the output doesn't depend on it. */
+export interface BuildLocateIndexOptions {
+    /**
+     * Roughly how many records to hold in memory at once. Countries are
+     * processed in batches whose records add up to about this many (a single
+     * country bigger than this is its own batch), and every chunk a batch
+     * touches is decoded once per batch. At ~9 bytes a record plus sort
+     * buffers, the default keeps the builder under a few hundred MB.
+     */
+    batchRecords?: number;
+}
+/**
+ * Builds a locate index (Section C.4) for every place in `reader` and
+ * returns the file's bytes.
+ *
+ * Every place's cells are gathered from the chunks country by country.
+ * Within a batch the places are laid out in depth-first order -- a
+ * country, then each of its regions followed by that region's cities --
+ * so the records of any place and everything under it are one contiguous
+ * run, and each place is one call to `representativeCell`.
+ */
+export declare function buildLocateIndex(reader: CGeoDataReader, options?: BuildLocateIndexOptions): Promise<Uint8Array>;
+/**
+ * An open locate index file (Section C.4). Opening reads only the header,
+ * and each `entry()` or `area()` reads just that entry's bytes; only
+ * `areas()`, which a search ranked by area needs, keeps anything (one
+ * byte per place), so an idle index otherwise costs an open file handle
+ * and no memory.
+ *
+ * Opening does NOT verify the source checksum -- `CGeoDataReader`'s
+ * `useLocateIndex()` does that against the file it's attached to.
+ */
+export declare class LocateIndex {
+    private readonly source;
+    /** The index file's name, when its source has one (`ByteSource.name`). */
+    readonly name?: string;
+    private readonly entriesStart;
+    private readonly areasStart;
+    private areasPromise;
+    /** Checksum of the header, directory and place table it was built
+     * from (Section C.4); a reader only accepts the index when it matches
+     * its own. */
+    readonly sourceChecksum: bigint;
+    /** Bytes per entry (Section C.2). */
+    readonly entryWidth: number;
+    /** How many places it has an entry for. */
+    readonly placeCount: number;
+    private constructor();
+    /** Opens a locate index file (read on demand, like a `.bin`).
+     * Validates signature, kind, version, entry width and length. Takes
+     * ownership of a `ByteSource`: `close()` closes it, as does a failed
+     * open. */
+    static open(input: SourceInput): Promise<LocateIndex>;
+    private static parseHeader;
+    /** Closes the index's source. */
+    close(): Promise<void>;
+    /** Place `id`'s raw entry (Section C.2); `0` means no geometry. */
+    entry(id: number): Promise<number>;
+    /** Place `id`'s area byte (Section C.3); `0` means no area. */
+    area(id: number): Promise<number>;
+    /** Every place's area byte, by id: one read of `placeCount` bytes, the
+     * first time, then kept -- what ranking a search by area needs. */
+    areas(): Promise<Uint8Array>;
+    private checkId;
+}