@delali/sirannon-db 0.3.4-next.62 → 0.3.4

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

@@ -1,65 +1,67 @@
-import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
-import { M as Migration } from '../types-DPSmjU54.js';
-import '../query-types-p1liOP-b.js';
+import { B as BaselineFileOption } from '../baseline-Co3iIsN_.js';
+import { M as Migration } from '../types-Dc8oWlxj.js';
+import '../query-types-5B02ixH0.js';
 
 /**
- * How a directory of migration files is turned into migrations.
+ * Configures how {@link loadMigrations} builds migrations from a directory of files.
  *
  * @public
  */
 interface LoadMigrationsOptions {
     /**
-     * Marks the migration an existing database starts from.
+     * Marks one migration as a baseline, which a new database runs in place of the earlier versions.
      */
     baseline?: BaselineFileOption;
 }
 /**
- * One migration found on disk, with the paths of its up and down files.
+ * Describes one migration that {@link scanDirectory} finds on disk, with the paths of its up and down files.
  *
  * @public
  */
 interface ScannedMigration {
     /**
-     * Version number the file name starts with.
+     * The version number at the start of the file name.
      */
     version: number;
     /**
-     * Migration name between the version and the direction.
+     * The migration name between the version and the direction.
      */
     name: string;
     /**
-     * Path of the file that applies the migration.
+     * The path of the file with the SQL that applies the migration.
      */
     upPath: string;
     /**
-     * Path of the file that undoes it, or null when the migration has none.
+     * The path of the file with the SQL that undoes the migration, or `null` when the directory has no down file for it.
      */
     downPath: string | null;
 }
 /**
- * Lists the migration files in a directory, in ascending version order.
+ * Returns the migrations in a directory, in ascending version order, and skips each file whose name has another form.
  *
- * @param dirPath - Directory holding the migration files.
+ * @param dirPath - The directory that holds 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.
+ * @throws A `MigrationError` when the path is unsafe or names no directory, when two file names share a version, or when a version has no up file.
  *
  * @public
  */
 declare function scanDirectory(dirPath: string): ScannedMigration[];
 /**
- * Reads the up files of scanned migrations, leaving each down file to be read only if a rollback needs it.
+ * Returns migrations with the SQL from each scanned migration's up file. The
+ * migrations hold only the up SQL, and {@link loadMigrations} adds the down
+ * file read that a rollback uses.
  *
- * @param scanned - Migrations found by {@link scanDirectory}.
+ * @param scanned - The migrations that {@link scanDirectory} returns.
  * @returns The migrations, in ascending version order.
  *
  * @public
  */
 declare function readUpMigrations(scanned: ScannedMigration[]): Migration[];
 /**
- * Reads a directory of migration files and returns the migrations to apply.
+ * Returns the migrations from a directory of migration files, and reads each down file only when you roll that migration back.
  *
- * @param dirPath - Directory holding the migration files.
- * @param options - The baseline to apply, when an existing database starts from one.
+ * @param dirPath - The directory that holds the migration files.
+ * @param options - The baseline, when one migration replaces the earlier versions for a new database.
  * @returns The migrations, in ascending version order.
  *
  * @public

package/dist/file-migrations/index.mjs

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

package/dist/forward-rpc-VRWFZXHN.mjs

@@ -0,0 +1,44 @@
+import { toForwardRequest } from './chunk-ADNWEHGZ.mjs';
+import { TransportError } from './chunk-KU32OT4H.mjs';
+import './chunk-BLMRNSUG.mjs';
+import { SirannonError } from './chunk-KINDFBQP.mjs';
+import { Metadata } from '@grpc/grpc-js';
+
+function forwardOverRpc(entry, request, deadlineMs) {
+  const protoRequest = toForwardRequest(request);
+  const deadline = new Date(Date.now() + deadlineMs);
+  return new Promise((resolve, reject) => {
+    entry.client.forward(
+      protoRequest,
+      new Metadata(),
+      { deadline },
+      (err, response) => {
+        if (err) {
+          reject(new TransportError(`Forward RPC failed: ${err.message}`));
+          return;
+        }
+        if (!response) {
+          reject(new TransportError("Forward RPC returned empty response"));
+          return;
+        }
+        if (response.error) {
+          reject(
+            response.errorCode ? new SirannonError(response.error, response.errorCode) : new TransportError(`Forward RPC error: ${response.error}`)
+          );
+          return;
+        }
+        resolve({
+          requestId: response.requestId,
+          results: response.results.map((r) => ({
+            changes: r.changes,
+            lastInsertRowId: Number(r.lastInsertRowId)
+          })),
+          groupId: response.groupId || void 0,
+          primaryTerm: response.primaryTerm === 0n ? void 0 : response.primaryTerm
+        });
+      }
+    );
+  });
+}
+
+export { forwardOverRpc };

package/dist/operation-registry-CGhNT-Sn.d.ts

@@ -0,0 +1,96 @@
+import { P as Params } from './query-types-5B02ixH0.js';
+
+/** One statement that a registered operation executes, with its parameters.
+ * @public
+ */
+interface OperationStatement {
+    /** The statement to execute. */
+    sql: string;
+    /** The parameters to bind to that statement. */
+    params?: Params;
+}
+/** The values that a caller passes when it invokes a registered operation by name.
+ * @public
+ */
+type OperationArguments = Record<string, unknown>;
+/** A read that a caller invokes by name, so that the caller sends no SQL over the network.
+ * @public
+ */
+interface ReadOperation<Identity = unknown> {
+    /** The argument names that this operation accepts from the caller. */
+    args?: readonly string[];
+    /** The arguments that the server fills from the authenticated identity; a request that supplies one of them fails with `ARGUMENT_NOT_ALLOWED`. */
+    fromIdentity?: Readonly<Record<string, keyof Identity & string>>;
+    /**
+     * The column names of each row that this read returns. Code generation builds
+     * a typed row from this list, and when the list is absent, it takes the
+     * columns from the statement text, but only for an operation that takes no
+     * arguments, because the statement text can change with the arguments.
+     */
+    columns?: readonly string[];
+    /** Builds the statement that this read executes for a given set of arguments. */
+    statement(args: OperationArguments): OperationStatement;
+}
+/** A write that a caller invokes by name; the server executes every statement that it returns in one transaction.
+ * @public
+ */
+interface WriteOperation<Identity = unknown> {
+    /** The argument names that this operation accepts from the caller. */
+    args?: readonly string[];
+    /** The arguments that the server fills from the authenticated identity; a request that supplies one of them fails with `ARGUMENT_NOT_ALLOWED`. */
+    fromIdentity?: Readonly<Record<string, keyof Identity & string>>;
+    /** Builds the statements that this write executes for a given set of arguments. */
+    statements(args: OperationArguments): OperationStatement | readonly OperationStatement[];
+}
+/** The reads and writes that callers may invoke by name on a database.
+ * @public
+ */
+interface DatabaseOperations<Identity = unknown> {
+    /** The reads that callers may invoke, keyed by operation name. */
+    reads?: Readonly<Record<string, ReadOperation<Identity>>>;
+    /** The writes that 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 that a remote caller invokes, typed with the argument and
+ * row types of the registered operation. Only `name` exists at runtime, and
+ * `types` stays unassigned so that the compiler can infer both type parameters
+ * at the call site. Code generation emits one reference per registered
+ * operation.
+ *
+ * @public
+ */
+interface OperationRef<Args = OperationArguments, Row = Record<string, unknown>> {
+    /** The name that the server registered this operation under. */
+    readonly name: string;
+    /** A field for type inference only, which stays unassigned 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 - The name that the server registered the operation under.
+ * @returns A reference with that name and the two inferred types.
+ *
+ * @public
+ */
+declare function operationRef<Args = OperationArguments, Row = Record<string, unknown>>(name: string): OperationRef<Args, Row>;
+/**
+ * Returns the operation name from 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-CHNOYuN7.d.ts

@@ -0,0 +1,81 @@
+import { C as ConflictResolver, a as ConflictContext, b as ConflictResolution } from './types-DqODKeOq.js';
+
+type ColumnVersionGetter = (table: string, rowId: string) => Promise<Map<string, {
+    hlc: string;
+    nodeId: string;
+}>>;
+/**
+ * Resolves a conflict column by column, and returns a merged row with both sides' changes when the two sides changed different columns.
+ *
+ * The resolver compares the local row and the remote row with the remote
+ * change's `oldData` to find the columns that each side changed. When the two
+ * sets share no column, the resolver returns one row that holds both sides'
+ * changes. For each column that both sides changed, the resolver compares the
+ * remote HLC with that column's stamp from `getColumnVersions`, and it takes
+ * the remote value when the remote stamp is higher, or equal with a higher
+ * node ID. When the row has no column stamps, the resolver applies whole-row
+ * {@link LWWResolver}.
+ *
+ * @public
+ */
+declare class FieldMergeResolver implements ConflictResolver {
+    private readonly getColumnVersions;
+    private readonly lww;
+    constructor(getColumnVersions: ColumnVersionGetter);
+    /**
+     * Returns the resolution for one conflicting row, merging changes to different columns and settling each column that both sides changed by its per-column stamp.
+     *
+     * @param ctx - The local and incoming versions of one row.
+     * @returns The version to keep, or the merged row.
+     */
+    resolve(ctx: ConflictContext): Promise<ConflictResolution>;
+}
+
+/**
+ * Resolves a conflict by keeping the write with the higher hybrid logical clock (HLC) timestamp.
+ *
+ * The resolver accepts every remote delete without comparing timestamps, so a
+ * delete wins over a concurrent update. It also accepts the remote write
+ * when the local row has no timestamp. When the two timestamps are equal, the
+ * resolver accepts the remote write only if its node ID sorts higher, so that
+ * every node reaches the same resolution without coordination. Sirannon uses
+ * this resolver by default, and {@link PrimaryWinsResolver} and
+ * {@link FieldMergeResolver} fall back to it.
+ *
+ * @public
+ */
+declare class LWWResolver implements ConflictResolver {
+    /**
+     * Returns the incoming row when its stamp is higher, and the local row otherwise.
+     *
+     * @param ctx - The local and incoming versions of one row.
+     * @returns Which version to write.
+     */
+    resolve(ctx: ConflictContext): ConflictResolution;
+}
+
+/**
+ * Resolves a conflict in favour of the node that you name as primary.
+ *
+ * The resolver accepts a remote change that the primary wrote, and it keeps a
+ * local change that the primary wrote. When neither change comes from the
+ * primary, as with two replicas that sync through a relay, the resolver falls
+ * back to {@link LWWResolver}. Use it in a primary-replica topology where the
+ * primary's write always wins over a replica's.
+ *
+ * @public
+ */
+declare class PrimaryWinsResolver implements ConflictResolver {
+    private readonly primaryNodeId;
+    private readonly lww;
+    constructor(primaryNodeId: string);
+    /**
+     * Returns the version that the primary node wrote, or the last-writer-wins result when neither version comes from the primary.
+     *
+     * @param ctx - The local and incoming versions of one row.
+     * @returns Which version to write.
+     */
+    resolve(ctx: ConflictContext): ConflictResolution;
+}
+
+export { FieldMergeResolver as F, LWWResolver as L, PrimaryWinsResolver as P };

package/dist/protocol-DFpNNsIT.d.ts

@@ -0,0 +1,153 @@
+import { W as WriteConcern, R as ReadConcern, E as ExecuteResult } from './query-types-5B02ixH0.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from './server-options-aYtCkefX.js';
+
+/**
+ * Body of `POST /db/{id}/query`.
+ *
+ * @public
+ */
+interface QueryRequest {
+    /** The statement to execute. */
+    sql: string;
+    /** The values to bind to the statement, by name or by position. */
+    params?: Record<string, unknown> | unknown[];
+    /** The read concern that this read requires. */
+    readConcern?: ReadConcern;
+}
+/**
+ * Body of `POST /db/{id}/execute`.
+ *
+ * @public
+ */
+interface ExecuteRequest {
+    /** The statement to execute. */
+    sql: string;
+    /** The values to bind to the statement, by name or by position. */
+    params?: Record<string, unknown> | unknown[];
+    /** The acknowledgements that the server waits for before it confirms this write. */
+    writeConcern?: WriteConcern;
+}
+/**
+ * One statement inside a transaction or a registered write.
+ *
+ * @public
+ */
+interface TransactionStatement {
+    /** The statement to execute. */
+    sql: string;
+    /** The values to bind to the statement, by name or by position. */
+    params?: Record<string, unknown> | unknown[];
+}
+/**
+ * Body of `POST /db/{id}/transaction`, whose statements all succeed or all fail.
+ *
+ * @public
+ */
+interface TransactionRequest {
+    /** The statements to execute, in order. */
+    statements: TransactionStatement[];
+    /** The acknowledgements that the server waits for before it confirms the transaction. */
+    writeConcern?: WriteConcern;
+}
+/** The body of `POST /db/{id}/batch`, which the server commits atomically in one transaction with one fsync.
+ * @public
+ */
+interface BatchRequest {
+    /** The statement to execute for each parameter set. */
+    sql: string;
+    /** One parameter set for each execution of the statement. */
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    /** The acknowledgements that the server waits for before it confirms the batch. */
+    writeConcern?: WriteConcern;
+}
+/**
+ * The body that a read route returns.
+ *
+ * @public
+ */
+interface QueryResponse {
+    /** The rows that the statement returned, with blobs and large integers in their tagged wire form. */
+    rows: Record<string, unknown>[];
+}
+/**
+ * The body that a write route returns.
+ *
+ * @public
+ */
+interface ExecuteResponse {
+    /** The number of rows that the statement inserted, updated, or deleted. */
+    changes: number;
+    /** The row id that SQLite assigned to the last inserted row, as a decimal string when it exceeds the safe integer range. */
+    lastInsertRowId: number | string;
+}
+/**
+ * The body that a transaction route returns.
+ *
+ * @public
+ */
+interface TransactionResponse {
+    /** One result per statement, in the order that the transaction executed them. */
+    results: ExecuteResponse[];
+}
+/**
+ * The body that a batch route returns.
+ *
+ * @public
+ */
+interface BatchResponse {
+    /** One result per parameter set, in order. */
+    results: ExecuteResponse[];
+}
+/**
+ * The body of `POST /db/{id}/load`, which loads rows while the server relaxes the
+ * writer's durability. The server restores the configured durability before it
+ * sends the response. When the process crashes during a load, SQLite rolls back the
+ * uncommitted rows, so the client can send the load again.
+ *
+ * @public
+ */
+interface LoadRequest {
+    /** The statement to execute for each parameter set. */
+    sql: string;
+    /** One parameter set per row. */
+    paramsBatch: (Record<string, unknown> | unknown[])[];
+    /** The writer's durability level during the load. Defaults to 'off'. */
+    durability?: BulkLoadDurability;
+    /** Whether the server checkpoints the WAL after this load. Defaults to true, so set it to false on every batch except 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 that every failed route returns.
+ *
+ * @public
+ */
+interface ErrorResponse {
+    /** A machine-readable code, a human-readable message, and any details that the route adds. */
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * Converts a write result into its wire form, and encodes a row id beyond the
+ * safe integer range as a decimal string.
+ *
+ * @param result - The result that the local write returns.
+ * @returns The result in its wire form.
+ *
+ * @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 TransactionResponse as T, type TransactionStatement 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-5B02ixH0.d.ts

@@ -0,0 +1,129 @@
+/** The values to bind to a statement, as an object for named parameters or an array for positional ones.
+ * @public
+ */
+type Params = Record<string, unknown> | unknown[];
+/** Which nodes must acknowledge a write before the call returns.
+ * @public
+ */
+type WriteConcernLevel = 'local' | 'majority' | 'all';
+/** Which nodes must acknowledge a write, and how long the caller waits for their acknowledgements.
+ * @public
+ */
+interface WriteConcern {
+    /** Which nodes must acknowledge the write before the call returns. */
+    level: WriteConcernLevel;
+    /** The number of milliseconds to wait for those acknowledgements before the call fails. */
+    timeoutMs?: number;
+}
+/** How current the data must be before a node serves a read.
+ * @public
+ */
+type ReadConcernLevel = 'local' | 'majority' | 'linearizable';
+/** How current the data must be before a node serves a read.
+ * @public
+ */
+interface ReadConcern {
+    /** The level that the node must confirm before it responds. */
+    level: ReadConcernLevel;
+}
+/** Per-statement settings that you pass with the SQL and its parameters.
+ * @public
+ */
+interface QueryOptions {
+    /** The acknowledgements that a write waits for; in coordinator mode, the replication engine applies 'majority' when you omit it. */
+    writeConcern?: WriteConcern;
+    /** How current the data must be for a read; in coordinator mode, the replication engine enforces it and applies 'majority' when you omit it, while in static mode the engine ignores the setting. */
+    readConcern?: ReadConcern;
+}
+/** The result of a write statement such as INSERT, UPDATE, or DELETE.
+ * @public
+ */
+interface ExecuteResult {
+    /** The number of rows that the statement inserted, updated, or deleted. */
+    changes: number;
+    /** The row id that SQLite assigned to the last inserted row. */
+    lastInsertRowId: number | bigint;
+}
+/** The kind of change that a change event records.
+ * @public
+ */
+type ChangeOperation = 'insert' | 'update' | 'delete';
+/** The event that Sirannon delivers when a row in a watched table changes.
+ * @public
+ */
+interface ChangeEvent<T = Record<string, unknown>> {
+    /** Whether the change inserted, updated, or deleted the row. */
+    type: ChangeOperation;
+    /** The table that contains the row. */
+    table: string;
+    /** The row after the change; for a delete, this is an empty object and {@link ChangeEvent.oldRow} contains the previous row. */
+    row: T;
+    /** The row before an update or a delete. */
+    oldRow?: T;
+    /** The position of this change in the database's change log, which a subscriber resumes from. */
+    seq: bigint;
+    /** The time when Sirannon recorded the change, in milliseconds since the Unix epoch. */
+    timestamp: number;
+    /** The hybrid logical clock stamp that the writing node gave this change. */
+    hlc?: string;
+    /** The identifier of the node that wrote the change. */
+    origin?: string;
+    /** The primary key of the changed row, encoded as a string. */
+    rowId?: string;
+    /** The identifier of the transaction that made this change. */
+    txId?: string;
+    /** True on the last change of a transaction, so that a consumer can apply the whole transaction at once. */
+    txEnd?: boolean;
+}
+/** Builds a change subscription with an optional filter.
+ * @public
+ */
+interface SubscriptionBuilder {
+    /**
+     * Narrows the subscription to rows whose columns equal the given values.
+     *
+     * Sirannon delivers an update that moves a row into the matching set as an
+     * insert with no `oldRow`, and an update that moves a row out of the set as a
+     * delete with the old row and an empty `row`. It delivers an update that keeps
+     * the row in the set unchanged, and no event for an update whose row is
+     * outside the set both before and after. A synthesised event looks the same as
+     * a real insert or delete, so read `type` as the row entering or leaving the
+     * filter.
+     */
+    filter(conditions: Record<string, unknown>): SubscriptionBuilder;
+    /**
+     * Starts the subscription and calls the callback for each matching change.
+     *
+     * Sirannon never awaits the promise that your callback returns, so two calls to
+     * an asynchronous callback can overlap; chain the work onto one promise when
+     * each change has to finish before the next one starts. Sirannon passes a throw
+     * or a rejection from the callback to `options.onError`, and still delivers the
+     * change to every other subscriber on this table.
+     *
+     * @typeParam T - The shape of the table's rows, which types `row` and `oldRow`.
+     * @param callback - The function that Sirannon calls with each change that this subscription matches.
+     * @param options - The subscription options, including `onError`, which Sirannon calls with a failure of the callback or of the change-log poll.
+     * @returns A handle whose `unsubscribe` ends the subscription.
+     */
+    subscribe<T = Record<string, unknown>>(callback: (event: ChangeEvent<T>) => void, options?: SubscriptionOptions): Subscription;
+}
+/** The failure reporter for a change subscription.
+ * @public
+ */
+interface SubscriptionOptions {
+    /**
+     * Sirannon calls this with the failure of a change callback, and with the
+     * failure that stops the change-log poll after ten consecutive errors.
+     * Sirannon discards anything that this reporter throws.
+     */
+    onError?: (error: Error) => void;
+}
+/** The handle of an active subscription.
+ * @public
+ */
+interface Subscription {
+    /** Ends the subscription, after which Sirannon delivers no further events to the callback. */
+    unsubscribe(): void;
+}
+
+export type { ChangeEvent as C, ExecuteResult as E, Params as P, QueryOptions as Q, ReadConcern as R, Subscription as S, WriteConcern as W, ReadConcernLevel as a, ChangeOperation as b, SubscriptionBuilder as c, SubscriptionOptions as d, WriteConcernLevel as e };