@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/{errors-Bw5MdNCu.d.ts → errors-Dei4GdBb.d.ts}

@@ -1,14 +1,25 @@
 /**
  * Base class for all sirannon-db errors. Extend this class to create
- * domain-specific errors that carry a machine-readable {@link code}.
+ * domain-specific errors that carry a machine-readable {@link SirannonError.code}.
+ *
+ * @public
  */
 declare class SirannonError extends Error {
+    /**
+     * Machine-readable code the server maps to an HTTP status.
+     */
     readonly code: string;
-    constructor(message: string, code: string);
+    constructor(message: string, 
+    /**
+     * Machine-readable code the server maps to an HTTP status.
+     */
+    code: string);
 }
 /**
  * Thrown when a database ID cannot be resolved in the registry.
  * This typically means the database was never opened or has already been closed.
+ *
+ * @public
  */
 declare class DatabaseNotFoundError extends SirannonError {
     constructor(id: string);
@@ -16,6 +27,8 @@ declare class DatabaseNotFoundError extends SirannonError {
 /**
  * Thrown when attempting to register a database with an ID that is already
  * in use. Each database ID must be unique within the registry.
+ *
+ * @public
  */
 declare class DatabaseAlreadyExistsError extends SirannonError {
     constructor(id: string);
@@ -23,50 +36,84 @@ declare class DatabaseAlreadyExistsError extends SirannonError {
 /**
  * Thrown when a write operation is attempted on a database that was opened
  * in read-only mode.
+ *
+ * @public
  */
 declare class ReadOnlyError extends SirannonError {
     constructor(id: string);
 }
 /**
- * Thrown when SQLite fails to execute a statement. The {@link sql} property
+ * Thrown when SQLite fails to execute a statement. The {@link QueryError.sql} property
  * holds the original SQL string that caused the failure, which is useful for
  * debugging and logging.
+ *
+ * @public
  */
 declare class QueryError extends SirannonError {
+    /**
+     * The statement that failed.
+     */
     readonly sql: string;
-    constructor(message: string, sql: string);
+    constructor(message: string, 
+    /**
+     * The statement that failed.
+     */
+    sql: string);
 }
 /**
  * Thrown when a transaction cannot be committed or is forcibly rolled back.
  * Check the message for the underlying cause.
+ *
+ * @public
  */
 declare class TransactionError extends SirannonError {
     constructor(message: string);
 }
 /**
- * Thrown when a migration step fails. The {@link version} property identifies
+ * Thrown when a migration step fails. The {@link MigrationError.version} property identifies
  * which schema version triggered the error so the failure can be pinpointed
  * in the migration history.
+ *
+ * @public
  */
 declare class MigrationError extends SirannonError {
+    /**
+     * Version of the migration that failed.
+     */
     readonly version: number;
-    constructor(message: string, version: number, code?: string);
+    constructor(message: string, 
+    /**
+     * Version of the migration that failed.
+     */
+    version: number, code?: string);
 }
 /**
  * Thrown when a before-hook explicitly rejects an operation. The optional
  * `reason` string is surfaced in the message so callers can distinguish
  * between different hook policies.
+ *
+ * @public
  */
 declare class HookDeniedError extends SirannonError {
     constructor(hookName: string, reason?: string);
 }
+/**
+ * Refuses one request with a status of your own. Throw it from an authenticate hook or a registered operation.
+ *
+ * @public
+ */
 declare class RequestDeniedError extends SirannonError {
+    /**
+     * HTTP status the server answers the refused request with.
+     */
     readonly status: number;
     constructor(status: number, code: string, message: string);
 }
 /**
  * Thrown when the change-data-capture pipeline encounters an unrecoverable
  * error, such as a failed event dispatch or a corrupt change record.
+ *
+ * @public
  */
 declare class CDCError extends SirannonError {
     constructor(message: string);
@@ -76,6 +123,8 @@ declare class CDCError extends SirannonError {
  * internal bookkeeping tables and SQLite's own catalogue are off limits to the
  * query API so a caller cannot read or corrupt the change log, replication
  * ledger, or schema catalogue.
+ *
+ * @public
  */
 declare class ForbiddenSqlError extends SirannonError {
     constructor(message: string);
@@ -83,6 +132,8 @@ declare class ForbiddenSqlError extends SirannonError {
 /**
  * Thrown when a backup operation fails, whether that is an online backup via
  * the SQLite backup API or a file-level copy.
+ *
+ * @public
  */
 declare class BackupError extends SirannonError {
     constructor(message: string);
@@ -90,6 +141,8 @@ declare class BackupError extends SirannonError {
 /**
  * Thrown when the connection pool reaches its limit or is configured with
  * invalid parameters such as a minimum size greater than the maximum.
+ *
+ * @public
  */
 declare class ConnectionPoolError extends SirannonError {
     constructor(message: string);
@@ -98,6 +151,8 @@ declare class ConnectionPoolError extends SirannonError {
  * Thrown when opening a new database would exceed the configured cap on
  * concurrently open databases. Close an existing database before opening
  * another one.
+ *
+ * @public
  */
 declare class MaxDatabasesError extends SirannonError {
     constructor(max: number);
@@ -105,16 +160,34 @@ declare class MaxDatabasesError extends SirannonError {
 /**
  * Thrown when more writes are pending than the writer-worker limit allows. It
  * signals load shedding, so the server maps it to a 503 with a Retry-After hint.
+ *
+ * @public
  */
 declare class WriteOverloadError extends SirannonError {
+    /**
+     * Number of pending writes the database accepts before it refuses more.
+     */
     readonly limit: number;
+    /**
+     * Milliseconds the caller should wait before retrying.
+     */
     readonly retryAfterMs: number;
-    constructor(limit: number, retryAfterMs: number);
+    constructor(
+    /**
+     * Number of pending writes the database accepts before it refuses more.
+     */
+    limit: number, 
+    /**
+     * Milliseconds the caller should wait before retrying.
+     */
+    retryAfterMs: number);
 }
 /**
  * Thrown when a native SQLite extension cannot be loaded. The `path` argument
  * is the filesystem path passed to `load_extension`, and the optional `cause`
  * string carries the error detail reported by SQLite.
+ *
+ * @public
  */
 declare class ExtensionError extends SirannonError {
     constructor(path: string, cause?: string);

package/dist/file-migrations/index.d.ts

@@ -1,17 +1,69 @@
-import { B as BaselineFileOption } from '../baseline-Br77Fnhb.js';
-import { M as Migration } from '../types-zhnRXrsb.js';
+import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
+import { M as Migration } from '../types-rVZKnKN-.js';
+import '../query-types-DL3LtPvY.js';
 
+/**
+ * @public
+ *
+ * How a directory of migration files is turned into migrations.
+ */
 interface LoadMigrationsOptions {
+    /**
+     * Marks the migration an existing database starts from.
+     */
     baseline?: BaselineFileOption;
 }
+/**
+ * @public
+ *
+ * One migration found on disk, with the paths of its up and down files.
+ */
 interface ScannedMigration {
+    /**
+     * Version number the file name starts with.
+     */
     version: number;
+    /**
+     * Migration name between the version and the direction.
+     */
     name: string;
+    /**
+     * Path of the file that applies the migration.
+     */
     upPath: string;
+    /**
+     * Path of the file that undoes it, or null when the migration has none.
+     */
     downPath: string | null;
 }
+/**
+ * @public
+ *
+ * Lists the migration files in a directory, in ascending version order.
+ *
+ * @param dirPath - Directory holding the migration files.
+ * @returns One entry per migration, with the paths of its up and down files.
+ * @throws When the path is unsafe or a file name does not parse.
+ */
 declare function scanDirectory(dirPath: string): ScannedMigration[];
+/**
+ * @public
+ *
+ * Reads the up files of scanned migrations, leaving each down file to be read only if a rollback needs it.
+ *
+ * @param scanned - Migrations found by {@link scanDirectory}.
+ * @returns The migrations, in ascending version order.
+ */
 declare function readUpMigrations(scanned: ScannedMigration[]): Migration[];
+/**
+ * @public
+ *
+ * Reads a directory of migration files and returns the migrations to apply.
+ *
+ * @param dirPath - Directory holding the migration files.
+ * @param options - The baseline to apply, when an existing database starts from one.
+ * @returns The migrations, in ascending version order.
+ */
 declare function loadMigrations(dirPath: string, options?: LoadMigrationsOptions): Migration[];
 
 export { type LoadMigrationsOptions, type ScannedMigration, loadMigrations, readUpMigrations, scanDirectory };

package/dist/file-migrations/index.mjs

@@ -1,6 +1,6 @@
-import { parseMigrationFilename, LAZY_DOWN_SQL } from '../chunk-LNY2VVHE.mjs';
-import { applyBaselineOption } from '../chunk-67M7KAH6.mjs';
-import { MigrationError } from '../chunk-UC3SCMIN.mjs';
+import { parseMigrationFilename, LAZY_DOWN_SQL } from '../chunk-7C36BCSN.mjs';
+import { applyBaselineOption } from '../chunk-IWGIYDMZ.mjs';
+import { MigrationError } from '../chunk-PBRXXISQ.mjs';
 import { statSync, readdirSync, readFileSync } from 'fs';
 import { resolve, join } from 'path';
 

package/dist/{operation-registry-9DcvxcE5.d.ts → operation-registry-hlbhqu7q.d.ts}

@@ -1,12 +1,25 @@
-import { P as Params } from './types-zhnRXrsb.js';
+import { P as Params } from './query-types-DL3LtPvY.js';
 
+/** One statement a registered operation runs, with its parameters bound.
+ * @public
+ */
 interface OperationStatement {
+    /** The statement to run. */
     sql: string;
+    /** Parameters bound to that statement. */
     params?: Params;
 }
+/** Values a caller passes when it invokes a registered operation by name.
+ * @public
+ */
 type OperationArguments = Record<string, unknown>;
+/** A read a caller invokes by name, so the server accepts no SQL from the network.
+ * @public
+ */
 interface ReadOperation<Identity = unknown> {
+    /** Argument names this operation accepts from the caller. */
     args?: readonly string[];
+    /** Arguments the server fills from the authenticated identity, so a caller cannot supply them. */
     fromIdentity?: Readonly<Record<string, keyof Identity & string>>;
     /**
      * The columns every row of this read carries. Code generation emits a typed
@@ -14,32 +27,68 @@ interface ReadOperation<Identity = unknown> {
      * operation takes no arguments, because arguments choose the statement.
      */
     columns?: readonly string[];
+    /** Builds the statement this read runs for a given set of arguments. */
     statement(args: OperationArguments): OperationStatement;
 }
+/** A write a caller invokes by name. The server runs every statement it returns in one transaction.
+ * @public
+ */
 interface WriteOperation<Identity = unknown> {
+    /** Argument names this operation accepts from the caller. */
     args?: readonly string[];
+    /** Arguments the server fills from the authenticated identity, so a caller cannot supply them. */
     fromIdentity?: Readonly<Record<string, keyof Identity & string>>;
+    /** Builds the statements this write runs for a given set of arguments. */
     statements(args: OperationArguments): OperationStatement | readonly OperationStatement[];
 }
+/** The reads and writes one database exposes by name.
+ * @public
+ */
 interface DatabaseOperations<Identity = unknown> {
+    /** Reads callers may invoke, keyed by operation name. */
     reads?: Readonly<Record<string, ReadOperation<Identity>>>;
+    /** Writes callers may invoke, keyed by operation name. */
     writes?: Readonly<Record<string, WriteOperation<Identity>>>;
 }
+/** Every database's registered operations, keyed by database identifier.
+ * @public
+ */
 type OperationRegistry<Identity = unknown> = Readonly<Record<string, DatabaseOperations<Identity>>>;
 /**
  * A named operation a remote caller invokes, carrying the argument and row
  * types of the registered operation. Only `name` exists at runtime; `types`
  * is never assigned and is present so both type parameters are inferable at
  * the call site. Code generation emits one reference per registered operation.
+ *
+ * @public
  */
 interface OperationRef<Args = OperationArguments, Row = Record<string, unknown>> {
+    /** Name the server registered this operation under. */
     readonly name: string;
+    /** Present for type inference only, and never assigned at runtime. */
     readonly types?: {
         args: Args;
         row: Row;
     };
 }
+/**
+ * Builds a typed reference to a registered operation so that a call site infers its
+ * argument and row types from the name alone.
+ *
+ * @param name - Name the server registered the operation under.
+ * @returns A reference carrying that name and the two inferred types.
+ *
+ * @public
+ */
 declare function operationRef<Args = OperationArguments, Row = Record<string, unknown>>(name: string): OperationRef<Args, Row>;
+/**
+ * Reads the operation name out of either a plain string or a typed reference.
+ *
+ * @param operation - The name itself, or a reference built by {@link operationRef}.
+ * @returns The registered operation name.
+ *
+ * @public
+ */
 declare function operationName(operation: string | OperationRef<never, never>): string;
 
 export { type DatabaseOperations as D, type OperationRef as O, type ReadOperation as R, type WriteOperation as W, type OperationRegistry as a, type OperationArguments as b, type OperationStatement as c, operationRef as d, operationName as o };

package/dist/{primary-wins-DPAm2AKG.d.ts → primary-wins-B0np8JS3.d.ts}

@@ -1,4 +1,4 @@
-import { C as ConflictResolver, a as ConflictContext, b as ConflictResolution } from './types-C_D8IhpO.js';
+import { C as ConflictResolver, a as ConflictContext, b as ConflictResolution } from './types-CjhxcjhA.js';
 
 type ColumnVersionGetter = (table: string, rowId: string) => Promise<Map<string, {
     hlc: string;
@@ -15,11 +15,19 @@ type ColumnVersionGetter = (table: string, rowId: string) => Promise<Map<string,
  * injected `getColumnVersions` callback) determine which side's value wins
  * for each contested column. If no column version metadata exists, the
  * resolver falls back to whole-row LWW.
+ *
+ * @public
  */
 declare class FieldMergeResolver implements ConflictResolver {
     private readonly getColumnVersions;
     private readonly lww;
     constructor(getColumnVersions: ColumnVersionGetter);
+    /**
+     * Merges columns only one side changed, and settles overlapping columns by their per-column stamps.
+     *
+     * @param ctx - The local and incoming versions of one row.
+     * @returns Which version to write, or the merged row.
+     */
     resolve(ctx: ConflictContext): Promise<ConflictResolution>;
 }
 
@@ -36,8 +44,16 @@ declare class FieldMergeResolver implements ConflictResolver {
  * resolution without coordination. This is the default resolver and the
  * fallback used by PrimaryWinsResolver and FieldMergeResolver when they
  * cannot make a more specific decision.
+ *
+ * @public
  */
 declare class LWWResolver implements ConflictResolver {
+    /**
+     * Takes the incoming row when its stamp is higher, and keeps the local row otherwise.
+     *
+     * @param ctx - The local and incoming versions of one row.
+     * @returns Which version to write.
+     */
     resolve(ctx: ConflictContext): ConflictResolution;
 }
 
@@ -50,11 +66,19 @@ declare class LWWResolver implements ConflictResolver {
  * the decision falls back to LWW ordering. This resolver is designed for
  * primary-replica topologies where the primary is the authoritative source of
  * truth and replica-side writes should never override it.
+ *
+ * @public
  */
 declare class PrimaryWinsResolver implements ConflictResolver {
     private readonly primaryNodeId;
     private readonly lww;
     constructor(primaryNodeId: string);
+    /**
+     * Takes the version authored by the configured primary node, and falls back to last-writer-wins otherwise.
+     *
+     * @param ctx - The local and incoming versions of one row.
+     * @returns Which version to write.
+     */
     resolve(ctx: ConflictContext): ConflictResolution;
 }
 

package/dist/protocol-rqANt-9Q.d.ts

@@ -0,0 +1,152 @@
+import { W as WriteConcern, R as ReadConcern, E as ExecuteResult } from './query-types-DL3LtPvY.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from './server-options-Dab_Jvd_.js';
+
+/**
+ * Body of `POST /db/{id}/query`.
+ *
+ * @public
+ */
+interface QueryRequest {
+    /** The statement to run. */
+    sql: string;
+    /** Values bound to the statement, named or positional. */
+    params?: Record<string, unknown> | unknown[];
+    /** Currency this read requires. */
+    readConcern?: ReadConcern;
+}
+/**
+ * Body of `POST /db/{id}/execute`.
+ *
+ * @public
+ */
+interface ExecuteRequest {
+    /** The statement to run. */
+    sql: string;
+    /** Values bound to the statement, named or positional. */
+    params?: Record<string, unknown> | unknown[];
+    /** Acknowledgements this write waits for. */
+    writeConcern?: WriteConcern;
+}
+/**
+ * One statement inside a transaction or a registered write.
+ *
+ * @public
+ */
+interface TransactionStatement {
+    /** The statement to run. */
+    sql: string;
+    /** Values bound to the statement, named or positional. */
+    params?: Record<string, unknown> | unknown[];
+}
+/**
+ * Body of `POST /db/{id}/transaction`, whose statements all succeed or all fail.
+ *
+ * @public
+ */
+interface TransactionRequest {
+    /** The statements to run, in order. */
+    statements: TransactionStatement[];
+    /** Acknowledgements the transaction waits for. */
+    writeConcern?: WriteConcern;
+}
+/** The whole batch commits atomically in one server-side transaction with one fsync.
+ * @public
+ */
+interface BatchRequest {
+    /** The statement to run for each parameter set. */
+    sql: string;
+    /** One parameter set per run. */
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    /** Acknowledgements the batch waits for. */
+    writeConcern?: WriteConcern;
+}
+/**
+ * What a read route answers with.
+ *
+ * @public
+ */
+interface QueryResponse {
+    /** The rows the statement produced, with blobs and large integers in their tagged wire form. */
+    rows: Record<string, unknown>[];
+}
+/**
+ * What a write route answers with.
+ *
+ * @public
+ */
+interface ExecuteResponse {
+    /** Number of rows the statement inserted, updated, or deleted. */
+    changes: number;
+    /** Row id SQLite assigned to the last inserted row, as a decimal string when it exceeds the safe range. */
+    lastInsertRowId: number | string;
+}
+/**
+ * What a transaction route answers with.
+ *
+ * @public
+ */
+interface TransactionResponse {
+    /** One result per statement, in the order the transaction ran them. */
+    results: ExecuteResponse[];
+}
+/**
+ * What a batch route answers with.
+ *
+ * @public
+ */
+interface BatchResponse {
+    /** One result per parameter set, in order. */
+    results: ExecuteResponse[];
+}
+/**
+ * Loads rows with relaxed writer durability; the configured durability is
+ * restored before the response is sent, and a load interrupted by a crash is
+ * recovered by re-running it.
+ *
+ * @public
+ */
+interface LoadRequest {
+    /** The statement to run for each parameter set. */
+    sql: string;
+    /** One parameter set per row. */
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    /** Durability in force while the load runs. Default: 'off'. */
+    durability?: BulkLoadDurability;
+    /** Whether this load ends with a checkpoint. Set it false on every batch but the last of a multi-batch import. */
+    checkpoint?: boolean;
+}
+/**
+ * How many rows a bulk load applied and how many rows changed.
+ *
+ * @public
+ */
+type LoadResponse = BulkLoadResult;
+interface AckResponse {
+    acked: boolean;
+    seq: string;
+}
+/**
+ * The body every failed route answers with.
+ *
+ * @public
+ */
+interface ErrorResponse {
+    /** Machine-readable code, human-readable message, and anything else the route attached. */
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * Turns a write result into its wire form, encoding a row id beyond the safe
+ * integer range as a decimal string.
+ *
+ * @param result - What the write reported locally.
+ * @returns The result as it crosses the wire.
+ *
+ * @public
+ */
+declare function toExecuteResponse(result: ExecuteResult): ExecuteResponse;
+
+export { type AckResponse as A, type BatchResponse as B, type ExecuteResponse as E, type LoadResponse as L, type QueryResponse as Q, type TransactionStatement as T, type TransactionResponse as a, type BatchRequest as b, type ErrorResponse as c, type ExecuteRequest as d, type LoadRequest as e, type QueryRequest as f, type TransactionRequest as g, toExecuteResponse as t };

package/dist/query-types-DL3LtPvY.d.ts

@@ -0,0 +1,95 @@
+/** Query parameter types: named (object) or positional (array).
+ * @public
+ */
+type Params = Record<string, unknown> | unknown[];
+/** How many nodes must acknowledge a write before it returns.
+ * @public
+ */
+type WriteConcernLevel = 'local' | 'majority' | 'all';
+/** How many nodes must acknowledge a write, and how long the caller waits for them.
+ * @public
+ */
+interface WriteConcern {
+    /** Number of acknowledgements the write waits for. */
+    level: WriteConcernLevel;
+    /** Milliseconds to wait for those acknowledgements before the write fails. */
+    timeoutMs?: number;
+}
+/** How current a read has to be before the node will serve it.
+ * @public
+ */
+type ReadConcernLevel = 'local' | 'majority' | 'linearizable';
+/** How current a read has to be before the node will serve it.
+ * @public
+ */
+interface ReadConcern {
+    /** Currency the node must prove before it answers. */
+    level: ReadConcernLevel;
+}
+/** Per-statement settings you pass alongside the SQL and its parameters.
+ * @public
+ */
+interface QueryOptions {
+    /** Acknowledgements a write waits for. Coordinator mode applies 'majority' when you omit it. */
+    writeConcern?: WriteConcern;
+    /** Currency a read requires. Coordinator mode enforces it and static mode ignores it. */
+    readConcern?: ReadConcern;
+}
+/** Result returned by mutation statements (INSERT, UPDATE, DELETE).
+ * @public
+ */
+interface ExecuteResult {
+    /** Number of rows the statement inserted, updated, or deleted. */
+    changes: number;
+    /** Row id SQLite assigned to the last inserted row. */
+    lastInsertRowId: number | bigint;
+}
+/** CDC operation type.
+ * @public
+ */
+type ChangeOperation = 'insert' | 'update' | 'delete';
+/** Event emitted when a watched table row changes.
+ * @public
+ */
+interface ChangeEvent<T = Record<string, unknown>> {
+    /** Whether the row was inserted, updated, or deleted. */
+    type: ChangeOperation;
+    /** Table the row belongs to. */
+    table: string;
+    /** The row as it stands after the change. A delete carries the row as it was. */
+    row: T;
+    /** The row as it stood before an update or a delete. */
+    oldRow?: T;
+    /** Position of this change in the database's change log. Subscribers resume from it. */
+    seq: bigint;
+    /** Milliseconds since the Unix epoch, taken when the change was recorded. */
+    timestamp: number;
+    /** Hybrid logical clock stamp the writing node gave this change. */
+    hlc?: string;
+    /** Identifier of the node that authored the change. */
+    origin?: string;
+    /** Primary key of the changed row, encoded as a string. */
+    rowId?: string;
+    /** Identifier of the transaction that produced this change. */
+    txId?: string;
+    /** Set on the last change of a transaction, so a consumer applies the whole transaction at once. */
+    txEnd?: boolean;
+}
+/** Builder for creating CDC subscriptions with optional filters.
+ * @public
+ */
+interface SubscriptionBuilder {
+    /** Narrows the subscription to rows whose columns equal the given values. */
+    filter(conditions: Record<string, unknown>): SubscriptionBuilder;
+    /** Starts the subscription and calls back on each change. */
+    subscribe(callback: (event: ChangeEvent) => void): Subscription;
+}
+/** Handle for an active subscription.
+ * @public
+ */
+interface Subscription {
+    /** Ends the subscription, so the callback receives no further events. */
+    unsubscribe(): void;
+}
+
+export type { ChangeEvent as C, ExecuteResult as E, Params as P, QueryOptions as Q, ReadConcern as R, SubscriptionBuilder as S, WriteConcern as W, ReadConcernLevel as a, ChangeOperation as b, Subscription as c, WriteConcernLevel as d };