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

package/dist/database-backup-B7oszQ2n.d.ts

@@ -1,141 +0,0 @@
-import { h as BackupChainBase, i as BackupChainChange, g as BackupChain, k as BackupChainRecord, B as BackupDestination, I as SQLiteConnection, P as DriverCapabilities, Q as BackupEngine, p as BackupFileReport, y as BackupToDestinationOptions, f as BackupRunReport, O as BackupScheduleOptions, n as BackupCycleOptions, o as BackupCycleStatus, z as BackupVerifyResult } from './types-DPSmjU54.js';
-
-/**
- * What one runtime supports of the backup operations, so a caller learns
- * before a run rather than at failure time. A runtime that hands over whole
- * databases only reports no full copy at all.
- *
- * @public
- */
-interface BackupCapabilities {
-    /** Whether this runtime copies an open database while writes continue. */
-    fullCopy: boolean;
-    /** Whether a full copy reaches the destination without a local file. */
-    streamedCopy: boolean;
-    /** Whether a full copy writes a local file and sends that file on. */
-    stagedCopy: boolean;
-    /** Local disk a full copy needs, which the staged route sets to the size of the backup. */
-    localDiskRequired: 'none' | 'equal-to-backup';
-    /** Whether this runtime repeats a full copy on a schedule. */
-    schedule: boolean;
-}
-
-/** What one restore has to read, and what it will produce.
- * @public
- */
-interface BackupRestorePlan {
-    /** The chain to read. */
-    chainId: string;
-    /** The full copy to start from. */
-    base: BackupChainBase;
-    /** The change pieces to apply on top of it, oldest first. */
-    changes: BackupChainChange[];
-    /**
-     * Epoch milliseconds the restored database will reflect. This is when the
-     * last piece in the plan was captured, which is at or before the moment you
-     * asked for.
-     */
-    restoresTo: number;
-}
-/** How far back you still want to be able to restore.
- * @public
- */
-interface BackupSafeToDeleteOptions {
-    /**
-     * Epoch milliseconds of the earliest moment a restore must still reach.
-     * Leave it out and the answer covers only the backups no restore could ever
-     * use.
-     */
-    restorableFrom?: number;
-}
-/**
- * Works out what a restore to a given moment has to read: the newest full copy
- * finished at or before it, then every change piece captured from that copy up
- * to it.
- *
- * You get back the moment the result will actually reflect, which is when the
- * last piece was captured. One piece covers every write in the interval it was
- * taken over, so a restore arrives at a piece boundary, not at the exact
- * millisecond you named.
- *
- * A gap in the chain fails the plan with `BACKUP_CHAIN_BROKEN` and names the
- * missing piece, because a plan that stopped part-way through would leave a
- * database nobody could trust.
- *
- * @param chains - The chains a destination holds, as {@link readBackupChains} returns them.
- * @param moment - Epoch milliseconds you want back.
- * @returns The full copy, the change pieces to apply, and the moment the result reflects.
- *
- * @public
- */
-declare function planBackupRestore(chains: readonly BackupChain[], moment: number): BackupRestorePlan;
-/**
- * Tells you which backups no restore still needs, so you can delete them
- * knowing exactly what you give up.
- *
- * Two kinds are dead whatever you ask for: a chain whose full copy has gone,
- * and every change piece after a gap, since nothing can be replayed past the
- * gap. Name the earliest moment you still want to reach and the answer also
- * covers the older chains a newer full copy already spans.
- *
- * Sirannon lists them and deletes nothing. The destination is yours.
- *
- * @param chains - The chains a destination holds, as {@link readBackupChains} returns them.
- * @param options - How far back you still want to be able to restore.
- * @returns The records you may delete, oldest first.
- *
- * @public
- */
-declare function backupPiecesSafeToDelete(chains: readonly BackupChain[], options?: BackupSafeToDeleteOptions): BackupChainRecord[];
-
-type RunExclusive = (op: () => Promise<void>) => Promise<void>;
-/** Where one database's backups are stored, and what a restore of that database reads.
- * @public
- */
-interface BackupChainLocation {
-    /** The destination its pieces and its chain records go to. */
-    destination: BackupDestination;
-    /** Name that destination lists its chains under. */
-    chainName: string;
-    /** Directory the cycle stages each capture in before that capture goes out. */
-    stagingDir: string;
-    /** Deadline the operator set on every call to that destination, where they set one. */
-    destinationTimeoutMs?: number;
-}
-declare class DatabaseBackupController {
-    private readonly runExclusive;
-    private readonly acquireWriter;
-    private readonly driverCapabilities;
-    private readonly databaseId;
-    private readonly sourcePath;
-    private readonly engine?;
-    private readonly cancellers;
-    private cycle;
-    private cycleOptions;
-    private cycleStarted;
-    constructor(runExclusive: RunExclusive, acquireWriter: () => SQLiteConnection, driverCapabilities: DriverCapabilities, databaseId: string, sourcePath: string, engine?: BackupEngine | undefined);
-    private require;
-    private requireCycle;
-    capabilities(): BackupCapabilities;
-    backup(destPath: string): Promise<BackupFileReport>;
-    backupTo(options: BackupToDestinationOptions): Promise<BackupRunReport>;
-    schedule(options: BackupScheduleOptions): void;
-    /**
-     * Builds the cycle and starts it in the background. Its first turn copies the
-     * whole database, and an open cannot wait on that. A failure reaches the
-     * caller through the cycle's own error callback.
-     */
-    startCycle(options: BackupCycleOptions): void;
-    captureChanges(): Promise<BackupRunReport | undefined>;
-    chains(): Promise<BackupChain[]>;
-    status(): BackupCycleStatus;
-    location(): BackupChainLocation;
-    verify(name: string): Promise<BackupVerifyResult>;
-    restorePlan(moment: number): Promise<BackupRestorePlan>;
-    piecesSafeToDelete(options?: BackupSafeToDeleteOptions): Promise<BackupChainRecord[]>;
-    /** Stops the cycle, capturing the log one final time so nothing written since the previous turn is lost. */
-    stopCycle(): Promise<void>;
-    cancelAll(): void;
-}
-
-export { type BackupCapabilities as B, DatabaseBackupController as D, type BackupChainLocation as a, type BackupRestorePlan as b, type BackupSafeToDeleteOptions as c, backupPiecesSafeToDelete as d, planBackupRestore as p };

package/dist/errors-Dei4GdBb.d.ts

@@ -1,196 +0,0 @@
-/**
- * Base class for all sirannon-db errors. Extend this class to create
- * 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, 
-    /**
-     * 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);
-}
-/**
- * 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);
-}
-/**
- * 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 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, 
-    /**
-     * 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 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 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);
-}
-/**
- * Thrown when a caller reaches for a table Sirannon reserves for itself. The
- * 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);
-}
-/**
- * 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);
-}
-/**
- * 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);
-}
-/**
- * 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);
-}
-/**
- * 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(
-    /**
-     * 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);
-}
-
-export { BackupError as B, CDCError as C, DatabaseAlreadyExistsError as D, ExtensionError as E, ForbiddenSqlError as F, HookDeniedError as H, MaxDatabasesError as M, QueryError as Q, ReadOnlyError as R, SirannonError as S, TransactionError as T, WriteOverloadError as W, ConnectionPoolError as a, DatabaseNotFoundError as b, MigrationError as c, RequestDeniedError as d };

package/dist/operation-registry-oiPuSYI6.d.ts

@@ -1,94 +0,0 @@
-import { P as Params } from './query-types-p1liOP-b.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
-     * row from it, and reads the columns from the statement only when the
-     * 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-B0np8JS3.d.ts

@@ -1,85 +0,0 @@
-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;
-    nodeId: string;
-}>>;
-/**
- * Per-column conflict resolver that merges non-overlapping field changes.
- *
- * Given a conflict between a local and remote write on the same row, this
- * resolver computes the set of columns each side changed relative to the
- * common ancestor (oldData). If the changed column sets don't overlap, both
- * sides' changes are merged into a single row, avoiding unnecessary data
- * loss. When columns do overlap, per-column HLC versions (retrieved via the
- * 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>;
-}
-
-/**
- * Last-Writer-Wins conflict resolver.
- *
- * A remote delete is accepted whatever the timestamps say, so a delete wins over
- * a concurrent update and a deleted row is never resurrected.
- *
- * Otherwise compares the remote HLC against the local HLC. The higher timestamp wins.
- * When both timestamps are equal (concurrent writes within the same
- * millisecond and logical tick), the tie is broken deterministically by
- * comparing node IDs lexicographically, so that every node reaches the same
- * 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;
-}
-
-/**
- * Conflict resolver that unconditionally favors the designated primary node.
- *
- * If the remote change originated from the primary, it is accepted. If the
- * local change originated from the primary, the remote is rejected. When
- * neither side is the primary (e.g., two replicas syncing through a relay),
- * 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;
-}
-
-export { FieldMergeResolver as F, LWWResolver as L, PrimaryWinsResolver as P };

package/dist/protocol-HI-nY8DD.d.ts

@@ -1,152 +0,0 @@
-import { W as WriteConcern, R as ReadConcern, E as ExecuteResult } from './query-types-p1liOP-b.js';
-import { B as BulkLoadDurability, a as BulkLoadResult } from './server-options-Bj5iJnjx.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 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 };