@libredb/libredb 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LibreDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# 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.
+
+**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 } },
+// ]
+```
+
+`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"`:
+
+```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()`.
+
+## 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:
+
+```ts
+import { open, table } from "libredb";
+
+const db = open(); // or open({ path: "data.libredb" }) for durability
+
+const users = table(db, "users", {
+  primaryKey: "id",
+  columns: { id: "string", name: "string", age: "number", active: "boolean" },
+});
+
+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
+
+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.
+
+## Read first
+
+- [`MANIFESTO.md`](./MANIFESTO.md) — what LibreDB is and what it refuses to be.
+- [`DESIGN.md`](./DESIGN.md) — the engineering decision record behind the manifesto.
+
+## License
+
+Open source and free under the MIT License.

package/dist/adapter/store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * adapter/store.ts — the storage seam a lens depends on.
+ *
+ * This is an edge, not the kernel: the open, fast-contribution tier (DESIGN.md
+ * section 5), holding no durability logic of its own. It names the one thing a
+ * lens needs from storage and nothing more.
+ *
+ * A lens (kv, and later document, relational) is a view over stored bytes. It
+ * reads and writes through transactions; it never opens, closes, or recovers the
+ * store — that lifecycle belongs to whoever called {@link import("../core.ts").open}.
+ * So the seam the lens depends on is exactly one method, `transact`, deliberately
+ * NARROWER than the kernel's {@link import("../core.ts").Database} (which also
+ * carries `close`). Depending on the narrow port instead of the whole Database
+ * keeps the open-edge lenses from binding to the guarded core's lifecycle, and
+ * lets any object that can run a transaction back a lens: the kernel today, an
+ * async-wrapped or remote core later, a fake in a test. The kernel's `Database`
+ * satisfies this port structurally, so the real, durable path runs through it.
+ *
+ * This is intentionally thin. The seam is a port the lens needs, not an
+ * abstraction layer the user pays for — there is no adapter class to subclass,
+ * just the minimal contract.
+ */
+import type { Transaction } from "../core.ts";
+/**
+ * The minimal storage capability a lens consumes: run a unit of atomic work and
+ * return its result. Semantics are the kernel's — see
+ * {@link import("../core.ts").Database.transact}.
+ */
+export interface Store {
+    transact<T>(run: (tx: Transaction) => T): T;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/adapter/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/adapter/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,CAAC,GAAG,CAAC,CAAC;CAC7C"}

package/dist/adapter/store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=store.js.map

package/dist/adapter/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/adapter/store.ts"],"names":[],"mappings":""}

package/dist/core.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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.
+ */
+/** The LibreDB package version. Kept in sync with package.json. */
+export declare const version = "0.0.1";
+/**
+ * A key in the kernel: an immutable sequence of bytes.
+ *
+ * Keys are bytes, not strings, on purpose. Byte order is unambiguous and
+ * stable (unlike JavaScript's UTF-16 string order), and only bytes let the
+ * higher lenses build COMPOSITE keys by concatenation and scan them as ranges
+ * — the move the whole multi-model architecture rests on. The kv lens adds
+ * string ergonomics on top; the kernel stays at the honest substrate.
+ */
+export type Key = Uint8Array;
+/** A value in the kernel: an opaque sequence of bytes. The kernel never
+ * interprets a value; serialization is a lens concern, not a kernel one. */
+export type Value = Uint8Array;
+/** One key/value pair yielded by an ordered range scan. */
+export interface Entry {
+    readonly key: Key;
+    readonly value: Value;
+}
+/**
+ * The unit of atomic work against the kernel.
+ *
+ * Every read and write happens inside a transaction — it is the kernel's one
+ * atomicity primitive. Within a transaction, reads observe the transaction's
+ * own pending writes (read-your-writes). Across transactions the isolation
+ * level is SERIALIZABLE: the synchronous, single-threaded API runs each body to
+ * completion before the next begins, so the schedule is always serial. The
+ * kernel forbids re-entrant transactions (the only way to overlap two) to keep
+ * that guarantee real — see {@link Database.transact}.
+ *
+ * Keys are ordered by unsigned byte-lexicographic comparison. That ordering is
+ * the kernel's defining property: it is what makes `getRange` meaningful and
+ * what later lenses encode their indexes against.
+ */
+export interface Transaction {
+    /** The value for `key`, or `undefined` if it is not set. */
+    get(key: Key): Value | undefined;
+    /** Set `key` to `value`, overwriting any existing value. */
+    set(key: Key, value: Value): void;
+    /** Remove `key`. A no-op if it is not set. */
+    delete(key: Key): void;
+    /**
+     * Scan the half-open range `[start, end)` in ascending key order:
+     * `start` is included, `end` is excluded. Lazy by design — callers iterate
+     * without the kernel materializing the whole range.
+     */
+    getRange(start: Key, end: Key): Iterable<Entry>;
+}
+/**
+ * An open kernel instance: the storage substrate plus its durability.
+ *
+ * The API is synchronous. LibreDB is embedded and single-process (its first
+ * home is test/dev), and SQLite shows a synchronous core is both correct and
+ * far easier to read than one colored by promises everywhere. Durability uses
+ * synchronous fsync (see the write-ahead log further down).
+ */
+export interface Database {
+    /**
+     * Run `run` inside a transaction and apply its writes atomically. If `run`
+     * returns, the writes commit together and become durable; if `run` throws,
+     * the transaction aborts and applies nothing. The return value of `run` is
+     * passed through.
+     */
+    transact<T>(run: (tx: Transaction) => T): T;
+    /** Flush pending state and release resources. Safe to call once. */
+    close(): void;
+}
+/**
+ * How to open a kernel instance.
+ *
+ * With `path`, the kernel is file-backed and durable: reopening the same path
+ * after a crash reconstructs exactly the committed state. Without `path`, the
+ * kernel is purely in-memory — the natural fit for tests and ephemeral use.
+ */
+export interface OpenOptions {
+    readonly path?: string;
+}
+/** The signature of the kernel's entry point (see {@link open} for the
+ * implementation). Naming the contract separately lets lenses depend on it. */
+export type Open = (options?: OpenOptions) => Database;
+/**
+ * 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 declare const open: Open;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,mEAAmE;AACnE,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,MAAM,GAAG,GAAG,UAAU,CAAC;AAE7B;4EAC4E;AAC5E,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAE/B,2DAA2D;AAC3D,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,GAAG,SAAS,CAAC;IACjC,4DAA4D;IAC5D,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAClC,8CAA8C;IAC9C,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5C,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;+EAC+E;AAC/E,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,QAAQ,CAAC;AAwSvD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,EAAE,IA0DlB,CAAC"}