zonemapdb 0.8.0

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,gBAAgB,GAChB,kBAAkB,GAClB,SAAS,GACT,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAGlC,SAAiB,GAAG,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAiB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEjC,YAAY,IAAI,EAAE,kBAAkB,EAOnC;CACF"}

package/dist/errors.js

@@ -0,0 +1,24 @@
+// The single catchable error surface (ADR-0007 §4): one exported class with a
+// discriminated `code`, chosen over a subclass hierarchy — same narrowing, far
+// less exported surface, no instanceof-across-bundlers fragility. Adding a code
+// later is non-breaking.
+/**
+ * The one error `findMany`/`count`/`get` ever throw for fetch/parse/limit
+ * failures: `catch (e) { if (e instanceof ZonemapDbError && e.code === "…") … }`.
+ * The triggering query object is deliberately NOT attached — a `where` can hold
+ * PII-ish filter values that would land in logs (ADR-0007 §8).
+ */
+export class ZonemapDbError extends Error {
+    code;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = "ZonemapDbError";
+        this.code = init.code;
+        // Conditionally assigned so "absent" means absent (`"url" in err` ⇔ provided).
+        if (init.url !== undefined)
+            this.url = init.url;
+        if (init.status !== undefined)
+            this.status = init.status;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,yBAAyB;AAuCzB;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAqB;IAMlC,YAAY,IAAwB;QAClC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,+EAA+E;QAC/E,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QAChD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3D,CAAC;CACF"}

package/dist/fetch-file.d.ts

@@ -0,0 +1,39 @@
+import { type Compression } from "./types.js";
+/**
+ * 404 routes by WHICH file was being fetched — always known at the call site
+ * (ADR-0007 §6): the manifest itself → `CONFIG` (wrong basePath); any
+ * manifest-referenced content-hashed file → `DEPLOY_INTEGRITY` (corrupt deploy).
+ */
+export type FetchedFileKind = "manifest" | "referenced";
+/** Fetch + JSON-parse; an unparseable 2xx body is CORRUPT_DATA (ADR-0007 §5). */
+export declare function fetchJson(url: string, kind: FetchedFileKind, fetchImpl: typeof fetch, signal?: AbortSignal, cache?: RequestCache): Promise<unknown>;
+/** Fetch + text; a 2xx body that won't read is CORRUPT_DATA. */
+export declare function fetchText(url: string, kind: FetchedFileKind, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<string>;
+/** The compression a served path implies. `.br` is the file suffix; `"brotli"` is the API's format name. */
+export declare function compressionOfPath(url: string): Compression;
+/**
+ * Fetch + decompress + text, for build-time-compressed files (ADR-0002 §8) — the native
+ * `DecompressionStream` API, no library/WASM. A 2xx body that won't decompress, or won't read once
+ * decompressed, is CORRUPT_DATA (same contract as `fetchText`).
+ *
+ * When the host serves the file under a matching `Content-Encoding`, the transport has already done
+ * the work and this returns the body as-is. That path is worth more than a mere fix: transport-level
+ * brotli is understood by every browser, whereas `DecompressionStream("brotli")` is not yet (Chrome
+ * 150 still rejects it) — so a `.br` deploy behind such a host works where a raw-bytes one cannot.
+ * Where the host serves raw bytes there is no fallback, which is why build-time compression stays
+ * opt-in.
+ */
+export declare function fetchCompressedText(url: string, kind: FetchedFileKind, format: "gzip" | "brotli", fetchImpl: typeof fetch, signal?: AbortSignal, cache?: RequestCache): Promise<string>;
+/**
+ * Fetch + JSON-parse a manifest-referenced file, decompressing first when the path says it was
+ * built gzipped (ADR-0002 §8).
+ *
+ * Index chunks and zonemap sidecars are referenced from the manifest **by full path**, so the `.gz`
+ * suffix is all the signal needed — no manifest flag to keep in sync, and a tree holding a mix of
+ * compressed and plain files still reads correctly. That matters because content-hashed filenames
+ * mean a rebuild replaces only the files whose contents changed.
+ */
+export declare function fetchReferencedJson(url: string, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<unknown>;
+/** Parse/decode a 2xx body's CONTENT into a domain structure; failures are CORRUPT_DATA. */
+export declare function parseCorruptible<T>(url: string, parse: () => T): T;
+//# sourceMappingURL=fetch-file.d.ts.map

package/dist/fetch-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-file.d.ts","sourceRoot":"","sources":["../src/fetch-file.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,YAAY,CAAC;AA0DxD,iFAAiF;AACjF,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,eAAe,EACrB,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAgBD,gEAAgE;AAChE,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,eAAe,EACrB,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,4GAA4G;AAC5G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAI1D;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,MAAM,GAAG,QAAQ,EACzB,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAKlB;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAWlE"}

package/dist/fetch-file.js

@@ -0,0 +1,179 @@
+// The WHATWG-fetch → ZonemapDbError mapping (ADR-0007 §3/§5/§6), shared by every
+// file the runtime fetches. The injected fetch rejects on network-level failure
+// but resolves on ANY HTTP status, so a fetch counts as failed when the promise
+// rejects OR resolves !response.ok. No retry/backoff/timeout here — that is the
+// injected fetch's / CDN's job (§2).
+import { ZonemapDbError } from "./errors.js";
+import { decompressionFormat } from "./types.js";
+function messageFor404(kind, url) {
+    return kind === "manifest"
+        ? `zonemapdb: no manifest.json at "${url}" (HTTP 404) — check basePath: it must point at the deployed dataset root. If the dataset was never deployed there, re-run \`zonemapdb build\` and deploy the output.`
+        : `zonemapdb: "${url}" referenced by the manifest returned HTTP 404 — the deploy is incomplete or corrupt, or a stale cache (a CDN, a fetch wrapper, or an old index.html / bundled client) is still serving an earlier deploy's manifest. If the deploy is complete, wait for caches to expire or hard-reload; otherwise re-run \`zonemapdb build\` and redeploy the whole output.`;
+}
+function messageForHtmlFallback(kind, url) {
+    return kind === "manifest"
+        ? `zonemapdb: "${url}" returned an HTML page instead of manifest.json, which is what a single-page-app fallback serves for a missing file — check basePath: it must point at the deployed dataset root.`
+        : `zonemapdb: "${url}" referenced by the manifest returned an HTML page, which is what a single-page-app fallback serves for a missing file — the deploy is incomplete, or a stale cache is still serving an earlier deploy's manifest. If the deploy is complete, wait for caches to expire or hard-reload; otherwise re-run \`zonemapdb build\` and redeploy the whole output.`;
+}
+/**
+ * Fetches `url`, mapping rejection / !ok to the right ZonemapDbError code. Resolves only on 2xx.
+ * `cache` is set only for the manifest (#32); content-hashed files leave it off so the browser's
+ * normal (forever-valid) caching applies, and their `init` stays exactly `{ signal }`.
+ */
+async function fetchOk(url, kind, fetchImpl, signal, cache) {
+    let response;
+    try {
+        response = await fetchImpl(url, cache === undefined ? { signal } : { signal, cache });
+    }
+    catch (cause) {
+        throw new ZonemapDbError({
+            code: "NETWORK",
+            url,
+            message: `zonemapdb: fetch for "${url}" failed at the network level (${cause instanceof Error ? cause.message : String(cause)}) — possibly transient. Retry by wrapping the injected fetch, or check connectivity/CORS.`,
+            cause,
+        });
+    }
+    // A single-page-app fallback (Netlify/Vercel/Cloudflare rewrites, `serve -s`) answers a missing file
+    // with 200 and index.html. zonemapdb never serves HTML, so that is the missing file, and it is routed as
+    // the 404 it stands for. Otherwise it would surface as CORRUPT_DATA and skip the stale-manifest recovery.
+    const servedHtml = response.ok && (response.headers?.get("content-type") ?? "").toLowerCase().startsWith("text/html");
+    if (response.ok && !servedHtml)
+        return response;
+    if (response.status === 404 || servedHtml) {
+        throw new ZonemapDbError({
+            code: kind === "manifest" ? "CONFIG" : "DEPLOY_INTEGRITY",
+            url,
+            status: response.status,
+            message: servedHtml ? messageForHtmlFallback(kind, url) : messageFor404(kind, url),
+        });
+    }
+    throw new ZonemapDbError({
+        code: "NETWORK",
+        url,
+        status: response.status,
+        message: `zonemapdb: fetch for "${url}" returned HTTP ${response.status} — possibly transient. Retry by wrapping the injected fetch, or check the host/CDN.`,
+    });
+}
+/** Fetch + JSON-parse; an unparseable 2xx body is CORRUPT_DATA (ADR-0007 §5). */
+export async function fetchJson(url, kind, fetchImpl, signal, cache) {
+    const response = await fetchOk(url, kind, fetchImpl, signal, cache);
+    try {
+        return await response.json();
+    }
+    catch (cause) {
+        throw new ZonemapDbError({
+            code: "CORRUPT_DATA",
+            url,
+            message: `zonemapdb: the body of "${url}" would not parse as JSON — the deploy is corrupt. Re-run \`zonemapdb build\` and redeploy.`,
+            cause,
+        });
+    }
+}
+/** Reads a 2xx body as text; a body that won't read is CORRUPT_DATA. */
+async function readText(response, url) {
+    try {
+        return await response.text();
+    }
+    catch (cause) {
+        throw new ZonemapDbError({
+            code: "CORRUPT_DATA",
+            url,
+            message: `zonemapdb: the body of "${url}" could not be read — the deploy is corrupt. Re-run \`zonemapdb build\` and redeploy.`,
+            cause,
+        });
+    }
+}
+/** Fetch + text; a 2xx body that won't read is CORRUPT_DATA. */
+export async function fetchText(url, kind, fetchImpl, signal) {
+    return await readText(await fetchOk(url, kind, fetchImpl, signal), url);
+}
+/** The compression a served path implies. `.br` is the file suffix; `"brotli"` is the API's format name. */
+export function compressionOfPath(url) {
+    if (url.endsWith(".gz"))
+        return "gzip";
+    if (url.endsWith(".br"))
+        return "brotli";
+    return "none";
+}
+/** The `Content-Encoding` token a codec travels under — `br` on the wire, `"brotli"` to the API. */
+const CONTENT_ENCODING_TOKEN = { gzip: "gzip", brotli: "br" };
+/**
+ * Whether the fetch layer has ALREADY undone this file's build-time compression.
+ *
+ * Most static hosts recognise a `.gz`/`.br` suffix and answer with the matching `Content-Encoding`
+ * (Vite's dev server, nginx `gzip_static`, most CDNs). The browser then decodes at the transport
+ * layer and hands over a plain body — while leaving the header visible on the response. Decompressing
+ * again would fail on what is already plain text, so the header is the signal to stand down.
+ *
+ * The match must be exact: a host that re-encodes our `.br` file as gzip has undone its own encoding,
+ * not the build's, and the runtime still has to do its part.
+ */
+function alreadyDecodedByTransport(response, format) {
+    const header = response.headers?.get("content-encoding");
+    if (!header)
+        return false;
+    return header.split(",").some((token) => token.trim().toLowerCase() === CONTENT_ENCODING_TOKEN[format]);
+}
+/**
+ * Fetch + decompress + text, for build-time-compressed files (ADR-0002 §8) — the native
+ * `DecompressionStream` API, no library/WASM. A 2xx body that won't decompress, or won't read once
+ * decompressed, is CORRUPT_DATA (same contract as `fetchText`).
+ *
+ * When the host serves the file under a matching `Content-Encoding`, the transport has already done
+ * the work and this returns the body as-is. That path is worth more than a mere fix: transport-level
+ * brotli is understood by every browser, whereas `DecompressionStream("brotli")` is not yet (Chrome
+ * 150 still rejects it) — so a `.br` deploy behind such a host works where a raw-bytes one cannot.
+ * Where the host serves raw bytes there is no fallback, which is why build-time compression stays
+ * opt-in.
+ */
+export async function fetchCompressedText(url, kind, format, fetchImpl, signal, cache) {
+    const response = await fetchOk(url, kind, fetchImpl, signal, cache);
+    if (alreadyDecodedByTransport(response, format))
+        return await readText(response, url);
+    try {
+        // Cast: TypeScript's DOM lib still types CompressionFormat as gzip/deflate/deflate-raw, though
+        // "brotli" is in the Compression Streams spec and shipping. The runtime check that matters is the
+        // catch below — an engine without the format throws here and surfaces as CORRUPT_DATA.
+        const decompressed = response.body.pipeThrough(new DecompressionStream(format));
+        return await new Response(decompressed).text();
+    }
+    catch (cause) {
+        throw new ZonemapDbError({
+            code: "CORRUPT_DATA",
+            url,
+            message: `zonemapdb: the ${format} body of "${url}" could not be decompressed — the deploy is corrupt, or this browser lacks ${format} support in DecompressionStream. Re-run \`zonemapdb build\` and redeploy.`,
+            cause,
+        });
+    }
+}
+/**
+ * Fetch + JSON-parse a manifest-referenced file, decompressing first when the path says it was
+ * built gzipped (ADR-0002 §8).
+ *
+ * Index chunks and zonemap sidecars are referenced from the manifest **by full path**, so the `.gz`
+ * suffix is all the signal needed — no manifest flag to keep in sync, and a tree holding a mix of
+ * compressed and plain files still reads correctly. That matters because content-hashed filenames
+ * mean a rebuild replaces only the files whose contents changed.
+ */
+export async function fetchReferencedJson(url, fetchImpl, signal) {
+    const format = decompressionFormat(compressionOfPath(url));
+    if (format === undefined)
+        return await fetchJson(url, "referenced", fetchImpl, signal);
+    const text = await fetchCompressedText(url, "referenced", format, fetchImpl, signal);
+    return parseCorruptible(url, () => JSON.parse(text));
+}
+/** Parse/decode a 2xx body's CONTENT into a domain structure; failures are CORRUPT_DATA. */
+export function parseCorruptible(url, parse) {
+    try {
+        return parse();
+    }
+    catch (cause) {
+        throw new ZonemapDbError({
+            code: "CORRUPT_DATA",
+            url,
+            message: `zonemapdb: the body of "${url}" would not parse — the deploy is corrupt. Re-run \`zonemapdb build\` and redeploy.`,
+            cause,
+        });
+    }
+}
+//# sourceMappingURL=fetch-file.js.map

package/dist/fetch-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-file.js","sourceRoot":"","sources":["../src/fetch-file.ts"],"names":[],"mappings":"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"}

package/dist/filter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Evaluates one field's operator filter against a record (T7): `isNull`/`isAbsent`/`exists`
+ * distinguish an explicit `null` from a genuinely missing key; every other operator
+ * (including `some` and the `not` rider) requires a present, non-null value.
+ */
+export declare function matchesFieldFilter(record: Record<string, unknown>, field: string, filter: Record<string, unknown>): boolean;
+/** Implicit-AND across every field in `where` (ADR-0001). */
+export declare function matchesWhere(record: Record<string, unknown>, where: Record<string, Record<string, unknown>> | undefined): boolean;
+//# sourceMappingURL=filter.d.ts.map

package/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AA0DA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CA4B3H;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GACzD,OAAO,CAMT"}

package/dist/filter.js

@@ -0,0 +1,104 @@
+/** Evaluates one non-null, present value against a single scalar operator (equals/in/gt/.../not). */
+function matchesValueOp(value, op, opValue) {
+    switch (op) {
+        case "equals":
+            return value === opValue;
+        case "not":
+            return value !== opValue;
+        case "in":
+            return opValue.includes(value);
+        case "gt":
+            return value > opValue;
+        case "gte":
+            return value >= opValue;
+        case "lt":
+            return value < opValue;
+        case "lte":
+            return value <= opValue;
+        case "startsWith":
+            return value.startsWith(opValue);
+        case "endsWith":
+            return value.endsWith(opValue);
+        case "contains":
+            return value.includes(opValue);
+        default:
+            throw new Error(`zonemapdb: unsupported operator "${op}"`);
+    }
+}
+/** One element against `some`/`every`'s element filter — shorthand value ≡ `{ equals: value }`. */
+function matchesElement(element, elementFilter) {
+    if (typeof elementFilter === "object" && elementFilter !== null) {
+        return Object.entries(elementFilter).every(([op, opValue]) => matchesValueOp(element, op, opValue));
+    }
+    return element === elementFilter;
+}
+/**
+ * The list operators on a multi-valued field: `some` (T7) plus ADR-0010's `hasEvery`, `every` and
+ * `isEmpty`. `undefined` means `op` isn't one of them.
+ */
+function matchesListOp(values, op, opValue) {
+    switch (op) {
+        case "some":
+            return values.some((element) => matchesElement(element, opValue));
+        case "every":
+            // Vacuously true for [] — "every colour is W or U" holds for a colourless card.
+            return values.every((element) => matchesElement(element, opValue));
+        case "hasEvery":
+            return opValue.every((wanted) => values.includes(wanted));
+        case "isEmpty":
+            return (values.length === 0) === opValue;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Evaluates one field's operator filter against a record (T7): `isNull`/`isAbsent`/`exists`
+ * distinguish an explicit `null` from a genuinely missing key; every other operator
+ * (including `some` and the `not` rider) requires a present, non-null value.
+ */
+export function matchesFieldFilter(record, field, filter) {
+    const isAbsent = !(field in record);
+    const value = isAbsent ? undefined : record[field];
+    const isNull = !isAbsent && value === null;
+    for (const [op, opValue] of Object.entries(filter)) {
+        if (op === "isNull") {
+            if (isNull !== opValue)
+                return false;
+            continue;
+        }
+        if (op === "isAbsent") {
+            if (isAbsent !== opValue)
+                return false;
+            continue;
+        }
+        if (op === "exists") {
+            const exists = !isAbsent && !isNull;
+            if (exists !== opValue)
+                return false;
+            continue;
+        }
+        if (isAbsent || isNull)
+            return false;
+        if (Array.isArray(value)) {
+            const listMatch = matchesListOp(value, op, opValue);
+            if (listMatch === false)
+                return false;
+            if (listMatch === true)
+                continue;
+        }
+        if (!matchesValueOp(value, op, opValue))
+            return false;
+    }
+    return true;
+}
+/** Implicit-AND across every field in `where` (ADR-0001). */
+export function matchesWhere(record, where) {
+    if (!where)
+        return true;
+    for (const [field, filter] of Object.entries(where)) {
+        if (!matchesFieldFilter(record, field, filter))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=filter.js.map

package/dist/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"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"}

package/dist/index-fetch.d.ts

@@ -0,0 +1,3 @@
+import type { IndexChunkFile } from "./secondary-index.js";
+export declare function fetchIndexChunk(basePath: string, file: string, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<IndexChunkFile>;
+//# sourceMappingURL=index-fetch.d.ts.map

package/dist/index-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-fetch.d.ts","sourceRoot":"","sources":["../src/index-fetch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAEzB"}

package/dist/index-fetch.js

@@ -0,0 +1,5 @@
+import { fetchReferencedJson } from "./fetch-file.js";
+export async function fetchIndexChunk(basePath, file, fetchImpl, signal) {
+    return (await fetchReferencedJson(`${basePath}/${file}`, fetchImpl, signal));
+}
+//# sourceMappingURL=index-fetch.js.map

package/dist/index-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-fetch.js","sourceRoot":"","sources":["../src/index-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,IAAY,EACZ,SAAuB,EACvB,MAAoB;IAEpB,OAAO,CAAC,MAAM,mBAAmB,CAAC,GAAG,QAAQ,IAAI,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,CAAmB,CAAC;AACjG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createClient } from "./client.js";
+export { ZonemapDbError, type ZonemapDbErrorCode } from "./errors.js";
+export { normalize, type NormalizerName } from "./normalize.js";
+export type { Manifest, BlockDescriptor, SchemaDescriptor, FieldSchemaEntry } from "./manifest.js";
+export { assertWhereHasPruning, wherePrunes, type ClientOptions, type Collection, type CollectionMeta, type CountOptions, type CountResult, type FieldKind, type FieldMeta, type BlockOrderScanArgs, type FindManyArgs, type QueryOptions, type FindManyResult, type GenericClient, type OrderByOf, type SchemaMeta, type ValidateWhere, type WhereOf, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,OAAO,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createClient } from "./client.js";
+export { ZonemapDbError } from "./errors.js";
+export { normalize } from "./normalize.js";
+export { assertWhereHasPruning, wherePrunes, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAA2B,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,SAAS,EAAuB,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EACL,qBAAqB,EACrB,WAAW,GAiBZ,MAAM,YAAY,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,127 @@
+import { type Compression } from "./types.js";
+export interface BlockDescriptor {
+    hash: string;
+    bytes: number;
+    count: number;
+}
+export interface FieldSchemaEntry {
+    kind: string;
+    isDate: boolean;
+    indexed: boolean;
+    /** Everything a `where` may write on this field (ADR-0013). */
+    operators: readonly string[];
+    /** The subset of `operators` that narrows which blocks a query reads; the rest are riders. */
+    pruning: readonly string[];
+    /** The key may be missing from a record (absent ≠ null). */
+    absent?: true;
+    /** The value may be `null` (null ≠ absent). */
+    nullable?: true;
+    /** Scalar leaf under an object-array — value is an array, matched existentially via `some` (T7). */
+    multi?: true;
+    /** Present (`true`) only for the user PK field (T8). */
+    pk?: true;
+}
+export interface SchemaDescriptor {
+    collection: string;
+    sortField: string;
+    /** Names the user PK field, if declared (T8). */
+    pk?: string;
+    fields: Record<string, FieldSchemaEntry>;
+}
+/** Records with a null/absent sort-field value cluster in a contiguous tail at the high end (ADR-0002 §9). */
+export interface MissingZonemapInfo {
+    /** Ordinal of the earliest block containing any missing (null or absent) sort-field value. */
+    blockFrom: number;
+    /** Records with an explicit `null` sort-field value. */
+    nullCount: number;
+    /** Records whose sort-field key is absent entirely (not just null). */
+    absentCount: number;
+}
+/** Sort field: N+1 monotonic split-points, binary-searchable (ADR-0003 §2). */
+export interface SplitPointZonemapEntry {
+    splitPoints: unknown[];
+    /** Present iff at least one record had a null/absent sort-field value (ADR-0002 §9). */
+    missing?: MissingZonemapInfo;
+}
+/** Secondary field: per-block [min,max] pairs, ordinal-aligned with `blocks[]` (ADR-0003 §2/§9). */
+export interface PairZonemapEntry {
+    pairs: [unknown, unknown][];
+    truncated?: boolean;
+}
+/** A secondary field's zonemap moved out of root into a per-field sidecar file (ADR-0003 §3) — spilled when the root manifest would exceed the gzip budget. */
+export interface SidecarZonemapEntry {
+    sidecar: string;
+}
+export type ZonemapEntry = SplitPointZonemapEntry | PairZonemapEntry | SidecarZonemapEntry;
+/** One index chunk's value-range coverage — routing metadata only (ADR-0003 §9). */
+export interface IndexChunkDirEntry {
+    from: unknown;
+    to: unknown;
+    file: string;
+}
+export interface IndexDescriptor {
+    operators: readonly string[];
+    chunks: IndexChunkDirEntry[];
+    /** Reversed-value index chunk directory — present iff `endsWith` opted in (ADR-0003 §7/§9). */
+    reversed?: {
+        chunks: IndexChunkDirEntry[];
+    };
+    /** Trigram index chunk directory — present iff `contains` opted in (ADR-0003 §7/§9). */
+    trigram?: {
+        chunks: IndexChunkDirEntry[];
+    };
+    /**
+     * Multi-valued fields only: ordinals of the blocks holding at least one present `[]` — what
+     * `isEmpty` and `every` prune on (ADR-0010 §4/§5). Missing (a pre-ADR-0010 build) means unknown.
+     */
+    emptyBlocks?: number[];
+}
+export interface Manifest {
+    formatVersion: number;
+    generatorVersion: string;
+    dataset: {
+        collection: string;
+        recordCount: number;
+        blockCount: number;
+        sortField: string;
+        /** Present (`true`) only when block payloads are gzipped at build time (ADR-0002 §8) — omitted otherwise. */
+        /**
+         * How every served file was pre-compressed, when the build did so (ADR-0002 §8). Absent means
+         * plain files. `gzip?: true` is the pre-`compression` spelling, still read so an older deploy keeps
+         * working against a newer client.
+         */
+        compression?: Compression;
+        /** @deprecated Superseded by `compression: "gzip"`. */
+        gzip?: true;
+    };
+    schema: SchemaDescriptor;
+    blocks: BlockDescriptor[];
+    zonemap: Record<string, ZonemapEntry>;
+    indexes: Record<string, IndexDescriptor>;
+}
+/**
+ * Fetches the root manifest. `gzipped` says the deploy pre-compressed it (ADR-0002 §8) — unlike index
+ * chunks and zonemap sidecars, whose `.gz` paths come FROM the manifest and so describe themselves,
+ * this is the bootstrap fetch: nothing has been read yet that could tell the client the encoding. The
+ * generated client carries the answer instead, stamped by the same `build` that wrote the file, so the
+ * two cannot drift.
+ *
+ * `cache` defaults to `"no-cache"` (#32): the manifest is the one stable-named file, and a host that
+ * caches everything for minutes (GitHub Pages sends `max-age=600`) would otherwise hand back the
+ * previous deploy's copy after a redeploy. Revalidating costs a 304 when nothing changed. The client
+ * passes `"reload"` when a referenced file 404s and it needs to know what the deploy says now.
+ */
+export declare function fetchManifest(basePath: string, fetchImpl: typeof fetch, compression?: Compression, cache?: RequestCache): Promise<Manifest>;
+/**
+ * How this deploy compressed the files the manifest points at. Reads the modern `compression` field
+ * and falls back to the original `gzip: true`, so a tree built before the field existed still works.
+ */
+export declare function datasetCompression(manifest: Manifest): Compression;
+/**
+ * Whether `manifest` points at `url` — a block, an index chunk (base, reversed or trigram) or a
+ * zonemap sidecar. The client asks this of a freshly fetched manifest after a referenced file 404s
+ * (#32): if the fresh manifest still names the file the deploy really is missing it, and if not, the
+ * 404 came from a stale manifest and the query is worth one retry.
+ */
+export declare function manifestReferences(manifest: Manifest, basePath: string, url: string): boolean;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}