@libredb/libredb 0.0.2 → 0.0.4

package/README.md

@@ -1,314 +1,211 @@
 # LibreDB
 
-> Status: pre-alpha. The kernel (`core.ts`) and all three lenses — `lens/kv.ts` (key-value), `lens/document.ts` (JSON documents), and `lens/relational.ts` (typed tables) — are implemented and tested.
+**Multi-model without the magic. One core, three lenses, every line tested.**
+
+[![npm version](https://img.shields.io/npm/v/@libredb/libredb.svg)](https://www.npmjs.com/package/@libredb/libredb)
+[![CI](https://github.com/libredb/libredb-database/actions/workflows/ci.yml/badge.svg)](https://github.com/libredb/libredb-database/actions/workflows/ci.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=libredb_libredb-database&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=libredb_libredb-database)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=libredb_libredb-database&metric=coverage)](https://sonarcloud.io/summary/new_code?id=libredb_libredb-database)
+[![license](https://img.shields.io/npm/l/@libredb/libredb.svg)](./LICENSE)
+[![types: included](https://img.shields.io/badge/types-included-blue.svg)](https://www.typescriptlang.org/)
+[![dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@libredb/libredb)](https://bundlephobia.com/package/@libredb/libredb)
+[![status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-orange.svg)](#project-status--roadmap)
+
+LibreDB is a small, readable, embeddable, multi-model database written in TypeScript. It is built on
+one idea: a database can be powerful and still be understood by opening its source. A single ordered
+key-value core handles durability and transactions; key-value, document, and relational APIs are thin
+*lenses* over that one core — not three separate engines. It runs in-memory for tests or file-backed
+for durability, ships **zero runtime dependencies**, and proves its crash recovery with deterministic
+simulation testing. Today it is pre-alpha, aimed at test and development environments — small enough to
+learn how a database actually works, and serious enough to grow into more.
+
+## Highlights
+
+- **One small core, three lenses** — key-value, document, and relational over a single ordered
+  key-value engine (FoundationDB-style), not three engines bolted together.
+- **Multi-model** — raw strings, JSON documents, and schema-validated typed tables in the same
+  database, even the same file.
+- **Readable by design** — the kernel is under 600 lines; open the source and learn how a database
+  actually works.
+- **Embeddable, zero dependencies** — `bun add @libredb/libredb` and go; nothing else to install or
+  run.
+- **In-memory or durable** — `open()` for tests, `open({ path })` for a crash-safe, WAL-backed,
+  fsync-on-commit file.
+- **TypeScript-native** — full types shipped, ESM-only, tree-shakeable, under 4 kB min+brotli.
+- **Crash recovery you can trust** — 100% line coverage on the core, plus deterministic simulation
+  testing that tortures the write-ahead log under a simulated crashing filesystem.
+- **Nothing hidden** — queries are plain in-engine scans, errors surface, and costs are obvious (O(n)
+  scans, no secret indexes).
+
+## Quick start
 
-**LibreDB is a small, readable, embeddable database.**
-
-It is built on one idea: a database can be powerful and still remain understandable. You should be able to open its source, learn how a database actually works, and embed it into your own product in an afternoon.
-
-- A single small storage core (`core.ts`), with relational, document, and key-value as thin *lenses* on top — not three separate engines (FoundationDB-style architecture).
-- Written in TypeScript, shipped on npm.
-- Open at the edges, guarded at the durability core. Every line of the core is tested.
-
-LibreDB is the database in a three-product family that shares one spine:
-
-- **LibreDB** — the database (this repository).
-- **LibreDB Studio** — the open-source IDE for every database (Postgres, MySQL, MongoDB, Redis, and more). LibreDB is one database it supports natively, not a requirement.
-- **LibreDB Platform** — the managed, team-oriented form of data.
-
-## Usage — the key-value lens
-
-The first lens is `kv`: a durable, ordered, string-keyed map over the kernel. You `open` a kernel database and put a `kv` lens over it.
-
-```ts
-import { open, kv } from "libredb";
-
-// In-memory: the natural fit for tests and ephemeral use.
-const db = open();
-
-// Or file-backed and durable. Every write is appended to a write-ahead
-// log and fsync'd before it returns, so a committed write survives a
-// crash; reopening the same path reconstructs exactly the committed state:
-//
-//   const db = open({ path: "data.libredb" });
-
-const store = kv(db);
-
-store.set("user:1", "Ada");
-store.set("user:2", "Grace");
-
-store.get("user:1"); // "Ada"
-store.get("missing"); // undefined
-
-db.close();
-```
-
-### Writes report what they changed
-
-Every write returns a `WriteResult` (`{ changed }`), so a caller can always see what the write actually did:
-
-```ts
-store.set("user:1", "Ada Lovelace").changed; // 1 (overwrote the existing value)
-
-store.delete("user:2").changed; // 1 (it existed)
-store.delete("user:2").changed; // 0 (already gone)
-```
-
-### Ordered scans
-
-Keys are ordered by byte order, so reads come back in ascending key order. `range(start, end)` scans the half-open interval `[start, end)` — `start` included, `end` excluded:
-
-```ts
-store.set("a", "1");
-store.set("b", "2");
-store.set("c", "3");
-
-store.range("a", "c").toArray();
-// [{ key: "a", value: "1" }, { key: "b", value: "2" }] — "c" is excluded
-```
-
-`prefix(p)` scans every key beginning with `p` — the canonical ordered-KV query:
-
-```ts
-store.prefix("user:").toArray();
-// [{ key: "user:1", value: "Ada Lovelace" }]
-```
-
-A read returns a `Result`, which is **lazy and re-iterable**: nothing runs until you iterate it (or call `toArray()`), and each pass re-runs the scan against the current state. Iterate it directly or materialize it:
-
-```ts
-for (const { key, value } of store.prefix("user:")) {
-  console.log(key, value);
-}
-```
-
-### Multi-key atomicity
-
-Each `kv` operation auto-commits in its own transaction. When you need several writes to apply atomically, drop to the kernel's `transact` directly — it commits all of the body's writes together, or nothing if the body throws:
-
-```ts
-const encode = new TextEncoder();
-
-db.transact((tx) => {
-  tx.set(encode.encode("from"), encode.encode("90"));
-  tx.set(encode.encode("to"), encode.encode("110"));
-}); // both writes commit together, or neither does
-```
-
-The kernel speaks raw bytes on purpose; the `kv` lens is the string-ergonomic face over it.
-
-## Usage — the document lens
-
-The `doc` lens is the JSON face over the same kernel: a *collection* of JSON documents, each stored under a string `id`. Where `kv` stores strings, `doc` stores objects — numbers stay numbers, and nested objects and arrays survive the round-trip.
-
-```ts
-import { open, doc } from "libredb";
-
-const db = open(); // or open({ path: "data.libredb" }) for durability
-
-const users = doc(db, "users");
-
-users.put("1", { name: "Ada", age: 36, active: true });
-users.put("2", { name: "Grace", age: 45, active: false });
-
-users.get("1"); // { name: "Ada", age: 36, active: true }
-users.get("missing"); // undefined
-
-db.close();
-```
-
-Documents are scoped to their collection: `doc(db, "users")` never sees a `doc(db, "orders")` document — and the boundary is exact, so `users` and `users2` stay fully separate.
-
-### Writes report what they changed
-
-Like the kv lens, every write returns a `WriteResult` (`{ changed }`):
-
-```ts
-users.put("1", { name: "Ada Lovelace", age: 36 }).changed; // 1 (overwrote the existing document)
-
-users.delete("2").changed; // 1 (it existed)
-users.delete("2").changed; // 0 (already gone)
-```
-
-### Scanning and finding
-
-`all()` returns every document in the collection as `{ id, doc }` rows, in ascending `id` (byte) order:
-
-```ts
-const people = doc(open(), "people");
-
-people.put("1", { name: "Ada", team: "research", active: true });
-people.put("2", { name: "Grace", team: "research", active: false });
-people.put("3", { name: "Edsger", team: "ops", active: true });
-
-people.all().toArray();
-// [
-//   { id: "1", doc: { name: "Ada", team: "research", active: true } },
-//   { id: "2", doc: { name: "Grace", team: "research", active: false } },
-//   { id: "3", doc: { name: "Edsger", team: "ops", active: true } },
-// ]
+```sh
+bun add @libredb/libredb
+# or: npm install @libredb/libredb
 ```
 
-`find(predicate)` returns the documents whose top-level fields all equal the predicate's. Multiple fields are AND'd, and equality is deep and type-sensitive — `1` does not match `"1"`:
+LibreDB is ESM-only, ships zero runtime dependencies, and targets Bun (the development runtime) and
+Node 22+. The same database speaks all three lenses — here they are in one file:
 
 ```ts
-people.find({ team: "research", active: true }).toArray();
-// [{ id: "1", doc: { name: "Ada", team: "research", active: true } }]
-```
-
-`find` is an O(n) full collection scan with an in-engine predicate — there are no secondary indexes (a deliberate v1 omission, so you can read exactly what a query costs). Like every read it returns a lazy, re-iterable `Result`, so you can iterate it directly or call `toArray()`.
+import { open, kv, doc, table } from "@libredb/libredb";
 
-## Usage — the relational lens
-
-The `table` lens is the *typed* face over the same kernel: a table is a schema-validated collection of rows. Where `doc` accepts any JSON object, `table` declares its columns and their types up front and enforces them at insert. A row is stored under `<table>:<pk>`, so a table is literally a schema-validated document collection — it reuses the document codec and the same collection-isolation boundary.
-
-You declare a schema (the columns, their types, and which one is the primary key) when you open the table:
+// In-memory for tests, or open({ path: "data.libredb" }) for a durable, crash-safe file.
+const db = open();
 
-```ts
-import { open, table } from "libredb";
+// 1. Key-value: a durable, ordered, string-keyed map.
+const cache = kv(db);
+cache.set("user:1", "Ada");
+cache.get("user:1"); // "Ada"
 
-const db = open(); // or open({ path: "data.libredb" }) for durability
+// 2. Document: a collection of JSON documents under string ids.
+const logs = doc(db, "logs");
+logs.put("l1", { level: "info", message: "started", at: 1 });
+logs.find({ level: "info" }).toArray(); // [{ id: "l1", doc: { ... } }]
 
+// 3. Relational: a schema-validated, typed table with where / select / join.
 const users = table(db, "users", {
   primaryKey: "id",
-  columns: { id: "string", name: "string", age: "number", active: "boolean" },
+  columns: { id: "string", name: "string", age: "number" },
 });
-
-users.insert({ id: "1", name: "Ada", age: 36, active: true });
-users.insert({ id: "2", name: "Grace", age: 45, active: false });
-
-users.get("1"); // { id: "1", name: "Ada", age: 36, active: true }
-users.get("missing"); // undefined
+users.insert({ id: "1", name: "Ada", age: 36 });
+users.where({ name: "Ada" }).select("id", "age").toArray(); // [{ id: "1", age: 36 }]
 
 db.close();
 ```
 
-A column type is one of `"string"`, `"number"`, `"boolean"`, or `"object"` (a plain JSON object). The `primaryKey` must name a declared `"string"` column — it becomes the kernel key.
-
-### Validation is strict at insert
-
-Insert rejects a row that is missing a declared column, has a wrong-typed value, or carries a field the schema does not declare — there is no silent coercion or field-dropping:
-
-```ts
-users.insert({ id: "3", name: "Edsger" });
-// throws: missing required column "age"
-
-users.insert({ id: "3", name: "Edsger", age: "old", active: true });
-// throws: column "age" expected number, got string
-
-users.insert({ id: "3", name: "Edsger", age: 40, active: true, role: "ops" });
-// throws: unknown column "role" (not declared in the table schema)
-```
-
-### Writes report what they changed
-
-Like the other lenses, every write returns a `WriteResult` (`{ changed }`):
-
-```ts
-users.insert({ id: "1", name: "Ada Lovelace", age: 36, active: true }).changed; // 1 (overwrote)
-
-users.delete("2").changed; // 1 (it existed)
-users.delete("2").changed; // 0 (already gone)
-```
-
-### Querying — where, select, join
-
-Reads return a chainable `Query` (which is itself a lazy, re-iterable `Result`). `where(predicate)` keeps the rows whose top-level fields all equal the predicate's — deep and type-sensitive, just like document `find`, so `36` does not match `"36"`. `select(...columns)` projects each row down to the named columns. They compose in any order:
-
-```ts
-const people = table(open(), "people", {
-  primaryKey: "id",
-  columns: { id: "string", name: "string", team: "string", active: "boolean" },
-});
-
-people.insert({ id: "1", name: "Ada", team: "research", active: true });
-people.insert({ id: "2", name: "Grace", team: "research", active: false });
-people.insert({ id: "3", name: "Edsger", team: "ops", active: true });
-
-people.where({ team: "research", active: true }).select("name").toArray();
-// [{ name: "Ada" }]
-```
-
-`join(other, leftField, rightField)` is an inner equi-join via nested loop: it pairs each left row with every right row whose `rightField` equals the left row's `leftField`. The result rows carry every column of both sides, qualified as `table.column`, so the two sides never collide — and `select`/`where` name a qualified column the same way as any other:
-
-```ts
-const orders = table(db, "orders", {
-  primaryKey: "id",
-  columns: { id: "string", userId: "string", total: "number" },
-});
-
-orders.insert({ id: "o1", userId: "1", total: 42 });
-orders.insert({ id: "o2", userId: "1", total: 7 });
-
-users.join(orders, "id", "userId").select("users.name", "orders.total").toArray();
-// [
-//   { "users.name": "Ada Lovelace", "orders.total": 42 },
-//   { "users.name": "Ada Lovelace", "orders.total": 7 },
-// ]
-```
-
-`where` is O(n) in the table size and `join` is O(n*m) — nested-loop, no indexes (the same deliberate v1 omission as the document lens). Unmatched rows on either side are dropped (inner join), and a left key matching several right rows fans out to several result rows.
-
-## The catalog — what a database holds
-
-Open a LibreDB file cold and the bytes alone don't say which lens each namespace belongs to. The catalog records that as you write: a `table` registers `{ kind: "relational", schema }` when its handle is built, and a `doc` collection registers `{ kind: "document" }` on its first write. `catalog(db)` reads the whole registry — a `Map` from namespace name to its entry — so a tool can render faithful per-kind views without guessing:
+Each lens has its own guide: [key-value](./docs/guides/key-value.md) ·
+[document](./docs/guides/document.md) · [relational](./docs/guides/relational.md) ·
+[catalog](./docs/guides/catalog.md).
+
+## How it works: one core, three lenses
+
+LibreDB has a single ordered byte key-value kernel (`src/core.ts`). Key-value, document, and relational
+are thin typed *lenses* over it — three faces of the same store. A relational table is physically a
+JSON document collection, which is physically ordered key-value entries built from composite keys like
+`users:42`. The kernel reaches the disk through one injectable filesystem seam, which is also what
+makes deterministic crash testing possible.
+
+```mermaid
+flowchart TB
+    subgraph consumers [Consumers]
+        App[Your app]
+        Studio[LibreDB Studio]
+        Platform[LibreDB Platform]
+    end
+
+    API["Public API · index.ts<br/>open · kv · doc · table · catalog"]
+
+    subgraph lenses [Lenses and shared edges - open, fast to contribute]
+        KV[kv<br/>strings]
+        DOC[document<br/>JSON]
+        REL[relational<br/>typed tables]
+        CAT[catalog<br/>self-describing registry]
+    end
+
+    CORE["core.ts - THE KERNEL<br/>ordered byte KV · serializable txns · WAL · crash recovery"]
+    FS["FileSystem seam<br/>node:fs adapter - or SimFS for crash tests"]
+
+    App --> API
+    Studio --> API
+    Platform --> API
+    API --> KV
+    API --> DOC
+    API --> REL
+    API --> CAT
+    REL --> DOC
+    KV --> CORE
+    DOC --> CORE
+    REL --> CORE
+    CAT --> CORE
+    CORE --> FS
+```
+
+**The file boundary is the trust boundary.** Below the line (`core.ts`) is guarded: heavy review and
+deterministic crash tests, because a bug there corrupts data. Above the line (lenses, query, catalog)
+is open and fast to contribute to, because the worst a bug can do is present a bad *view* — it reaches
+the store only through one narrow `transact` port. For the full tour, read
+[`ARCHITECTURE.md`](./ARCHITECTURE.md).
+
+## When to use LibreDB
+
+**Reach for it when you want to:**
+
+- Back tests and local development with a real, durable, multi-model store instead of mocks.
+- Embed a small database directly in a TypeScript / Bun / Node app with zero infrastructure.
+- Learn how a database works by reading — and hacking — a small, honest codebase.
+- Prototype across key-value, document, and relational shapes without standing up three systems.
+
+**Do not use it (yet) when you need:**
+
+- A hardened production datastore at scale — it is **pre-alpha**; today's beachhead is test/dev.
+- Secondary indexes or a query planner — queries are O(n) scans by design in v1 (on the roadmap).
+- Concurrent multi-process access, replication, or a networked client/server — it is embedded and
+  in-process.
+- SQL wire compatibility or an existing-driver ecosystem.
+
+These limits are deliberate v1 scope, not hidden gaps — LibreDB's strength comes from what it refuses.
+See the [Manifesto](./MANIFESTO.md).
+
+## Reliability
+
+A transaction that returns has been written to a length-framed, CRC-32-checksummed write-ahead log and
+`fsync`'d *before* the commit becomes visible — so a committed write survives a crash, and a crash can
+only ever damage the last, un-fsync'd record (which recovery detects and truncates). This is not just
+asserted: the kernel's crash/recovery path is proven by **deterministic simulation testing**, running
+the real engine against a seeded in-memory filesystem that tears, corrupts, and crashes the log on
+command, then checking that recovery is always a valid committed prefix.
 
-```ts
-import { open, table, doc, catalog } from "libredb";
-
-const db = open();
-
-table(db, "users", { primaryKey: "id", columns: { id: "string", age: "number" } });
-doc(db, "logs").put("l1", { message: "hello" });
-
-const registry = catalog(db);
-registry.get("users");
-// { kind: "relational", schema: { primaryKey: "id", columns: { id: "string", age: "number" } } }
-registry.get("logs");
-// { kind: "document" }
-[...registry.keys()].sort();
-// ["logs", "users"]
+```sh
+bun run test    # includes a bounded 50-seed DST run
 ```
 
-The catalog lives under a reserved key prefix that sorts below all user data, so its entries never appear in a `kv`, `doc`, or `table` scan — and no user row leaks into the registry. `kv` namespaces are deliberately not cataloged: `kv` is the raw layer with full keyspace access.
+The full durability and DST walkthrough is in [`docs/RELIABILITY.md`](./docs/RELIABILITY.md).
 
-## Reliability — deterministic simulation testing
+## Documentation
 
-Durability is the trust-critical promise: a transaction that returns has been fsync'd, and a crash can only ever damage the last, un-fsync'd record. LibreDB proves this with **deterministic simulation testing (DST)** — the WAL's crash/recovery path is tortured under a seeded, in-memory simulated filesystem. The kernel reaches the disk only through an injectable FS seam (`open({ path, fs })`), so a test can run the real engine on a `SimFS` that crashes on command, tears the un-fsync'd tail at a seeded point, and injects CRC corruption or short reads.
+| Topic | Where |
+|-------|-------|
+| Lens guides (kv, document, relational, catalog) | [`docs/guides/`](./docs/guides/) |
+| Architecture — the guided tour under the hood | [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
+| Design — the locked engineering decisions | [`docs/DESIGN.md`](./docs/DESIGN.md) |
+| Reliability — durability and crash recovery | [`docs/RELIABILITY.md`](./docs/RELIABILITY.md) |
+| Manifesto — what LibreDB is and refuses to be | [`MANIFESTO.md`](./MANIFESTO.md) |
+| LibreDB Studio integration | [`docs/STUDIO.md`](./docs/STUDIO.md) |
 
-Every run is driven by one integer seed and a seeded workload of `set`/`delete`/`transact` operations. After the crash and reopen, recovery must reproduce **a valid committed prefix** of the workload — every transaction that returned successfully, and never a torn or un-committed one. An independent committed-map model (sharing no code with the engine) is the oracle the recovered state is compared against.
+## Project status & roadmap
 
-The DST suite runs as part of the normal gate:
+LibreDB is **pre-alpha** (`0.0.x`). The architecture is in place and every line of the core is tested,
+but the API may still change and it is not yet meant for production data.
 
-```sh
-bun run test            # runs a bounded 50 seeds (fast, CI-friendly)
-```
+- **Done:** the ordered key-value kernel (transactions, WAL, crash recovery); the key-value, document,
+  and relational lenses; the self-describing catalog; the deterministic simulation testing harness;
+  100% line/function/statement coverage on the core.
+- **Next:** secondary indexes and a richer query surface; more query operators; additional lenses;
+  production-hardening milestones (directory fsync on first create, WAL compaction/checkpointing).
 
-Run a longer soak by raising the seed count (and optionally the base seed):
+## The LibreDB family
 
-```sh
-LIBREDB_DST_SEEDS=5000 bun test src/sim/dst.test.ts
-LIBREDB_DST_BASE=1000000 LIBREDB_DST_SEEDS=5000 bun test src/sim/dst.test.ts
-```
+LibreDB is the database in a three-product family that shares one access-model spine:
 
-When a seed fails, the suite prints the exact replay hint — `Replay with runSeed(<seed>)`. Because everything is seed-driven, one seed reproduces the whole run byte-for-byte:
-
-```ts
-import { runSeed } from "./src/sim/dst.ts";
+- **LibreDB** — the database (this repository).
+- **LibreDB Studio** — the open-source IDE for *every* database (Postgres, MySQL, MongoDB, Redis, and
+  more). LibreDB is one database it supports natively, not a requirement.
+- **LibreDB Platform** — the managed, team-oriented form of data.
 
-const result = runSeed(42);
-result.passed;     // true — recovered state is a valid committed prefix
-result.recovered;  // Map of the recovered committed key-value state
-result.expected;   // the model oracle's committed state
-```
+## Contributing
 
-The DST harness lives in `src/sim/` and is excluded from the published package — it is test machinery, not shipped code.
+Contributions are welcome. LibreDB is open at the edges and guarded at the durability core — see
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for how to get set up, the `bun run gate` bar every change must
+pass, and where contributions land fastest. Please also read the
+[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
 
-## Read first
+## Security
 
-- [`MANIFESTO.md`](./MANIFESTO.md) — what LibreDB is and what it refuses to be.
-- [`DESIGN.md`](./DESIGN.md) — the engineering decision record behind the manifesto.
+To report a security vulnerability, see [`SECURITY.md`](./SECURITY.md) — please do not open a public
+issue.
 
 ## License
 
-Open source and free under the MIT License.
+Open source and free under the [MIT License](./LICENSE).

package/dist/core.d.ts

@@ -20,7 +20,7 @@
  * and discards any record a crash left half-written.
  */
 /** The LibreDB package version. Kept in sync with package.json. */
-export declare const version = "0.0.2";
+export declare const version = "0.0.4";
 /**
  * A key in the kernel: an immutable sequence of bytes.
  *

package/dist/core.js

@@ -19,9 +19,9 @@
  * transactions, and a write-ahead log for durability. Recovery replays that log
  * and discards any record a crash left half-written.
  */
-import { closeSync, fsyncSync, openSync, readFileSync, statSync, truncateSync, writeSync, } from "node:fs";
+import { closeSync, fsyncSync, openSync, readFileSync, statSync, truncateSync, writeSync } from "node:fs";
 /** The LibreDB package version. Kept in sync with package.json. */
-export const version = "0.0.2";
+export const version = "0.0.4";
 /**
  * Compare two keys by unsigned byte-lexicographic order: the first differing
  * byte decides, and if one key is a prefix of the other the shorter sorts

package/dist/index.d.ts

@@ -6,7 +6,9 @@
  * documents). The kernel's byte-level internals (and each lens's private codec)
  * stay unexported on purpose — the lens is the usable face. The relational lens
  * ({@link table}) completes the trio. {@link catalog} reads the registry of
- * namespaces a database holds, so a tool can render faithful per-kind views.
+ * namespaces a database holds, so a tool can render faithful per-kind views;
+ * {@link isReservedKey} (with {@link RESERVED_MARKER} / {@link CATALOG_PREFIX})
+ * lets a raw-KV tool hide engine-internal keys instead of hardcoding the layout.
  */
 export { version, open } from "./core.ts";
 export type { Database, OpenOptions } from "./core.ts";
@@ -16,6 +18,6 @@ export { doc } from "./lens/document.ts";
 export type { DocCollection, Doc, DocEntry, JsonValue } from "./lens/document.ts";
 export { table } from "./lens/relational.ts";
 export type { Table, TableSchema, Row, ColumnType, Query } from "./lens/relational.ts";
-export { catalog } from "./lens/catalog.ts";
+export { catalog, isReservedKey, CATALOG_PREFIX, RESERVED_MARKER } from "./lens/catalog.ts";
 export type { CatalogEntry, CatalogRegistry } from "./lens/catalog.ts";
 export type { Result, WriteResult } from "./lens/types.ts";

package/dist/index.js

@@ -6,10 +6,12 @@
  * documents). The kernel's byte-level internals (and each lens's private codec)
  * stay unexported on purpose — the lens is the usable face. The relational lens
  * ({@link table}) completes the trio. {@link catalog} reads the registry of
- * namespaces a database holds, so a tool can render faithful per-kind views.
+ * namespaces a database holds, so a tool can render faithful per-kind views;
+ * {@link isReservedKey} (with {@link RESERVED_MARKER} / {@link CATALOG_PREFIX})
+ * lets a raw-KV tool hide engine-internal keys instead of hardcoding the layout.
  */
 export { version, open } from "./core.js";
 export { kv } from "./lens/kv.js";
 export { doc } from "./lens/document.js";
 export { table } from "./lens/relational.js";
-export { catalog } from "./lens/catalog.js";
+export { catalog, isReservedKey, CATALOG_PREFIX, RESERVED_MARKER } from "./lens/catalog.js";

package/dist/lens/catalog.d.ts

@@ -16,7 +16,7 @@ export declare const RESERVED_MARKER = "\0";
  * `libredb:catalog:` tail keeps the namespace self-describing if a raw-KV tool
  * dumps the file before it understands the catalog.
  */
-export declare const CATALOG_PREFIX = "\0libredb:catalog:";
+export declare const CATALOG_PREFIX: string;
 /**
  * Reject a user namespace name that begins with the reserved marker — a loud
  * error, the same class of correctness rule as the prefix-soundness checks the
@@ -27,6 +27,19 @@ export declare const CATALOG_PREFIX = "\0libredb:catalog:";
  * layer with full keyspace access (DESIGN.md section 6.3).
  */
 export declare function assertUserName(name: string): void;
+/**
+ * Whether `key` lies in LibreDB's reserved internal namespace — that is, whether
+ * it begins with the {@link RESERVED_MARKER}. This is the public contract a tool
+ * that renders RAW key-value data (e.g. the LibreDB Studio provider) uses to HIDE
+ * engine-internal keys: the catalog today, and any further reserved sub-namespace
+ * added under the marker later. Testing the marker rather than the specific
+ * {@link CATALOG_PREFIX} is deliberate — a tool that depends on this stays correct
+ * if the reserved namespace grows, so it never has to track the byte layout.
+ *
+ * {@link assertUserName} guarantees no user namespace name begins with the marker,
+ * so this predicate partitions reserved keys from user keys with no overlap.
+ */
+export declare function isReservedKey(key: string): boolean;
 /**
  * The lens a cataloged namespace belongs to, plus (for a relational table) its
  * schema — the otherwise-unrecoverable interpretation a cold-opening tool needs

package/dist/lens/catalog.js

@@ -52,6 +52,21 @@ export function assertUserName(name) {
         throw new Error(`libredb: namespace name ${JSON.stringify(name)} may not start with the reserved catalog marker (U+0000)`);
     }
 }
+/**
+ * Whether `key` lies in LibreDB's reserved internal namespace — that is, whether
+ * it begins with the {@link RESERVED_MARKER}. This is the public contract a tool
+ * that renders RAW key-value data (e.g. the LibreDB Studio provider) uses to HIDE
+ * engine-internal keys: the catalog today, and any further reserved sub-namespace
+ * added under the marker later. Testing the marker rather than the specific
+ * {@link CATALOG_PREFIX} is deliberate — a tool that depends on this stays correct
+ * if the reserved namespace grows, so it never has to track the byte layout.
+ *
+ * {@link assertUserName} guarantees no user namespace name begins with the marker,
+ * so this predicate partitions reserved keys from user keys with no overlap.
+ */
+export function isReservedKey(key) {
+    return key.startsWith(RESERVED_MARKER);
+}
 const utf8 = new TextEncoder();
 const fromUtf8 = new TextDecoder();
 /** The kernel key for one namespace's catalog entry: the reserved prefix plus

package/dist/lens/document.js

@@ -116,7 +116,10 @@ export function doc(store, collection) {
         for (const entry of tx.getRange(start, end)) {
             const document = decodeDoc(entry.value);
             if (keep(document)) {
-                rows.push({ id: fromUtf8.decode(entry.key).slice(prefix.length), doc: document });
+                rows.push({
+                    id: fromUtf8.decode(entry.key).slice(prefix.length),
+                    doc: document,
+                });
             }
         }
         return rows;

package/dist/lens/relational.js

@@ -38,6 +38,10 @@ function matchesType(value, type) {
         case "boolean":
             return typeof value === "boolean";
         case "object":
+            // typeof null === "object" at runtime, so this null guard is real
+            // defensive validation even though the static Row type excludes null:
+            // a JS caller (no TypeScript) can still pass null into a column.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             return typeof value === "object" && value !== null && !Array.isArray(value);
     }
 }
@@ -191,7 +195,10 @@ export function table(store, name, schema) {
     // drop the document lens's DocEntry id wrapper (the pk lives in the row), then
     // let where/select compose over it. Each call rebuilds the Query so laziness
     // and re-iterability carry through from the document scan.
-    const allRows = () => query(name, () => rows.all().toArray().map((entry) => entry.doc));
+    const allRows = () => query(name, () => rows
+        .all()
+        .toArray()
+        .map((entry) => entry.doc));
     return {
         name,
         insert(row) {

package/dist/lens/types.d.ts

@@ -3,8 +3,8 @@
  *
  * A lens (kv, document, relational) is a typed view over the kernel in core.ts.
  * Lenses differ wildly in HOW you ask for data — a kv key range, a document
- * filter, a relational SELECT — and that is on purpose: DESIGN.md section 2 (and
- * the founding brainstorm in HANDOFF.md) reject a single unified query
+ * filter, a relational SELECT — and that is on purpose: DESIGN.md section 2
+ * rejects a single unified query
  * *language* as a lowest-common-denominator trap. So what lenses share is not
  * the query syntax but the RESULT envelope: every read hands back a
  * {@link Result}, every write reports a {@link WriteResult}. Pinning these two

package/dist/lens/types.js

@@ -3,8 +3,8 @@
  *
  * A lens (kv, document, relational) is a typed view over the kernel in core.ts.
  * Lenses differ wildly in HOW you ask for data — a kv key range, a document
- * filter, a relational SELECT — and that is on purpose: DESIGN.md section 2 (and
- * the founding brainstorm in HANDOFF.md) reject a single unified query
+ * filter, a relational SELECT — and that is on purpose: DESIGN.md section 2
+ * rejects a single unified query
  * *language* as a lowest-common-denominator trap. So what lenses share is not
  * the query syntax but the RESULT envelope: every read hands back a
  * {@link Result}, every write reports a {@link WriteResult}. Pinning these two

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "@libredb/libredb",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "A small, readable, embeddable, multi-model database. One ordered key-value core, thin model lenses on top.",
+  "keywords": [
+    "database",
+    "embedded",
+    "embeddable",
+    "key-value",
+    "document",
+    "relational",
+    "multi-model",
+    "typescript",
+    "bun"
+  ],
+  "homepage": "https://github.com/libredb/libredb-database#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/libredb/libredb-database.git"
+  },
+  "bugs": {
+    "url": "https://github.com/libredb/libredb-database/issues"
+  },
   "type": "module",
   "license": "MIT",
   "files": [
@@ -19,21 +38,50 @@
       "import": "./dist/index.js"
     }
   },
+  "sideEffects": false,
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.3.0",
+    "node": ">=22"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
+    "format": "biome format src eslint.config.js",
+    "format:fix": "biome format --write src eslint.config.js",
+    "lint": "oxlint && eslint .",
     "test": "bun test --coverage",
     "build": "tsc --project tsconfig.build.json",
-    "gate": "bun run typecheck && bun run lint && bun run test && bun run build"
+    "size": "size-limit",
+    "attw": "rm -rf .attw && bun pm pack --quiet --destination .attw && attw .attw/*.tgz --profile esm-only",
+    "publint": "publint",
+    "audit": "bun audit --ignore GHSA-h67p-54hq-rp68",
+    "secrets": "secretlint '**/*'",
+    "commitlint": "commitlint",
+    "license:check": "sh scripts/license-check.sh",
+    "changeset": "changeset",
+    "sync-version": "bun scripts/sync-version.ts",
+    "changeset:version": "changeset version && bun run sync-version",
+    "knip": "knip-bun",
+    "knip:production": "knip-bun --production --strict",
+    "prepublishOnly": "bun run build && bun run attw && bun run publint",
+    "prepare": "git config core.hooksPath .githooks",
+    "gate": "bun run typecheck && bun run format && bun run lint && bun run knip && bun run build && bun run size && bun run test"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
+    "@arethetypeswrong/cli": "^0.18.4",
+    "@biomejs/biome": "^2.5.1",
+    "@changesets/cli": "2.31.0",
+    "@commitlint/cli": "21.1.0",
+    "@commitlint/config-conventional": "21.1.0",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.2",
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@types/bun": "latest",
-    "eslint": "^9.0.0",
-    "typescript": "^5.4.0",
+    "eslint": "^10.0.0",
+    "knip": "^6.20.0",
+    "oxlint": "^1.71.0",
+    "publint": "^0.3.21",
+    "secretlint": "13.0.2",
+    "size-limit": "^12.1.0",
+    "typescript": "^6.0.0",
     "typescript-eslint": "^8.0.0"
   }
 }