@bitcobblers/wod-wiki-storage 0.35.2115 → 0.35.2117

package/dist/sql/index.d.cts

@@ -1,5 +1,5 @@
 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 { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, T 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-Cfvz-I0h.cjs';
 import '@bitcobblers/wod-wiki-core';
 import '@bitcobblers/wod-wiki-lang';
 
@@ -30,9 +30,14 @@ declare class StorageError extends Error {
 
 type SqlValue = string | number | null;
 type SqlRow = Record<string, unknown>;
+interface SqlStatement {
+    sql: string;
+    params?: SqlValue[];
+}
 interface SqlConnection {
     query(sql: string, params?: SqlValue[]): Promise<SqlRow[]>;
     exec(sql: string, params?: SqlValue[]): Promise<void>;
+    batch?(statements: SqlStatement[]): Promise<SqlRow[][]>;
 }
 interface Database extends SqlConnection {
     readonly dialect: 'sqlite' | 'postgres';
@@ -57,8 +62,6 @@ declare function libsqlDatabase(client: LibsqlClient): Database;
  * 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
@@ -76,55 +79,24 @@ declare function decodeRowJson<T = unknown>(text: string, binaryField?: string):
 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 getRows(conn: SqlConnection, def: StoreDef, keys: KeyDTO[]): Promise<(unknown | undefined)[]>;
+declare function listRowsFromIndexMany(conn: SqlConnection, def: StoreDef, indexName: string, keys: KeyDTO[]): Promise<unknown[][]>;
 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 putRows(conn: SqlConnection, def: StoreDef, values: unknown[], changedKeys?: KeyDTO[]): Promise<KeyDTO[]>;
 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>;
+declare function clearRows(conn: SqlConnection, def: StoreDef, wipe?: boolean): 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.
- */
+/** Current Note and actionable-block SQL projections. */
 
-/**
- * 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)[]>;
+/** Checks precede mutations; pins and projections commit with source rows. */
+declare function refreshDomain(conn: SqlConnection, ops: TxOp[]): 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
@@ -141,20 +113,7 @@ declare const MAX_BODY: number;
  * 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.
- */
+/** SQL storage with atomic, change-scoped projections and buffered reads. */
 
 interface SqlStorageOptions {
     /** Rows in user-owned stores are stamped with this userId on write. Omit
@@ -182,11 +141,7 @@ declare class SqlStorage implements IStorage {
     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).
-     */
+    /** Bulk writes use the same affected-key refresh as ordinary transactions. */
     bulkTransaction<K extends StoreName, R>(stores: K[], fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
     private runTx;
     /**
@@ -217,4 +172,4 @@ 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 };
+export { BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, SCHEMA_TABLE, type SqlConnection, type SqlRow, type SqlStatement, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, getRows, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, listRowsFromIndexMany, putRow, putRows, rebuildProjections, refreshDomain, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };

package/dist/sql/index.d.ts

@@ -1,5 +1,5 @@
 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 { a as StoreDef, R as RangeDTO, K as KeyDTO, e as DomainQueryResult, T 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-Cfvz-I0h.js';
 import '@bitcobblers/wod-wiki-core';
 import '@bitcobblers/wod-wiki-lang';
 
@@ -30,9 +30,14 @@ declare class StorageError extends Error {
 
 type SqlValue = string | number | null;
 type SqlRow = Record<string, unknown>;
+interface SqlStatement {
+    sql: string;
+    params?: SqlValue[];
+}
 interface SqlConnection {
     query(sql: string, params?: SqlValue[]): Promise<SqlRow[]>;
     exec(sql: string, params?: SqlValue[]): Promise<void>;
+    batch?(statements: SqlStatement[]): Promise<SqlRow[][]>;
 }
 interface Database extends SqlConnection {
     readonly dialect: 'sqlite' | 'postgres';
@@ -57,8 +62,6 @@ declare function libsqlDatabase(client: LibsqlClient): Database;
  * 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
@@ -76,55 +79,24 @@ declare function decodeRowJson<T = unknown>(text: string, binaryField?: string):
 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 getRows(conn: SqlConnection, def: StoreDef, keys: KeyDTO[]): Promise<(unknown | undefined)[]>;
+declare function listRowsFromIndexMany(conn: SqlConnection, def: StoreDef, indexName: string, keys: KeyDTO[]): Promise<unknown[][]>;
 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 putRows(conn: SqlConnection, def: StoreDef, values: unknown[], changedKeys?: KeyDTO[]): Promise<KeyDTO[]>;
 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>;
+declare function clearRows(conn: SqlConnection, def: StoreDef, wipe?: boolean): 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.
- */
+/** Current Note and actionable-block SQL projections. */
 
-/**
- * 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)[]>;
+/** Checks precede mutations; pins and projections commit with source rows. */
+declare function refreshDomain(conn: SqlConnection, ops: TxOp[]): 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
@@ -141,20 +113,7 @@ declare const MAX_BODY: number;
  * 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.
- */
+/** SQL storage with atomic, change-scoped projections and buffered reads. */
 
 interface SqlStorageOptions {
     /** Rows in user-owned stores are stamped with this userId on write. Omit
@@ -182,11 +141,7 @@ declare class SqlStorage implements IStorage {
     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).
-     */
+    /** Bulk writes use the same affected-key refresh as ordinary transactions. */
     bulkTransaction<K extends StoreName, R>(stores: K[], fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
     private runTx;
     /**
@@ -217,4 +172,4 @@ 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 };
+export { BrowserTursoStorage, type Database, type LibsqlClient, MAX_BODY, SCHEMA_TABLE, type SqlConnection, type SqlRow, type SqlStatement, SqlStorage, type SqlStorageOptions, type SqlValue, StorageError, type TursoSettings, clearRows, countRows, decodeRowJson, deleteRows, encodeRowJson, getRow, getRows, handleDomainQuery, initializeDomain, initializeStore, libsqlDatabase, listRows, listRowsFromIndexMany, putRow, putRows, rebuildProjections, refreshDomain, storeDefinition, validateTursoUrl, wipeDomain, wipeRows };