@libredb/libredb 0.0.3 → 0.1.0

package/dist/adapter/opfs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * adapter/opfs.ts — an OPFS-backed {@link FileSystem} for the browser.
+ *
+ * An edge, not the kernel: it carries no durability logic, only the mapping from
+ * the kernel's synchronous {@link FileSystem} seam onto an OPFS sync access
+ * handle. The point is that a `FileSystemSyncAccessHandle` exposes SYNCHRONOUS
+ * read/write/getSize/truncate/flush/close — the exact shape the kernel's WAL
+ * needs — so LibreDB can be durable in a browser with no async core.
+ *
+ * Sync access handles only exist inside a Web Worker, and obtaining one is async
+ * (navigator.storage.getDirectory -> getFileHandle -> createSyncAccessHandle).
+ * That async acquisition is the caller's, done once before {@link
+ * import("../core.ts").open}; this adapter takes the already-open handle and
+ * wraps it synchronously, keeping `open` synchronous. Typical use in a Worker:
+ *
+ *   const root = await navigator.storage.getDirectory();
+ *   const file = await root.getFileHandle("app.libredb", { create: true });
+ *   const handle = await file.createSyncAccessHandle();
+ *   const db = open({ path: "app.libredb", fs: opfsFileSystem(handle) });
+ *
+ * The handle is bound to one file, so the kernel's `path` is unused here — the
+ * database opened with this adapter is the file the handle was created for.
+ */
+import type { FileSystem } from "../core.ts";
+/**
+ * The synchronous subset of a browser `FileSystemSyncAccessHandle` the WAL uses.
+ * Declared locally so the package needs no DOM lib types; a real sync access
+ * handle satisfies it structurally.
+ */
+export interface SyncAccessHandle {
+    /** Read into `buffer` starting at `options.at` (default 0); returns bytes read. */
+    read(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    /** Write `buffer` starting at `options.at` (default 0); returns bytes written. */
+    write(buffer: Uint8Array, options?: {
+        at?: number;
+    }): number;
+    /** The file's current size in bytes. */
+    getSize(): number;
+    /** Resize the file to `newSize`, dropping anything beyond it. */
+    truncate(newSize: number): void;
+    /** Persist buffered writes to storage. */
+    flush(): void;
+    /** Release the handle. */
+    close(): void;
+}
+/** Build a {@link FileSystem} backed by an open OPFS sync access `handle`. */
+export declare function opfsFileSystem(handle: SyncAccessHandle): FileSystem;

package/dist/adapter/opfs.js

@@ -0,0 +1,36 @@
+/** Build a {@link FileSystem} backed by an open OPFS sync access `handle`. */
+export function opfsFileSystem(handle) {
+    return {
+        open() {
+            return {
+                size() {
+                    return handle.getSize();
+                },
+                read(offset, length) {
+                    const buffer = new Uint8Array(length);
+                    const read = handle.read(buffer, { at: offset });
+                    return buffer.subarray(0, read);
+                },
+                append(data) {
+                    // write() may write fewer bytes than asked (hence the returned count),
+                    // so loop until the whole record is on the handle — otherwise a short
+                    // write would persist a torn record while fsync reports success. This
+                    // mirrors the node-fs adapter's writeSync loop.
+                    const base = handle.getSize();
+                    for (let written = 0; written < data.length;) {
+                        written += handle.write(data.subarray(written), { at: base + written });
+                    }
+                },
+                fsync() {
+                    handle.flush();
+                },
+                truncate(length) {
+                    handle.truncate(length);
+                },
+                close() {
+                    handle.close();
+                },
+            };
+        },
+    };
+}

package/dist/browser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * browser.ts — the browser entry point of the LibreDB npm package
+ * (`@libredb/libredb/browser`).
+ *
+ * Same lens surface as the default Node entry ({@link import("./index.ts")}),
+ * with one difference: `open` is the kernel's own, carrying NO default
+ * filesystem. An in-memory database (`open()`) works anywhere; a path-backed
+ * open requires an injected `fs` (e.g. the bundled {@link opfsFileSystem}). The
+ * point of this entry is the import graph: it reaches nothing in `node:`, so a
+ * bundler can ship it to a browser. The node:fs adapter lives behind Node only.
+ */
+export { open, version } from "./core.ts";
+export type { Database, FileSystem, OpenOptions, WalFile } from "./core.ts";
+export { opfsFileSystem } from "./adapter/opfs.ts";
+export type { SyncAccessHandle } from "./adapter/opfs.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 { 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/browser.js

@@ -0,0 +1,19 @@
+/**
+ * browser.ts — the browser entry point of the LibreDB npm package
+ * (`@libredb/libredb/browser`).
+ *
+ * Same lens surface as the default Node entry ({@link import("./index.ts")}),
+ * with one difference: `open` is the kernel's own, carrying NO default
+ * filesystem. An in-memory database (`open()`) works anywhere; a path-backed
+ * open requires an injected `fs` (e.g. the bundled {@link opfsFileSystem}). The
+ * point of this entry is the import graph: it reaches nothing in `node:`, so a
+ * bundler can ship it to a browser. The node:fs adapter lives behind Node only.
+ */
+export { open, version } from "./core.js";
+// OPFS persistence (browser-only): wrap an OPFS sync access handle as the
+// filesystem for a path-backed open. See adapter/opfs.ts for usage in a Worker.
+export { opfsFileSystem } from "./adapter/opfs.js";
+export { kv } from "./lens/kv.js";
+export { doc } from "./lens/document.js";
+export { table } from "./lens/relational.js";
+export { catalog, isReservedKey, CATALOG_PREFIX, RESERVED_MARKER } from "./lens/catalog.js";

package/dist/cli/lock.d.ts

@@ -0,0 +1,7 @@
+/** A held lock. Call {@link Lock.release} once the write is done. */
+export interface Lock {
+    release(): void;
+}
+/** Acquire the advisory lock for `path`. With `force`, an existing libredb lock
+ * is dropped first; otherwise an existing lock makes this throw. */
+export declare function acquireLock(path: string, force: boolean): Lock;

package/dist/cli/lock.js

@@ -0,0 +1,51 @@
+/**
+ * cli/lock.ts — an advisory write lock for the CLI.
+ *
+ * LibreDB is single-process and does no file locking itself, so two writers to
+ * one file would corrupt it. Write commands take a `<path>.lock` first: an
+ * exclusive create that fails if the file already exists, turning a concurrent
+ * writer into a loud error instead of silent corruption. It is advisory only —
+ * `--force` drops a stale lock and proceeds. The lock is always released after
+ * the write (see withWriteDb in run.ts).
+ */
+import { closeSync, openSync, readFileSync, rmSync, writeSync } from "node:fs";
+// Written into every lock file so a forced acquire can tell a real libredb lock
+// from an unrelated file that merely happens to be named <path>.lock, and refuse
+// to delete the latter.
+const SENTINEL = "libredb-lock\n";
+/** Acquire the advisory lock for `path`. With `force`, an existing libredb lock
+ * is dropped first; otherwise an existing lock makes this throw. */
+export function acquireLock(path, force) {
+    const lockPath = `${path}.lock`;
+    if (force)
+        dropOwnLock(lockPath);
+    try {
+        const fd = openSync(lockPath, "wx"); // "wx": exclusive create, fails if it exists
+        writeSync(fd, SENTINEL);
+        closeSync(fd);
+    }
+    catch {
+        throw new Error(`libredb: ${path} is locked (${lockPath}); another writer may be active — use --force to override`);
+    }
+    return {
+        release() {
+            rmSync(lockPath, { force: true });
+        },
+    };
+}
+/** Remove an existing libredb lock so a forced acquire can proceed. Refuses to
+ * touch a file that is not a libredb lock, so `--force` can never delete
+ * unrelated user data that happens to share the `.lock` name. */
+function dropOwnLock(lockPath) {
+    let contents;
+    try {
+        contents = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return; // no lock file to drop
+    }
+    if (!contents.startsWith(SENTINEL)) {
+        throw new Error(`libredb: refusing to remove ${lockPath} with --force: not a libredb lock file`);
+    }
+    rmSync(lockPath, { force: true });
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * cli/main.ts — the `libredb` bin shim.
+ *
+ * The only file that touches the real process: it wires process argv/stdout/
+ * stderr/exit code to the pure {@link run}. All behaviour lives in run.ts and is
+ * tested there; this glue is excluded from coverage (see bunfig.toml) because it
+ * cannot be exercised without spawning a process, and a behavioural smoke test
+ * (main.test.ts) runs the bin end-to-end instead.
+ */
+import { run } from "./run.js";
+process.exitCode = run(process.argv.slice(2), {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`${line}\n`),
+});

package/dist/cli/readonly-fs.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from "../core.ts";
+/** Build a read-only {@link FileSystem} over `node:fs`. */
+export declare function readonlyFileSystem(): FileSystem;

package/dist/cli/readonly-fs.js

@@ -0,0 +1,41 @@
+/**
+ * cli/readonly-fs.ts — a read-only {@link FileSystem} for the inspection CLI.
+ *
+ * An edge, not the kernel: it carries no durability logic, only the node:fs
+ * calls a read needs. Inspection commands open a database purely to read it, but
+ * open() runs recovery, which truncates a torn tail — a write. This adapter makes
+ * that impossible: `append` and `fsync` refuse, and `truncate` is a no-op, so a
+ * crash-interrupted file is recovered correctly IN MEMORY (the torn tail is
+ * dropped from the returned entries) while the bytes on disk are left exactly as
+ * found. `size` and `read` are the obvious read syscalls.
+ */
+import { closeSync, openSync, readFileSync, statSync } from "node:fs";
+/** Build a read-only {@link FileSystem} over `node:fs`. */
+export function readonlyFileSystem() {
+    return {
+        open(path) {
+            const fd = openSync(path, "r"); // read-only; throws if the file is absent
+            return {
+                size() {
+                    return statSync(path).size;
+                },
+                read(offset, length) {
+                    return new Uint8Array(readFileSync(path)).subarray(offset, offset + length);
+                },
+                append() {
+                    throw new Error("libredb: read-only database; refusing to write");
+                },
+                fsync() {
+                    throw new Error("libredb: read-only database; refusing to write");
+                },
+                truncate() {
+                    // Deliberate no-op: a read must not alter the file. Recovery still
+                    // drops a torn tail from the in-memory state; the disk is untouched.
+                },
+                close() {
+                    closeSync(fd);
+                },
+            };
+        },
+    };
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,7 @@
+/** Where the CLI writes its output. One call is one line; the sink adds newlines. */
+interface Io {
+    out(line: string): void;
+    err(line: string): void;
+}
+export declare function run(argv: string[], io: Io): number;
+export {};

package/dist/cli/run.js

@@ -0,0 +1,231 @@
+/**
+ * cli/run.ts — the LibreDB CLI as a pure function.
+ *
+ * `run(argv, io)` takes an argument vector and an IO sink and returns a process
+ * exit code. Keeping the whole CLI behind this seam — no direct stdout, no
+ * process.exit — is what makes every command and error path unit-testable; the
+ * bin shim (main.ts) is the only place that touches the real process.
+ *
+ * This is open-edge tooling over the public API, not kernel code: it adds no
+ * durability logic. Read commands (inspect/stats/get/scan) open through the
+ * read-only filesystem adapter so inspecting a file never mutates it. Write
+ * commands (set/delete/import) take an advisory lock first, and import commits
+ * all keys in one transaction so a bulk load is atomic.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { open } from "../index.js";
+import { catalog, isReservedKey } from "../lens/catalog.js";
+import { kv } from "../lens/kv.js";
+import { acquireLock } from "./lock.js";
+import { readonlyFileSystem } from "./readonly-fs.js";
+const encoder = new TextEncoder();
+const utf8 = (s) => encoder.encode(s);
+const USAGE = [
+    "libredb - inspect and edit .libredb files",
+    "",
+    "Usage:",
+    "  libredb inspect <path>             List each namespace, its kind, and table schemas",
+    "  libredb stats <path>               Summarize the file: size and namespace counts",
+    "  libredb get <path> <key>           Print the value stored at a key",
+    "  libredb scan <path> <prefix>       Print key=value for every key under a prefix",
+    "  libredb set <path> <key> <value>   Set a key to a value",
+    "  libredb delete <path> <key>        Remove a key",
+    "  libredb import <path> <file.json>  Bulk-set keys from a JSON object (one atomic commit)",
+    "",
+    "Options:",
+    "  --force                            Override an existing write lock",
+].join("\n");
+/** Open `path` read-only, run `fn`, and always close — so a read leaves the file
+ * exactly as it was (recovery cannot truncate a torn tail through this adapter). */
+const withReadDb = (path, fn) => {
+    const db = open({ path, fs: readonlyFileSystem() });
+    try {
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+};
+/** Take the advisory lock, open `path` for writing, run `fn`, then always close
+ * and release — so a crash mid-write cannot leave the lock stranded. */
+const withWriteDb = (path, force, fn) => {
+    const lock = acquireLock(path, force);
+    try {
+        const db = open({ path });
+        try {
+            return fn(db);
+        }
+        finally {
+            db.close();
+        }
+    }
+    finally {
+        lock.release();
+    }
+};
+function inspect({ path, io }) {
+    return withReadDb(path, (db) => {
+        const registry = catalog(db);
+        io.out(`${path}  ${statSync(path).size} bytes`);
+        if (registry.size === 0) {
+            io.out("  (no catalogued namespaces)");
+            return 0;
+        }
+        for (const [name, entry] of registry) {
+            const schema = entry.schema === undefined ? "" : `  ${JSON.stringify(entry.schema)}`;
+            io.out(`  ${name}  ${entry.kind}${schema}`);
+        }
+        return 0;
+    });
+}
+function stats({ path, io }) {
+    return withReadDb(path, (db) => {
+        const registry = catalog(db);
+        const counts = { kv: 0, document: 0, relational: 0 };
+        for (const entry of registry.values())
+            counts[entry.kind]++;
+        io.out(`${path}  ${statSync(path).size} bytes  ${registry.size} namespaces`);
+        io.out(`  kv: ${counts.kv}  document: ${counts.document}  relational: ${counts.relational}`);
+        return 0;
+    });
+}
+function get({ path, args, io }) {
+    const [key] = args;
+    if (key === undefined) {
+        io.err("missing <key>");
+        return 2;
+    }
+    return withReadDb(path, (db) => {
+        const value = kv(db).get(key);
+        if (value === undefined) {
+            io.err(`key not found: ${key}`);
+            return 1;
+        }
+        io.out(value);
+        return 0;
+    });
+}
+function scan({ path, args, io }) {
+    const [prefix] = args;
+    if (prefix === undefined) {
+        io.err("missing <prefix>");
+        return 2;
+    }
+    return withReadDb(path, (db) => {
+        for (const entry of kv(db).prefix(prefix))
+            io.out(`${entry.key}=${entry.value}`);
+        return 0;
+    });
+}
+function set({ path, args, io, force }) {
+    const [key, value] = args;
+    if (key === undefined || value === undefined) {
+        io.err("missing <key> <value>");
+        return 2;
+    }
+    if (isReservedKey(key)) {
+        io.err(`refusing to write a reserved key: ${key}`);
+        return 2;
+    }
+    return withWriteDb(path, force, (db) => {
+        const { changed } = kv(db).set(key, value);
+        io.out(`set ${key} (${changed} changed)`);
+        return 0;
+    });
+}
+function remove({ path, args, io, force }) {
+    const [key] = args;
+    if (key === undefined) {
+        io.err("missing <key>");
+        return 2;
+    }
+    return withWriteDb(path, force, (db) => {
+        const { changed } = kv(db).delete(key);
+        io.out(`delete ${key} (${changed} removed)`);
+        return 0;
+    });
+}
+function importKeys({ path, args, io, force }) {
+    const [file] = args;
+    if (file === undefined) {
+        io.err("missing <file>");
+        return 2;
+    }
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        io.err("import expects a JSON object of string values");
+        return 2;
+    }
+    const pairs = [];
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string") {
+            io.err("import expects a JSON object of string values");
+            return 2;
+        }
+        if (isReservedKey(key)) {
+            io.err(`import: refusing to write a reserved key: ${key}`);
+            return 2;
+        }
+        pairs.push([key, value]);
+    }
+    return withWriteDb(path, force, (db) => {
+        // One transaction for the whole load: a bulk import either lands entirely or,
+        // on a crash mid-write, not at all (recovery discards the torn record).
+        db.transact((tx) => {
+            for (const [key, value] of pairs)
+                tx.set(utf8(key), utf8(value));
+        });
+        io.out(`import ${pairs.length} keys`);
+        return 0;
+    });
+}
+/** The commands, keyed by name. Each takes the parsed {@link Ctx}. */
+const commands = {
+    inspect,
+    stats,
+    get,
+    scan,
+    set,
+    delete: remove,
+    import: importKeys,
+};
+export function run(argv, io) {
+    let positionals;
+    let values;
+    try {
+        const parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: { help: { type: "boolean", short: "h" }, force: { type: "boolean" } },
+        });
+        positionals = parsed.positionals;
+        values = parsed.values;
+    }
+    catch (error) {
+        io.err(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    if (values.help === true || positionals.length === 0) {
+        io.out(USAGE);
+        return 0;
+    }
+    const command = positionals[0];
+    const handler = commands[command];
+    if (handler === undefined) {
+        io.err(`unknown command: ${command}`);
+        return 2;
+    }
+    const path = positionals[1];
+    if (path === undefined) {
+        io.err("missing <path>");
+        return 2;
+    }
+    try {
+        return handler({ path, args: positionals.slice(2), io, force: values.force === true });
+    }
+    catch (error) {
+        io.err(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

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.3";
+export declare const version = "0.1.0";
 /**
  * A key in the kernel: an immutable sequence of bytes.
  *
@@ -94,9 +94,10 @@ export interface Database {
  * goes through this interface. That keeps the IO boundary explicit and in one
  * place (a readability gain), and it lets a test inject a simulated filesystem
  * to torture crash recovery without a real disk (DESIGN.md section 6.4). The
- * default is a thin real-`node:fs` adapter, so production behaviour is
- * unchanged. The interface is deliberately the SMALLEST set of operations the
- * WAL performs and nothing more.
+ * kernel carries NO default filesystem: a path-backed open must be given one.
+ * The Node entry (index.ts) supplies a `node:fs`-backed adapter by default; the
+ * browser entry supplies none. The interface is deliberately the SMALLEST set
+ * of operations the WAL performs and nothing more.
  */
 export interface FileSystem {
     /** Open the log file at `path` for reading and appending, creating it if it
@@ -133,10 +134,12 @@ export interface WalFile {
 export interface OpenOptions {
     readonly path?: string;
     /**
-     * The filesystem the write-ahead log runs on. Defaults to a thin real
-     * `node:fs` adapter. Injecting one lets tests simulate crashes and IO faults
-     * deterministically (DESIGN.md section 6.4). Ignored when there is no `path`
-     * (an in-memory database never touches a filesystem).
+     * The filesystem the write-ahead log runs on. Required for a path-backed open:
+     * the kernel carries no default, so omitting it with a `path` throws. (The
+     * Node entry defaults this to a `node:fs` adapter; the browser entry has none.)
+     * Injecting one lets tests simulate crashes and IO faults deterministically
+     * (DESIGN.md section 6.4). Ignored when there is no `path` (an in-memory
+     * database never touches a filesystem).
      */
     readonly fs?: FileSystem;
 }

package/dist/core.js

@@ -19,9 +19,8 @@
  * 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";
 /** The LibreDB package version. Kept in sync with package.json. */
-export const version = "0.0.3";
+export const version = "0.1.0";
 /**
  * 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
@@ -245,44 +244,6 @@ function recover(file) {
         file.truncate(offset);
     return entries;
 }
-/**
- * The default {@link FileSystem}: a thin adapter over `node:fs`. Each method is
- * the obvious synchronous syscall, so the seam adds an interface, not behaviour.
- * Appends go through one append-mode descriptor (creating the file if missing);
- * reads, size and truncate work by path, matching how the WAL has always
- * reached the disk.
- */
-function nodeFileSystem() {
-    return {
-        open(path) {
-            const fd = openSync(path, "a"); // append-only; creates the file if missing
-            return {
-                size() {
-                    return statSync(path).size;
-                },
-                read(offset, length) {
-                    // A fresh Uint8Array so the returned slice is an independent copy, not
-                    // a view aliasing a shared Buffer pool.
-                    return new Uint8Array(readFileSync(path)).subarray(offset, offset + length);
-                },
-                append(bytes) {
-                    for (let written = 0; written < bytes.length;) {
-                        written += writeSync(fd, bytes, written);
-                    }
-                },
-                fsync() {
-                    fsyncSync(fd);
-                },
-                truncate(length) {
-                    truncateSync(path, length);
-                },
-                close() {
-                    closeSync(fd);
-                },
-            };
-        },
-    };
-}
 /** Open the log file at `path` on `fs`, recover the store from it, and return
  * the recovered entries together with a {@link Log} that appends future commits
  * to the same file. */
@@ -317,7 +278,20 @@ export const open = (options) => {
     let committed;
     let log;
     if (options?.path !== undefined) {
-        const opened = openLog(options.path, options.fs ?? nodeFileSystem());
+        // A path must actually name a file: reject the degenerate empty string here
+        // with a clear error, rather than letting it reach the filesystem and
+        // surface a raw, adapter-specific failure (e.g. node's ENOENT for "").
+        if (options.path === "") {
+            throw new Error("libredb: open({ path }) requires a non-empty path");
+        }
+        // The kernel is runtime-agnostic: it carries no default filesystem, so a
+        // path-backed open MUST be given one. The default node:fs adapter lives at
+        // the package edge (index.ts wires it in); the browser entry has none. A
+        // pathless, in-memory open never reaches here and needs no filesystem.
+        if (options.fs === undefined) {
+            throw new Error("libredb: open({ path }) requires a filesystem; none was provided");
+        }
+        const opened = openLog(options.path, options.fs);
         committed = opened.entries;
         log = opened.log;
     }

package/dist/index.d.ts

@@ -10,8 +10,18 @@
  * {@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";
+import { type Open } from "./core.ts";
+export { version } from "./core.ts";
+export type { Database, FileSystem, OpenOptions, WalFile } from "./core.ts";
+/**
+ * Open a LibreDB database on Node or Bun. Identical to the kernel's
+ * {@link import("./core.ts").open}, except a path-backed open with no `fs`
+ * defaults to the real `node:fs` adapter — so `open({ path })` is durable out of
+ * the box. A pathless open stays in-memory; an explicit `fs` is passed through.
+ * The browser entry (`@libredb/libredb/browser`) omits this default so it never
+ * imports `node:fs`.
+ */
+export declare const open: Open;
 export { kv } from "./lens/kv.ts";
 export type { Kv, KvEntry } from "./lens/kv.ts";
 export { doc } from "./lens/document.ts";

package/dist/index.js

@@ -10,7 +10,20 @@
  * {@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";
+import { open as openKernel } from "./core.js";
+import { nodeFileSystem } from "./adapter/node-fs.js";
+export { version } from "./core.js";
+/**
+ * Open a LibreDB database on Node or Bun. Identical to the kernel's
+ * {@link import("./core.ts").open}, except a path-backed open with no `fs`
+ * defaults to the real `node:fs` adapter — so `open({ path })` is durable out of
+ * the box. A pathless open stays in-memory; an explicit `fs` is passed through.
+ * The browser entry (`@libredb/libredb/browser`) omits this default so it never
+ * imports `node:fs`.
+ */
+export const open = (options) => options?.path !== undefined && options.fs === undefined
+    ? openKernel({ ...options, fs: nodeFileSystem() })
+    : openKernel(options);
 export { kv } from "./lens/kv.js";
 export { doc } from "./lens/document.js";
 export { table } from "./lens/relational.js";