zonemapdb 0.8.0

package/dist/manifest.js

@@ -0,0 +1,86 @@
+import { ZonemapDbError } from "./errors.js";
+import { compressionSuffix, decompressionFormat } from "./types.js";
+import { blockRelPath } from "./block-fetch.js";
+import { fetchCompressedText, fetchJson, parseCorruptible } from "./fetch-file.js";
+import { FORMAT_VERSION } from "./version.js";
+/**
+ * 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 async function fetchManifest(basePath, fetchImpl, compression = "none", cache = "no-cache") {
+    const url = `${basePath}/manifest.json${compressionSuffix(compression)}`;
+    const format = decompressionFormat(compression);
+    let parsed;
+    if (format === undefined) {
+        parsed = (await fetchJson(url, "manifest", fetchImpl, undefined, cache));
+    }
+    else {
+        const text = await fetchCompressedText(url, "manifest", format, fetchImpl, undefined, cache);
+        parsed = parseCorruptible(url, () => JSON.parse(text));
+    }
+    // JSON-valid but not a manifest — the body "won't parse" into one (ADR-0007 §5).
+    if (typeof parsed.formatVersion !== "number") {
+        throw new ZonemapDbError({
+            code: "CORRUPT_DATA",
+            url,
+            message: `zonemapdb: the manifest at "${url}" parsed as JSON but has no numeric formatVersion — the deploy is corrupt. Re-run \`zonemapdb build\` and redeploy.`,
+        });
+    }
+    // ADR-0005: same major → always compatible (SemVer); major mismatch → fail loud.
+    if (parsed.formatVersion !== FORMAT_VERSION) {
+        throw new ZonemapDbError({
+            code: "FORMAT_VERSION",
+            url,
+            message: `zonemapdb: the dataset at "${url}" was built with zonemapdb major ${String(parsed.formatVersion)} ` +
+                `but this runtime is major ${FORMAT_VERSION} — align versions and re-run \`zonemapdb build\`.`,
+        });
+    }
+    // ADR-0013 added each field's `pruning` list inside major 0. The rider rule can't be enforced
+    // without it, so a tree built before it is refused like any format mismatch rather than guessed at.
+    if (Object.values(parsed.schema?.fields ?? {}).some((field) => !Array.isArray(field.pruning))) {
+        throw new ZonemapDbError({
+            code: "FORMAT_VERSION",
+            url,
+            message: `zonemapdb: the dataset at "${url}" was built by a zonemapdb older than this runtime (before 0.3.0, which ` +
+                `added which operators prune) — re-run \`zonemapdb build\` with the current version and redeploy.`,
+        });
+    }
+    return parsed;
+}
+/**
+ * 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 function datasetCompression(manifest) {
+    return manifest.dataset.compression ?? (manifest.dataset.gzip === true ? "gzip" : "none");
+}
+/**
+ * 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 function manifestReferences(manifest, basePath, url) {
+    const prefix = `${basePath}/`;
+    if (!url.startsWith(prefix))
+        return false;
+    const path = url.slice(prefix.length);
+    const compression = datasetCompression(manifest);
+    if (manifest.blocks.some((block) => blockRelPath(block.hash, manifest.blocks.length, compression) === path))
+        return true;
+    for (const index of Object.values(manifest.indexes)) {
+        const directories = [index.chunks, index.reversed?.chunks ?? [], index.trigram?.chunks ?? []];
+        if (directories.some((chunks) => chunks.some((chunk) => chunk.file === path)))
+            return true;
+    }
+    return Object.values(manifest.zonemap).some((entry) => "sidecar" in entry && entry.sidecar === path);
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/dist/normalize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The derived-field normalizers (ADR-0009), for normalizing a QUERY value the same way the build
+ * normalized the column it targets. A `name_fold` column holds `fold(name)`, so a search box has to
+ * send `normalize("fold", input)` or its trigrams won't line up with the index.
+ *
+ * This duplicates `zonemapdb-cli/src/normalize.ts` rather than importing it, like the other
+ * cli/runtime pairs: the runtime stays dependency-free, and the CLI's test suite checks the two
+ * produce identical output.
+ */
+declare const NORMALIZERS: {
+    numeric(value: unknown): number | null;
+    lowercase(value: unknown): string | null;
+    trim(value: unknown): string | null;
+    fold(value: unknown): string | null;
+};
+export type NormalizerName = keyof typeof NORMALIZERS;
+/**
+ * Applies a derived-field normalizer. `null` means "no derivable value" — the build omits the derived
+ * key for such records, so there is nothing a query with that value could match.
+ */
+export declare function normalize(using: "numeric", value: unknown): number | null;
+export declare function normalize(using: "lowercase" | "trim" | "fold", value: unknown): string | null;
+export declare function normalize(using: NormalizerName, value: unknown): string | number | null;
+export {};
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,QAAA,MAAM,WAAW;IACf,OAAO,QAAQ,OAAO,GAAG,MAAM,GAAG,IAAI;IAOtC,SAAS,QAAQ,OAAO,GAAG,MAAM,GAAG,IAAI;IAIxC,IAAI,QAAQ,OAAO,GAAG,MAAM,GAAG,IAAI;IAInC,IAAI,QAAQ,OAAO,GAAG,MAAM,GAAG,IAAI;CAKpC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,WAAW,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AAC3E,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AAC/F,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC"}

package/dist/normalize.js

@@ -0,0 +1,43 @@
+/**
+ * The derived-field normalizers (ADR-0009), for normalizing a QUERY value the same way the build
+ * normalized the column it targets. A `name_fold` column holds `fold(name)`, so a search box has to
+ * send `normalize("fold", input)` or its trigrams won't line up with the index.
+ *
+ * This duplicates `zonemapdb-cli/src/normalize.ts` rather than importing it, like the other
+ * cli/runtime pairs: the runtime stays dependency-free, and the CLI's test suite checks the two
+ * produce identical output.
+ */
+/** Combining marks left behind by NFD, stripped to fold `û` → `u`. */
+const COMBINING_MARKS = /\p{M}/gu;
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+const NORMALIZERS = {
+    numeric(value) {
+        if (typeof value === "number")
+            return Number.isFinite(value) ? value : null;
+        const text = asString(value)?.trim();
+        if (text === undefined || text.length === 0)
+            return null;
+        const parsed = Number(text);
+        return Number.isFinite(parsed) ? parsed : null;
+    },
+    lowercase(value) {
+        const text = asString(value);
+        return text === undefined ? null : text.toLowerCase();
+    },
+    trim(value) {
+        const text = asString(value)?.trim();
+        return text === undefined || text.length === 0 ? null : text;
+    },
+    fold(value) {
+        const text = asString(value);
+        if (text === undefined)
+            return null;
+        return text.normalize("NFD").replace(COMBINING_MARKS, "").normalize("NFC").toLowerCase();
+    },
+};
+export function normalize(using, value) {
+    return NORMALIZERS[using](value);
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,eAAe,GAAG,SAAS,CAAC;AAElC,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,WAAW,GAAG;IAClB,OAAO,CAAC,KAAc;QACpB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5E,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;QACrC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IACD,SAAS,CAAC,KAAc;QACtB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACxD,CAAC;IACD,IAAI,CAAC,KAAc;QACjB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;QACrC,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,KAAc;QACjB,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3F,CAAC;CACF,CAAC;AAWF,MAAM,UAAU,SAAS,CAAC,KAAqB,EAAE,KAAc;IAC7D,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/secondary-index.d.ts

@@ -0,0 +1,32 @@
+import type { IndexChunkDirEntry } from "./manifest.js";
+import type { FieldKind } from "./types.js";
+export interface IndexChunkEntry {
+    /** Chars shared with the PREVIOUS entry's canonical key; 0 for a chunk's first entry (ADR-0003 §4). */
+    prefixLen: number;
+    suffix: string;
+    /** Delta-encoded ascending block ordinals — cumulative-sum from 0 reconstructs them (ADR-0003 §5). */
+    postings: number[];
+}
+export interface IndexChunkFile {
+    entries: IndexChunkEntry[];
+}
+export interface DecodedIndexEntry {
+    value: unknown;
+    blockIndices: number[];
+}
+/** Reconstructs a chunk's front-coded dictionary + delta-encoded postings into typed values. */
+export declare function decodeIndexChunk(file: IndexChunkFile, kind: FieldKind): DecodedIndexEntry[];
+export interface SecondaryFieldFilter {
+    equals?: unknown;
+    in?: unknown[];
+    startsWith?: string;
+}
+/** The chunk directory entries a filter could possibly match — routes which chunks to fetch. */
+export declare function chunksForFilter(chunks: IndexChunkDirEntry[], filter: SecondaryFieldFilter): IndexChunkDirEntry[];
+/** The union of block ordinals whose decoded entry value satisfies the filter. */
+export declare function blockIndicesForFilter(decoded: DecodedIndexEntry[], filter: SecondaryFieldFilter): Set<number>;
+/** Codepoint-safe reversal (ADR-0003 §7): `endsWith(suffix)` becomes `startsWith` on the reversed index once both sides are reversed. */
+export declare function reverseString(value: string): string;
+/** Every sliding 3-char window of `value` — the query-side counterpart of the trigram index's dictionary keys (ADR-0003 §7). */
+export declare function trigramsOf(value: string): string[];
+//# sourceMappingURL=secondary-index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secondary-index.d.ts","sourceRoot":"","sources":["../src/secondary-index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,uGAAuG;IACvG,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAQD,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,GAAG,iBAAiB,EAAE,CAQ3F;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAYD,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,oBAAoB,GAAG,kBAAkB,EAAE,CAYhH;AASD,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,EAAE,EAAE,MAAM,EAAE,oBAAoB,GAAG,GAAG,CAAC,MAAM,CAAC,CAM7G;AAED,yIAAyI;AACzI,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,gIAAgI;AAChI,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlD"}

package/dist/secondary-index.js

@@ -0,0 +1,80 @@
+// Secondary-field pruning (ADR-0003): decode a chunked inverted-index chunk,
+// pick the chunk(s) a filter could touch from the (always-in-manifest) chunk
+// directory, and resolve which blocks actually hold a matching value.
+function fromCanonicalKey(key, kind) {
+    if (kind === "number")
+        return Number(key);
+    if (kind === "boolean")
+        return key === "true";
+    return key; // string | date — dates are already ISO strings
+}
+/** Reconstructs a chunk's front-coded dictionary + delta-encoded postings into typed values. */
+export function decodeIndexChunk(file, kind) {
+    let prevKey = "";
+    return file.entries.map((entry) => {
+        prevKey = prevKey.slice(0, entry.prefixLen) + entry.suffix;
+        let acc = 0;
+        const blockIndices = entry.postings.map((delta) => (acc += delta));
+        return { value: fromCanonicalKey(prevKey, kind), blockIndices };
+    });
+}
+function overlapsValue(dir, value) {
+    return dir.from <= value && value <= dir.to;
+}
+/** Any string with `prefix` lies lexicographically within [prefix, prefix + a sentinel higher than any real char]. */
+function overlapsPrefix(dir, prefix) {
+    const sentinel = prefix + "￿";
+    return dir.from <= sentinel && dir.to >= prefix;
+}
+/** The chunk directory entries a filter could possibly match — routes which chunks to fetch. */
+export function chunksForFilter(chunks, filter) {
+    const matched = new Set();
+    if (filter.equals !== undefined) {
+        for (const chunk of chunks)
+            if (overlapsValue(chunk, filter.equals))
+                matched.add(chunk);
+    }
+    if (filter.in !== undefined) {
+        for (const value of filter.in)
+            for (const chunk of chunks)
+                if (overlapsValue(chunk, value))
+                    matched.add(chunk);
+    }
+    if (filter.startsWith !== undefined) {
+        for (const chunk of chunks)
+            if (overlapsPrefix(chunk, filter.startsWith))
+                matched.add(chunk);
+    }
+    return [...matched];
+}
+function matchesEntryValue(value, filter) {
+    if (filter.equals !== undefined && value !== filter.equals)
+        return false;
+    if (filter.in !== undefined && !filter.in.includes(value))
+        return false;
+    if (filter.startsWith !== undefined && !value.startsWith(filter.startsWith))
+        return false;
+    return true;
+}
+/** The union of block ordinals whose decoded entry value satisfies the filter. */
+export function blockIndicesForFilter(decoded, filter) {
+    const blockIndices = new Set();
+    for (const entry of decoded) {
+        if (matchesEntryValue(entry.value, filter))
+            for (const s of entry.blockIndices)
+                blockIndices.add(s);
+    }
+    return blockIndices;
+}
+/** Codepoint-safe reversal (ADR-0003 §7): `endsWith(suffix)` becomes `startsWith` on the reversed index once both sides are reversed. */
+export function reverseString(value) {
+    return [...value].reverse().join("");
+}
+/** Every sliding 3-char window of `value` — the query-side counterpart of the trigram index's dictionary keys (ADR-0003 §7). */
+export function trigramsOf(value) {
+    const grams = [];
+    for (let i = 0; i <= value.length - 3; i++)
+        grams.push(value.slice(i, i + 3));
+    return grams;
+}
+//# sourceMappingURL=secondary-index.js.map

package/dist/secondary-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secondary-index.js","sourceRoot":"","sources":["../src/secondary-index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,sEAAsE;AAsBtE,SAAS,gBAAgB,CAAC,GAAW,EAAE,IAAe;IACpD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,GAAG,KAAK,MAAM,CAAC;IAC9C,OAAO,GAAG,CAAC,CAAC,gDAAgD;AAC9D,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,IAAoB,EAAE,IAAe;IACpE,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3D,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC;QACnE,OAAO,EAAE,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC;AAQD,SAAS,aAAa,CAAC,GAAuB,EAAE,KAAc;IAC5D,OAAQ,GAAG,CAAC,IAAc,IAAK,KAAe,IAAK,KAAe,IAAK,GAAG,CAAC,EAAY,CAAC;AAC1F,CAAC;AAED,sHAAsH;AACtH,SAAS,cAAc,CAAC,GAAuB,EAAE,MAAc;IAC7D,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,CAAC;IAC9B,OAAQ,GAAG,CAAC,IAAe,IAAI,QAAQ,IAAK,GAAG,CAAC,EAAa,IAAI,MAAM,CAAC;AAC1E,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,eAAe,CAAC,MAA4B,EAAE,MAA4B;IACxF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,IAAI,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,EAAE;YAAE,KAAK,MAAM,KAAK,IAAI,MAAM;gBAAE,IAAI,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC;oBAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjH,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,IAAI,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc,EAAE,MAA4B;IACrE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACzE,IAAI,MAAM,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxE,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,CAAE,KAAgB,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IACtG,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,qBAAqB,CAAC,OAA4B,EAAE,MAA4B;IAC9F,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,iBAAiB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY;gBAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,yIAAyI;AACzI,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,gIAAgI;AAChI,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,319 @@
+/**
+ * How the deploy pre-compresses every file it serves (ADR-0002 §8). `"none"` is the default: most
+ * hosts apply `Content-Encoding` themselves, which negotiates per client, whereas a pre-compressed
+ * file cannot — a baked `.br` is unreadable to a client without brotli, with no fallback.
+ *
+ * Note the mismatch the file extension hides: the served suffix is `.br` (matching `Content-Encoding:
+ * br`), but the DecompressionStream format string is `"brotli"`.
+ */
+export type Compression = "none" | "gzip" | "brotli";
+/** The suffix a compressed file carries. Duplicated in both packages and pinned by an equivalence test — the runtime must derive block paths without reading anything the CLI wrote. */
+export declare function compressionSuffix(compression: Compression): string;
+/** The `DecompressionStream` format name for a compression, or `undefined` when nothing was applied. */
+export declare function decompressionFormat(compression: Compression): "gzip" | "brotli" | undefined;
+/**
+ * `json` is a payload-only field (an object, or a list of objects): no value operators and no
+ * ordering, but a field marked `absent`/`nullable` still gets the missing-value operators (ADR-0012),
+ * which is why codegen emits it into the schema at all.
+ */
+export type FieldKind = "string" | "number" | "date" | "boolean" | "json";
+export interface FieldMeta {
+    readonly kind: FieldKind;
+    /** Every operator a `where` may write on this field (ADR-0013). */
+    readonly operators: readonly string[];
+    /**
+     * The subset of `operators` that narrows which blocks a query reads; the others are riders. Always
+     * emitted by codegen. A hand-written schema that omits it falls back to "every operator but `not`
+     * and the missing-value operators prunes".
+     */
+    readonly pruning?: readonly string[];
+    /** Multi-valued (string[]) → the list operators `some`/`every`/`hasEvery`/`isEmpty` (ADR-0010). */
+    readonly multi?: boolean;
+    /** This field is the user PK. */
+    readonly pk?: boolean;
+    /** The key may be missing from a record. Informational: `isAbsent`/`exists` arrive via `operators`. */
+    readonly absent?: boolean;
+    /** The value may be `null`. Informational: `isNull`/`exists` arrive via `operators`. */
+    readonly nullable?: boolean;
+    /**
+     * The field's observed value set, baked in by codegen for low-cardinality string fields (an
+     * "enum-like" field: MTG colours, a rarity, a status). Narrows the *equality-shaped* operators so
+     * they autocomplete; absent → those operators accept any `string`.
+     */
+    readonly values?: readonly string[];
+}
+export interface CollectionMeta {
+    /** Present ⟺ a user PK was declared → `get(id)` is emitted. */
+    readonly pk?: string;
+    readonly fields: {
+        readonly [field: string]: FieldMeta;
+    };
+}
+export interface SchemaMeta {
+    readonly [collection: string]: CollectionMeta;
+}
+/**
+ * `V` is the field's value union when codegen baked one in (else `string`). Only the
+ * equality-shaped operators narrow to it: `startsWith`/`contains`/`endsWith` match a *fragment* of
+ * a value, and a fragment of an enum member is not itself an enum member — narrowing those would
+ * reject `contains: "art"` against a value of `"artifact"`.
+ */
+type AllStringOps<V extends string = string> = {
+    equals: V;
+    not: V;
+    in: V[];
+    startsWith: string;
+    contains: string;
+    endsWith: string;
+    gt: string;
+    gte: string;
+    lt: string;
+    lte: string;
+};
+type AllNumberOps = {
+    equals: number;
+    not: number;
+    in: number[];
+    gt: number;
+    gte: number;
+    lt: number;
+    lte: number;
+};
+type AllDateOps = {
+    equals: string;
+    not: string;
+    in: string[];
+    gt: string;
+    gte: string;
+    lt: string;
+    lte: string;
+};
+type AllBoolOps = {
+    equals: boolean;
+    not: boolean;
+};
+type PickOps<All, Ops extends string> = {
+    [K in Extract<keyof All, Ops>]?: All[K];
+};
+/** The missing-value operators, offered per field through its `operators` like any other. */
+type MissingValueOps = {
+    isNull: true;
+    isAbsent: true;
+    exists: boolean;
+};
+/**
+ * A field's baked value union, or `string` when codegen didn't bake one (high-cardinality field, or
+ * a schema typed loosely as `SchemaMeta` rather than an `as const` literal — which degrades to the
+ * previous wide behavior rather than breaking).
+ */
+type ValuesOf<F extends FieldMeta> = F extends {
+    values: readonly (infer V extends string)[];
+} ? V : string;
+/** `{ some: value }` ≡ `{ some: { equals: value } }` (ADR-0001) — only offered where `equals` is itself enabled. */
+type SomeShorthand<F extends FieldMeta> = "equals" extends F["operators"][number] ? ValuesOf<F> : never;
+/** What `some` and `every` apply to each element: the field's own operators, or the equals shorthand. */
+type ElementFilter<F extends FieldMeta> = PickOps<AllStringOps<ValuesOf<F>>, F["operators"][number]> | SomeShorthand<F>;
+/** A multi-valued field's list operators (T7 `some`, ADR-0010 the rest). Keys on one field AND together. */
+type ListOps<F extends FieldMeta> = {
+    some?: ElementFilter<F>;
+    every?: ElementFilter<F>;
+    hasEvery?: ValuesOf<F>[];
+    isEmpty?: true;
+};
+type FilterFor<F extends FieldMeta> = F extends {
+    kind: "string";
+    multi: true;
+} ? ListOps<F> : F extends {
+    kind: "string";
+} ? PickOps<AllStringOps<ValuesOf<F>> & MissingValueOps, F["operators"][number]> : F extends {
+    kind: "number";
+} ? PickOps<AllNumberOps & MissingValueOps, F["operators"][number]> : F extends {
+    kind: "date";
+} ? PickOps<AllDateOps & MissingValueOps, F["operators"][number]> : F extends {
+    kind: "boolean";
+} ? PickOps<AllBoolOps & MissingValueOps, F["operators"][number]> : F extends {
+    kind: "json";
+} ? PickOps<MissingValueOps, F["operators"][number]> : never;
+/** The where type: every queryable field, each with ONLY its valid operators. */
+export type WhereOf<C extends CollectionMeta> = {
+    [K in keyof C["fields"]]?: FilterFor<C["fields"][K]>;
+};
+/**
+ * orderBy over every queryable field — sorting happens in memory, so an index doesn't matter
+ * (ADR-0013). Not `json` fields: an object has no order.
+ */
+export type OrderByOf<C extends CollectionMeta> = {
+    [K in keyof C["fields"] as C["fields"][K]["kind"] extends "json" ? never : K]?: "asc" | "desc";
+};
+type ValidateFilter<F, Allowed> = {
+    [Op in keyof F]: Op extends keyof Allowed ? Allowed[Op] : never;
+};
+export type ValidateWhere<W, C extends CollectionMeta> = {
+    [K in keyof W]: K extends keyof C["fields"] ? ValidateFilter<NonNullable<W[K]>, FilterFor<C["fields"][K]>> : never;
+};
+type RiderOp = "not" | "isNull" | "isAbsent" | "exists";
+type PruningOp<F extends FieldMeta> = F extends {
+    pruning: infer P extends readonly string[];
+} ? P[number] : Exclude<F["operators"][number], RiderOp>;
+/** A list field's `some`/`every` prune through their element filter; `hasEvery` and `isEmpty` do by name (their values are checked at runtime, by `wherePrunes`). */
+type ElementPrunes<E, F extends FieldMeta> = E extends object ? Extract<keyof E, PruningOp<F>> extends never ? false : true : "equals" extends PruningOp<F> ? true : false;
+type ListFilterPrunes<Filter, F extends FieldMeta> = Extract<keyof Filter, "hasEvery" | "isEmpty"> extends never ? true extends (Filter extends {
+    some: infer E;
+} ? ElementPrunes<E, F> : false) | (Filter extends {
+    every: infer E;
+} ? ElementPrunes<E, F> : false) ? true : false : true;
+type FilterPrunes<Filter, F extends FieldMeta> = Filter extends object ? F extends {
+    multi: true;
+} ? ListFilterPrunes<Filter, F> : Extract<keyof Filter, PruningOp<F>> extends never ? false : true : false;
+type AnyPrunes<W, C extends CollectionMeta> = true extends {
+    [K in keyof W]: K extends keyof C["fields"] ? FilterPrunes<NonNullable<W[K]>, C["fields"][K]> : false;
+}[keyof W] ? true : false;
+export type RiderGuard<W, C extends CollectionMeta> = [keyof W] extends [never] ? {} : AnyPrunes<W, C> extends true ? {} : {
+    "❌ every filter here is a rider — add one on the sort field or an indexed field, so the query doesn't read every block": never;
+};
+/**
+ * `where` with every `undefined` left out: a filter set to `undefined`, an operator whose value is
+ * `undefined`, and a filter (or a list field's element filter) left empty by that. `undefined` means
+ * "no filter here", so `{ set: chosen ? { equals: chosen } : undefined }` and `{ year: { gte: from } }`
+ * with no `from` both drop out, the way they read. `findMany`, `count` and `wherePrunes` all see the
+ * compacted form, so the rider check and the query agree on what the `where` says.
+ */
+export declare function compactWhere(where: Record<string, Record<string, unknown> | undefined> | undefined): Record<string, Record<string, unknown>> | undefined;
+/** The fields a pruning check reads: each field's operators and, when codegen emitted it, its `pruning` list. */
+type PruningSchema = {
+    fields: Record<string, {
+        operators: readonly string[];
+        pruning?: readonly string[];
+        multi?: true | boolean;
+    }>;
+};
+/**
+ * Whether `where` has at least one filter that narrows which blocks are read, which is the rule
+ * `findMany` enforces with `NEEDS_PRUNING` (ADR-0013). For a `where` built from UI input: check it,
+ * and fall back (add a sort-field range, say) instead of catching the error. Pass the collection's
+ * `getSchema()`. An empty or missing `where` counts as pruning, since it is allowed.
+ *
+ * The rules the types can't see, because they depend on the value: `contains` prunes only with 3 or
+ * more characters (a shorter needle has no trigram to look up), and an empty `startsWith`/`endsWith`,
+ * an empty `hasEvery` and `isEmpty: false` match every block. Each of these rides.
+ */
+export declare function wherePrunes(where: Record<string, Record<string, unknown> | undefined> | undefined, schema: PruningSchema): boolean;
+/**
+ * The rider rule at runtime (ADR-0013), for untyped JS callers and `where` objects built dynamically
+ * (e.g. from UI input) that the compiler never sees. Throws `NEEDS_PRUNING` naming the fields that
+ * could prune on this dataset. `wherePrunes` is the non-throwing check.
+ */
+export declare function assertWhereHasPruning(where: Record<string, Record<string, unknown>> | undefined, schema: PruningSchema & {
+    sortField: string;
+}): void;
+type PkField<C extends CollectionMeta> = C extends {
+    pk: infer P extends string;
+} ? P : never;
+type KindValueType<K extends FieldKind> = K extends "number" ? number : K extends "boolean" ? boolean : string;
+type PkIdOf<C extends CollectionMeta> = PkField<C> extends keyof C["fields"] ? KindValueType<C["fields"][PkField<C>]["kind"]> : never;
+type GetMember<C extends CollectionMeta, Rec> = PkField<C> extends never ? {} : {
+    get(id: PkIdOf<C>, opts?: QueryOptions): Promise<Rec | null>;
+};
+/**
+ * Per-query options every collection method accepts. `signal` cancels the query: its pending block,
+ * index and sidecar fetches are aborted and the call rejects with `ZonemapDbError` code `ABORTED`.
+ * The manifest fetch, shared by every query on the client, is never cancelled: an aborted query only
+ * stops waiting for it. For search-as-you-type, abort the previous keystroke's query before starting
+ * the next.
+ */
+export interface QueryOptions {
+    signal?: AbortSignal;
+}
+export interface FindManyArgs<C extends CollectionMeta, W extends WhereOf<C>> extends QueryOptions {
+    where?: W & ValidateWhere<W, C> & RiderGuard<W, C>;
+    orderBy?: OrderByOf<C>;
+    limit?: number;
+    offset?: number;
+    scan?: never;
+}
+/**
+ * A `findMany` that may filter on riders alone, by walking the data files in sort order until the
+ * page is full. Needs a `limit`, and no `orderBy` other than the sort field (checked at runtime, which
+ * is where the sort field is known), because that is what lets the walk stop early.
+ *
+ * Opt-in because the cost depends on the data: a rider most records match fills the page from the
+ * first file or two, and one few records match can read most of the dataset before it does. Use it
+ * for a browse-style search where either outcome is acceptable, not as a way around NEEDS_PRUNING.
+ */
+export interface BlockOrderScanArgs<C extends CollectionMeta, W extends WhereOf<C>> extends QueryOptions {
+    where?: W & ValidateWhere<W, C>;
+    scan: "block-order";
+    orderBy?: OrderByOf<C>;
+    limit: number;
+    offset?: number;
+}
+export interface FindManyResult<Rec> {
+    records: Rec[];
+    hasMore: boolean;
+    /**
+     * The EXACT number of records matching `where`, present only when answering the query already
+     * required seeing all of them (refines ADR-0008 §5). Free when it appears — the engine had the
+     * match set in hand and would otherwise have discarded its size.
+     *
+     * Present when every candidate block was read: any `orderBy` on a non-sort field (ordering can't be
+     * decided without them), no `limit`, or a block walk that ran out of candidates before it filled the
+     * page. Absent when the walk stopped early, which is exactly when the engine has NOT seen the tail.
+     *
+     * Prefer this over `count()` whenever it is present: `count()` is a zero-fetch upper bound that can
+     * be an order of magnitude high, while this is the truth. It is not `offset + records.length` — on a
+     * page past the end that formula returns the offset, not the total.
+     */
+    total?: number;
+}
+/**
+ * Approximate upper bound for pagination totals (ADR-0008 §2/§3): `exact: true`
+ * only for an empty where (→ recordCount) and pruned-to-zero (→ 0), so
+ * `count === 0` is always a trustworthy existence check.
+ */
+export interface CountResult {
+    count: number;
+    exact: boolean;
+}
+/**
+ * Reserved for the deferred v2 exact mode — 1.0 locks the slot to `false`, so
+ * passing `exact: true` is a compile-time error (ADR-0008 §4).
+ */
+export interface CountOptions extends QueryOptions {
+    exact?: false;
+}
+interface CollectionBase<C extends CollectionMeta, Rec> {
+    findMany<W extends WhereOf<C>>(args?: FindManyArgs<C, W>): Promise<FindManyResult<Rec>>;
+    findMany<W extends WhereOf<C>>(args: BlockOrderScanArgs<C, W>): Promise<FindManyResult<Rec>>;
+    count<W extends WhereOf<C>>(where?: W & ValidateWhere<W, C>, opts?: CountOptions): Promise<CountResult>;
+    getSchema(): C;
+}
+export type Collection<C extends CollectionMeta, Rec> = CollectionBase<C, Rec> & GetMember<C, Rec>;
+export interface ClientOptions {
+    basePath: string;
+    /**
+     * Injectable for non-browser / testing; defaults to global `fetch`. The manifest request passes
+     * `cache: "no-cache"` (and `"reload"` when recovering from a stale one, #32) in its `init`; a
+     * wrapper should forward `init` so the browser sees it.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Client-level result ceiling (default 10_000), a guardrail distinct from
+     * per-query `limit` — fail-loud (ADR-0004/0007): an explicit `limit` above
+     * it throws `LIMIT_EXCEEDED`, and an unbounded query that would match more
+     * than it throws rather than silently truncating.
+     */
+    maxResults?: number;
+    /**
+     * Set by codegen when the build pre-compressed the manifest. Only the manifest needs telling:
+     * everything else it points at carries `.gz`/`.br` in its own path. Hand-written callers of
+     * `createClient` must match their deploy; the generated `connect()` already does.
+     */
+    manifestCompression?: Compression;
+    /** @deprecated Use `manifestCompression: "gzip"`. */
+    manifestGzip?: boolean;
+}
+export type GenericClient<S extends SchemaMeta, Records> = {
+    [K in keyof S]: K extends keyof Records ? Collection<S[K], Records[K]> : never;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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