zonemapdb 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Elgaard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# zonemapdb
+
+Query large datasets from any static host: no backend, no WASM, no HTTP Range requests.
+
+This is the **runtime** package: a zero-third-party-dependency, ESM-only browser client that fetches a manifest and the handful of small block/index files a query actually needs, and returns fully-typed records. It has no `bin` and does no building — pair it with [`zonemapdb-cli`](https://www.npmjs.com/package/zonemapdb-cli) (a devDependency) to partition your data and generate the typed client this package powers.
+
+See the [project README](https://github.com/shivan2418/blockdb#readme) for the full pitch, design, and alternatives comparison.
+
+## Quickstart
+
+```bash
+pnpm add zonemapdb && pnpm add -D zonemapdb-cli
+npx zonemapdb init data/movies.ndjson   # a guided wizard reads your data, recommends
+                                      #   what to index, and writes zonemapdb.config.json
+npx zonemapdb build                     # → public/zonemapdb/ (deploy this) + src/zonemapdb/ (commit this)
+```
+
+```ts
+import { connect } from "./zonemapdb/client";
+
+const db = connect();
+const { records, hasMore } = await db.movies.findMany({
+  where: { year: { gte: 2000 }, rating: { gt: 8 } },
+  orderBy: { rating: "desc" },
+  limit: 20,
+});
+```
+
+`db.<collection>` is a real, named member with go-to-definition and intellisense on both the field and its available operators — the type system offers exactly the operators each field's type allows, and rejects a query none of whose filters can narrow which files are read (see [Riders](https://github.com/shivan2418/blockdb/blob/master/docs/query-guide.md#riders-filters-that-dont-narrow-the-read)). See [`examples/`](https://github.com/shivan2418/blockdb/tree/master/examples) in the repo for two complete, working example apps (movie catalog, product lookup) that build → deploy → query in a real browser.
+
+## Querying
+
+The full reference, with every operator, sorting, pagination, counting, errors and what each query costs, is the **[query guide](https://github.com/shivan2418/blockdb/blob/master/docs/query-guide.md)**. Two things worth knowing up front:
+
+### List fields
+
+A multi-valued field (`"multi": true`) takes list operators instead of scalar ones:
+
+```ts
+await db.books.findMany({ where: { tags: { some: "poetry" } } });                       // any tag is poetry
+await db.books.findMany({ where: { tags: { hasEvery: ["poetry", "travel"] } } });       // has both
+await db.books.findMany({ where: { tags: { every: { in: ["poetry", "travel"] } } } });  // no other tags; [] passes
+await db.books.findMany({ where: { tags: { isEmpty: true } } });                        // []
+// Operators on one field AND together, so exactly [poetry, travel] is:
+await db.books.findMany({ where: { tags: { hasEvery: ["poetry", "travel"], every: { in: ["poetry", "travel"] } } } });
+```
+
+A record whose list is missing or `null` matches none of them, including `isEmpty`.
+
+### Case-insensitive search: fold at build time
+
+Every string operator compares **exactly**, against an index built from the stored values, so on Title Case data `contains: "atlas"` finds nothing. Folding only the query can't fix that. Instead, add a **derived field** that the build computes with the `fold` normalizer (lowercase, accents stripped):
+
+```json
+"title_fold": { "kind": "string", "indexed": true, "contains": true, "derive": { "from": "title", "using": "fold" } }
+```
+
+Then fold the query the same way with the exported `normalize`, which is the same function the build uses:
+
+```ts
+import { normalize } from "zonemapdb";
+
+const q = normalize("fold", input) ?? "";
+await db.books.findMany({ where: { title_fold: { contains: q } } }); // "cafe" finds "Café Atlas"
+```
+
+`title` itself is untouched, so you still display it, sort by it and match it exactly. The other normalizers are `lowercase`, `trim` and `numeric`.
+
+## License
+
+MIT

package/dist/block-fetch.d.ts

@@ -0,0 +1,11 @@
+import { type Compression } from "./types.js";
+/**
+ * The served path of a block file, given the TOTAL block count (`manifest.blocks.length`) and
+ * whether the deploy gzips block payloads (`manifest.dataset.gzip`). Exported (rather than kept
+ * module-private) solely so the CLI's own test suite can assert this stays byte-for-byte
+ * identical to `block.ts`'s build-side `blockRelPath` — the two are independent implementations
+ * with no shared module, so an equivalence test is the only thing that catches drift between them.
+ */
+export declare function blockRelPath(hash: string, blockCount: number, compression: Compression): string;
+export declare function fetchBlockRecords(basePath: string, hash: string, blockCount: number, compression: Compression, fetchImpl: typeof fetch, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+//# sourceMappingURL=block-fetch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"block-fetch.d.ts","sourceRoot":"","sources":["../src/block-fetch.ts"],"names":[],"mappings":"AACA,OAAO,EAA0C,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAMtF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,MAAM,CAG/F;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,OAAO,KAAK,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAcpC"}

package/dist/block-fetch.js

@@ -0,0 +1,29 @@
+import { fetchCompressedText, fetchText, parseCorruptible } from "./fetch-file.js";
+import { compressionSuffix, decompressionFormat } from "./types.js";
+/** Past this many blocks, files nest under a 2-hex-char prefix subdir (ADR-0002 §8) — must match `blockRelPath` in the CLI's `block.ts` exactly, since no manifest field records which layout a deploy used. */
+const HASH_PREFIX_THRESHOLD = 1000;
+const HASH_PREFIX_LEN = 2;
+/**
+ * The served path of a block file, given the TOTAL block count (`manifest.blocks.length`) and
+ * whether the deploy gzips block payloads (`manifest.dataset.gzip`). Exported (rather than kept
+ * module-private) solely so the CLI's own test suite can assert this stays byte-for-byte
+ * identical to `block.ts`'s build-side `blockRelPath` — the two are independent implementations
+ * with no shared module, so an equivalence test is the only thing that catches drift between them.
+ */
+export function blockRelPath(hash, blockCount, compression) {
+    const filename = `${hash}.ndjson${compressionSuffix(compression)}`;
+    return blockCount > HASH_PREFIX_THRESHOLD ? `blocks/${hash.slice(0, HASH_PREFIX_LEN)}/${filename}` : `blocks/${filename}`;
+}
+export async function fetchBlockRecords(basePath, hash, blockCount, compression, fetchImpl, signal) {
+    const url = `${basePath}/${blockRelPath(hash, blockCount, compression)}`;
+    const format = decompressionFormat(compression);
+    const text = format === undefined
+        ? await fetchText(url, "referenced", fetchImpl, signal)
+        : await fetchCompressedText(url, "referenced", format, fetchImpl, signal);
+    return parseCorruptible(url, () => text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line)));
+}
+//# sourceMappingURL=block-fetch.js.map

package/dist/block-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-fetch.js","sourceRoot":"","sources":["../src/block-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAoB,MAAM,YAAY,CAAC;AAEtF,gNAAgN;AAChN,MAAM,qBAAqB,GAAG,IAAI,CAAC;AACnC,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,UAAkB,EAAE,WAAwB;IACrF,MAAM,QAAQ,GAAG,GAAG,IAAI,UAAU,iBAAiB,CAAC,WAAW,CAAC,EAAE,CAAC;IACnE,OAAO,UAAU,GAAG,qBAAqB,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,QAAQ,EAAE,CAAC;AAC5H,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,IAAY,EACZ,UAAkB,EAClB,WAAwB,EACxB,SAAuB,EACvB,MAAoB;IAEpB,MAAM,GAAG,GAAG,GAAG,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC;IACzE,MAAM,MAAM,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,IAAI,GACR,MAAM,KAAK,SAAS;QAClB,CAAC,CAAC,MAAM,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC;QACvD,CAAC,CAAC,MAAM,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAC9E,OAAO,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,CAChC,IAAI;SACD,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACjC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC,CAC9D,CAAC;AACJ,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+import { type ClientOptions, type GenericClient, type SchemaMeta } from "./types.js";
+export declare function createClient<S extends SchemaMeta, Records>(schema: S, opts: ClientOptions): GenericClient<S, Records>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,aAAa,EAIlB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAqkBpB,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EACxD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,aAAa,GAClB,aAAa,CAAC,CAAC,EAAE,OAAO,CAAC,CAyH3B"}