@delali/sirannon-db 0.1.7 → 0.2.0

package/dist/server-options-1JHu8pid.d.ts

@@ -0,0 +1,191 @@
+import { a as OperationRegistry } from './operation-registry-9DcvxcE5.js';
+import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult } from './types-C_D8IhpO.js';
+import { N as NodeHealth, P as Params, Q as QueryOptions, E as ExecuteResult, T as Transaction, C as ClusterStatusInfo } from './types-zhnRXrsb.js';
+
+interface AppliedMigrationRow {
+    version: number;
+    name: string;
+    checksum: string | null;
+}
+
+/** Context passed to the authenticate hook. */
+interface RequestContext {
+    headers: Record<string, string>;
+    method: string;
+    path: string;
+    databaseId?: string;
+    remoteAddress: string;
+}
+type AuthenticateHook<Identity = unknown> = (ctx: RequestContext) => Identity | undefined | Promise<Identity | undefined>;
+type ClusterStatusAuthorizer = (ctx: RequestContext) => boolean | Promise<boolean>;
+/**
+ * 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>;
+    applyChanges?(batch: ReplicationBatch, resolver?: ConflictResolver | ((table: string) => ConflictResolver)): Promise<ApplyResult>;
+    appliedMigrations?(): Promise<AppliedMigrationRow[]>;
+}
+type ServerExecutionTargetResolver = (databaseId: string) => ServerExecutionTarget | null | undefined | Promise<ServerExecutionTarget | null | undefined>;
+/** Options for the standalone HTTP + WS server. */
+interface ServerOptions<Identity = unknown> {
+    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;
+    deviceCursorRetentionMs?: number;
+    maxUnacknowledgedChanges?: number;
+    authenticate?: AuthenticateHook<Identity>;
+    operations?: OperationRegistry<Identity>;
+    acceptSql?: boolean;
+    resolveExecutionTarget?: ServerExecutionTargetResolver;
+    getReplicationStatus?: () => ReplicationStatusInfo | null;
+    getClusterStatus?: (databaseId: string) => ClusterStatusInfo | null;
+    authorizeClusterStatus?: ClusterStatusAuthorizer;
+}
+interface ReplicationStatusInfo {
+    role: string;
+    writeForwarding: boolean;
+    peers: number;
+    localSeq: bigint;
+    health: NodeHealth;
+    replicationGroupId?: string;
+    primaryTerm?: bigint;
+    currentPrimary?: string;
+    coordinator?: {
+        connected: boolean;
+        authority: boolean;
+    };
+    controller?: {
+        state: 'disabled' | 'standby' | 'active' | 'lost';
+    };
+    inSyncReplicas?: string[];
+    laggingReplicas?: string[];
+    syncState?: string;
+}
+/** CORS configuration. */
+interface CorsOptions {
+    origin?: string | string[];
+    methods?: string[];
+    headers?: string[];
+}
+/** Options for the mountable WebSocket handler. */
+interface WSHandlerOptions<Identity = unknown> {
+    /** 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;
+    deviceCursorRetentionMs?: number;
+    maxUnacknowledgedChanges?: number;
+    acceptSql?: boolean;
+    operations?: OperationRegistry<Identity>;
+    resolveExecutionTarget?: ServerExecutionTargetResolver;
+}
+/** Options for the client SDK. */
+interface ClientOptions {
+    /** Transport to use. Default: 'websocket'. */
+    transport?: 'websocket' | 'http';
+    /**
+     * Custom headers for HTTP requests, and for the WebSocket upgrade in a
+     * runtime whose WebSocket carries a handshake header, which Node and Bun do
+     * and a browser does not. Constructing a WebSocket-transport client with
+     * headers and no {@link ClientOptions.webSocketProtocols} in a runtime that
+     * carries none fails with `INVALID_ARGUMENT`. Pass both when a browser client
+     * needs each one, and the headers still reach every HTTP request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * WebSocket subprotocols offered during the handshake, which is how a browser
+     * carries a short-lived credential. The client offers the `sirannon.v1`
+     * identifier alongside them and the server selects that identifier, so the
+     * credential never comes back in the handshake response.
+     */
+    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;
+}
+
+export type { AppliedMigrationRow as A, BulkLoadDurability as B, ClientOptions as C, ReplicationStatusInfo as R, ServerOptions as S, WSHandlerOptions as W, BulkLoadResult as a, BulkLoadOptions as b, AuthenticateHook as c, ClusterStatusAuthorizer as d, CorsOptions as e, RequestContext as f, ServerExecutionTarget as g, ServerExecutionTargetResolver as h };

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

@@ -1,10 +1,12 @@
-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';
+import { D as Database } from './database-BY0L5Q2n.js';
+import { S as SirannonOptions, a as SQLiteDriver, D as DatabaseOptions, M as Migration, B as BeforeQueryHook, A as AfterQueryHook, b as BeforeConnectHook, c as DatabaseOpenHook, d as DatabaseCloseHook } from './types-zhnRXrsb.js';
 
 declare class Sirannon {
     readonly options: SirannonOptions;
     private readonly dbs;
     private readonly opening;
+    private readonly resolving;
+    private migrationSet;
     private _shutdown;
     private readonly _driver;
     private readonly hookRegistry;
@@ -17,6 +19,9 @@ declare class Sirannon {
     close(id: string): Promise<void>;
     get(id: string): Database | undefined;
     resolve(id: string): Promise<Database | undefined>;
+    registryMigrations(): Promise<Migration[]>;
+    private applyRegistryMigrations;
+    private loadMigrationSet;
     has(id: string): boolean;
     databases(): Map<string, Database>;
     shutdown(): Promise<void>;

package/dist/transport/grpc.d.ts

@@ -1,10 +1,11 @@
 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-BsjobKbl.js';
-import '../change-tracker-CbmaMO-N.js';
-import '../types-D_hQW1hr.js';
-import '../types-BEu1I_9_.js';
+import { R as ReplicationAck, F as ForwardedTransaction, a as ForwardedTransactionResult, N as NodeInfo, S as SyncRequest, b as SyncBatch, c as SyncComplete, d as SyncAck, e as ReplicationTransport, f as TopologyRole, T as TransportConfig } from '../types-B7gmEsZW.js';
+import { R as ReplicationBatch } from '../types-C_D8IhpO.js';
+import '../change-tracker-DKRVUC3l.js';
+import '../types-zhnRXrsb.js';
+import '../types-BsVabqSI.js';
 
 interface ColumnValue {
     nullValue?: boolean | undefined;
@@ -79,6 +80,7 @@ interface SyncRequestPayload {
     completedTables: string[];
     groupId: string;
     primaryTerm: bigint;
+    supportsStreamVerification: boolean;
 }
 declare const SyncRequestPayload: MessageFns<SyncRequestPayload>;
 interface SyncBatchPayload {
@@ -106,6 +108,7 @@ interface SyncTableManifest {
     table: string;
     rowCount: number;
     pkHash: string;
+    batchDigest: string;
 }
 declare const SyncTableManifest: MessageFns<SyncTableManifest>;
 interface SyncAckPayload {