@delali/sirannon-db 0.1.5 → 0.1.7

package/dist/{sirannon-Cd-lK6T0.d.ts → sirannon-4SspRvP5.d.ts}

@@ -1,6 +1,5 @@
-import { D as Database } from './database-BVY1GqE7.js';
-import { S as SQLiteDriver } from './types-BFSsG77t.js';
-import { S as SirannonOptions, D as DatabaseOptions, B as BeforeQueryHook, A as AfterQueryHook, a as BeforeConnectHook, b as DatabaseOpenHook, c as DatabaseCloseHook } from './types-D-74JiXb.js';
+import { D as Database } from './database-DuGp0Rtr.js';
+import { S as SirannonOptions, a as SQLiteDriver, D as DatabaseOptions, B as BeforeQueryHook, A as AfterQueryHook, b as BeforeConnectHook, c as DatabaseOpenHook, d as DatabaseCloseHook } from './types-D_hQW1hr.js';
 
 declare class Sirannon {
     readonly options: SirannonOptions;
@@ -14,6 +13,7 @@ declare class Sirannon {
     constructor(options: SirannonOptions);
     get driver(): SQLiteDriver;
     open(id: string, path: string, options?: DatabaseOptions): Promise<Database>;
+    private withRegistryDefaults;
     close(id: string): Promise<void>;
     get(id: string): Database | undefined;
     resolve(id: string): Promise<Database | undefined>;

package/dist/transport/grpc.d.ts

@@ -1,10 +1,9 @@
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { Client, ClientDuplexStream, CallOptions, Metadata, ServiceError, ClientUnaryCall, ChannelCredentials, ClientOptions, ServerDuplexStream, Server } from '@grpc/grpc-js';
 import { HealthImplementation } from 'grpc-health-check';
-import { R as ReplicationBatch, a as ReplicationAck, F as ForwardedTransaction, b as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, c as SyncBatch, d as SyncComplete, e as SyncAck, f as ReplicationTransport, T as TopologyRole, g as TransportConfig } from '../types-B2byqt0B.js';
-import '../change-tracker-CFTQ9TSn.js';
-import '../types-BFSsG77t.js';
-import '../types-D-74JiXb.js';
+import { R as ReplicationBatch, a as ReplicationAck, F as ForwardedTransaction, b as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, c as SyncBatch, d as SyncComplete, e as SyncAck, f as ReplicationTransport, T as TopologyRole, g as TransportConfig } from '../types-BsjobKbl.js';
+import '../change-tracker-CbmaMO-N.js';
+import '../types-D_hQW1hr.js';
 import '../types-BEu1I_9_.js';
 
 interface ColumnValue {
@@ -92,6 +91,7 @@ interface SyncBatchPayload {
     isLastBatchForTable: boolean;
     groupId: string;
     primaryTerm: bigint;
+    totalTables: number;
 }
 declare const SyncBatchPayload: MessageFns<SyncBatchPayload>;
 interface SyncCompletePayload {

package/dist/transport/grpc.mjs

@@ -1,5 +1,5 @@
-import { TransportError } from '../chunk-UVMVN3OT.mjs';
-import '../chunk-O7BHI3CF.mjs';
+import { TransportError } from '../chunk-H5AB6NIR.mjs';
+import '../chunk-YPYVQJ4C.mjs';
 import { makeGenericClientConstructor, Metadata, Server, status, ServerCredentials, credentials } from '@grpc/grpc-js';
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import { readFileSync } from 'fs';
@@ -160,7 +160,8 @@ function toSyncBatchPayload(batch) {
     checksum: batch.checksum,
     isLastBatchForTable: batch.isLastBatchForTable,
     groupId: batch.groupId ?? "",
-    primaryTerm: batch.primaryTerm ?? 0n
+    primaryTerm: batch.primaryTerm ?? 0n,
+    totalTables: batch.totalTables ?? 0
   };
 }
 function fromSyncBatchPayload(p) {
@@ -173,7 +174,8 @@ function fromSyncBatchPayload(p) {
     checksum: p.checksum,
     isLastBatchForTable: p.isLastBatchForTable,
     groupId: p.groupId || void 0,
-    primaryTerm: p.primaryTerm === 0n ? void 0 : p.primaryTerm
+    primaryTerm: p.primaryTerm === 0n ? void 0 : p.primaryTerm,
+    totalTables: p.totalTables === 0 ? void 0 : p.totalTables
   };
 }
 function toSyncCompletePayload(complete) {
@@ -1455,7 +1457,8 @@ function createBaseSyncBatchPayload() {
     checksum: "",
     isLastBatchForTable: false,
     groupId: "",
-    primaryTerm: 0n
+    primaryTerm: 0n,
+    totalTables: 0
   };
 }
 var SyncBatchPayload = {
@@ -1490,6 +1493,9 @@ var SyncBatchPayload = {
       }
       writer.uint32(72).int64(message.primaryTerm);
     }
+    if (message.totalTables !== 0) {
+      writer.uint32(80).int32(message.totalTables);
+    }
     return writer;
   },
   decode(input, length) {
@@ -1562,6 +1568,13 @@ var SyncBatchPayload = {
           message.primaryTerm = reader.int64();
           continue;
         }
+        case 10: {
+          if (tag !== 80) {
+            break;
+          }
+          message.totalTables = reader.int32();
+          continue;
+        }
       }
       if ((tag & 7) === 4 || tag === 0) {
         break;
@@ -1580,7 +1593,8 @@ var SyncBatchPayload = {
       checksum: isSet(object.checksum) ? globalThis.String(object.checksum) : "",
       isLastBatchForTable: isSet(object.isLastBatchForTable) ? globalThis.Boolean(object.isLastBatchForTable) : isSet(object.is_last_batch_for_table) ? globalThis.Boolean(object.is_last_batch_for_table) : false,
       groupId: isSet(object.groupId) ? globalThis.String(object.groupId) : isSet(object.group_id) ? globalThis.String(object.group_id) : "",
-      primaryTerm: isSet(object.primaryTerm) ? BigInt(object.primaryTerm) : isSet(object.primary_term) ? BigInt(object.primary_term) : 0n
+      primaryTerm: isSet(object.primaryTerm) ? BigInt(object.primaryTerm) : isSet(object.primary_term) ? BigInt(object.primary_term) : 0n,
+      totalTables: isSet(object.totalTables) ? globalThis.Number(object.totalTables) : isSet(object.total_tables) ? globalThis.Number(object.total_tables) : 0
     };
   },
   toJSON(message) {
@@ -1612,6 +1626,9 @@ var SyncBatchPayload = {
     if (message.primaryTerm !== 0n) {
       obj.primaryTerm = message.primaryTerm.toString();
     }
+    if (message.totalTables !== 0) {
+      obj.totalTables = Math.round(message.totalTables);
+    }
     return obj;
   },
   create(base) {
@@ -1628,6 +1645,7 @@ var SyncBatchPayload = {
     message.isLastBatchForTable = object.isLastBatchForTable ?? false;
     message.groupId = object.groupId ?? "";
     message.primaryTerm = object.primaryTerm ?? 0n;
+    message.totalTables = object.totalTables ?? 0;
     return message;
   }
 };

package/dist/transport/memory.d.ts

@@ -106,6 +106,7 @@ interface SyncBatch {
     schema?: string[];
     checksum: string;
     isLastBatchForTable: boolean;
+    totalTables?: number;
     groupId?: string;
     primaryTerm?: bigint;
 }

package/dist/transport/memory.mjs

@@ -66,7 +66,7 @@ function isValidSyncRequest(req) {
 function isValidSyncBatch(batch) {
   if (typeof batch !== "object" || batch === null) return false;
   const b = batch;
-  return typeof b.requestId === "string" && typeof b.table === "string" && typeof b.batchIndex === "number" && Array.isArray(b.rows) && typeof b.checksum === "string" && typeof b.isLastBatchForTable === "boolean" && optionalString(b.groupId) && optionalBigint(b.primaryTerm);
+  return typeof b.requestId === "string" && typeof b.table === "string" && typeof b.batchIndex === "number" && Array.isArray(b.rows) && typeof b.checksum === "string" && typeof b.isLastBatchForTable === "boolean" && optionalNonNegativeInteger(b.totalTables) && optionalString(b.groupId) && optionalBigint(b.primaryTerm);
 }
 function isValidSyncComplete(complete) {
   if (typeof complete !== "object" || complete === null) return false;
@@ -84,6 +84,9 @@ function optionalString(value) {
 function optionalBigint(value) {
   return value === void 0 || typeof value === "bigint";
 }
+function optionalNonNegativeInteger(value) {
+  return value === void 0 || typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
 
 // src/transport/memory/transport.ts
 var InMemoryTransport = class {

package/dist/{types-B2byqt0B.d.ts → types-BsjobKbl.d.ts}

@@ -1,5 +1,5 @@
-import { C as ChangeTracker } from './change-tracker-CFTQ9TSn.js';
-import { a as SQLiteConnection } from './types-BFSsG77t.js';
+import { C as ChangeTracker } from './change-tracker-CbmaMO-N.js';
+import { e as SQLiteConnection } from './types-D_hQW1hr.js';
 import { C as ClusterCoordinator, j as CoordinatorCompatibilityMetadata, c as ReplicationGroupState } from './types-BEu1I_9_.js';
 
 interface NodeInfo {
@@ -238,6 +238,7 @@ interface SyncBatch {
     schema?: string[];
     checksum: string;
     isLastBatchForTable: boolean;
+    totalTables?: number;
     groupId?: string;
     primaryTerm?: bigint;
 }

package/dist/{types-BeozgNPr.d.ts → types-D4p4UyDK.d.ts}

@@ -1,4 +1,4 @@
-import { T as Transaction } from './types-D-74JiXb.js';
+import { T as Transaction } from './types-D_hQW1hr.js';
 
 interface AppliedMigration {
     version: number;

package/dist/types-D_hQW1hr.d.ts

@@ -0,0 +1,494 @@
+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>;
+}
+
+/** 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[];
+}
+interface ClusterStatusInfo {
+    databaseId: string;
+    replicationGroupId?: string;
+    role?: 'primary' | 'replica';
+    currentPrimary?: {
+        nodeId: string;
+        endpoint?: string;
+    } | null;
+    primaryTerm?: bigint;
+    readEndpoints?: ClusterReadEndpointInfo[];
+    health: 'healthy' | 'degraded' | 'failing_over' | 'unavailable' | 'repairing' | 'syncing';
+}
+/** 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;
+}
+/** 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;
+    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;
+}
+/** Context passed to the onRequest middleware hook. */
+interface RequestContext {
+    headers: Record<string, string>;
+    method: string;
+    path: string;
+    databaseId?: string;
+    remoteAddress: string;
+}
+/** Return this from an onRequest hook to deny the request with a custom response. */
+interface RequestDenial {
+    status: number;
+    code: string;
+    message: string;
+}
+/** Middleware hook for auth, rate limiting, and request validation. */
+type OnRequestHook = (ctx: RequestContext) => undefined | RequestDenial | Promise<undefined | RequestDenial>;
+/**
+ * Durability level in force while a bulk load runs. SQLite sanctions 'off' for
+ * a from-scratch load that the operator can re-run after a power loss; 'off'
+ * gives up corruption safety, so it fits only a load that starts from nothing.
+ * 'normal' keeps WAL-mode corruption safety and suits loads into a database
+ * that already holds data the operator cannot afford to lose.
+ */
+type BulkLoadDurability = 'off' | 'normal';
+interface BulkLoadOptions {
+    /** Durability during the load. Default: 'off'. */
+    durability?: BulkLoadDurability;
+    /**
+     * Whether this load ends with a WAL checkpoint. Default: true. Set it false
+     * on every load but the last of a multi-batch import so the one fsyncing
+     * checkpoint is paid once at the end instead of once per batch; the
+     * configured durability is still restored after each batch regardless, so an
+     * abandoned import never leaves the writer at the relaxed level.
+     */
+    checkpoint?: boolean;
+}
+/** Aggregate outcome of a bulk load. Summed rather than per-row so a
+ * million-row load never holds a million result objects in memory. */
+interface BulkLoadResult {
+    rowsLoaded: number;
+    changes: number;
+}
+interface ServerExecutionTarget {
+    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
+    /**
+     * Optional single-pass read that returns rows already encoded for the wire
+     * (safe-range integers as plain numbers, larger integers and BLOBs as tagged
+     * envelopes). When present the server uses it instead of {@link query}
+     * followed by a separate tag-encoding walk. A target that omits it stays
+     * correct: the server falls back to encoding {@link query} rows itself.
+     */
+    queryForWire?(sql: string, params?: Params, options?: QueryOptions): Promise<unknown[]>;
+    execute(sql: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>, options?: QueryOptions): Promise<T>;
+    /**
+     * Optional entry point for a transaction whose statements are all known
+     * before it starts, which lets concurrent transactions share one commit. A
+     * target that omits it stays correct: the server falls back to
+     * {@link transaction} and runs the statements one at a time.
+     */
+    executeTransaction?(statements: readonly {
+        sql: string;
+        params?: Params;
+    }[], options?: QueryOptions): Promise<ExecuteResult[]>;
+    /**
+     * Optional bulk-load entry point. Targets that proxy to a remote primary
+     * may omit it; the server rejects load requests for such targets instead
+     * of silently degrading to per-statement writes.
+     */
+    bulkLoad?(sql: string, paramsBatch: Params[], options?: BulkLoadOptions): Promise<BulkLoadResult>;
+}
+type ServerExecutionTargetResolver = (databaseId: string) => ServerExecutionTarget | null | undefined | Promise<ServerExecutionTarget | null | undefined>;
+/** Options for the standalone HTTP + WS server. */
+interface ServerOptions {
+    host?: string;
+    port?: number;
+    cors?: boolean | CorsOptions;
+    /**
+     * Maximum HTTP request body and WebSocket message size in bytes. Applied
+     * identically to both transports. Must be a positive, finite integer no
+     * larger than 4_294_967_295 (the unsigned 32-bit ceiling uWebSockets.js can
+     * store; larger values would silently wrap modulo 2^32).
+     * Default: 1_048_576 (1 MB), matching the general web default and acting as
+     * a denial-of-service guard on a memory-limited server.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Maximum bytes buffered per WebSocket connection before the server stops
+     * absorbing backpressure. A single frame can be as large as `maxBodyBytes`,
+     * so this must hold several of them; the resolved value is raised to at
+     * least `maxBodyBytes` and, like `maxBodyBytes`, must not exceed
+     * 4_294_967_295. When the buffer is exceeded the server closes the
+     * connection so the client reconnects rather than losing a frame silently.
+     * Default: the larger of 16 MB and `maxBodyBytes`.
+     */
+    maxWebSocketBackpressureBytes?: number;
+    /**
+     * How long, in milliseconds, change events are retained for WebSocket CDC
+     * subscriptions. Retention bounds both on-disk growth of the change log and
+     * how far back a reconnecting subscriber can resume. Default: 3_600_000
+     * (one hour).
+     */
+    cdcRetentionMs?: number;
+    onRequest?: OnRequestHook;
+    resolveExecutionTarget?: ServerExecutionTargetResolver;
+    getReplicationStatus?: () => ReplicationStatusInfo | null;
+    getClusterStatus?: (databaseId: string) => ClusterStatusInfo | null;
+}
+interface ReplicationStatusInfo {
+    role: string;
+    writeForwarding: boolean;
+    peers: number;
+    localSeq: bigint;
+    replicationGroupId?: string;
+    primaryTerm?: bigint;
+    currentPrimary?: string;
+    coordinator?: {
+        connected: boolean;
+        authority: boolean;
+    };
+    controller?: {
+        state: 'disabled' | 'standby' | 'active' | 'lost';
+    };
+    inSyncReplicas?: string[];
+    laggingReplicas?: string[];
+    syncState?: string;
+    readAvailability?: 'available' | 'unavailable';
+    writeAvailability?: 'available' | 'unavailable';
+}
+/** CORS configuration. */
+interface CorsOptions {
+    origin?: string | string[];
+    methods?: string[];
+    headers?: string[];
+}
+/** Options for the mountable WebSocket handler. */
+interface WSHandlerOptions {
+    /** Maximum message size in bytes. Default: 1_048_576 (1 MB). */
+    maxPayloadLength?: number;
+    /** Change-log retention for CDC subscriptions in milliseconds. Default: 3_600_000. */
+    cdcRetentionMs?: number;
+    resolveExecutionTarget?: ServerExecutionTargetResolver;
+}
+/** Options for the client SDK. */
+interface ClientOptions {
+    /** Transport to use. Default: 'websocket'. */
+    transport?: 'websocket' | 'http';
+    /** Custom headers for HTTP requests. */
+    headers?: Record<string, string>;
+    /** WebSocket subprotocols sent during the browser-compatible handshake. */
+    webSocketProtocols?: string | string[];
+    /** Reconnect on WebSocket disconnect. Default: true. */
+    autoReconnect?: boolean;
+    /** Reconnect interval in ms. Default: 1000. */
+    reconnectInterval?: number;
+    /**
+     * Per-request timeout in milliseconds for the WebSocket transport. A bulk
+     * load or batch of tens of millions of rows can legitimately run longer than
+     * the default, so raise this for large writes. Set to 0 to wait indefinitely.
+     * Default: 30000.
+     */
+    requestTimeout?: number;
+}
+
+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[];
+        }[];
+    }[]): 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 WriteConcernLevel as $, type AfterQueryHook as A, type BeforeQueryHook as B, type ChangeEvent as C, type DatabaseOptions as D, type ExecuteResult as E, type DriverCapabilities as F, type DriverWorkerEntry as G, type HookConfig as H, type OpenOptions as I, type ReadConcernLevel as J, type ReplicationStatusInfo as K, type LifecycleConfig as L, type MetricsConfig as M, type RequestContext as N, type OnRequestHook as O, type Params as P, type QueryHookContext as Q, type ReadConcern as R, type SirannonOptions as S, Transaction as T, type RequestDenial as U, type RunResult as V, type WriteConcern as W, type SQLiteStatement as X, type ServerExecutionTarget as Y, type ServerExecutionTargetResolver as Z, type Subscription as _, type SQLiteDriver as a, type WriterWorkerOptions as a0, type BeforeConnectHook as b, type DatabaseOpenHook as c, type DatabaseCloseHook as d, type SQLiteConnection as e, type BackupScheduleOptions as f, type BulkLoadDurability as g, type BulkLoadResult as h, type ServerOptions as i, type WSHandlerOptions as j, type ConnectionHookContext as k, type BeforeSubscribeHook as l, type QueryMetrics as m, type ConnectionMetrics as n, type CDCMetrics as o, type QueryOptions as p, type BulkLoadOptions as q, type SubscriptionBuilder as r, type SynchronousLevel as s, type WorkerHostOptions as t, type BatchSummary as u, type ChangeOperation as v, type ClientOptions as w, type ClusterReadEndpointInfo as x, type ClusterStatusInfo as y, type CorsOptions as z };