@libredb/libredb 0.0.1

package/dist/core.js

@@ -0,0 +1,343 @@
+/**
+ * core.ts — the LibreDB kernel.
+ *
+ * This file is the trust boundary, the comprehension boundary, and the
+ * architecture boundary all at once (see DESIGN.md section 5). Everything that
+ * touches durability lives here and nowhere else:
+ *
+ *   - storage      an ordered key-value substrate
+ *   - transactions atomic apply with the isolation scoped in DESIGN.md
+ *   - recovery     survive a crash and reopen with consistent state
+ *
+ * The kernel is small because it is genuinely minimal, never because
+ * complexity was swept into sibling files. Model lenses (lens/kv.ts,
+ * lens/document.ts, lens/relational.ts) sit on top of this; they never
+ * reach around it.
+ *
+ * The boundaries are declared first as types — the contract every lens builds
+ * on — followed by the implementation: an ordered key-value store, serializable
+ * transactions, and a write-ahead log for durability. Recovery replays that log
+ * and discards any record a crash left half-written.
+ */
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, truncateSync, writeSync, } from "node:fs";
+/** The LibreDB package version. Kept in sync with package.json. */
+export const version = "0.0.1";
+/**
+ * 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
+ * first. Returns <0, 0, or >0 like every comparator.
+ *
+ * Bytes are unsigned (0..255) because they come from a Uint8Array, so this is
+ * the byte order a sorted file would use — not JavaScript's UTF-16 string
+ * order, where "10" would sort before "2".
+ */
+function compareKeys(a, b) {
+    const shared = Math.min(a.length, b.length);
+    for (let i = 0; i < shared; i++) {
+        const delta = a[i] - b[i];
+        if (delta !== 0)
+            return delta;
+    }
+    return a.length - b.length;
+}
+/**
+ * Binary-search a sorted entry array for `key`. Returns whether it is present
+ * and the index: the entry's own index if found, otherwise the index at which
+ * inserting would keep the array sorted.
+ */
+function locate(entries, key) {
+    let low = 0;
+    let high = entries.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        const order = compareKeys(entries[mid].key, key);
+        if (order === 0)
+            return { found: true, index: mid };
+        if (order < 0)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    return { found: false, index: low };
+}
+/** Set `key` to `value` in a sorted entry array, keeping it sorted. Shared by
+ * live transaction writes and by log replay during recovery, so "what a set
+ * means" has exactly one definition. */
+function applySet(entries, key, value) {
+    const { found, index } = locate(entries, key);
+    if (found)
+        entries[index] = { key, value };
+    else
+        entries.splice(index, 0, { key, value });
+}
+/** Remove `key` from a sorted entry array. A no-op if it is absent. Shared by
+ * live writes and log replay (see {@link applySet}). */
+function applyDelete(entries, key) {
+    const { found, index } = locate(entries, key);
+    if (found)
+        entries.splice(index, 1);
+}
+/**
+ * A transaction backed by `working`, a mutable snapshot of the committed store.
+ * Reads and writes hit the snapshot directly, which is what gives
+ * read-your-writes; the caller commits or discards the snapshot as a whole.
+ * Every mutation is also appended to `journal`, the redo record a durable
+ * database writes to its log on commit (and ignores when purely in-memory).
+ */
+function makeTransaction(working, journal) {
+    return {
+        get(key) {
+            const { found, index } = locate(working, key);
+            return found ? working[index].value : undefined;
+        },
+        set(key, value) {
+            applySet(working, key, value);
+            journal.push({ kind: "set", key, value });
+        },
+        delete(key) {
+            applyDelete(working, key);
+            journal.push({ kind: "delete", key });
+        },
+        *getRange(start, end) {
+            // locate() returns the first index whose key is >= start (the insertion
+            // point), so the scan is naturally inclusive of start. It stops at the
+            // first key that is not < end, making the range half-open [start, end).
+            for (let i = locate(working, start).index; i < working.length; i++) {
+                const entry = working[i];
+                if (compareKeys(entry.key, end) >= 0)
+                    break;
+                yield entry;
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Durability: a write-ahead log
+//
+// Without a path the kernel is purely in-memory. With one, durability is a
+// write-ahead log (a redo log): every committed transaction is appended to the
+// file as a single record and fsync'd BEFORE the commit becomes visible, so a
+// returned transact() is durable. Recovery replays the records in order to
+// rebuild the store. This is the same mechanism real databases use, written
+// plainly so the file still teaches how durability works.
+//
+// On-disk record = an 8-byte header followed by a payload:
+//   [u32 payloadLength][u32 crc32(payload)][payload]
+// The payload is the transaction's mutations back to back. Each op is:
+//   set:    [u8 1][u32 keyLength][key][u32 valueLength][value]
+//   delete: [u8 0][u32 keyLength][key]
+// Integers are big-endian. Because the log is append-only and fsync'd, a crash
+// can only ever damage the LAST record, so recovery trusts every record up to
+// the first one that is incomplete or fails its checksum, and truncates the
+// rest away.
+// ---------------------------------------------------------------------------
+const OP_SET = 1;
+const OP_DELETE = 0;
+/** Bytes in a record header: the payload length and its checksum, both u32. */
+const RECORD_HEADER = 8;
+/** Write `value` as a big-endian u32 at `offset`. */
+function writeU32(out, offset, value) {
+    out[offset] = (value >>> 24) & 0xff;
+    out[offset + 1] = (value >>> 16) & 0xff;
+    out[offset + 2] = (value >>> 8) & 0xff;
+    out[offset + 3] = value & 0xff;
+}
+/** Read a big-endian u32 from `offset`. The top byte is multiplied, not
+ * shifted: `<< 24` would land on the sign bit and yield a negative int. */
+function readU32(buffer, offset) {
+    return ((buffer[offset] * 0x1000000 +
+        (buffer[offset + 1] << 16) +
+        (buffer[offset + 2] << 8) +
+        buffer[offset + 3]) >>>
+        0);
+}
+/**
+ * CRC-32 (IEEE 802.3 polynomial), computed without a lookup table to keep the
+ * mechanism in plain sight. It lets recovery tell a fully-written record from
+ * one a crash left half-flushed.
+ */
+function crc32(data) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.length; i++) {
+        crc ^= data[i];
+        for (let bit = 0; bit < 8; bit++) {
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+        }
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** Encode one committed transaction's ops as a length-framed, checksummed
+ * record ready to append to the log. */
+function encodeRecord(ops) {
+    let size = 0;
+    for (const op of ops) {
+        size += 1 + 4 + op.key.length;
+        if (op.kind === "set")
+            size += 4 + op.value.length;
+    }
+    const payload = new Uint8Array(size);
+    let off = 0;
+    for (const op of ops) {
+        payload[off++] = op.kind === "set" ? OP_SET : OP_DELETE;
+        writeU32(payload, off, op.key.length);
+        off += 4;
+        payload.set(op.key, off);
+        off += op.key.length;
+        if (op.kind === "set") {
+            writeU32(payload, off, op.value.length);
+            off += 4;
+            payload.set(op.value, off);
+            off += op.value.length;
+        }
+    }
+    const record = new Uint8Array(RECORD_HEADER + size);
+    writeU32(record, 0, size);
+    writeU32(record, 4, crc32(payload));
+    record.set(payload, RECORD_HEADER);
+    return record;
+}
+/** Replay one record's payload onto `entries`, in order, reconstructing the
+ * committed state the transaction produced. */
+function replayPayload(entries, payload) {
+    let off = 0;
+    while (off < payload.length) {
+        const tag = payload[off++];
+        const keyLength = readU32(payload, off);
+        off += 4;
+        const key = payload.slice(off, off + keyLength);
+        off += keyLength;
+        if (tag === OP_SET) {
+            const valueLength = readU32(payload, off);
+            off += 4;
+            const value = payload.slice(off, off + valueLength);
+            off += valueLength;
+            applySet(entries, key, value);
+        }
+        else {
+            applyDelete(entries, key);
+        }
+    }
+}
+/**
+ * Rebuild the committed store from the log at `path`, returning its entries.
+ * Replays every intact record and stops at the first record a crash left torn
+ * (header promises bytes that are not there) or corrupt (checksum mismatch),
+ * truncating that tail away so the next append starts from a clean boundary.
+ */
+function recover(path) {
+    const entries = [];
+    if (!existsSync(path))
+        return entries;
+    // Copy into a plain Uint8Array so slices are independent copies, not views
+    // aliasing a shared Buffer pool.
+    const log = new Uint8Array(readFileSync(path));
+    let offset = 0;
+    while (offset + RECORD_HEADER <= log.length) {
+        const size = readU32(log, offset);
+        const checksum = readU32(log, offset + 4);
+        const start = offset + RECORD_HEADER;
+        const end = start + size;
+        if (end > log.length)
+            break; // torn: fewer bytes than the header promised
+        const payload = log.subarray(start, end);
+        if (crc32(payload) !== checksum)
+            break; // corrupt: record damaged mid-write
+        replayPayload(entries, payload);
+        offset = end;
+    }
+    if (offset < log.length)
+        truncateSync(path, offset);
+    return entries;
+}
+/** Recover the store at `path` and return it together with a {@link Log} that
+ * appends future commits to the same file. */
+function openLog(path) {
+    const entries = recover(path);
+    const fd = openSync(path, "a"); // append-only; creates the file if missing
+    return {
+        entries,
+        log: {
+            append(ops) {
+                const record = encodeRecord(ops);
+                for (let written = 0; written < record.length;) {
+                    written += writeSync(fd, record, written);
+                }
+                fsyncSync(fd); // the durability point: bytes are on disk before we return
+            },
+            close() {
+                closeSync(fd);
+            },
+        },
+    };
+}
+/**
+ * Open a kernel instance. See {@link Open} and {@link OpenOptions}.
+ *
+ * With a `path` the store is recovered from its write-ahead log and future
+ * commits are appended to it durably. Without one the store is purely
+ * in-memory.
+ */
+export const open = (options) => {
+    // The committed store. Each transaction works on a copy and replaces this
+    // reference on success, so a commit is one atomic assignment and an abort is
+    // simply never reaching that assignment. With a path, the initial contents
+    // are recovered from the log and `log` persists every later commit.
+    let committed;
+    let log;
+    if (options?.path !== undefined) {
+        const opened = openLog(options.path);
+        committed = opened.entries;
+        log = opened.log;
+    }
+    else {
+        committed = [];
+        log = null;
+    }
+    let closed = false;
+    // Guards against re-entrancy. The API is synchronous and single-threaded, so
+    // a transaction body runs to completion before the next one begins — making
+    // the schedule serial (hence serializable) by construction. The only way to
+    // overlap two transactions is to call transact() from inside another, which
+    // we forbid: the inner snapshot would miss the outer's pending writes and the
+    // outer's later commit would clobber the inner's, a silent lost update. With
+    // this guard the serializable guarantee is a fact, not an assumption.
+    let inTransaction = false;
+    return {
+        transact(run) {
+            if (closed)
+                throw new Error("libredb: database is closed");
+            if (inTransaction) {
+                throw new Error("libredb: nested transactions are not supported");
+            }
+            inTransaction = true;
+            try {
+                const working = committed.slice();
+                const journal = [];
+                const result = run(makeTransaction(working, journal));
+                // Reached only if run() did not throw. Make the commit DURABLE before
+                // exposing it in memory: if the append fails, we throw with memory and
+                // disk still agreeing on the prior state. A read-only transaction has
+                // nothing to persist, so it skips the log entirely. The in-memory
+                // commit is then one atomic reference swap.
+                if (log !== null && journal.length > 0)
+                    log.append(journal);
+                committed = working;
+                return result;
+            }
+            finally {
+                // Always clear the guard, even on abort, so a thrown body does not wedge
+                // the database against all future transactions.
+                inTransaction = false;
+            }
+        },
+        close() {
+            if (closed)
+                return; // idempotent: never double-close the underlying file
+            closed = true;
+            if (log !== null)
+                log.close();
+            committed = [];
+        },
+    };
+};
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,GACV,MAAM,SAAS,CAAC;AAEjB,mEAAmE;AACnE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AA2G/B;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,CAAM,EAAE,CAAM;IACjC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,KAAK,GAAI,CAAC,CAAC,CAAC,CAAY,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC;QAClD,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAChC,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CACb,OAA+B,EAC/B,GAAQ;IAER,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAC1B,OAAO,GAAG,GAAG,IAAI,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,WAAW,CAAE,OAAO,CAAC,GAAG,CAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAClE,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACpD,IAAI,KAAK,GAAG,CAAC;YAAE,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;;YACxB,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACtC,CAAC;AAED;;wCAEwC;AACxC,SAAS,QAAQ,CAAC,OAAsB,EAAE,GAAQ,EAAE,KAAY;IAC9D,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9C,IAAI,KAAK;QAAE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;;QACtC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC;AAED;wDACwD;AACxD,SAAS,WAAW,CAAC,OAAsB,EAAE,GAAQ;IACnD,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9C,IAAI,KAAK;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC;AAWD;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,OAAsB,EAAE,OAAa;IAC5D,OAAO;QACL,GAAG,CAAC,GAAG;YACL,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC9C,OAAO,KAAK,CAAC,CAAC,CAAE,OAAO,CAAC,KAAK,CAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACnE,CAAC;QACD,GAAG,CAAC,GAAG,EAAE,KAAK;YACZ,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,CAAC,GAAG;YACR,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;QACxC,CAAC;QACD,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG;YAClB,wEAAwE;YACxE,uEAAuE;YACvE,wEAAwE;YACxE,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnE,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAgB,CAAC;gBACxC,IAAI,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC;oBAAE,MAAM;gBAC5C,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,0DAA0D;AAC1D,EAAE;AACF,2DAA2D;AAC3D,qDAAqD;AACrD,uEAAuE;AACvE,+DAA+D;AAC/D,uCAAuC;AACvC,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,aAAa;AACb,8EAA8E;AAE9E,MAAM,MAAM,GAAG,CAAC,CAAC;AACjB,MAAM,SAAS,GAAG,CAAC,CAAC;AACpB,+EAA+E;AAC/E,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,qDAAqD;AACrD,SAAS,QAAQ,CAAC,GAAe,EAAE,MAAc,EAAE,KAAa;IAC9D,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACxC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;IACvC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;AACjC,CAAC;AAED;2EAC2E;AAC3E,SAAS,OAAO,CAAC,MAAkB,EAAE,MAAc;IACjD,OAAO,CACL,CAAE,MAAM,CAAC,MAAM,CAAY,GAAG,SAAS;QACrC,CAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;QACtC,CAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAY,IAAI,CAAC,CAAC;QACpC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAY,CAAC;QACjC,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,IAAgB;IAC7B,IAAI,GAAG,GAAG,UAAU,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAW,CAAC;QACzB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;YACjC,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED;wCACwC;AACxC,SAAS,YAAY,CAAC,GAAkB;IACtC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC;QAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK;YAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;IACrD,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QACxD,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,GAAG,IAAI,CAAC,CAAC;QACT,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACzB,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC;QACrB,IAAI,EAAE,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACtB,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACxC,GAAG,IAAI,CAAC,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC3B,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;QACzB,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;+CAC+C;AAC/C,SAAS,aAAa,CAAC,OAAsB,EAAE,OAAmB;IAChE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAW,CAAC;QACrC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACxC,GAAG,IAAI,CAAC,CAAC;QACT,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS,CAAC,CAAC;QAChD,GAAG,IAAI,SAAS,CAAC;QACjB,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YACnB,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC1C,GAAG,IAAI,CAAC,CAAC;YACT,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW,CAAC,CAAC;YACpD,GAAG,IAAI,WAAW,CAAC;YACnB,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAEtC,2EAA2E;IAC3E,iCAAiC;IACjC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,MAAM,GAAG,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,MAAM,GAAG,aAAa,CAAC;QACrC,MAAM,GAAG,GAAG,KAAK,GAAG,IAAI,CAAC;QACzB,IAAI,GAAG,GAAG,GAAG,CAAC,MAAM;YAAE,MAAM,CAAC,6CAA6C;QAC1E,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,MAAM,CAAC,oCAAoC;QAC5E,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,GAAG,GAAG,CAAC;IACf,CAAC;IAED,IAAI,MAAM,GAAG,GAAG,CAAC,MAAM;QAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC;AACjB,CAAC;AAWD;8CAC8C;AAC9C,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,2CAA2C;IAC3E,OAAO;QACL,OAAO;QACP,GAAG,EAAE;YACH,MAAM,CAAC,GAAG;gBACR,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;gBACjC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,GAAI,CAAC;oBAChD,OAAO,IAAI,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC5C,CAAC;gBACD,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,2DAA2D;YAC5E,CAAC;YACD,KAAK;gBACH,SAAS,CAAC,EAAE,CAAC,CAAC;YAChB,CAAC;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,IAAI,GAAS,CAAC,OAAO,EAAE,EAAE;IACpC,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,oEAAoE;IACpE,IAAI,SAAwB,CAAC;IAC7B,IAAI,GAAe,CAAC;IACpB,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrC,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC;QAC3B,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;IACnB,CAAC;SAAM,CAAC;QACN,SAAS,GAAG,EAAE,CAAC;QACf,GAAG,GAAG,IAAI,CAAC;IACb,CAAC;IAED,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,sEAAsE;IACtE,IAAI,aAAa,GAAG,KAAK,CAAC;IAE1B,OAAO;QACL,QAAQ,CAAC,GAAG;YACV,IAAI,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YAC3D,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;YACpE,CAAC;YACD,aAAa,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC;gBAClC,MAAM,OAAO,GAAS,EAAE,CAAC;gBACzB,MAAM,MAAM,GAAG,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBACtD,sEAAsE;gBACtE,uEAAuE;gBACvE,sEAAsE;gBACtE,kEAAkE;gBAClE,4CAA4C;gBAC5C,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;oBAAE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC5D,SAAS,GAAG,OAAO,CAAC;gBACpB,OAAO,MAAM,CAAC;YAChB,CAAC;oBAAS,CAAC;gBACT,yEAAyE;gBACzE,gDAAgD;gBAChD,aAAa,GAAG,KAAK,CAAC;YACxB,CAAC;QACH,CAAC;QACD,KAAK;YACH,IAAI,MAAM;gBAAE,OAAO,CAAC,qDAAqD;YACzE,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,GAAG,KAAK,IAAI;gBAAE,GAAG,CAAC,KAAK,EAAE,CAAC;YAC9B,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * index.ts — the public entry point of the LibreDB npm package.
+ *
+ * The public surface is the kv lens (DESIGN.md section 6): you `open` a kernel
+ * database and put a lens over it — {@link kv} (strings) or {@link doc} (JSON
+ * 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.
+ */
+export { version, open } from "./core.ts";
+export type { Database, OpenOptions } from "./core.ts";
+export { kv } from "./lens/kv.ts";
+export type { Kv, KvEntry } from "./lens/kv.ts";
+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 type { Result, WriteResult } from "./lens/types.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAClC,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAElF,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAEvF,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * index.ts — the public entry point of the LibreDB npm package.
+ *
+ * The public surface is the kv lens (DESIGN.md section 6): you `open` a kernel
+ * database and put a lens over it — {@link kv} (strings) or {@link doc} (JSON
+ * 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.
+ */
+export { version, open } from "./core.js";
+export { kv } from "./lens/kv.js";
+export { doc } from "./lens/document.js";
+export { table } from "./lens/relational.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAG1C,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAGlC,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAGzC,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/lens/document.d.ts

@@ -0,0 +1,104 @@
+/**
+ * lens/document.ts — the document lens, LibreDB's differentiator lens.
+ *
+ * Where kv (lens/kv.ts) is the *string* face over the byte kernel, document is
+ * the *JSON* face: a document is a JSON-serializable object stored as UTF-8 JSON
+ * bytes (the value) under a `<collection>:<id>` kernel key. The lens adds JSON
+ * ergonomics and nothing else — no storage, transactions, or recovery live here;
+ * those stay in core.ts (DESIGN.md section 6.1).
+ *
+ * The collection handle from {@link doc} adds by-id CRUD on top of that codec;
+ * collection scans (`all`) and field matching (`find`) build on it in the
+ * phases that follow.
+ */
+import { type Result, type WriteResult } from "./types.ts";
+import type { Store } from "../adapter/store.ts";
+/**
+ * Any value JSON can represent: the closure of the primitives under arrays and
+ * objects. This is the honest type of "what survives a JSON round-trip" —
+ * `undefined`, functions, and symbols are deliberately absent because JSON drops
+ * them.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * A document: a JSON object. Stored as one value in the kernel, keyed by its id
+ * within a collection. The top level is always an object (the unit a collection
+ * holds), while field values range over all of {@link JsonValue}.
+ */
+export type Doc = {
+    [key: string]: JsonValue;
+};
+/**
+ * One document from a collection scan: its `id` paired with the decoded `doc`.
+ * This is the document-lens Row type — collection reads return
+ * `Result<DocEntry>` (lens/types.ts), the same envelope the kv lens uses.
+ */
+export interface DocEntry {
+    readonly id: string;
+    readonly doc: Doc;
+}
+/** Serialize a document to UTF-8 JSON bytes — the form the kernel stores. */
+export declare function encodeDoc(doc: Doc): Uint8Array;
+/**
+ * Parse UTF-8 JSON bytes back into a document. The inverse of {@link encodeDoc}:
+ * bytes produced by it round-trip with full fidelity (numbers stay numbers,
+ * nested objects and unicode survive), which the document lens relies on for
+ * type-sensitive field matching.
+ */
+export declare function decodeDoc(bytes: Uint8Array): Doc;
+/**
+ * Whether `document` satisfies `predicate`: every top-level field named in the
+ * predicate is present on the document and deeply equal to the predicate's value
+ * (DESIGN.md section 6.1). Multiple fields are an implicit AND. An empty
+ * predicate names no fields and so matches every document.
+ *
+ * Exported so the relational lens's `where` can reuse the exact same matching
+ * semantics over rows (a row is a Doc), instead of re-deriving a second matcher.
+ */
+export declare function matches(document: Doc, predicate: Doc): boolean;
+/**
+ * A handle on one collection: by-id CRUD over the kernel.
+ *
+ * Each operation auto-commits in its own kernel transaction, so the collection
+ * behaves like a durable map of documents — a write is atomic and, on a
+ * file-backed database, fsync'd before it returns. Multi-document atomicity is a
+ * conscious omission (DESIGN.md section 6.1): a caller that needs it drops to the
+ * kernel's `transact`. The handle is a view — it depends only on the
+ * {@link Store} seam and never touches the store's lifecycle.
+ */
+export interface DocCollection {
+    /** Store `document` under `id`, overwriting any existing document at that id.
+     * Always reports one changed entry. */
+    put(id: string, document: Doc): WriteResult;
+    /** The document stored at `id`, decoded, or `undefined` if none is set. */
+    get(id: string): Doc | undefined;
+    /** Remove the document at `id`. Reports one changed entry if it existed, zero
+     * if it did not. */
+    delete(id: string): WriteResult;
+    /** Every document in the collection, as {@link DocEntry} rows in ascending id
+     * order (the kernel's byte order over the `<collection>:<id>` keys). The
+     * {@link Result} is lazy and re-iterable: each pass re-runs the scan against
+     * the current state. A scan sees only this collection's documents — the
+     * `<collection>:` prefix is a byte boundary, so a sibling whose name shares a
+     * prefix (`users` vs `users2`) is never included. */
+    all(): Result<DocEntry>;
+    /** Every document whose top-level fields match `predicate` by deep
+     * (structural) equality; multiple fields are an implicit AND, and an empty
+     * predicate matches everything (so `find({})` equals `all()`). Returns the
+     * same lazy, re-iterable {@link Result} as `all`, scoped to this collection.
+     *
+     * Cost: O(n) in the collection size. `find` is a full collection scan with an
+     * in-engine predicate — there are no secondary indexes (DESIGN.md section 6.1,
+     * a deliberate v1 omission). Every document is decoded and tested on each
+     * pass. */
+    find(predicate: Doc): Result<DocEntry>;
+}
+/**
+ * Build a {@link DocCollection} handle scoped to `collection` over a
+ * {@link Store} (the kernel's `Database` satisfies it, as does any object that
+ * can run a transaction).
+ */
+export declare function doc(store: Store, collection: string): DocCollection;
+//# sourceMappingURL=document.d.ts.map

package/dist/lens/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/lens/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAU,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,GAAG,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAKD,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,CAEhD;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAE9D;AAaD;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;2CACuC;IACvC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,WAAW,CAAC;IAC5C,2EAA2E;IAC3E,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;IACjC;wBACoB;IACpB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC;;;;;yDAKqD;IACrD,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxB;;;;;;;;eAQW;IACX,IAAI,CAAC,SAAS,EAAE,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,aAAa,CA2DnE"}

package/dist/lens/document.js

@@ -0,0 +1,152 @@
+/**
+ * lens/document.ts — the document lens, LibreDB's differentiator lens.
+ *
+ * Where kv (lens/kv.ts) is the *string* face over the byte kernel, document is
+ * the *JSON* face: a document is a JSON-serializable object stored as UTF-8 JSON
+ * bytes (the value) under a `<collection>:<id>` kernel key. The lens adds JSON
+ * ergonomics and nothing else — no storage, transactions, or recovery live here;
+ * those stay in core.ts (DESIGN.md section 6.1).
+ *
+ * The collection handle from {@link doc} adds by-id CRUD on top of that codec;
+ * collection scans (`all`) and field matching (`find`) build on it in the
+ * phases that follow.
+ */
+import { result } from "./types.js";
+import { prefixRange } from "../query/range.js";
+const utf8 = new TextEncoder();
+const fromUtf8 = new TextDecoder();
+/** Serialize a document to UTF-8 JSON bytes — the form the kernel stores. */
+export function encodeDoc(doc) {
+    return utf8.encode(JSON.stringify(doc));
+}
+/**
+ * Parse UTF-8 JSON bytes back into a document. The inverse of {@link encodeDoc}:
+ * bytes produced by it round-trip with full fidelity (numbers stay numbers,
+ * nested objects and unicode survive), which the document lens relies on for
+ * type-sensitive field matching.
+ */
+export function decodeDoc(bytes) {
+    return JSON.parse(fromUtf8.decode(bytes));
+}
+/**
+ * Deep structural equality over {@link JsonValue}. This is what document
+ * matching compares with, so it must be the JSON notion of "same value", not
+ * reference identity and not `JSON.stringify` (which is sensitive to object key
+ * order and so would call two equal objects unequal).
+ *
+ * - Primitives (string/number/boolean/null) compare by `===`, which is
+ *   type-sensitive on purpose: `1` is not `"1"` and `true` is not `"true"`.
+ * - Arrays are equal element-wise, in order (order is part of an array's value).
+ * - Objects are equal when they have the same set of keys and every value is
+ *   deeply equal; key *order* is irrelevant.
+ *
+ * The arguments are `JsonValue | undefined` so a missing field (`doc[key]` with
+ * no such key) is handled directly: it is `undefined`, which equals nothing a
+ * predicate can hold (predicate values are always defined {@link JsonValue}).
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true; // same primitive, same reference, or both undefined
+    if (a === null || b === null)
+        return false; // one is null but not the other (=== caught both)
+    if (typeof a !== "object" || typeof b !== "object")
+        return false; // unequal primitives/undefined
+    const aIsArray = Array.isArray(a);
+    if (aIsArray !== Array.isArray(b))
+        return false; // an array is never equal to a plain object
+    if (aIsArray) {
+        const bArr = b;
+        if (a.length !== bArr.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, bArr[i]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    if (aKeys.length !== Object.keys(bObj).length)
+        return false;
+    return aKeys.every((key) => Object.prototype.hasOwnProperty.call(bObj, key) && deepEqual(aObj[key], bObj[key]));
+}
+/**
+ * Whether `document` satisfies `predicate`: every top-level field named in the
+ * predicate is present on the document and deeply equal to the predicate's value
+ * (DESIGN.md section 6.1). Multiple fields are an implicit AND. An empty
+ * predicate names no fields and so matches every document.
+ *
+ * Exported so the relational lens's `where` can reuse the exact same matching
+ * semantics over rows (a row is a Doc), instead of re-deriving a second matcher.
+ */
+export function matches(document, predicate) {
+    return Object.keys(predicate).every((key) => deepEqual(document[key], predicate[key]));
+}
+/**
+ * The kernel key for one document: `<collection>:<id>`, UTF-8 encoded (DESIGN.md
+ * section 6.1). Prefixing every id with the collection name is what scopes a
+ * collection to a contiguous byte range, so a later `<collection>:` prefix scan
+ * (D3) selects exactly that collection. For a point operation it just makes the
+ * key deterministic: the same `(collection, id)` always maps to the same bytes.
+ */
+function keyOf(collection, id) {
+    return utf8.encode(`${collection}:${id}`);
+}
+/**
+ * Build a {@link DocCollection} handle scoped to `collection` over a
+ * {@link Store} (the kernel's `Database` satisfies it, as does any object that
+ * can run a transaction).
+ */
+export function doc(store, collection) {
+    // The byte range covering every `<collection>:` key. prefixRange computes the
+    // [start, end) bound on raw bytes so it agrees with the kernel's order, which
+    // is what makes the colon a sound collection boundary (a sibling like "users2"
+    // sorts outside ["users:", "users;") and is never seen). The prefix string
+    // length is also where every key's id begins, so stripping it recovers the id.
+    const prefix = `${collection}:`;
+    const { start, end } = prefixRange(utf8.encode(prefix));
+    // The shared collection scan behind both all() and find(): walk the prefix
+    // range in id (byte) order and return the documents `keep` accepts. The thunk
+    // re-runs per iteration, so the Result stays lazy and re-iterable; rows are
+    // materialized inside the transaction because the kernel's getRange is only
+    // valid in the tx body.
+    const scan = (keep) => result(() => store.transact((tx) => {
+        const rows = [];
+        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 });
+            }
+        }
+        return rows;
+    }));
+    return {
+        put(id, document) {
+            store.transact((tx) => {
+                tx.set(keyOf(collection, id), encodeDoc(document));
+            });
+            return { changed: 1 };
+        },
+        get(id) {
+            return store.transact((tx) => {
+                const bytes = tx.get(keyOf(collection, id));
+                return bytes === undefined ? undefined : decodeDoc(bytes);
+            });
+        },
+        delete(id) {
+            // Read-before-delete in one transaction: the kernel's delete is a silent
+            // no-op on a missing key, so this is how the lens tells 1 from 0 changes.
+            const changed = store.transact((tx) => {
+                const k = keyOf(collection, id);
+                const existed = tx.get(k) !== undefined;
+                tx.delete(k);
+                return existed ? 1 : 0;
+            });
+            return { changed };
+        },
+        all() {
+            return scan(() => true);
+        },
+        find(predicate) {
+            return scan((document) => matches(document, predicate));
+        },
+    };
+}
+//# sourceMappingURL=document.js.map