@ferrybig/cgeodata-reader 0.0.0-stage → 0.1.0

package/dist/cli/shared.d.ts

@@ -0,0 +1,50 @@
+import { type ParseArgsConfig } from "node:util";
+import type { BoundingBox } from "../cellBounds.ts";
+import { FileSource } from "../node.ts";
+import { CGeoDataReader, type Place, type PlaceLevel } from "../reader.ts";
+/** grep's convention: 0 = success/matched, 1 = ran fine but found nothing
+ * (search only), 2 = usage or runtime error. */
+export declare const EXIT_OK = 0;
+export declare const EXIT_NO_MATCH = 1;
+export declare const EXIT_ERROR = 2;
+/** A usage problem: reported with the command's usage text, exit 2. */
+export declare class UsageError extends Error {
+}
+export interface Command {
+    name: string;
+    summary: string;
+    usage: string;
+    run(argv: string[]): Promise<number> | number;
+}
+type Options = NonNullable<ParseArgsConfig["options"]>;
+export declare function parse<O extends Options>(argv: string[], options: O): {
+    values: O extends import("util").ParseArgsOptionsConfig ? { -readonly [LongOption in keyof O]?: { [LongOption_2 in keyof O]: O[LongOption_2]["multiple"] extends infer T ? T extends O[LongOption_2]["multiple"] ? T extends false ? O[LongOption_2]["type"] extends "string" ? string : O[LongOption_2]["type"] extends "boolean" ? boolean : string | boolean : T extends true ? (O[LongOption_2]["type"] extends "string" ? string : O[LongOption_2]["type"] extends "boolean" ? boolean : string | boolean)[] : O[LongOption_2]["type"] extends "string" ? string : O[LongOption_2]["type"] extends "boolean" ? boolean : string | boolean : never : never; }[LongOption]; } & { [LongOption_1 in keyof O as O[LongOption_1]["default"] extends {} ? LongOption_1 : never]: { [LongOption_3 in keyof O]: O[LongOption_3]["multiple"] extends infer T ? T extends O[LongOption_3]["multiple"] ? T extends false ? O[LongOption_3]["type"] extends "string" ? string : O[LongOption_3]["type"] extends "boolean" ? boolean : string | boolean : T extends true ? (O[LongOption_3]["type"] extends "string" ? string : O[LongOption_3]["type"] extends "boolean" ? boolean : string | boolean)[] : O[LongOption_3]["type"] extends "string" ? string : O[LongOption_3]["type"] extends "boolean" ? boolean : string | boolean : never : never; }[LongOption_1]; } extends infer P ? { [K in keyof P]: P[K]; } : never : {};
+    positionals: string[];
+};
+/** "-" reads the whole file from stdin; the reader needs random access,
+ * so that means buffering it, which is fine at the sizes these files come
+ * in (the worldwide build is under 10MB). */
+export declare function openReader(file: string | undefined): Promise<CGeoDataReader>;
+/** `--index <file>`: attaches that index file instead of the one next to
+ * the .bin, naming it in any error. */
+export declare function useIndexFile(use: (index: FileSource) => Promise<void>, path: string): Promise<void>;
+export declare function parseLevel(text: string | undefined): PlaceLevel | undefined;
+/** `--area-tie-break auto|on|off`, as `SearchOptions.areaTieBreak`. */
+export declare function parseAreaTieBreak(text: string | undefined): "auto" | boolean;
+export declare function parseId(text: string, what: string): number;
+/** `--country` takes an id or a name; a name must match exactly one
+ * country, case-insensitively, on any of its names. */
+export declare function resolveCountry(reader: CGeoDataReader, text: string): Promise<number>;
+export declare function names(list: string[] | null | undefined): string;
+/** One place per line: id, level, its own names, region, country -- `-`
+ * where a level doesn't apply. Fixed columns so `cut`/`awk` work
+ * regardless of level. */
+export declare function formatPlaceLine(place: Place): string;
+/** The block form used by `show` and `lookup`. */
+export declare function formatPlaceBlock(place: Place): string[];
+/** Decimal places that meaningfully represent a coordinate given the cell
+ * it came out of. Shared by `locate` and `search --locate`, which have to
+ * print the same coordinate the same way. */
+export declare function coordPrecision(box: BoundingBox): number;
+export declare function writeLine(line: string): void;
+export {};

package/dist/cli/shared.js

@@ -0,0 +1,140 @@
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { FileSource, nodeInflater, openFile } from "../node.js";
+import { CGeoDataReader } from "../reader.js";
+/** grep's convention: 0 = success/matched, 1 = ran fine but found nothing
+ * (search only), 2 = usage or runtime error. */
+export const EXIT_OK = 0;
+export const EXIT_NO_MATCH = 1;
+export const EXIT_ERROR = 2;
+/** A usage problem: reported with the command's usage text, exit 2. */
+export class UsageError extends Error {
+}
+/**
+ * parseArgs with every option unknown to the command rejected, and
+ * negative numbers ("-10,10", a perfectly good latitude) allowed as
+ * positionals -- parseArgs would otherwise read that as short options
+ * `-1 -0 ...`. Such tokens are hidden behind a NUL prefix for the parse
+ * and restored afterwards; nothing else can legitimately start with NUL.
+ *
+ * The leading digit may come after a decimal point: "-.5,10" is as good a
+ * coordinate as "-0.5,10", and matching only `-\d` rejected it with
+ * "Unknown option '-.'".
+ */
+const NEGATIVE_NUMBER = /^-(?:\d|\.\d)/;
+export function parse(argv, options) {
+    const shielded = argv.map((arg) => NEGATIVE_NUMBER.test(arg) ? `\0${arg}` : arg);
+    try {
+        const { values, positionals } = parseArgs({
+            args: shielded,
+            options,
+            allowPositionals: true,
+            strict: true,
+        });
+        return {
+            values,
+            positionals: positionals.map((p) => p.startsWith("\0") ? p.slice(1) : p),
+        };
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error
+            ? err.message.replace(/\. To specify.*$/s, "")
+            : String(err));
+    }
+}
+/** "-" reads the whole file from stdin; the reader needs random access,
+ * so that means buffering it, which is fine at the sizes these files come
+ * in (the worldwide build is under 10MB). */
+export async function openReader(file) {
+    if (file === undefined)
+        throw new UsageError("missing <file.bin>");
+    return file === "-"
+        ? CGeoDataReader.open(readFileSync(0), { inflater: nodeInflater })
+        : openFile(file);
+}
+/** `--index <file>`: attaches that index file instead of the one next to
+ * the .bin, naming it in any error. */
+export async function useIndexFile(use, path) {
+    try {
+        await use(await FileSource.open(path));
+    }
+    catch (error) {
+        throw new Error(`--index ${path}: ${error.message}`);
+    }
+}
+export function parseLevel(text) {
+    if (text === undefined)
+        return undefined;
+    if (text === "country" || text === "region" || text === "city")
+        return text;
+    throw new UsageError(`--level must be country, region or city, not ${JSON.stringify(text)}`);
+}
+/** `--area-tie-break auto|on|off`, as `SearchOptions.areaTieBreak`. */
+export function parseAreaTieBreak(text) {
+    if (text === undefined || text === "auto")
+        return "auto";
+    if (text === "on")
+        return true;
+    if (text === "off")
+        return false;
+    throw new UsageError(`--area-tie-break must be auto, on or off, not ${JSON.stringify(text)}`);
+}
+export function parseId(text, what) {
+    const id = Number(text);
+    if (!/^\d+$/.test(text) || !Number.isSafeInteger(id))
+        throw new UsageError(`${what} ${JSON.stringify(text)} is not a place id`);
+    return id;
+}
+/** `--country` takes an id or a name; a name must match exactly one
+ * country, case-insensitively, on any of its names. */
+export async function resolveCountry(reader, text) {
+    if (/^\d+$/.test(text))
+        return parseId(text, "--country");
+    const wanted = text.toLowerCase();
+    const matches = [];
+    for await (const c of reader.places({ level: "country" })) {
+        if (c.names.some((n) => n.toLowerCase() === wanted))
+            matches.push(c);
+    }
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length === 0)
+        throw new UsageError(`no country is named ${JSON.stringify(text)}`);
+    throw new UsageError(`${JSON.stringify(text)} names ${matches.length} countries: ${matches.map((m) => `${m.id} (${m.names.join(" | ")})`).join(", ")}`);
+}
+export function names(list) {
+    return list ? list.join(" | ") : "-";
+}
+/** One place per line: id, level, its own names, region, country -- `-`
+ * where a level doesn't apply. Fixed columns so `cut`/`awk` work
+ * regardless of level. */
+export function formatPlaceLine(place) {
+    const region = place.level === "city" ? place.region?.names : null;
+    const country = place.level === "country" ? null : place.country.names;
+    return [
+        place.id,
+        place.level,
+        names(place.names),
+        names(region),
+        names(country),
+    ].join("\t");
+}
+/** The block form used by `show` and `lookup`. */
+export function formatPlaceBlock(place) {
+    return [
+        `  country  ${names(place.country.names)}  [${place.country.id}]`,
+        `  region   ${place.region ? `${names(place.region.names)}  [${place.region.id}]` : "-"}`,
+        `  city     ${place.city ? `${names(place.city.names)}  [${place.city.id}]` : "-"}`,
+    ];
+}
+/** Decimal places that meaningfully represent a coordinate given the cell
+ * it came out of. Shared by `locate` and `search --locate`, which have to
+ * print the same coordinate the same way. */
+export function coordPrecision(box) {
+    const cellSize = Math.min(box.maxLat - box.minLat, box.maxLon - box.minLon);
+    return Math.max(0, Math.round(-Math.log10(cellSize) + 1));
+}
+export function writeLine(line) {
+    process.stdout.write(line + "\n");
+}
+//# sourceMappingURL=shared.js.map

package/dist/cli/show.d.ts

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

package/dist/cli/show.js

@@ -0,0 +1,38 @@
+import { formatPlaceBlock, openReader, parse, parseId, UsageError, writeLine, } from "./shared.js";
+export const show = {
+    name: "show",
+    summary: "resolve place ids to names and parents",
+    usage: `usage: cgeodata show <file.bin> <id> [<id> ...] [--json]
+
+Resolves each place id (as printed by list, search, lookup or chunk) to
+its level, names and ancestors.
+
+  --json   one JSON object per id instead of the readable form`,
+    async run(argv) {
+        const { values, positionals } = parse(argv, {
+            json: { type: "boolean", default: false },
+        });
+        const [file, ...idArgs] = positionals;
+        if (idArgs.length === 0)
+            throw new UsageError("missing <id>");
+        const ids = idArgs.map((arg) => parseId(arg, "id"));
+        const reader = await openReader(file);
+        try {
+            for (const id of ids) {
+                const place = await reader.place(id);
+                if (values.json) {
+                    writeLine(JSON.stringify(place));
+                    continue;
+                }
+                writeLine(`${place.id}\t${place.level}`);
+                for (const line of formatPlaceBlock(place))
+                    writeLine(line);
+            }
+            return 0;
+        }
+        finally {
+            await reader.close();
+        }
+    },
+};
+//# sourceMappingURL=show.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { buildLocateIndexCmd } from "./cli/buildLocateIndex.js";
+import { buildSearchIndexCmd } from "./cli/buildSearchIndex.js";
+import { chunk } from "./cli/chunk.js";
+import { info } from "./cli/info.js";
+import { list } from "./cli/list.js";
+import { locate } from "./cli/locate.js";
+import { lookup } from "./cli/lookup.js";
+import { search } from "./cli/search.js";
+import { EXIT_ERROR, UsageError } from "./cli/shared.js";
+import { show } from "./cli/show.js";
+const COMMANDS = [
+    info,
+    lookup,
+    list,
+    search,
+    buildSearchIndexCmd,
+    show,
+    chunk,
+    locate,
+    buildLocateIndexCmd,
+];
+// Wide enough for the longest name there actually is: a fixed 8 left
+// `build-search-index` and `build-locate-index` hanging ten characters
+// into their own summaries.
+const NAME_WIDTH = Math.max(...COMMANDS.map((c) => c.name.length));
+const USAGE = `usage: cgeodata <command> <file.bin> [...]
+       cgeodata help [<command>]
+
+Reads a CGEODATA file. <file.bin> may be "-" to read the file from stdin.
+
+commands:
+${COMMANDS.map((c) => `  ${c.name.padEnd(NAME_WIDTH)}  ${c.summary}`).join("\n")}
+
+Options:
+  -h, --help     show this help
+  -v, --version  print the package version
+
+Exit status is 0 on success, 1 when a search matched nothing, 2 on a
+usage or runtime error.`;
+function findCommand(name) {
+    return COMMANDS.find((c) => c.name === name);
+}
+// `../package.json` is the package's own from both `src/` and `dist/`.
+function packageVersion() {
+    const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return manifest.version;
+}
+async function main(argv) {
+    const [name, ...rest] = argv;
+    if (name === "--version" || name === "-v") {
+        process.stdout.write(`${packageVersion()}\n`);
+        return 0;
+    }
+    if (name === undefined ||
+        name === "help" ||
+        name === "--help" ||
+        name === "-h") {
+        const topic = rest[0] === undefined ? undefined : findCommand(rest[0]);
+        if (rest[0] !== undefined && !topic) {
+            process.stderr.write(`unknown command ${JSON.stringify(rest[0])}\n${USAGE}\n`);
+            return EXIT_ERROR;
+        }
+        const text = topic ? topic.usage : USAGE;
+        if (name === undefined) {
+            process.stderr.write(`${text}\n`);
+            return EXIT_ERROR;
+        }
+        process.stdout.write(`${text}\n`);
+        return 0;
+    }
+    const command = findCommand(name);
+    if (!command) {
+        process.stderr.write(`unknown command ${JSON.stringify(name)}\n${USAGE}\n`);
+        return EXIT_ERROR;
+    }
+    try {
+        return await command.run(rest);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`${err.message}\n${command.usage}\n`);
+            return EXIT_ERROR;
+        }
+        throw err;
+    }
+}
+// `cgeodata list world.bin | head` closes our stdout early; that's the
+// reader's business, not an error worth a stack trace.
+process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(0);
+    // Throwing from an 'error' listener raises an uncaughtException, so a
+    // plain write failure (`cgeodata list world.bin > /dev/full`, ENOSPC)
+    // would print a stack trace -- the very thing this handler exists to
+    // avoid. Report it the way main()'s own failure path does.
+    process.stderr.write(`${err.message}\n`);
+    process.exit(EXIT_ERROR);
+});
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = EXIT_ERROR;
+});
+//# sourceMappingURL=cli.js.map

package/dist/container.d.ts

@@ -0,0 +1,17 @@
+import { type CGeoDataDirectory } from "./directory.ts";
+import { type CGeoDataHeader } from "./header.ts";
+import type { ByteSource } from "./source.ts";
+/**
+ * Reads the header and directory (Sections 5-6), which per the spec are
+ * "small and expected to be read once and kept in memory". Since the
+ * directory's size depends on the header (W x H entries) and the header's
+ * size depends on the attribution string length, this starts with a small
+ * probe read and grows it until both parse cleanly -- never reading more of
+ * the file than these two small, fixed-at-load-time sections actually need.
+ */
+export declare function readHeaderAndDirectory(source: ByteSource): Promise<{
+    /** The parsed header (Section 5). */
+    header: CGeoDataHeader;
+    /** The parsed directory (Section 6). */
+    directory: CGeoDataDirectory;
+}>;

package/dist/container.js

@@ -0,0 +1,68 @@
+import { parseDirectory } from "./directory.js";
+import { CGeoDataFormatError } from "./errors.js";
+import { parseHeader } from "./header.js";
+import { IncompleteBufferError } from "./varint.js";
+/**
+ * Reads the header and directory (Sections 5-6), which per the spec are
+ * "small and expected to be read once and kept in memory". Since the
+ * directory's size depends on the header (W x H entries) and the header's
+ * size depends on the attribution string length, this starts with a small
+ * probe read and grows it until both parse cleanly -- never reading more of
+ * the file than these two small, fixed-at-load-time sections actually need.
+ */
+export async function readHeaderAndDirectory(source) {
+    let size = Math.min(1024, source.size);
+    for (;;) {
+        const buf = await source.read(0, size);
+        try {
+            const header = parseHeader(buf);
+            checkDirectoryFits(header, source.size);
+            const directory = parseDirectory(buf, header.headerLength, header.width, header.height);
+            checkSectionsWithinFile(directory, source.size);
+            return { header, directory };
+        }
+        catch (err) {
+            if (err instanceof IncompleteBufferError && size < source.size) {
+                size = Math.min(size * 4, source.size);
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * The cheap half of Section 11's "chunk offsets and lengths MUST lie
+ * within the file", checkable from the header alone: the directory is
+ * `place_table_length` plus one varint per chunk, every varint at least
+ * one byte, so a header claiming more chunks than the file has bytes
+ * left cannot be well formed.
+ *
+ * Checking this *before* parsing matters: `width_exp` and `height_exp` of
+ * 15 are both legal (Section 5) and claim 2^30 chunks, so without this a
+ * ~1 MiB crafted file sends the growing read above through a dozen passes
+ * that each allocate a 2^30-entry array -- ~1 s of CPU and a few hundred
+ * MB of RSS -- before finally failing on a short varint.
+ */
+function checkDirectoryFits(header, fileSize) {
+    const chunkCount = header.width * header.height;
+    const afterHeader = fileSize - header.headerLength;
+    if (chunkCount + 1 > afterHeader) {
+        throw new CGeoDataFormatError(`header's ${header.width}x${header.height} grid needs a directory of at least ${chunkCount + 1} bytes, but only ${afterHeader} follow the header in this ${fileSize}-byte file`);
+    }
+}
+/** The rest of Section 11's bounds check. Chunk offsets are the running
+ * sum of the lengths from the place table's end, so the last chunk's end
+ * bounds every chunk's. */
+function checkSectionsWithinFile(directory, fileSize) {
+    const { placeTableStart, placeTableLength, chunkOffsets, chunkLengths } = directory;
+    const placeTableEnd = placeTableStart + placeTableLength;
+    if (placeTableEnd > fileSize) {
+        throw new CGeoDataFormatError(`place table runs to byte ${placeTableEnd}, past the end of the ${fileSize}-byte file`);
+    }
+    const last = chunkLengths.length - 1;
+    const chunksEnd = last < 0 ? placeTableEnd : chunkOffsets[last] + chunkLengths[last];
+    if (chunksEnd > fileSize) {
+        throw new CGeoDataFormatError(`chunks run to byte ${chunksEnd}, past the end of the ${fileSize}-byte file`);
+    }
+}
+//# sourceMappingURL=container.js.map

package/dist/directory.d.ts

@@ -0,0 +1,21 @@
+/** The directory (Section 6): where the place table and each chunk are. */
+export interface CGeoDataDirectory {
+    /** Absolute file offset of the place table (Section 7). */
+    placeTableStart: number;
+    /** Byte length of the place table. */
+    placeTableLength: number;
+    /** Entry i is the compressed byte length of chunk i (0 = empty). */
+    chunkLengths: number[];
+    /** Entry i is the absolute file offset of chunk i (meaningless when
+     * chunkLengths[i] === 0). Precomputed per Section 6.3. */
+    chunkOffsets: number[];
+    /** Byte length of the directory itself. */
+    directoryLength: number;
+}
+/**
+ * Parses Section 6. `buf` MUST start at the file's absolute byte 0 (not a
+ * sub-slice), since offsets computed here -- and returned in
+ * `placeTableStart`/`chunkOffsets` -- are absolute file offsets. `offset` is
+ * the header length, i.e. where the directory begins.
+ */
+export declare function parseDirectory(buf: Uint8Array, offset: number, width: number, height: number): CGeoDataDirectory;

package/dist/directory.js

@@ -0,0 +1,31 @@
+import { readVarint, readVarintList } from "./varint.js";
+/**
+ * Parses Section 6. `buf` MUST start at the file's absolute byte 0 (not a
+ * sub-slice), since offsets computed here -- and returned in
+ * `placeTableStart`/`chunkOffsets` -- are absolute file offsets. `offset` is
+ * the header length, i.e. where the directory begins.
+ */
+export function parseDirectory(buf, offset, width, height) {
+    const start = offset;
+    const { value: placeTableLength, bytesRead: b1 } = readVarint(buf, offset);
+    offset += b1;
+    const count = width * height;
+    const { values: chunkLengths, bytesRead: b2 } = readVarintList(buf, offset, count);
+    offset += b2;
+    const placeTableStart = offset;
+    const chunksStart = placeTableStart + placeTableLength;
+    const chunkOffsets = new Array(count);
+    let running = chunksStart;
+    for (let i = 0; i < count; i++) {
+        chunkOffsets[i] = running;
+        running += chunkLengths[i];
+    }
+    return {
+        placeTableStart,
+        placeTableLength,
+        chunkLengths,
+        chunkOffsets,
+        directoryLength: offset - start,
+    };
+}
+//# sourceMappingURL=directory.js.map

package/dist/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare class CGeoDataError extends Error {
+    /** "CGeoDataError", and each subclass its own name. */
+    name: string;
+}
+/** 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 declare class CGeoDataFormatError extends CGeoDataError {
+    /** "CGeoDataFormatError" */
+    name: string;
+}
+/** 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 declare class CGeoDataVersionError extends CGeoDataFormatError {
+    /** "CGeoDataVersionError" */
+    name: string;
+    /** The version number the file declares. */
+    readonly version: number;
+    constructor(message: string, version: number);
+}
+/** 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 declare class CGeoDataUnsupportedError extends CGeoDataFormatError {
+    /** "CGeoDataUnsupportedError" */
+    name: string;
+}
+/** 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 declare class CGeoDataIndexMismatchError extends CGeoDataError {
+    /** "CGeoDataIndexMismatchError" */
+    name: string;
+}

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,21 @@
+/**
+ * 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 { 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,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 { 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 { 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