@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/types-zhnRXrsb.d.ts

@@ -1,384 +0,0 @@
-declare class Transaction {
-    private readonly conn;
-    private _lastInsertRowId;
-    constructor(conn: SQLiteConnection);
-    query<T = Record<string, unknown>>(sql: string, params?: Params): Promise<T[]>;
-    execute(sql: string, params?: Params): Promise<ExecuteResult>;
-    executeBatch(sql: string, paramsBatch: Params[]): Promise<ExecuteResult[]>;
-    get lastInsertRowId(): number | bigint;
-    static run<T>(conn: SQLiteConnection, fn: (tx: Transaction) => Promise<T>): Promise<T>;
-}
-
-declare const MIGRATION_NAME_RE: RegExp;
-interface AppliedMigration {
-    version: number;
-    name: string;
-    applied_at: number;
-}
-interface MigrationBaseline {
-    through: number;
-}
-interface Migration {
-    version: number;
-    name: string;
-    up: string | ((tx: Transaction) => void | Promise<void>);
-    down?: string | ((tx: Transaction) => void | Promise<void>);
-    baseline?: MigrationBaseline;
-}
-type MigrationSource = Migration[] | (() => Migration[] | Promise<Migration[]>);
-interface AppliedMigrationEntry {
-    version: number;
-    name: string;
-}
-interface MigrationResult {
-    applied: AppliedMigrationEntry[];
-    skipped: number;
-}
-interface RollbackResult {
-    rolledBack: AppliedMigrationEntry[];
-}
-
-/** Query parameter types: named (object) or positional (array). */
-type Params = Record<string, unknown> | unknown[];
-type WriteConcernLevel = 'local' | 'majority' | 'all';
-interface WriteConcern {
-    level: WriteConcernLevel;
-    timeoutMs?: number;
-}
-type ReadConcernLevel = 'local' | 'majority' | 'linearizable';
-interface ReadConcern {
-    level: ReadConcernLevel;
-}
-interface QueryOptions {
-    writeConcern?: WriteConcern;
-    readConcern?: ReadConcern;
-}
-interface ClusterReadEndpointInfo {
-    nodeId: string;
-    endpoint: string;
-    readConcerns: ReadConcernLevel[];
-}
-/** The single word describing what a node can do right now. */
-type NodeHealthState = 'healthy' | 'degraded' | 'failing_over' | 'repairing' | 'syncing' | 'unavailable';
-/** The condition that produced a {@link NodeHealthState}. */
-type NodeHealthReason = 'in-sync' | 'lagging' | 'coordinator-unreachable' | 'draining' | 'repairing' | 'faulted' | 'sync-pending' | 'no-group-state';
-/**
- * The health of one node, covering only the node that reports it.
- *
- * `canRead` and `canWrite` are what that node will accept at this moment;
- * `state` and `reason` name the condition behind them.
- */
-interface NodeHealth {
-    state: NodeHealthState;
-    reason: NodeHealthReason;
-    canRead: boolean;
-    canWrite: boolean;
-}
-interface ClusterStatusInfo {
-    databaseId: string;
-    replicationGroupId?: string;
-    role?: 'primary' | 'replica';
-    currentPrimary?: {
-        nodeId: string;
-        endpoint?: string;
-    } | null;
-    primaryTerm?: bigint;
-    readEndpoints?: ClusterReadEndpointInfo[];
-    health: NodeHealthState;
-    healthReason: NodeHealthReason;
-}
-/** Result returned by mutation statements (INSERT, UPDATE, DELETE). */
-interface ExecuteResult {
-    changes: number;
-    lastInsertRowId: number | bigint;
-}
-/** CDC operation type. */
-type ChangeOperation = 'insert' | 'update' | 'delete';
-/** Event emitted when a watched table row changes. */
-interface ChangeEvent<T = Record<string, unknown>> {
-    type: ChangeOperation;
-    table: string;
-    row: T;
-    oldRow?: T;
-    seq: bigint;
-    timestamp: number;
-    hlc?: string;
-    origin?: string;
-    rowId?: string;
-    txId?: string;
-    txEnd?: boolean;
-}
-/** Context passed to query hooks. */
-interface QueryHookContext {
-    databaseId: string;
-    sql: string;
-    params?: Params;
-    metadata?: Record<string, unknown>;
-    writeConcern?: WriteConcern;
-    readConcern?: ReadConcern;
-}
-/** Hook invoked before a query is executed. Throw to deny. */
-type BeforeQueryHook = (ctx: QueryHookContext) => void | Promise<void>;
-/** Hook invoked after a query is executed. */
-type AfterQueryHook = (ctx: QueryHookContext & {
-    durationMs: number;
-}) => void | Promise<void>;
-/** Context passed to connection hooks. */
-interface ConnectionHookContext {
-    databaseId: string;
-    path: string;
-}
-/** Hook invoked before a database connection is established. */
-type BeforeConnectHook = (ctx: ConnectionHookContext) => void | Promise<void>;
-/** Hook invoked when a database is opened. */
-type DatabaseOpenHook = (ctx: ConnectionHookContext) => void | Promise<void>;
-/** Hook invoked when a database is closed. */
-type DatabaseCloseHook = (ctx: ConnectionHookContext) => void | Promise<void>;
-/** Hook invoked before a subscription is created. Throw to deny. */
-type BeforeSubscribeHook = (ctx: {
-    databaseId: string;
-    table: string;
-    filter?: Record<string, unknown>;
-}) => void | Promise<void>;
-/** Aggregated hook configuration. */
-interface HookConfig {
-    onBeforeQuery?: BeforeQueryHook | BeforeQueryHook[];
-    onAfterQuery?: AfterQueryHook | AfterQueryHook[];
-    onBeforeConnect?: BeforeConnectHook | BeforeConnectHook[];
-    onDatabaseOpen?: DatabaseOpenHook | DatabaseOpenHook[];
-    onDatabaseClose?: DatabaseCloseHook | DatabaseCloseHook[];
-    onBeforeSubscribe?: BeforeSubscribeHook | BeforeSubscribeHook[];
-}
-/** Metrics emitted after a query completes. */
-interface QueryMetrics {
-    databaseId: string;
-    sql: string;
-    durationMs: number;
-    rowsReturned?: number;
-    changes?: number;
-    error?: boolean;
-}
-/** Metrics emitted when a connection opens or closes. */
-interface ConnectionMetrics {
-    databaseId: string;
-    path: string;
-    readerCount: number;
-    event: 'open' | 'close';
-}
-/** Metrics emitted when a CDC event is dispatched. */
-interface CDCMetrics {
-    databaseId: string;
-    table: string;
-    operation: ChangeOperation;
-    subscriberCount: number;
-}
-/** Callbacks for metrics collection. */
-interface MetricsConfig {
-    onQueryComplete?: (metrics: QueryMetrics) => void;
-    onConnectionOpen?: (metrics: ConnectionMetrics) => void;
-    onConnectionClose?: (metrics: ConnectionMetrics) => void;
-    onCDCEvent?: (metrics: CDCMetrics) => void;
-}
-/** Configuration for automatic database lifecycle management. */
-interface LifecycleConfig {
-    autoOpen?: {
-        resolver: (id: string) => {
-            path: string;
-            options?: DatabaseOptions;
-        } | undefined;
-    };
-    /** Milliseconds before an idle database is closed. 0 = disabled. */
-    idleTimeout?: number;
-    /** Maximum number of concurrently open databases. 0 = unlimited. */
-    maxOpen?: number;
-}
-/** Options for opening a single database. */
-interface DatabaseOptions {
-    /** Open the database in read-only mode. */
-    readOnly?: boolean;
-    /** Number of read connections in the pool. Default: 4. */
-    readPoolSize?: number;
-    /** Enable WAL mode. Default: true. */
-    walMode?: boolean;
-    /**
-     * Writer durability (`PRAGMA synchronous`). Default: 'normal'. This is the
-     * level restored after every bulk load, whatever the load relaxed it to.
-     */
-    synchronous?: SynchronousLevel;
-    /** CDC polling interval in milliseconds. Default: 50. */
-    cdcPollInterval?: number;
-    /** CDC retention period in milliseconds. Default: 3_600_000 (1 hour). */
-    cdcRetention?: number;
-    /**
-     * Run writes on a dedicated worker thread so disk flushes never block the
-     * thread serving connections; reads stay on the calling thread. Requires a
-     * driver with a worker entry (the `better-sqlite3` and `node` drivers have
-     * one), otherwise opening throws. Default: off.
-     */
-    writerWorker?: boolean | WriterWorkerOptions;
-}
-interface WriterWorkerOptions {
-    /** Writes allowed in flight before new writes are rejected with a busy signal. Default: 1024. */
-    maxPendingWrites?: number;
-    /** Per-operation deadline in ms; when an operation stalls past it, its caller is rejected loudly while the worker keeps running, so a stalled write's outcome is indeterminate. 0 disables it. Default: 30000. */
-    writeTimeoutMs?: number;
-    /** Restarts the worker this many times after it crashes on its own before writes fail permanently. Default: 5. */
-    maxRestarts?: number;
-}
-/** Top-level options for the Sirannon database registry. */
-interface SirannonOptions {
-    driver: SQLiteDriver;
-    hooks?: HookConfig;
-    metrics?: MetricsConfig;
-    lifecycle?: LifecycleConfig;
-    migrations?: MigrationSource;
-    writerWorker?: boolean | WriterWorkerOptions;
-}
-/** Options for scheduled backups. */
-interface BackupScheduleOptions {
-    /** Cron expression (e.g., '0 * * * *' for hourly). */
-    cron: string;
-    /** Directory to store backup files. */
-    destDir: string;
-    /** Maximum number of backup files to keep. Default: 5. */
-    maxFiles?: number;
-    /**
-     * Sirannon evaluates the cron expression in this IANA time zone (e.g. 'America/New_York').
-     * When omitted, it uses the host's local time zone, which also sets the daylight saving rules that apply.
-     */
-    timezone?: string;
-    /** Called when a scheduled backup fails. Without this, errors are silently discarded. */
-    onError?: (error: Error) => void;
-}
-/** Builder for creating CDC subscriptions with optional filters. */
-interface SubscriptionBuilder {
-    filter(conditions: Record<string, unknown>): SubscriptionBuilder;
-    subscribe(callback: (event: ChangeEvent) => void): Subscription;
-}
-/** Handle for an active subscription. */
-interface Subscription {
-    unsubscribe(): void;
-}
-
-interface WorkerHostOptions {
-    writeTimeoutMs?: number;
-    maxRestarts?: number;
-}
-
-interface RunResult {
-    changes: number;
-    lastInsertRowId: number | bigint;
-}
-/**
- * Tells a caller running inside the operation that holds the writer from one
- * merely waiting on it. A runtime without async context tracking cannot answer
- * this, and answering it wrongly runs one caller's writes inside another
- * caller's transaction.
- */
-interface WriterContext {
-    run<T>(operation: () => T): T;
-    isActive(): boolean;
-    exit<T>(operation: () => T): T;
-}
-interface BackupEngine {
-    backup(conn: SQLiteConnection, destPath: string): Promise<void>;
-    schedule(conn: SQLiteConnection, options: BackupScheduleOptions, runExclusive: (op: () => Promise<void>) => Promise<void>): () => void;
-}
-interface BatchSummary {
-    rowsLoaded: number;
-    changes: number;
-}
-interface SQLiteStatement {
-    all<T = unknown>(...params: unknown[]): Promise<T[]>;
-    get<T = unknown>(...params: unknown[]): Promise<T | undefined>;
-    run(...params: unknown[]): Promise<RunResult>;
-    /**
-     * Like {@link all} but skips the safe-range BigInt narrowing, leaving every
-     * integer as a BigInt. The server wire path narrows and tags in one pass, so
-     * feeding it raw rows avoids a second walk. Optional: a driver that omits it
-     * falls back to {@link all}, still correct but with the extra narrowing walk.
-     */
-    allRaw?<T = unknown>(...params: unknown[]): Promise<T[]>;
-}
-interface GroupRunError {
-    message: string;
-    name?: string;
-    code?: string;
-}
-type GroupRunOutcome = {
-    ok: true;
-    results: RunResult[];
-} | {
-    ok: false;
-    error: GroupRunError;
-};
-interface SQLiteConnection {
-    exec(sql: string): Promise<void>;
-    prepare(sql: string): Promise<SQLiteStatement>;
-    transaction<T>(fn: (conn: SQLiteConnection) => Promise<T>): Promise<T>;
-    close(): Promise<void>;
-    runBatch?(sql: string, paramsBatch: readonly unknown[][]): Promise<RunResult[]>;
-    runBatchSummary?(sql: string, paramsBatch: readonly unknown[][]): Promise<BatchSummary>;
-    /**
-     * Runs several independent units in one transaction, one outcome per unit in
-     * order. A unit is one write or one whole transaction, and a unit that fails
-     * must not disturb the others.
-     */
-    runGroup?(units: readonly {
-        statements: readonly {
-            sql: string;
-            params?: readonly unknown[];
-            trusted?: boolean;
-        }[];
-    }[]): Promise<GroupRunOutcome[]>;
-}
-/**
- * SQLite `PRAGMA synchronous` level applied to a connection. `normal` is safe
- * from corruption in WAL mode but can lose the most recent commits on power
- * loss; `full` fsyncs every commit; `extra` adds a directory sync after the
- * rollback journal is unlinked in DELETE journal mode and equals `full` in
- * WAL mode; `off` hands writes to the OS without syncing and is sanctioned
- * only for re-runnable bulk loads.
- */
-type SynchronousLevel = 'off' | 'normal' | 'full' | 'extra';
-interface OpenOptions {
-    readonly?: boolean;
-    walMode?: boolean;
-    synchronous?: SynchronousLevel;
-}
-interface DriverCapabilities {
-    multipleConnections: boolean;
-    extensions: boolean;
-}
-/**
- * Lets a worker thread rebuild the driver, since the driver's `open` function
- * cannot cross the thread boundary. `specifier` must be importable from the
- * worker and `config` must survive a structured clone; the worker imports the
- * module and calls its `exportName` factory (default export otherwise) with it.
- */
-interface DriverWorkerEntry {
-    specifier: string;
-    exportName?: string;
-    config?: unknown;
-}
-interface SQLiteDriver {
-    readonly capabilities: DriverCapabilities;
-    open(path: string, options?: OpenOptions): Promise<SQLiteConnection>;
-    readonly worker?: DriverWorkerEntry;
-    /**
-     * Offloads writes to a worker thread. Only a driver whose runtime has
-     * threads implements this, which is what keeps the thread machinery out of
-     * bundles built for runtimes that do not.
-     */
-    startWriterHost?(path: string, options: OpenOptions, hostOptions?: WorkerHostOptions): Promise<SQLiteConnection>;
-    createWriterContext?(): WriterContext;
-    createBackupEngine?(): BackupEngine;
-    /**
-     * Makes an extension path absolute. Passing a bare name to `load_extension`
-     * would let the dynamic linker search its own paths and open a different
-     * library than the operator named.
-     */
-    resolveExtensionPath?(extensionPath: string): string;
-}
-
-export { type AfterQueryHook as A, type BeforeQueryHook as B, type ClusterStatusInfo as C, type DatabaseOptions as D, type ExecuteResult as E, type DriverWorkerEntry as F, MIGRATION_NAME_RE as G, type HookConfig as H, type MigrationBaseline as I, type MigrationSource as J, type NodeHealthReason as K, type LifecycleConfig as L, type Migration as M, type NodeHealth as N, type NodeHealthState as O, type Params as P, type QueryOptions as Q, type ReadConcern as R, type SirannonOptions as S, Transaction as T, type OpenOptions as U, type RunResult as V, type WriteConcern as W, type SQLiteStatement as X, type Subscription as Y, type WriteConcernLevel as Z, type WriterWorkerOptions as _, type SQLiteDriver as a, type BeforeConnectHook as b, type DatabaseOpenHook as c, type DatabaseCloseHook as d, type SQLiteConnection as e, type BackupScheduleOptions as f, type ReadConcernLevel as g, type ChangeEvent as h, type QueryHookContext as i, type ConnectionHookContext as j, type BeforeSubscribeHook as k, type MetricsConfig as l, type QueryMetrics as m, type ConnectionMetrics as n, type CDCMetrics as o, type SubscriptionBuilder as p, type MigrationResult as q, type RollbackResult as r, type SynchronousLevel as s, type WorkerHostOptions as t, type AppliedMigration as u, type AppliedMigrationEntry as v, type BatchSummary as w, type ChangeOperation as x, type ClusterReadEndpointInfo as y, type DriverCapabilities as z };