zonemapdb 0.8.0

package/dist/types.js

@@ -0,0 +1,164 @@
+import { ZonemapDbError } from "./errors.js";
+/** 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 function compressionSuffix(compression) {
+    return compression === "gzip" ? ".gz" : compression === "brotli" ? ".br" : "";
+}
+/** The `DecompressionStream` format name for a compression, or `undefined` when nothing was applied. */
+export function decompressionFormat(compression) {
+    return compression === "none" ? undefined : compression;
+}
+const RUNTIME_RIDER_OPS = new Set(["not", "isNull", "isAbsent", "exists"]);
+/** The operators of `field` that prune — from the manifest, or the pre-ADR-0013 rule for a hand-written schema. */
+function pruningOpsOf(field) {
+    return field.pruning ?? field.operators.filter((op) => !RUNTIME_RIDER_OPS.has(op));
+}
+/** Whether one element filter of `some`/`every` can use the field's index. */
+function elementPrunes(elementFilter, pruning) {
+    if (typeof elementFilter !== "object" || elementFilter === null)
+        return pruning.includes("equals");
+    return Object.keys(elementFilter).some((op) => filterOpPrunes(op, elementFilter[op], pruning));
+}
+/**
+ * Whether one operator, with this value, narrows which blocks are read. A pruning operator can still
+ * match everything: `contains` routes on the trigrams of its argument, so one shorter than three
+ * characters has none, and an empty `startsWith`/`endsWith` is a prefix of every value.
+ */
+function filterOpPrunes(op, value, pruning) {
+    if (value === undefined || !pruning.includes(op))
+        return false;
+    if (op === "contains")
+        return typeof value === "string" && value.length >= 3;
+    if (op === "startsWith" || op === "endsWith")
+        return typeof value === "string" && value.length > 0;
+    return true;
+}
+/** A list field's `hasEvery`/`isEmpty`: an empty `hasEvery` and `isEmpty: false` match every block. */
+function listOpPrunes(op, value) {
+    if (op === "hasEvery")
+        return Array.isArray(value) && value.length > 0;
+    if (op === "isEmpty")
+        return value === true;
+    return false;
+}
+/**
+ * `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 function compactWhere(where) {
+    if (where === undefined)
+        return undefined;
+    const compactFilter = (filter, nested) => {
+        const out = {};
+        for (const [op, value] of Object.entries(filter)) {
+            if (value === undefined)
+                continue;
+            if (!nested && (op === "some" || op === "every") && isPlainObject(value)) {
+                const element = compactFilter(value, true);
+                if (element !== undefined)
+                    out[op] = element;
+                continue;
+            }
+            out[op] = value;
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
+    };
+    const out = {};
+    for (const [field, filter] of Object.entries(where)) {
+        if (filter === undefined)
+            continue;
+        const compacted = isPlainObject(filter) ? compactFilter(filter, false) : filter;
+        if (compacted !== undefined)
+            out[field] = compacted;
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+/**
+ * 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 function wherePrunes(where, schema) {
+    const entries = Object.entries(compactWhere(where) ?? {});
+    if (entries.length === 0)
+        return true;
+    return entries.some(([field, filter]) => {
+        const meta = schema.fields[field];
+        if (!meta)
+            return false;
+        const pruning = pruningOpsOf(meta);
+        return Object.entries(filter ?? {}).some(([op, value]) => {
+            if (meta.multi) {
+                if (op === "hasEvery" || op === "isEmpty")
+                    return listOpPrunes(op, value);
+                if (op === "some" || op === "every")
+                    return elementPrunes(value, pruning);
+                return false;
+            }
+            return filterOpPrunes(op, value, pruning);
+        });
+    });
+}
+/**
+ * Why a pruning operator in `where` (or in a list field's element filter) still rides, given its value:
+ * the notes NEEDS_PRUNING appends. The operator names are right in these cases, so without the note
+ * the error would look wrong.
+ */
+function valueRiderNotes(where) {
+    let shortContains = false;
+    let matchesAll = false;
+    const visit = (filter) => {
+        if (typeof filter !== "object" || filter === null)
+            return;
+        for (const [op, value] of Object.entries(filter)) {
+            if (op === "contains" && typeof value === "string" && value.length < 3)
+                shortContains = true;
+            if ((op === "startsWith" || op === "endsWith") && value === "")
+                matchesAll = true;
+            if ((op === "hasEvery" && Array.isArray(value) && value.length === 0) || (op === "isEmpty" && value === false))
+                matchesAll = true;
+            if (op === "some" || op === "every")
+                visit(value);
+        }
+    };
+    Object.values(where).forEach(visit);
+    const notes = [];
+    if (shortContains)
+        notes.push(" A `contains` needs at least 3 characters to use its trigram index; a shorter one is a rider.");
+    if (matchesAll)
+        notes.push(" An empty `startsWith` or `endsWith`, an empty `hasEvery` and `isEmpty: false` match every block, so they are riders too.");
+    return notes;
+}
+/**
+ * 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 function assertWhereHasPruning(where, schema) {
+    if (wherePrunes(where, schema))
+        return;
+    const prunable = Object.entries(schema.fields)
+        .filter(([name, meta]) => name !== schema.sortField && pruningOpsOf(meta).length > 0)
+        .map(([name]) => name);
+    throw new ZonemapDbError({
+        code: "NEEDS_PRUNING",
+        message: `zonemapdb: every filter in this where is a rider (it tests fetched records but can't narrow which blocks are read), ` +
+            `so the query would read the whole dataset. Add a filter on the sort field "${schema.sortField}"` +
+            (prunable.length > 0 ? ` or on an indexed field (${prunable.join(", ")})` : "") +
+            `.` +
+            valueRiderNotes(compactWhere(where) ?? {}).join("") +
+            ` Check with wherePrunes() before querying. For a browse-style search that is rider-only on purpose, pass ` +
+            `scan: "block-order" with a limit, which reads files in sort order until the page is full. See "Riders" in docs/query-guide.md.`,
+    });
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The on-disk/runtime compatibility contract (ADR-0005): `formatVersion` = the
+ * package major. One number governs both data-format and code-contract
+ * compatibility — a manifest whose major differs from this runtime's is
+ * rejected with `FORMAT_VERSION` when the manifest loads. Keep in sync with
+ * package.json's major (a test asserts exactly that).
+ */
+export declare const FORMAT_VERSION = 0;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC"}

package/dist/version.js

@@ -0,0 +1,9 @@
+/**
+ * The on-disk/runtime compatibility contract (ADR-0005): `formatVersion` = the
+ * package major. One number governs both data-format and code-contract
+ * compatibility — a manifest whose major differs from this runtime's is
+ * rejected with `FORMAT_VERSION` when the manifest loads. Keep in sync with
+ * package.json's major (a test asserts exactly that).
+ */
+export const FORMAT_VERSION = 0;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC"}

package/dist/zonemap-fetch.d.ts

@@ -0,0 +1,9 @@
+import type { PairZonemapEntry } from "./manifest.js";
+/**
+ * Lazily fetches a secondary field's zonemap sidecar (ADR-0003 §3) — only reached once a query
+ * actually needs that field's zonemap and finds a `{ sidecar }` reference in root instead of
+ * inline pairs. A missing sidecar 404s as DEPLOY_INTEGRITY, same as any other manifest-referenced
+ * file (`fetch-file.ts`'s shared "referenced" mapping) — the deploy is incomplete, not the caller's fault.
+ */
+export declare function fetchZonemapSidecar(basePath: string, file: string, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<PairZonemapEntry>;
+//# sourceMappingURL=zonemap-fetch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"zonemap-fetch.d.ts","sourceRoot":"","sources":["../src/zonemap-fetch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAE3B"}

package/dist/zonemap-fetch.js

@@ -0,0 +1,11 @@
+import { fetchReferencedJson } from "./fetch-file.js";
+/**
+ * Lazily fetches a secondary field's zonemap sidecar (ADR-0003 §3) — only reached once a query
+ * actually needs that field's zonemap and finds a `{ sidecar }` reference in root instead of
+ * inline pairs. A missing sidecar 404s as DEPLOY_INTEGRITY, same as any other manifest-referenced
+ * file (`fetch-file.ts`'s shared "referenced" mapping) — the deploy is incomplete, not the caller's fault.
+ */
+export async function fetchZonemapSidecar(basePath, file, fetchImpl, signal) {
+    return (await fetchReferencedJson(`${basePath}/${file}`, fetchImpl, signal));
+}
+//# sourceMappingURL=zonemap-fetch.js.map

package/dist/zonemap-fetch.js.map

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

package/dist/zonemap.d.ts

@@ -0,0 +1,35 @@
+export type SortValue = number | string;
+export interface SortFieldFilter {
+    equals?: SortValue;
+    in?: SortValue[];
+    gt?: SortValue;
+    gte?: SortValue;
+    lt?: SortValue;
+    lte?: SortValue;
+    /** String sort fields only: a prefix is a contiguous range once values are sorted (ADR-0003 §7). */
+    startsWith?: string;
+}
+/** Block ordinals (into `manifest.blocks`) that could satisfy `filter` on the sort field. */
+export declare function candidateBlockIndices(splitPoints: readonly SortValue[], filter: SortFieldFilter | undefined): number[];
+/**
+ * A secondary field's constraint, in the shapes a per-block [min,max] pair can prune (ADR-0003 §6
+ * step 1): point lookups (`equals`/`in`) and ranges (`gt`/`gte`/`lt`/`lte`).
+ */
+export interface PairRangeFilter {
+    equals?: unknown;
+    in?: unknown[];
+    gt?: unknown;
+    gte?: unknown;
+    lt?: unknown;
+    lte?: unknown;
+}
+/**
+ * Block ordinals whose per-block `[min,max]` pair could contain any of `filter`'s values — the
+ * secondary-field counterpart of `candidateBlockIndices` (ADR-0003 §6 step 1: "apply all free
+ * zonemap pruning first"). String bounds are truncated but never past the true value (ADR-0003
+ * §2), so this can only ever OVER-approximate — it never excludes a real match. `undefined` means
+ * the filter shape (e.g. `startsWith`) isn't one a min/max pair can prune; the caller should treat
+ * that as "no zonemap signal" rather than as an empty set.
+ */
+export declare function pairCandidateBlockIndices(pairs: readonly (readonly [unknown, unknown])[], filter: PairRangeFilter): Set<number> | undefined;
+//# sourceMappingURL=zonemap.d.ts.map

package/dist/zonemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zonemap.d.ts","sourceRoot":"","sources":["../src/zonemap.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC;IACjB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,oGAAoG;IACpG,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqDD,6FAA6F;AAC7F,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,SAAS,EAAE,EACjC,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,MAAM,EAAE,CAiCV;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AA+BD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,EAAE,EAC/C,MAAM,EAAE,eAAe,GACtB,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAezB"}

package/dist/zonemap.js

@@ -0,0 +1,139 @@
+// Zonemap pruning over the sort field's split-points (ADR-0002/0003): the
+// split-points ARE the search structure — binary search finds the blocks that
+// could possibly satisfy a where-filter on the sort field, so only those need
+// to be fetched.
+/** Higher than any realistic code point in a stored value, so `[p, p + this]` brackets every string starting with `p`. */
+const PREFIX_UPPER_SENTINEL = "\u{10FFFF}";
+function pointBlockIndex(splitPoints, value, blockCount) {
+    let lo = 0;
+    let hi = blockCount - 1;
+    let ans = 0;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (splitPoints[mid] <= value) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans;
+}
+function upperBoundBlockIndex(splitPoints, value, blockCount, strict) {
+    let lo = 0;
+    let hi = blockCount - 1;
+    let ans = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const boundOk = strict ? splitPoints[mid] < value : splitPoints[mid] <= value;
+        if (boundOk) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans;
+}
+function isWithinGlobalRange(splitPoints, value) {
+    return value >= splitPoints[0] && value <= splitPoints[splitPoints.length - 1];
+}
+function range(start, end) {
+    const out = [];
+    for (let i = start; i <= end; i++)
+        out.push(i);
+    return out;
+}
+/** Block ordinals (into `manifest.blocks`) that could satisfy `filter` on the sort field. */
+export function candidateBlockIndices(splitPoints, filter) {
+    const blockCount = splitPoints.length - 1;
+    if (blockCount <= 0)
+        return [];
+    if (!filter || Object.keys(filter).length === 0)
+        return range(0, blockCount - 1);
+    if (filter.in !== undefined) {
+        const indices = new Set();
+        for (const value of filter.in) {
+            if (isWithinGlobalRange(splitPoints, value))
+                indices.add(pointBlockIndex(splitPoints, value, blockCount));
+        }
+        return [...indices].sort((a, b) => a - b);
+    }
+    if (filter.equals !== undefined) {
+        if (!isWithinGlobalRange(splitPoints, filter.equals))
+            return [];
+        return [pointBlockIndex(splitPoints, filter.equals, blockCount)];
+    }
+    // `startsWith(p)` IS the closed range [p, p+sentinel] on a sorted string field — free pruning off
+    // the split-points already in the manifest, no index chunk to fetch. Composes with an explicit
+    // range by intersecting: both bounds narrow the same span.
+    const lower = filter.startsWith !== undefined ? filter.startsWith : (filter.gte ?? filter.gt);
+    const upper = filter.startsWith !== undefined ? filter.startsWith + PREFIX_UPPER_SENTINEL : (filter.lte ?? filter.lt);
+    const strictUpper = filter.startsWith === undefined && filter.lt !== undefined;
+    const startIdx = lower !== undefined ? pointBlockIndex(splitPoints, lower, blockCount) : 0;
+    const endIdx = upper !== undefined ? upperBoundBlockIndex(splitPoints, upper, blockCount, strictUpper) : blockCount - 1;
+    if (endIdx < startIdx)
+        return [];
+    return range(startIdx, endIdx);
+}
+function withinPair(pair, value) {
+    const [min, max] = pair;
+    // A block with zero non-null values for this field has no bound to compare against (ADR-0002 §5/T7).
+    if (min === undefined || max === undefined)
+        return false;
+    return min <= value && value <= max;
+}
+function hasRangeBound(filter) {
+    return filter.gt !== undefined || filter.gte !== undefined || filter.lt !== undefined || filter.lte !== undefined;
+}
+/**
+ * Whether a block's [min,max] overlaps the filter's range — the only question a pair can answer
+ * about a range. A block survives unless its whole span sits on one side of a bound.
+ *
+ * `gt`/`lt` differ from `gte`/`lte` only at the boundary: a block whose max is exactly the bound can
+ * satisfy `gte` but not `gt`. Since number/date pairs are exact (only string pairs are truncated —
+ * ADR-0003 §2), that distinction is sound rather than merely conservative.
+ */
+function overlapsRange(pair, filter) {
+    const [min, max] = pair;
+    if (min === undefined || max === undefined)
+        return false;
+    if (filter.gte !== undefined && max < filter.gte)
+        return false;
+    if (filter.gt !== undefined && max <= filter.gt)
+        return false;
+    if (filter.lte !== undefined && min > filter.lte)
+        return false;
+    if (filter.lt !== undefined && min >= filter.lt)
+        return false;
+    return true;
+}
+/**
+ * Block ordinals whose per-block `[min,max]` pair could contain any of `filter`'s values — the
+ * secondary-field counterpart of `candidateBlockIndices` (ADR-0003 §6 step 1: "apply all free
+ * zonemap pruning first"). String bounds are truncated but never past the true value (ADR-0003
+ * §2), so this can only ever OVER-approximate — it never excludes a real match. `undefined` means
+ * the filter shape (e.g. `startsWith`) isn't one a min/max pair can prune; the caller should treat
+ * that as "no zonemap signal" rather than as an empty set.
+ */
+export function pairCandidateBlockIndices(pairs, filter) {
+    const hasPoint = filter.equals !== undefined || filter.in !== undefined;
+    const hasRange = hasRangeBound(filter);
+    if (!hasPoint && !hasRange)
+        return undefined;
+    // Point and range constraints on one field are ANDed, matching `matchesWhere`: `{ equals: 5, gte: 10 }`
+    // is unsatisfiable and must prune to nothing, not to the union of what each shape would admit.
+    const values = filter.in ?? [filter.equals];
+    const indices = new Set();
+    pairs.forEach((pair, i) => {
+        if (hasPoint && !values.some((value) => withinPair(pair, value)))
+            return;
+        if (hasRange && !overlapsRange(pair, filter))
+            return;
+        indices.add(i);
+    });
+    return indices;
+}
+//# sourceMappingURL=zonemap.js.map

package/dist/zonemap.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "zonemapdb",
+  "version": "0.8.0",
+  "description": "Query large static datasets from any static host — partitioned into many small files, typed client, no WASM, no HTTP Range.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Emil Elgaard",
+  "keywords": [
+    "static",
+    "database",
+    "partitioning",
+    "query",
+    "large-data",
+    "browser",
+    "static-site",
+    "typescript",
+    "typed",
+    "codegen",
+    "cdn",
+    "no-backend"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shivan2418/blockdb.git",
+    "directory": "packages/zonemapdb"
+  },
+  "homepage": "https://github.com/shivan2418/blockdb#readme",
+  "bugs": "https://github.com/shivan2418/blockdb/issues",
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "zonemapdb-cli": "0.8.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "pack:check": "pnpm pack --dry-run --json"
+  }
+}