@bitcobblers/wod-wiki-storage 0.0.0-stage → 0.35.2116

package/dist/sql/index.d.cts

@@ -0,0 +1,220 @@
+import { Client } from '@libsql/client';
+import { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, E as TxOp, I as IStorage, S as StoreName, b as IReadOnlyStore, c as StoreType, d as IReadWriteStore, D as DomainQuery, f as IStorageTransaction } from '../wire-C7ZtlBKe.cjs';
+import '@bitcobblers/wod-wiki-core';
+import '@bitcobblers/wod-wiki-lang';
+
+/**
+ * StorageError — the single error type every shared SQL layer throws.
+ * Replaces the API server's HTTP-specific error: `status` keeps the wire
+ * mapping for the HTTP surface, `code` carries a stable machine identifier
+ * (e.g. 'domain_projection_unavailable') for browser callers.
+ */
+declare class StorageError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+
+/**
+ * Connection contracts + a generic libsql adapter. The adapter takes a
+ * *structural* client so the browser passes @libsql/client/web and the server
+ * passes @libsql/client (node) — this module never imports either, keeping
+ * the browser graph free of native drivers.
+ *
+ * All operations are serialized through one promise chain: the underlying
+ * client shares a single connection, so concurrent transactions/reads could
+ * otherwise interleave on it. Transactions run on a transaction-owned
+ * connection (libsql interactive transaction), so writes inside a transaction
+ * commit or roll back atomically and are not visible outside it.
+ */
+
+type SqlValue = string | number | null;
+type SqlRow = Record<string, unknown>;
+interface SqlConnection {
+    query(sql: string, params?: SqlValue[]): Promise<SqlRow[]>;
+    exec(sql: string, params?: SqlValue[]): Promise<void>;
+}
+interface Database extends SqlConnection {
+    readonly dialect: 'sqlite' | 'postgres';
+    transaction<T>(fn: (tx: SqlConnection) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Minimal surface used from a libsql client (node or web build) — the real
+ * @libsql/client types, type-only so the browser graph stays driver-free. */
+type LibsqlClient = Pick<Client, 'execute' | 'transaction' | 'close'>;
+/** Wrap a libsql client (node or web build) into the shared Database surface. */
+declare function libsqlDatabase(client: LibsqlClient): Database;
+
+/**
+ * Row codec for the SQL `data` column. Plain JSON.stringify destroys
+ * ArrayBuffer values ({}); attachment rows carry raw blobs, so encoding tags
+ * the declared binary field and decoding revives it.
+ *
+ * Collision safety: tagging applies ONLY to the declared binary field of the
+ * declared store (attachments.data) — arbitrary rows (meta, notes, …) are
+ * plain JSON in both directions, so authored {$binary:…}-shaped objects
+ * anywhere else round-trip byte-for-byte. Within attachments.data the value
+ * is typed `ArrayBuffer | string`; strings pass through, and only the exact
+ * two-key tag revives.
+ */
+/** Serialize a row; when `binaryField` is set and holds an ArrayBuffer, it is
+ * replaced by the lossless tag (shallow copy — the input row is untouched). */
+declare function encodeRowJson(value: unknown, binaryField?: string): string;
+/** Parse a row; when `binaryField` is set, a tagged value there revives as an
+ * ArrayBuffer. Every other value — including tag-shaped data in other fields
+ * or stores — is returned exactly as authored. */
+declare function decodeRowJson<T = unknown>(text: string, binaryField?: string): T;
+
+/**
+ * Schema-driven store operations: IDB-style stores persisted into SQL tables
+ * (one per store, extracted key/index columns + full JSON in `data`). The
+ * schema derives entirely from STORE_DEFS / COLUMN_TYPES; JSON payloads stay
+ * the source of truth. Shared by the API server and the browser
+ * BrowserTursoStorage/SqlStorage backends.
+ */
+
+declare const SCHEMA_TABLE = "_wodwiki_schema";
+declare function storeDefinition(name: string): StoreDef;
+declare function getRow(conn: SqlConnection, def: StoreDef, key: KeyDTO): Promise<unknown | undefined>;
+declare function listRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, count?: number, indexName?: string): Promise<unknown[]>;
+declare function countRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, indexName?: string): Promise<number>;
+declare function putRow(conn: SqlConnection, def: StoreDef, value: unknown): Promise<KeyDTO>;
+declare function deleteRows(conn: SqlConnection, def: StoreDef, keyOrRange: KeyDTO | RangeDTO): Promise<void>;
+declare function clearRows(conn: SqlConnection, def: StoreDef): Promise<void>;
+/** Wipe all user stores; system stores (memberships) survive and the internal
+ * schema metadata table is not a store, so the version guard is untouched. */
+declare function wipeRows(conn: SqlConnection): Promise<void>;
+/** Internal schema metadata is not exposed or cleared by the store API. */
+declare function initializeStore(db: Database): Promise<void>;
+
+/**
+ * Domain read models + incremental projection refresh over the shared SQL
+ * store tables.
+ *
+ * Three derived tables, rebuilt from the per-store source tables (source of
+ * truth) when incompatible and refreshed per affected key inside the same
+ * transaction as every mutation:
+ *   domain_note  — note metadata selector + original payload
+ *   query_block  — one occurrence row per block_index row, parent resolved by
+ *                  exact noteId or sourcePath (ambiguous/orphan → NULL parent,
+ *                  which gates ALL domain reads with 409 until healed)
+ *   segment_head — MAX(version) per segment id taken BEFORE the isHistory
+ *                  filter, so a superseded revision can never resurrect
+ *
+ * Rebuilds are guarded: a `_wodwiki_schema` row stamps the projection
+ * version, so repeated ready()/boot cycles skip the rebuild while the
+ * derived shape is already compatible.
+ *
+ * Query plans are fixed and fully validated: every value is a bound parameter,
+ * names come from this module, counts run before paging, and text matching is
+ * a literal substring over JS-lowercased materialized columns (Unicode-exact;
+ * instr/strpos never treat % or _ as wildcards).
+ *
+ * `journal` is materialized in JS (sourceMatches from the wql package — the
+ * exact predicate the app applies) so no SQL regex re-implementation exists.
+ */
+
+/**
+ * Applies ops in order, collecting projection impact per affected key, then
+ * refreshes derived rows — all on the caller's transaction. Returns one entry
+ * per op: the put key, or null for delete/clear. `opts.deferProjection`
+ * skips the per-key refresh pass; the caller MUST rebuild derived state in
+ * the same transaction afterwards (see rebuildProjections) or reads will
+ * operate on stale projections behind a valid guard.
+ */
+declare function refreshDomain(conn: SqlConnection, ops: TxOp[], opts?: {
+    deferProjection?: boolean;
+}): Promise<(KeyDTO | null)[]>;
+/**
+ * Rebuild the derived tables from the source-of-truth store rows and stamp
+ * the projection guard. Caller owns the transaction (atomicity) — the guard
+ * row commits together with the rebuilt rows.
+ */
+declare function rebuildProjections(conn: SqlConnection): Promise<void>;
+/** Boot-time derived state: DDL + rebuild only when the guard is incompatible
+ * (first run, projection version bump, or an interrupted prior rebuild). */
+declare function initializeDomain(db: Database): Promise<void>;
+/** Clears derived tables after a data wipe (empty is a consistent state). */
+declare function wipeDomain(conn: SqlConnection): Promise<void>;
+declare const MAX_BODY: number;
+/** Validate, gate, execute on one consistent snapshot (server route and
+ * SqlStorage.queryDomain share this entry). */
+declare function handleDomainQuery(db: Database, body: unknown): Promise<DomainQueryResult>;
+
+/**
+ * SqlStorage — IStorage over the shared SQL store operations (server or
+ * browser). Transactions buffer writes and flush them as one refreshDomain
+ * pass inside a real SQL transaction: throw → rollback, success → commit,
+ * and buffered reads overlay committed rows (read-your-writes). Projections
+ * refresh inside the same transaction; bulkTransaction() batches a migration
+ * into one rebuild instead of per-key refreshes. verifyWritable() proves the
+ * backend accepts writes with a real INSERT that is rolled back.
+ *
+ * BrowserTursoStorage opens a direct-to-Turso backend via @libsql/client/web;
+ * the constructor only builds the client (HTTP is connectionless), `ready()`
+ * initializes schema + projections and every operation awaits it, so a
+ * transient init failure never wedges the backend — ready() retries.
+ */
+
+interface SqlStorageOptions {
+    /** Rows in user-owned stores are stamped with this userId on write. Omit
+     * for stamp-free writers (data migration preserves ownership verbatim). */
+    getUserId?: () => string;
+}
+declare class SqlStorage implements IStorage {
+    private readonly db;
+    private readonly options;
+    private readonly defs;
+    private readyPromise?;
+    constructor(db: Database, options?: SqlStorageOptions);
+    /**
+     * Idempotent schema + projection initialization. Cheap when already
+     * compatible (both initializers are guard-protected); a failed attempt
+     * clears the memo so the next call retries instead of caching the error.
+     */
+    ready(): Promise<void>;
+    /** Every store operation starts here, so views created before (or during)
+     * an in-flight ready() block until initialization actually succeeded. */
+    ensureReady(): Promise<void>;
+    def(store: StoreName): StoreDef;
+    private makeView;
+    readonly<K extends StoreName>(store: K): IReadOnlyStore<StoreType<K>>;
+    readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
+    queryDomain(query: DomainQuery): Promise<DomainQueryResult | undefined>;
+    transaction<K extends StoreName, R>(stores: K[], mode: 'readonly' | 'readwrite', fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    /**
+     * Bulk load for migration destinations: like transaction(), but the
+     * buffered writes skip per-key projection refresh and derived state is
+     * rebuilt once — everything inside one SQL transaction (throw → rollback).
+     */
+    bulkTransaction<K extends StoreName, R>(stores: K[], fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    private runTx;
+    /**
+     * Proves the backend accepts writes: one real INSERT into `meta` inside a
+     * transaction that is then deliberately rolled back — zero rows committed.
+     * A read-only backend, bad token or transport failure rejects here.
+     */
+    verifyWritable(): Promise<void>;
+    wipe(): Promise<void>;
+    close(): Promise<void>;
+    applyOps(ops: TxOp[]): Promise<void>;
+    stamp(store: StoreName, value: unknown): unknown;
+}
+interface TursoSettings {
+    url: string;
+    authToken?: string;
+}
+/** libsql/https/wss only; plain http only for loopback development; tokens
+ * travel via authToken, never the URL. Rejects credentials, query strings
+ * and fragments (no secret or option injection through the URL). */
+declare function validateTursoUrl(url: string): string;
+/**
+ * Direct-from-browser Turso backend. Construction only validates and builds
+ * the client; `await storage.ready()` initializes schema + projections.
+ * Errors never embed the auth token.
+ */
+declare class BrowserTursoStorage extends SqlStorage {
+    constructor(settings: TursoSettings, options?: SqlStorageOptions);
+}
+
+export { BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, SCHEMA_TABLE, type SqlConnection, type SqlRow, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, putRow, rebuildProjections, refreshDomain, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };

package/dist/sql/index.d.ts

@@ -0,0 +1,220 @@
+import { Client } from '@libsql/client';
+import { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, E as TxOp, I as IStorage, S as StoreName, b as IReadOnlyStore, c as StoreType, d as IReadWriteStore, D as DomainQuery, f as IStorageTransaction } from '../wire-C7ZtlBKe.js';
+import '@bitcobblers/wod-wiki-core';
+import '@bitcobblers/wod-wiki-lang';
+
+/**
+ * StorageError — the single error type every shared SQL layer throws.
+ * Replaces the API server's HTTP-specific error: `status` keeps the wire
+ * mapping for the HTTP surface, `code` carries a stable machine identifier
+ * (e.g. 'domain_projection_unavailable') for browser callers.
+ */
+declare class StorageError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+
+/**
+ * Connection contracts + a generic libsql adapter. The adapter takes a
+ * *structural* client so the browser passes @libsql/client/web and the server
+ * passes @libsql/client (node) — this module never imports either, keeping
+ * the browser graph free of native drivers.
+ *
+ * All operations are serialized through one promise chain: the underlying
+ * client shares a single connection, so concurrent transactions/reads could
+ * otherwise interleave on it. Transactions run on a transaction-owned
+ * connection (libsql interactive transaction), so writes inside a transaction
+ * commit or roll back atomically and are not visible outside it.
+ */
+
+type SqlValue = string | number | null;
+type SqlRow = Record<string, unknown>;
+interface SqlConnection {
+    query(sql: string, params?: SqlValue[]): Promise<SqlRow[]>;
+    exec(sql: string, params?: SqlValue[]): Promise<void>;
+}
+interface Database extends SqlConnection {
+    readonly dialect: 'sqlite' | 'postgres';
+    transaction<T>(fn: (tx: SqlConnection) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Minimal surface used from a libsql client (node or web build) — the real
+ * @libsql/client types, type-only so the browser graph stays driver-free. */
+type LibsqlClient = Pick<Client, 'execute' | 'transaction' | 'close'>;
+/** Wrap a libsql client (node or web build) into the shared Database surface. */
+declare function libsqlDatabase(client: LibsqlClient): Database;
+
+/**
+ * Row codec for the SQL `data` column. Plain JSON.stringify destroys
+ * ArrayBuffer values ({}); attachment rows carry raw blobs, so encoding tags
+ * the declared binary field and decoding revives it.
+ *
+ * Collision safety: tagging applies ONLY to the declared binary field of the
+ * declared store (attachments.data) — arbitrary rows (meta, notes, …) are
+ * plain JSON in both directions, so authored {$binary:…}-shaped objects
+ * anywhere else round-trip byte-for-byte. Within attachments.data the value
+ * is typed `ArrayBuffer | string`; strings pass through, and only the exact
+ * two-key tag revives.
+ */
+/** Serialize a row; when `binaryField` is set and holds an ArrayBuffer, it is
+ * replaced by the lossless tag (shallow copy — the input row is untouched). */
+declare function encodeRowJson(value: unknown, binaryField?: string): string;
+/** Parse a row; when `binaryField` is set, a tagged value there revives as an
+ * ArrayBuffer. Every other value — including tag-shaped data in other fields
+ * or stores — is returned exactly as authored. */
+declare function decodeRowJson<T = unknown>(text: string, binaryField?: string): T;
+
+/**
+ * Schema-driven store operations: IDB-style stores persisted into SQL tables
+ * (one per store, extracted key/index columns + full JSON in `data`). The
+ * schema derives entirely from STORE_DEFS / COLUMN_TYPES; JSON payloads stay
+ * the source of truth. Shared by the API server and the browser
+ * BrowserTursoStorage/SqlStorage backends.
+ */
+
+declare const SCHEMA_TABLE = "_wodwiki_schema";
+declare function storeDefinition(name: string): StoreDef;
+declare function getRow(conn: SqlConnection, def: StoreDef, key: KeyDTO): Promise<unknown | undefined>;
+declare function listRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, count?: number, indexName?: string): Promise<unknown[]>;
+declare function countRows(conn: SqlConnection, def: StoreDef, range?: RangeDTO, indexName?: string): Promise<number>;
+declare function putRow(conn: SqlConnection, def: StoreDef, value: unknown): Promise<KeyDTO>;
+declare function deleteRows(conn: SqlConnection, def: StoreDef, keyOrRange: KeyDTO | RangeDTO): Promise<void>;
+declare function clearRows(conn: SqlConnection, def: StoreDef): Promise<void>;
+/** Wipe all user stores; system stores (memberships) survive and the internal
+ * schema metadata table is not a store, so the version guard is untouched. */
+declare function wipeRows(conn: SqlConnection): Promise<void>;
+/** Internal schema metadata is not exposed or cleared by the store API. */
+declare function initializeStore(db: Database): Promise<void>;
+
+/**
+ * Domain read models + incremental projection refresh over the shared SQL
+ * store tables.
+ *
+ * Three derived tables, rebuilt from the per-store source tables (source of
+ * truth) when incompatible and refreshed per affected key inside the same
+ * transaction as every mutation:
+ *   domain_note  — note metadata selector + original payload
+ *   query_block  — one occurrence row per block_index row, parent resolved by
+ *                  exact noteId or sourcePath (ambiguous/orphan → NULL parent,
+ *                  which gates ALL domain reads with 409 until healed)
+ *   segment_head — MAX(version) per segment id taken BEFORE the isHistory
+ *                  filter, so a superseded revision can never resurrect
+ *
+ * Rebuilds are guarded: a `_wodwiki_schema` row stamps the projection
+ * version, so repeated ready()/boot cycles skip the rebuild while the
+ * derived shape is already compatible.
+ *
+ * Query plans are fixed and fully validated: every value is a bound parameter,
+ * names come from this module, counts run before paging, and text matching is
+ * a literal substring over JS-lowercased materialized columns (Unicode-exact;
+ * instr/strpos never treat % or _ as wildcards).
+ *
+ * `journal` is materialized in JS (sourceMatches from the wql package — the
+ * exact predicate the app applies) so no SQL regex re-implementation exists.
+ */
+
+/**
+ * Applies ops in order, collecting projection impact per affected key, then
+ * refreshes derived rows — all on the caller's transaction. Returns one entry
+ * per op: the put key, or null for delete/clear. `opts.deferProjection`
+ * skips the per-key refresh pass; the caller MUST rebuild derived state in
+ * the same transaction afterwards (see rebuildProjections) or reads will
+ * operate on stale projections behind a valid guard.
+ */
+declare function refreshDomain(conn: SqlConnection, ops: TxOp[], opts?: {
+    deferProjection?: boolean;
+}): Promise<(KeyDTO | null)[]>;
+/**
+ * Rebuild the derived tables from the source-of-truth store rows and stamp
+ * the projection guard. Caller owns the transaction (atomicity) — the guard
+ * row commits together with the rebuilt rows.
+ */
+declare function rebuildProjections(conn: SqlConnection): Promise<void>;
+/** Boot-time derived state: DDL + rebuild only when the guard is incompatible
+ * (first run, projection version bump, or an interrupted prior rebuild). */
+declare function initializeDomain(db: Database): Promise<void>;
+/** Clears derived tables after a data wipe (empty is a consistent state). */
+declare function wipeDomain(conn: SqlConnection): Promise<void>;
+declare const MAX_BODY: number;
+/** Validate, gate, execute on one consistent snapshot (server route and
+ * SqlStorage.queryDomain share this entry). */
+declare function handleDomainQuery(db: Database, body: unknown): Promise<DomainQueryResult>;
+
+/**
+ * SqlStorage — IStorage over the shared SQL store operations (server or
+ * browser). Transactions buffer writes and flush them as one refreshDomain
+ * pass inside a real SQL transaction: throw → rollback, success → commit,
+ * and buffered reads overlay committed rows (read-your-writes). Projections
+ * refresh inside the same transaction; bulkTransaction() batches a migration
+ * into one rebuild instead of per-key refreshes. verifyWritable() proves the
+ * backend accepts writes with a real INSERT that is rolled back.
+ *
+ * BrowserTursoStorage opens a direct-to-Turso backend via @libsql/client/web;
+ * the constructor only builds the client (HTTP is connectionless), `ready()`
+ * initializes schema + projections and every operation awaits it, so a
+ * transient init failure never wedges the backend — ready() retries.
+ */
+
+interface SqlStorageOptions {
+    /** Rows in user-owned stores are stamped with this userId on write. Omit
+     * for stamp-free writers (data migration preserves ownership verbatim). */
+    getUserId?: () => string;
+}
+declare class SqlStorage implements IStorage {
+    private readonly db;
+    private readonly options;
+    private readonly defs;
+    private readyPromise?;
+    constructor(db: Database, options?: SqlStorageOptions);
+    /**
+     * Idempotent schema + projection initialization. Cheap when already
+     * compatible (both initializers are guard-protected); a failed attempt
+     * clears the memo so the next call retries instead of caching the error.
+     */
+    ready(): Promise<void>;
+    /** Every store operation starts here, so views created before (or during)
+     * an in-flight ready() block until initialization actually succeeded. */
+    ensureReady(): Promise<void>;
+    def(store: StoreName): StoreDef;
+    private makeView;
+    readonly<K extends StoreName>(store: K): IReadOnlyStore<StoreType<K>>;
+    readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
+    queryDomain(query: DomainQuery): Promise<DomainQueryResult | undefined>;
+    transaction<K extends StoreName, R>(stores: K[], mode: 'readonly' | 'readwrite', fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    /**
+     * Bulk load for migration destinations: like transaction(), but the
+     * buffered writes skip per-key projection refresh and derived state is
+     * rebuilt once — everything inside one SQL transaction (throw → rollback).
+     */
+    bulkTransaction<K extends StoreName, R>(stores: K[], fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    private runTx;
+    /**
+     * Proves the backend accepts writes: one real INSERT into `meta` inside a
+     * transaction that is then deliberately rolled back — zero rows committed.
+     * A read-only backend, bad token or transport failure rejects here.
+     */
+    verifyWritable(): Promise<void>;
+    wipe(): Promise<void>;
+    close(): Promise<void>;
+    applyOps(ops: TxOp[]): Promise<void>;
+    stamp(store: StoreName, value: unknown): unknown;
+}
+interface TursoSettings {
+    url: string;
+    authToken?: string;
+}
+/** libsql/https/wss only; plain http only for loopback development; tokens
+ * travel via authToken, never the URL. Rejects credentials, query strings
+ * and fragments (no secret or option injection through the URL). */
+declare function validateTursoUrl(url: string): string;
+/**
+ * Direct-from-browser Turso backend. Construction only validates and builds
+ * the client; `await storage.ready()` initializes schema + projections.
+ * Errors never embed the auth token.
+ */
+declare class BrowserTursoStorage extends SqlStorage {
+    constructor(settings: TursoSettings, options?: SqlStorageOptions);
+}
+
+export { BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, SCHEMA_TABLE, type SqlConnection, type SqlRow, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, putRow, rebuildProjections, refreshDomain, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };