@libredb/libredb 0.0.2 → 0.0.3

package/README.md

@@ -272,6 +272,18 @@ registry.get("logs");
 
 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.
 
+A tool that renders the raw `kv` layer (so it sees everything, including the catalog) should hide those engine-internal keys. Rather than hardcode the byte layout, import the contract: `isReservedKey(key)` is true for any key in the reserved namespace, and `RESERVED_MARKER` / `CATALOG_PREFIX` are the underlying constants if you need to build a range.
+
+```ts
+import { open, kv, isReservedKey } from "libredb";
+
+const db = open();
+// ... user writes through doc/table, which also write catalog entries ...
+
+const visible = kv(db).range("", "￿").toArray().filter((e) => !isReservedKey(e.key));
+// only user keys; catalog entries (under the reserved marker) are filtered out
+```
+
 ## Reliability — deterministic simulation testing
 
 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.

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.3";
 /**
  * A key in the kernel: an immutable sequence of bytes.
  *

package/dist/core.js

@@ -21,7 +21,7 @@
  */
 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.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/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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libredb/libredb",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A small, readable, embeddable, multi-model database. One ordered key-value core, thin model lenses on top.",
   "type": "module",
   "license": "MIT",