@delali/sirannon-db 0.1.6 → 0.1.7

package/dist/client/index.d.ts

@@ -24,6 +24,20 @@ interface ChangeEvent<T = Record<string, unknown>> {
     seq: bigint;
     timestamp: number;
 }
+/**
+ * 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';
+/** 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;
+}
 /** Options for the client SDK. */
 interface ClientOptions {
     /** Transport to use. Default: 'websocket'. */
@@ -36,22 +50,39 @@ interface ClientOptions {
     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;
 }
 
-/** Response for a successful query. */
 interface QueryResponse {
     rows: Record<string, unknown>[];
 }
-/** Response for a successful execute. */
 interface ExecuteResponse {
     changes: number;
     lastInsertRowId: number | string;
 }
-/** Response for a successful transaction. */
 interface TransactionResponse {
     results: ExecuteResponse[];
 }
+interface BatchResponse {
+    results: ExecuteResponse[];
+}
+type LoadResponse = BulkLoadResult;
 
+/** Optional behaviours for a CDC subscription. */
+interface SubscribeOptions {
+    /**
+     * Invoked when a reconnect cannot replay missed changes because they fell
+     * outside the server's retained history. The subscription continues live
+     * from the current moment; treat any prior state as stale and re-read.
+     */
+    onReset?: () => void;
+}
 /**
  * Transport layer for communicating with a sirannon-db server.
  * Each transport instance is bound to a specific database.
@@ -63,7 +94,9 @@ interface Transport {
         sql: string;
         params?: Params;
     }>): Promise<TransactionResponse>;
-    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
     close(): void;
 }
 /** Handle for an active remote subscription. */
@@ -73,7 +106,7 @@ interface RemoteSubscription {
 /** Builder for creating remote CDC subscriptions with optional filters. */
 interface RemoteSubscriptionBuilder {
     filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
-    subscribe(callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    subscribe(callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
 }
 /**
  * Error originating from a remote sirannon-db server.
@@ -84,6 +117,17 @@ declare class RemoteError extends Error {
     constructor(code: string, message: string);
 }
 
+/** Options for {@link RemoteDatabase.loadAll}. */
+interface LoadAllOptions {
+    /**
+     * Rows per batch sent to the server. Each batch is one request, so it must
+     * fit under the server's `maxBodyBytes`; widen that cap or lower this for
+     * wide rows. Default: 1000.
+     */
+    batchSize?: number;
+    /** Durability during the load. Default: 'off'. */
+    durability?: BulkLoadDurability;
+}
 /**
  * Proxy for a remote sirannon-db database. Mirrors the core
  * {@link Database} query interface with async methods that send
@@ -114,13 +158,54 @@ declare class RemoteDatabase {
      * Execute multiple statements as a single atomic transaction.
      * Returns an array of results, one per statement.
      *
-     * Requires HTTP transport. WebSocket transport does not
-     * support server-side transactions.
+     * The whole list travels in one request and commits or rolls back as a
+     * unit, so the client is never in the loop between statements.
      */
     transaction(statements: Array<{
         sql: string;
         params?: Params;
     }>): Promise<ExecuteResponse[]>;
+    /**
+     * Run the same statement once per parameter set as a single atomic
+     * transaction that commits with one fsync. Returns one result per
+     * parameter set, in order. Use this for a burst of same-shape writes
+     * (an import, a bulk insert) that must all commit or all roll back.
+     */
+    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<ExecuteResponse[]>;
+    /**
+     * Load a whole dataset through the same statement, batching it into requests
+     * for you and paying the one fsyncing WAL checkpoint once, after the final
+     * batch. The configured durability is restored after every batch, so an
+     * import that stops partway never leaves the writer at the relaxed level.
+     * Prefer this over {@link load} for anything larger than a single request:
+     * it runs the finalize itself, so there is no checkpoint flag to forget.
+     *
+     * Accepts a synchronous or asynchronous iterable of parameter sets, so rows
+     * can stream from a file or the network without being held in memory at
+     * once. Returns the total rows loaded and changes applied.
+     *
+     * ```ts
+     * const summary = await db.loadAll(
+     *   'INSERT INTO events (id, payload) VALUES (?, ?)',
+     *   rowStream,
+     *   { batchSize: 5000, durability: 'off' },
+     * )
+     * ```
+     */
+    loadAll(sql: string, rows: Iterable<Params> | AsyncIterable<Params>, options?: LoadAllOptions): Promise<BulkLoadResult>;
+    /**
+     * Load one batch of rows through the same statement with writer durability
+     * relaxed for the duration, then restored before this resolves. This is the
+     * low-level primitive; prefer {@link loadAll} for a dataset that spans more
+     * than one request, since it runs the finalize itself rather than relying on
+     * a `checkpoint` flag.
+     *
+     * Returns the total rows loaded and changes applied. When splitting a dataset
+     * across many `load` calls by hand, pass `checkpoint: false` on every call
+     * but the last so the one fsyncing WAL checkpoint runs once at the end; the
+     * configured durability is restored after each call regardless.
+     */
+    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<BulkLoadResult>;
     /**
      * Start building a CDC subscription for the given table.
      * Chain `.filter()` to narrow the events, then call `.subscribe()`
@@ -160,6 +245,7 @@ declare class SirannonClient {
     private readonly webSocketProtocols;
     private readonly autoReconnect;
     private readonly reconnectInterval;
+    private readonly requestTimeout;
     private readonly databases;
     private closed;
     private readonly topologyEnabled;
@@ -220,7 +306,9 @@ declare class TopologyAwareTransport implements Transport {
         sql: string;
         params?: Params;
     }>): Promise<TransactionResponse>;
-    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
     _handleClusterRoutingChanged(): Promise<void>;
     close(): void;
     private subscribeOnCurrentEndpoint;
@@ -249,14 +337,14 @@ declare class RemoteSubscriptionBuilderImpl implements RemoteSubscriptionBuilder
     private conditions;
     constructor(table: string, transport: Transport);
     filter(conditions: Record<string, unknown>): RemoteSubscriptionBuilder;
-    subscribe(callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    subscribe(callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
 }
 
 /**
  * HTTP transport for sirannon-db. Sends requests via `fetch` to the
- * server's REST endpoints. Supports query, execute, and transaction
- * operations. Real-time subscriptions are not available over HTTP;
- * use {@link WebSocketTransport} for CDC subscriptions.
+ * server's REST endpoints. Supports query, execute, transaction, batch,
+ * and load operations. Real-time subscriptions are not available over
+ * HTTP; use {@link WebSocketTransport} for CDC subscriptions.
  */
 declare class HttpTransport implements Transport {
     private readonly baseUrl;
@@ -269,6 +357,8 @@ declare class HttpTransport implements Transport {
         sql: string;
         params?: Params;
     }>): Promise<TransactionResponse>;
+    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
     subscribe(_table: string, _filter: Record<string, unknown> | undefined, _callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
     close(): void;
     private post;
@@ -295,11 +385,13 @@ declare class WebSocketTransport implements Transport {
     });
     query(sql: string, params?: Params): Promise<QueryResponse>;
     execute(sql: string, params?: Params): Promise<ExecuteResponse>;
-    transaction(_statements: Array<{
+    transaction(statements: Array<{
         sql: string;
         params?: Params;
     }>): Promise<TransactionResponse>;
-    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
     close(): void;
     private nextId;
     private ensureConnected;
@@ -313,4 +405,4 @@ declare class WebSocketTransport implements Transport {
     private cancelReconnect;
 }
 
-export { HttpTransport, RemoteDatabase, RemoteError, type RemoteSubscription, type RemoteSubscriptionBuilder, RemoteSubscriptionBuilderImpl, SirannonClient, type TopologyAwareClientOptions, type Transport, WebSocketTransport };
+export { HttpTransport, type LoadAllOptions, RemoteDatabase, RemoteError, type RemoteSubscription, type RemoteSubscriptionBuilder, RemoteSubscriptionBuilderImpl, SirannonClient, type TopologyAwareClientOptions, type Transport, WebSocketTransport };