@libredb/libredb 0.1.2 → 0.1.3

package/README.md

@@ -8,6 +8,8 @@
 **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)
+[![JSR](https://jsr.io/badges/@libredb/libredb)](https://jsr.io/@libredb/libredb)
+[![Docker Hub](https://img.shields.io/docker/v/libredb/libredb?logo=docker&logoColor=white&label=docker%20hub&color=2496ED&sort=semver)](https://hub.docker.com/r/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)
@@ -98,7 +100,7 @@ bunx jsr add @libredb/libredb
 **CDN** — every release is served from the npm registry by the usual CDNs. Pin a version:
 
 ```ts
-import { open, kv } from "https://esm.sh/@libredb/libredb@0.1.2";
+import { open, kv } from "https://esm.sh/@libredb/libredb@0.1.3";
 ```
 
 **Browser** — a dedicated entry that imports nothing from `node:`, so it bundles for the browser
@@ -124,8 +126,11 @@ const handle = await file.createSyncAccessHandle();
 const db = open({ path: "app.libredb", fs: opfsFileSystem(handle) });
 ```
 
-A browser-targeting bundler resolves the browser build automatically via the package's `browser`
-export condition, so importing the main `@libredb/libredb` entry works too.
+A browser-targeting bundler also resolves the browser build from the main `@libredb/libredb` entry
+via the package's `browser` export condition. Note that TypeScript usually still resolves the Node
+types for that entry (where `fs` is optional) unless it is configured for the `browser` condition
+(`customConditions`). To get the browser-specific typing — `fs` required when `path` is given — and
+keep types in step with the runtime, import the explicit `@libredb/libredb/browser` subpath.
 
 ## Command-line tool
 
@@ -142,7 +147,9 @@ npx libredb import data.libredb seed.json # bulk-set from a JSON object, atomica
 ```
 
 Read commands open the file read-only, so inspection never mutates it. Write commands take an
-advisory `<path>.lock` to refuse a second concurrent writer; pass `--force` to override a stale lock.
+advisory `<path>.lock` to refuse a second concurrent writer. Use `--force` only to clear a stale
+lock left by a crashed writer: the lock is advisory and LibreDB is single-process, so two writers
+that force at the same time can still race and corrupt the file.
 
 Prefer a standalone binary with no Node or Bun installed? Each release attaches self-contained
 executables (Linux, macOS, Windows; x64 and arm64) with `.sha256` checksums on its
@@ -157,7 +164,10 @@ docker run --rm -v "$PWD:/data" ghcr.io/libredb/libredb inspect /data/app.libred
 # or from Docker Hub: docker run --rm -v "$PWD:/data" libredb/libredb inspect /data/app.libredb
 ```
 
-The image is a CLI shell, not a server: LibreDB stays an embedded, in-process database.
+The same multi-arch image is published to both registries:
+[Docker Hub](https://hub.docker.com/r/libredb/libredb) and
+[GHCR](https://github.com/libredb/libredb-database/pkgs/container/libredb). It is a CLI shell, not a
+server: LibreDB stays an embedded, in-process database.
 
 ## How it works: one core, three lenses
 

package/dist/browser.d.ts

@@ -3,14 +3,38 @@
  * (`@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.
+ * with one difference: `open` carries NO default filesystem. An in-memory
+ * database (`open()`) works anywhere; a path-backed open requires an injected
+ * `fs` (e.g. the bundled {@link opfsFileSystem}). Here that requirement is in
+ * the TYPE — {@link BrowserOpenOptions} makes `fs` mandatory when `path` is
+ * given, so misuse is a compile error rather than a runtime throw. 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";
+import { type Database, type FileSystem } from "./core.ts";
+export { version } from "./core.ts";
+export type { Database, FileSystem, WalFile } from "./core.ts";
+/**
+ * Options for the browser {@link open}. Unlike the kernel's permissive
+ * `OpenOptions`, `fs` is REQUIRED whenever `path` is present, because the browser
+ * entry has no default filesystem — so a path-backed open without an `fs` fails
+ * to compile here instead of throwing at runtime. An in-memory open (no `path`)
+ * needs no filesystem.
+ */
+export type BrowserOpenOptions = {
+    readonly path: string;
+    readonly fs: FileSystem;
+} | {
+    readonly path?: never;
+    readonly fs?: FileSystem;
+};
+/**
+ * Open a database in the browser. The same runtime as the kernel's `open`, typed
+ * so a path-backed open requires an injected filesystem (e.g.
+ * {@link opfsFileSystem}). Assigning the kernel's wider-typed `open` here is
+ * sound by parameter contravariance, so the kernel itself stays unchanged.
+ */
+export declare const open: (options?: BrowserOpenOptions) => Database;
 export { opfsFileSystem } from "./adapter/opfs.ts";
 export type { SyncAccessHandle } from "./adapter/opfs.ts";
 export { kv } from "./lens/kv.ts";

package/dist/browser.js

@@ -3,13 +3,23 @@
  * (`@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.
+ * with one difference: `open` carries NO default filesystem. An in-memory
+ * database (`open()`) works anywhere; a path-backed open requires an injected
+ * `fs` (e.g. the bundled {@link opfsFileSystem}). Here that requirement is in
+ * the TYPE — {@link BrowserOpenOptions} makes `fs` mandatory when `path` is
+ * given, so misuse is a compile error rather than a runtime throw. 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";
+import { open as openKernel } from "./core.js";
+export { version } from "./core.js";
+/**
+ * Open a database in the browser. The same runtime as the kernel's `open`, typed
+ * so a path-backed open requires an injected filesystem (e.g.
+ * {@link opfsFileSystem}). Assigning the kernel's wider-typed `open` here is
+ * sound by parameter contravariance, so the kernel itself stays unchanged.
+ */
+export const open = openKernel;
 // 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";

package/dist/cli/lock.js

@@ -8,7 +8,7 @@
  * `--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";
+import { closeSync, existsSync, 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.
@@ -21,11 +21,22 @@ export function acquireLock(path, force) {
         dropOwnLock(lockPath);
     try {
         const fd = openSync(lockPath, "wx"); // "wx": exclusive create, fails if it exists
-        writeSync(fd, SENTINEL);
-        closeSync(fd);
+        try {
+            writeSync(fd, SENTINEL);
+        }
+        finally {
+            closeSync(fd); // always release the descriptor, even if the write throws
+        }
     }
-    catch {
-        throw new Error(`libredb: ${path} is locked (${lockPath}); another writer may be active — use --force to override`);
+    catch (error) {
+        // A failed sentinel write (e.g. ENOSPC) leaves an EMPTY <path>.lock behind;
+        // that stray is recoverable because dropOwnLock treats an empty file as ours.
+        // Only an existing lock file (EEXIST) means "locked". Surface any other IO
+        // error (missing directory, permissions, ...) unchanged, so a real problem
+        // is not misreported as a held lock.
+        if (error.code !== "EEXIST")
+            throw error;
+        throw new Error(`libredb: ${path} is locked (${lockPath}); another writer may be active — use --force to override`, { cause: error });
     }
     return {
         release() {
@@ -33,18 +44,17 @@ export function acquireLock(path, force) {
         },
     };
 }
-/** 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. */
+/** Remove an existing libredb lock so a forced acquire can proceed. A lock this
+ * tool created carries the SENTINEL; an empty file is a stray from a crash or a
+ * failed sentinel write (also ours) and is safe to drop. Any other content means
+ * the file is not our lock, so `--force` refuses it rather than delete unrelated
+ * user data that happens to share the `.lock` name. A read error other than "no
+ * such file" (e.g. EACCES) propagates instead of being silently swallowed. */
 function dropOwnLock(lockPath) {
-    let contents;
-    try {
-        contents = readFileSync(lockPath, "utf8");
-    }
-    catch {
-        return; // no lock file to drop
-    }
-    if (!contents.startsWith(SENTINEL)) {
+    if (!existsSync(lockPath))
+        return; // nothing to drop
+    const contents = readFileSync(lockPath, "utf8");
+    if (contents !== "" && !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/run.js

@@ -140,6 +140,10 @@ function remove({ path, args, io, force }) {
         io.err("missing <key>");
         return 2;
     }
+    if (isReservedKey(key)) {
+        io.err(`refusing to delete a reserved key: ${key}`);
+        return 2;
+    }
     return withWriteDb(path, force, (db) => {
         const { changed } = kv(db).delete(key);
         io.out(`delete ${key} (${changed} removed)`);
@@ -152,7 +156,17 @@ function importKeys({ path, args, io, force }) {
         io.err("missing <file>");
         return 2;
     }
-    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    const raw = readFileSync(file, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Malformed JSON is bad input, not a runtime fault — report it like the other
+        // usage errors (exit 2) instead of letting it fall through to exit 1.
+        io.err("import expects a file containing a JSON object of string values");
+        return 2;
+    }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
         io.err("import expects a JSON object of string values");
         return 2;
@@ -180,16 +194,17 @@ function importKeys({ path, args, io, force }) {
         return 0;
     });
 }
-/** The commands, keyed by name. Each takes the parsed {@link Ctx}. */
-const commands = {
-    inspect,
-    stats,
-    get,
-    scan,
-    set,
-    delete: remove,
-    import: importKeys,
-};
+/** The commands, keyed by name. A Map (not a plain object) so an inherited
+ * property name like "toString" or "__proto__" can never resolve to a handler. */
+const commands = new Map([
+    ["inspect", inspect],
+    ["stats", stats],
+    ["get", get],
+    ["scan", scan],
+    ["set", set],
+    ["delete", remove],
+    ["import", importKeys],
+]);
 export function run(argv, io) {
     let positionals;
     let values;
@@ -211,7 +226,7 @@ export function run(argv, io) {
         return 0;
     }
     const command = positionals[0];
-    const handler = commands[command];
+    const handler = commands.get(command);
     if (handler === undefined) {
         io.err(`unknown command: ${command}`);
         return 2;

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.1.2";
+export declare const version = "0.1.3";
 /**
  * A key in the kernel: an immutable sequence of bytes.
  *
@@ -134,12 +134,13 @@ export interface WalFile {
 export interface OpenOptions {
     readonly path?: string;
     /**
-     * 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).
+     * The filesystem the write-ahead log runs on. Optional at the type level, but a
+     * path-backed open needs one at runtime: the kernel and the browser entry throw
+     * when `path` is given without `fs`, while the Node entry (index.ts) supplies a
+     * `node:fs` adapter by default so `open({ path })` works there. 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

@@ -20,7 +20,7 @@
  * and discards any record a crash left half-written.
  */
 /** The LibreDB package version. Kept in sync with package.json. */
-export const version = "0.1.2";
+export const version = "0.1.3";
 /**
  * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libredb/libredb",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A small, readable, embeddable, multi-model database. One ordered key-value core, thin model lenses on top.",
   "keywords": [
     "database",