@orkestrel/database 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+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,36 @@
+# @orkestrel/database
+
+A typed database abstraction for the `@orkestrel` line — a single
+environment-agnostic core engine (`Database`, `Table`, `Query`, `Cursor`,
+`Clause`) over pluggable storage drivers at the seams. Built to sit beside
+`@orkestrel/contract` (validation) and `@orkestrel/emitter` (observable
+lifecycle), reusing both as it takes shape.
+
+## Install
+
+```sh
+npm install @orkestrel/database
+```
+
+## Requirements
+
+- Node.js >= 24
+- Core is ESM; the `./server` subpath ships a CommonJS build
+
+## Status
+
+Pre-release (`0.0.1`): the core engine and the memory and JSON file drivers
+are implemented and tested, but the public API is still unstable and may
+change without notice. See [guides/src/database.md](./guides/src/database.md)
+for the full documented surface.
+
+## Package
+
+Published as two environment-scoped entry points per the `exports` field in
+`package.json`: a shared core (with the in-memory driver) and `./server` (the
+JSON file driver). IndexedDB and SQLite drivers are planned once their
+backing packages exist.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

package/dist/src/core/Clause.d.ts

@@ -0,0 +1,30 @@
+import type { FieldPath } from '@orkestrel/contract';
+import type { Condition, Connector, QueryInterface, ClauseInterface } from './types.js';
+/**
+ * A pending condition opened by a query's `where` / `and` / `or`.
+ *
+ * @remarks
+ * Holds the column, the connector that will join this condition to the ones
+ * before it, and a recorder the owning query supplies. Each operator builds the
+ * {@link Condition}, hands it to the recorder, and returns the query — so the
+ * fluent chain flows straight back into the builder without exposing a mutator.
+ */
+export declare class Clause<T = Record<string, unknown>> implements ClauseInterface<T> {
+    #private;
+    constructor(record: (condition: Condition) => QueryInterface<T>, column: FieldPath, connector: Connector);
+    equals(value: unknown): QueryInterface<T>;
+    not(value: unknown): QueryInterface<T>;
+    above(value: unknown): QueryInterface<T>;
+    below(value: unknown): QueryInterface<T>;
+    from(value: unknown): QueryInterface<T>;
+    to(value: unknown): QueryInterface<T>;
+    between(lower: unknown, upper: unknown): QueryInterface<T>;
+    like(pattern: string): QueryInterface<T>;
+    glob(pattern: string): QueryInterface<T>;
+    starts(prefix: string): QueryInterface<T>;
+    ends(suffix: string): QueryInterface<T>;
+    any(values: readonly unknown[]): QueryInterface<T>;
+    none(values: readonly unknown[]): QueryInterface<T>;
+    absent(): QueryInterface<T>;
+    present(): QueryInterface<T>;
+}

package/dist/src/core/Cursor.d.ts

@@ -0,0 +1,21 @@
+import type { CursorInterface, Key, TableInterface } from './types.js';
+/**
+ * A forward row cursor for bulk in-place mutation.
+ *
+ * @remarks
+ * Iterates a snapshot of the table's keys captured when the cursor was opened,
+ * reading each row lazily through the owning table — so a mutation made during
+ * iteration cannot corrupt the walk, and a key removed mid-iteration is simply
+ * skipped. `update` and `remove` act on the row at the current position.
+ */
+export declare class Cursor<T = Record<string, unknown>> implements CursorInterface<T> {
+    #private;
+    constructor(table: TableInterface<T>, keys: readonly Key[]);
+    get value(): T | undefined;
+    get index(): number;
+    get done(): boolean;
+    next(): Promise<void>;
+    update(changes: Partial<T>): Promise<void>;
+    remove(): Promise<void>;
+    close(): void;
+}

package/dist/src/core/Database.d.ts

@@ -0,0 +1,80 @@
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { DatabaseEventMap, DatabaseInterface, DatabaseOptions, DatabaseStatus, Migration, ReadOptions, RowOf, TableExport, TableInterface, TableKeys, TableSchema, TablesShape } from './types.js';
+/**
+ * A database — the ergonomic entry point over a {@link DriverInterface}.
+ *
+ * @remarks
+ * Owns the driver and a `tables` shape map, connecting the driver lazily on first
+ * use so a freshly created database is immediately usable. `table(name)` returns
+ * a table typed by that table's shape `Infer`. `import` registers more tables and
+ * returns a database re-typed with them over the **same** driver and storage;
+ * `export` emits a portable {@link TableExport} per table. `transaction` snapshots
+ * the driver, runs the scope, and rolls every table back if it throws — an
+ * optimistic model that works uniformly across backends rather than reconciling
+ * SQL's and IndexedDB's incompatible native transactions.
+ *
+ * @remarks
+ * - **Versioned (optional).** When {@link DatabaseOptions.version} is set and the driver
+ *   implements both {@link DriverInterface.meta} and {@link DriverInterface.stamp},
+ *   `open()` reconciles the driver's persisted {@link DriverMeta} against the declared
+ *   version INSIDE the same lazy-connect chain, AFTER the `open` event fires — see
+ *   {@link DatabaseOptions.version} for the full reconciliation contract.
+ * - **Observable (§13).** The owned {@link emitter} ({@link DatabaseEventMap}) carries the
+ *   connection + transaction lifecycle — `open` / `close` / `transaction` / `commit` /
+ *   `rollback` — for fire-and-forget observers, ALONGSIDE each table's per-row events. Every
+ *   event is emitted directly, strictly AFTER the relevant transition: `commit` only after
+ *   the scope succeeds, `rollback` only after every table is restored. The `rollback` emit
+ *   OBSERVES the propagated error — it never swallows it (the original throw propagates
+ *   exactly as before). The emitter isolates a listener throw and routes it to its `error`
+ *   handler (the `error` option), so observation can never reorder, throw into, or corrupt
+ *   the snapshot / commit / rollback flow.
+ */
+export declare class Database<T extends TablesShape = TablesShape> implements DatabaseInterface<T> {
+    #private;
+    constructor(options: DatabaseOptions<T>);
+    get emitter(): EmitterInterface<DatabaseEventMap>;
+    get name(): string;
+    get status(): DatabaseStatus;
+    table<K extends keyof T & string>(name: K): TableInterface<RowOf<T[K]>>;
+    import<U extends TablesShape>(tables: U, keys?: TableKeys): DatabaseInterface<U>;
+    export(): Readonly<Record<string, TableExport>>;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Run `scope` transactionally: commit its writes on success, roll every table
+     * back if it throws.
+     *
+     * @remarks
+     * When the driver implements the optional native {@link DriverInterface.transaction}
+     * hook, that native `commit` / `rollback` handle drives the transaction; otherwise
+     * the universal snapshot floor (`driver.snapshot()`) runs unchanged. Either path
+     * emits the same `transaction` / `commit` / `rollback` lifecycle (AGENTS §13).
+     * `options.signal` is checked ONCE at entry, before connecting or starting any
+     * transactional work — an already-aborted signal throws `ABORTED` and neither the
+     * native hook nor the snapshot floor is invoked. Nesting is unguarded and
+     * unsupported exactly as before: this is a single-writer model, not reentrant.
+     * On the native path, a `scope` throw rolls back via the native handle; a
+     * native `commit` failure propagates as-is with no rollback attempt — the
+     * engine owns transaction state after a failed COMMIT.
+     *
+     * @param scope - The transactional work to run
+     * @param options - `{ signal }` to abort before the transaction starts
+     * @returns The scope's resolved value
+     * @throws An `ABORTED` {@link DatabaseError} when `options.signal` has already fired
+     */
+    transaction<R>(scope: () => Promise<R>, options?: ReadOptions): Promise<R>;
+    /**
+     * Diff `deployed` against this database's declared schema and apply the
+     * resulting plan through the driver's optional `migrate` hook.
+     *
+     * @param deployed - The schema currently deployed, as {@link TableSchema}s
+     * @param options - `{ signal }` to abort before the migration starts
+     * @returns The applied {@link Migration} plan
+     * @throws A `MIGRATION` {@link DatabaseError} when the driver does not
+     * implement `migrate`, or when a step references an unknown table
+     * (propagated from the driver)
+     * @throws An `ABORTED` {@link DatabaseError} when `options.signal` has
+     * already fired at entry
+     */
+    migrate(deployed: readonly TableSchema[], options?: ReadOptions): Promise<Migration>;
+}

package/dist/src/core/Query.d.ts

@@ -0,0 +1,47 @@
+import type { FieldPath } from '@orkestrel/contract';
+import type { AggregateFunction, ClauseInterface, QueryInterface, ReadOptions, TableInterface } from './types.js';
+/**
+ * A fluent query builder bound to one table.
+ *
+ * @remarks
+ * Accumulates conditions, ordering, JS filters, and a page; each builder method
+ * mutates and returns the same instance, so a chain reads as one statement. The
+ * portable parts (conditions, order, page) compile into a {@link Criteria} the
+ * table resolves; a `filter` predicate is applied in memory after the read and
+ * before paging, so it composes with the rest without a backend ever seeing a
+ * JS callback.
+ */
+export declare class Query<T = Record<string, unknown>> implements QueryInterface<T> {
+    #private;
+    constructor(table: TableInterface<T>);
+    where(column: FieldPath): ClauseInterface<T>;
+    and(column: FieldPath): ClauseInterface<T>;
+    or(column: FieldPath): ClauseInterface<T>;
+    filter(predicate: (row: T) => boolean): QueryInterface<T>;
+    ascending(column: FieldPath): QueryInterface<T>;
+    descending(column: FieldPath): QueryInterface<T>;
+    limit(count: number): QueryInterface<T>;
+    offset(count: number): QueryInterface<T>;
+    all(): Promise<readonly T[]>;
+    first(): Promise<T | undefined>;
+    count(): Promise<number>;
+    /**
+     * Lazy per-row evaluation of this query's conditions / filters / offset /
+     * limit.
+     *
+     * @remarks
+     * `order` and its comparators are IGNORED (streaming yields unsorted, as rows
+     * are evaluated one at a time). Same abort semantics as
+     * `TableInterface.scan`: the signal (if any) is checked before each yield,
+     * and breaking out early closes the underlying source.
+     *
+     * @param options - `signal` to cancel the iteration; checked before each yield
+     * @returns An async iterable of matching rows
+     */
+    stream(options?: ReadOptions): AsyncGenerator<T>;
+    aggregate(operation: AggregateFunction, column: FieldPath): Promise<number | undefined>;
+    sum(column: FieldPath): Promise<number | undefined>;
+    average(column: FieldPath): Promise<number | undefined>;
+    minimum(column: FieldPath): Promise<number | undefined>;
+    maximum(column: FieldPath): Promise<number | undefined>;
+}

package/dist/src/core/Table.d.ts

@@ -0,0 +1,69 @@
+import type { ContractInterface, FieldPath } from '@orkestrel/contract';
+import type { EmitterErrorHandler, EmitterHooks, EmitterInterface } from '@orkestrel/emitter';
+import type { AggregateFunction, Criteria, CursorInterface, DriverInterface, Key, KeyFunction, QueryInterface, ReadOptions, Row, TableEventMap, TableInterface } from './types.js';
+/**
+ * A table — typed keyed CRUD plus fluent query and cursor access over a driver.
+ *
+ * @remarks
+ * The table's contract is the load-bearing piece: writes go through `parse`
+ * (coercing inputs and rejecting rows that don't fit with a `VALIDATION` throw),
+ * reads come back through the contract guard (narrowing a stored {@link Row} to
+ * the table's type — no assertion, AGENTS §1), and `contract` is exposed for
+ * introspection and seeding. The driver only stores and scans; all querying is
+ * the shared core engine in `helpers.ts`.
+ *
+ * @remarks
+ * - **Observable (§13).** The owned {@link emitter} ({@link TableEventMap}) carries the
+ *   per-row mutation moments — `write` (set / add / update), `remove`, `clear` — for
+ *   fire-and-forget observers (cache invalidation, sync, an audit log), ALONGSIDE the
+ *   database-level lifecycle. Events carry the affected KEY only (no value payload, to
+ *   keep fan-out lean); reads / queries / counts are not emitted. Every event is emitted
+ *   directly, strictly AFTER the driver write / delete / clear completes; the emitter
+ *   isolates a listener throw and routes it to its `error` handler (the `error` option),
+ *   so a buggy observer can never corrupt a write or perturb a transaction.
+ */
+export declare class Table<T = Row> implements TableInterface<T> {
+    #private;
+    constructor(ready: () => Promise<void>, driver: DriverInterface, name: string, key: string, contract: ContractInterface<T>, generate?: KeyFunction, on?: EmitterHooks<TableEventMap>, error?: EmitterErrorHandler);
+    get emitter(): EmitterInterface<TableEventMap>;
+    get name(): string;
+    get primary(): string;
+    get contract(): ContractInterface<T>;
+    get(key: Key): Promise<T | undefined>;
+    get(keys: readonly Key[]): Promise<readonly (T | undefined)[]>;
+    resolve(key: Key): Promise<T>;
+    resolve(keys: readonly Key[]): Promise<readonly T[]>;
+    has(key: Key): Promise<boolean>;
+    has(keys: readonly Key[]): Promise<readonly boolean[]>;
+    keys(): Promise<readonly Key[]>;
+    records(criteria?: Criteria, options?: ReadOptions): Promise<readonly T[]>;
+    count(criteria?: Criteria, options?: ReadOptions): Promise<number>;
+    aggregate(operation: AggregateFunction, column: FieldPath, criteria?: Criteria, options?: ReadOptions): Promise<number | undefined>;
+    /**
+     * Stream the table's rows matching `criteria`, applying offset/limit paging.
+     *
+     * @remarks
+     * `criteria.limit` counts rows that pass BOTH the criteria conditions AND the
+     * table's contract guard (a stored row that fails the guard is skipped and
+     * does not count toward `limit`) — this can differ from {@link records}'s
+     * `limit`, which a driver's optional native `records` hook applies BEFORE
+     * the contract guard runs, when storage holds rows that no longer conform
+     * to the table's contract.
+     *
+     * @param criteria - Optional conditions plus offset/limit paging
+     * @param options - `{ signal }` to abort mid-stream
+     * @returns An async generator of matching, guard-conforming rows
+     */
+    scan(criteria?: Criteria, options?: ReadOptions): AsyncGenerator<T>;
+    set(row: T, options?: ReadOptions): Promise<Key>;
+    set(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
+    add(row: T, options?: ReadOptions): Promise<Key>;
+    add(rows: readonly T[], options?: ReadOptions): Promise<readonly Key[]>;
+    update(key: Key, changes: Partial<T>, options?: ReadOptions): Promise<boolean>;
+    update(keys: readonly Key[], changes: Partial<T>, options?: ReadOptions): Promise<readonly boolean[]>;
+    remove(key: Key, options?: ReadOptions): Promise<boolean>;
+    remove(keys: readonly Key[], options?: ReadOptions): Promise<readonly boolean[]>;
+    clear(): Promise<void>;
+    query(): QueryInterface<T>;
+    cursor(): Promise<CursorInterface<T>>;
+}

package/dist/src/core/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The primary-key column assumed when {@link TableKeys} does not name one.
+ *
+ * @remarks
+ * `id` is the convention IndexedDB (`keyPath: 'id'`) and SQL (`id` / rowid) both
+ * lean on, so a table that omits `key` keys its rows by `id`.
+ */
+export declare const DEFAULT_PRIMARY = "id";
+/**
+ * The longest `LIKE` / `GLOB` pattern the wildcard matcher accepts before rejecting it.
+ *
+ * @remarks
+ * A ReDoS bound (AGENTS §6.5): the SA1–SA4 migration lets a model supply `list`
+ * criteria over the wire, so `likeMatch` / `globMatch` run attacker-controlled
+ * patterns. The matcher is the LINEAR greedy two-pointer wildcard match — never a
+ * backtracking regex (`.*`-segments-separated-by-literals against a long input is the
+ * catastrophic shape JS cannot bound without atomic groups), so it is O(value ×
+ * pattern). Capping the pattern length bounds that pattern factor, leaving a match
+ * linear in the value length whatever the pattern. A longer pattern throws a
+ * `VALIDATION` {@link DatabaseError}; the cap is generous for any legitimate search.
+ */
+export declare const MAX_PATTERN_LENGTH = 1024;

package/dist/src/core/drivers/MemoryDriver.d.ts

@@ -0,0 +1,94 @@
+import type { Criteria, DriverInterface, DriverMeta, Key, Migration, Row, TableSchema } from '../types.js';
+/**
+ * The reference {@link DriverInterface} — nested maps, no I/O.
+ *
+ * @remarks
+ * The in-between made concrete: it runs identically in a browser or on a server,
+ * so it is the storage behind tests, ephemeral caches, and any code that wants
+ * the database API without a persistent backend. Rows are copied in and out so a
+ * caller can never mutate stored state by reference (AGENTS §11), and `snapshot`
+ * clones every table to give transactions an exact rollback point. `scan` and
+ * `keys` yield in key order — sorted by the core {@link compareValues} total
+ * order, the same contract the SQLite (`ORDER BY`) and IndexedDB (key-ordered
+ * reads) backends honor, so an unordered read agrees across every backend rather
+ * than leaking Map insertion order. A persistent backend (IndexedDB, SQLite)
+ * implements the same nine methods over real storage.
+ */
+export declare class MemoryDriver implements DriverInterface {
+    #private;
+    open(schema: readonly TableSchema[]): Promise<void>;
+    close(): Promise<void>;
+    read(table: string, key: Key): Promise<Row | undefined>;
+    write(table: string, key: Key, row: Row): Promise<void>;
+    delete(table: string, key: Key): Promise<boolean>;
+    keys(table: string): Promise<readonly Key[]>;
+    scan(table: string): AsyncIterable<Row>;
+    /**
+     * Natively filtered lazy iteration — the {@link DriverInterface.stream} hook.
+     *
+     * @remarks
+     * Iterates the table's keys in the same key order `scan` and `keys` yield
+     * (sorted by {@link compareValues}), testing each row against
+     * `criteria.conditions` (via {@link matchesCriteria}) before counting it
+     * toward `offset` / `limit`. Both are applied lazily as matches are found —
+     * `offset` matches are skipped without being yielded, and iteration stops the
+     * instant `limit` yields have been produced, so a large table is never fully
+     * walked for a small page. `criteria.order` is IGNORED (the same contract as
+     * `TableInterface.scan` and `QueryInterface.stream`): streaming yields key
+     * order, sorted output is `records()`'s job. Rows yield copy-out (AGENTS
+     * §11), and an unknown table mirrors `scan`'s empty-yield behavior.
+     *
+     * @param table - The table to stream
+     * @param criteria - The filter / offset / limit to apply lazily
+     *
+     * @example
+     * ```ts
+     * for await (const row of driver.stream('users', { conditions, limit: 10 })) {
+     *   // one matched row at a time, in key order
+     * }
+     * ```
+     */
+    stream(table: string, criteria: Criteria): AsyncIterable<Row>;
+    clear(table: string): Promise<void>;
+    /**
+     * Capture the current state and return a thunk that rolls back to it.
+     *
+     * @remarks
+     * `tables` omitted clones and restores the WHOLE store, byte-identical to the
+     * prior whole-store behavior. `tables` provided clones ONLY the named tables,
+     * and the returned thunk restores ONLY those — every other table keeps
+     * whatever it was mutated to after the snapshot was taken.
+     *
+     * @param tables - The table names to scope the snapshot to; omitted captures every table
+     * @returns A thunk that restores the captured tables
+     */
+    snapshot(tables?: readonly string[]): Promise<() => Promise<void>>;
+    /**
+     * Return the persisted {@link DriverMeta}, or `undefined` when the store has
+     * never been stamped.
+     *
+     * @remarks
+     * In-process only — the metadata lives in this instance's memory, exactly
+     * like the rest of this driver's storage. A driver-conformance-valid
+     * implementation of the optional `meta` / `stamp` pair.
+     *
+     * @returns The last-stamped {@link DriverMeta}, or `undefined`
+     */
+    meta(): Promise<DriverMeta | undefined>;
+    /**
+     * Persist `meta` verbatim for a later `meta()` to return.
+     *
+     * @param meta - The {@link DriverMeta} to persist
+     */
+    stamp(meta: DriverMeta): Promise<void>;
+    /**
+     * Apply a {@link Migration} plan's steps against the in-memory store.
+     *
+     * @remarks
+     * A multi-step plan applies its steps sequentially and is NOT atomic — a
+     * failure partway through a plan leaves the earlier steps already applied.
+     *
+     * @param plan - The migration plan to apply
+     */
+    migrate(plan: Migration): Promise<void>;
+}

package/dist/src/core/errors.d.ts

@@ -0,0 +1,38 @@
+import type { DatabaseErrorCode } from './types.js';
+/**
+ * An error thrown by the database layer.
+ *
+ * @remarks
+ * Carries a {@link DatabaseErrorCode} and an optional `context` bag naming the
+ * offending table / key. Thrown for: operating on a closed database (`CLOSED`), a
+ * `resolve` miss (`NOT_FOUND`), an `add` onto an existing key (`CONFLICT`), a
+ * row that fails its table's contract (`VALIDATION`), a cancelled operation whose
+ * {@link ReadOptions.signal} aborted (`ABORTED`, carrying `signal.reason` in
+ * `context`), an inapplicable {@link Migration} plan (`MIGRATION`), a
+ * driver that violates a {@link DriverInterface} invariant, thrown by the
+ * `conformDriver` helper (`CONFORMANCE`), and an unexpected infrastructure
+ * fault surfaced by a driver seam — e.g. a filesystem failure while
+ * persisting (`DRIVER`) — as opposed to expected domain conditions, which
+ * keep their specific codes.
+ */
+export declare class DatabaseError extends Error {
+    readonly code: DatabaseErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: DatabaseErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Narrow an unknown caught value to a {@link DatabaseError}.
+ *
+ * @param value - The value to test (typically a `catch` binding)
+ * @returns `true` when `value` is a {@link DatabaseError}
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	await users.add(row)
+ * } catch (error) {
+ * 	if (isDatabaseError(error) && error.code === 'CONFLICT') await users.set(row)
+ * }
+ * ```
+ */
+export declare function isDatabaseError(value: unknown): value is DatabaseError;

package/dist/src/core/factories.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseInterface, DatabaseOptions, DriverInterface, TablesShape } from './types.js';
+/**
+ * Create a database over a driver and a declared `tables` schema.
+ *
+ * @remarks
+ * `tables` maps each name to its columns (a `column → shape` map); the database
+ * wraps each in an `objectShape`, so you never write `objectShape` at the table
+ * level. The `const` type parameter captures the literal names and columns, so
+ * `db.table('users')` is checked against the schema and typed by `Infer` of its
+ * columns — no annotations. Name a non-`id` primary-key column per table via the
+ * optional `keys` map.
+ *
+ * @param options - The driver, the `tables` column map, optional `keys`, and an
+ *                   optional `name`
+ * @returns A typed {@link DatabaseInterface}
+ *
+ * @example
+ * ```ts
+ * import { createDatabase, createMemoryDriver } from '@orkestrel/database'
+ * import { integerShape, stringShape } from '@orkestrel/contract'
+ *
+ * const db = createDatabase({
+ * 	driver: createMemoryDriver(),
+ * 	tables: {
+ * 		users: { id: stringShape(), age: integerShape() },
+ * 		posts: { slug: stringShape(), title: stringShape() },
+ * 	},
+ * 	keys: { posts: 'slug' },
+ * })
+ * await db.table('users').set({ id: 'u1', age: 36 }) // typed; coerced + validated
+ * ```
+ */
+export declare function createDatabase<const T extends TablesShape>(options: DatabaseOptions<T>): DatabaseInterface<T>;
+/**
+ * Create the in-memory reference {@link DriverInterface}.
+ *
+ * @remarks
+ * Backed by nested maps with no I/O — the same driver runs in a browser or on a
+ * server, making it the natural choice for tests and ephemeral storage.
+ *
+ * @returns A fresh in-memory driver
+ */
+export declare function createMemoryDriver(): DriverInterface;