@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/client/index.d.ts

@@ -1,31 +1,66 @@
-export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-DPAm2AKG.js';
-import { C as ConflictResolver, R as ReplicationBatch } from '../types-C_D8IhpO.js';
-export { a as ConflictContext, b as ConflictResolution } from '../types-C_D8IhpO.js';
-import { C as ClientOptions, B as BulkLoadDurability } from '../server-options-1JHu8pid.js';
-import { D as DatabaseClient, T as Transport, L as LiveHandlers, R as RemoteSubscription, a as RemoteSubscriptionBuilder, S as SubscribeOptions, b as RegistryDigestSource } from '../client-base-CLWmH5Ln.js';
-export { c as LoadAllOptions, d as RemoteDatabase, e as RemoteError, f as SQL_REFUSED_MESSAGE, g as ServerCapabilities, h as ServerCapabilityCheck } from '../client-base-CLWmH5Ln.js';
-import { a as LiveQuery, b as LiveQueryState, c as LiveUpdate } from '../types-CL6piSnD.js';
-import { e as DeviceSyncPort, D as Database } from '../database-BY0L5Q2n.js';
-import { h as ChangeEvent, P as Params, R as ReadConcern, W as WriteConcern } from '../types-zhnRXrsb.js';
-import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-6KrSq2Hy.js';
-import '../operation-registry-9DcvxcE5.js';
+export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-B0np8JS3.js';
+import { C as ConflictResolver, R as ReplicationBatch } from '../types-CjhxcjhA.js';
+export { a as ConflictContext, b as ConflictResolution } from '../types-CjhxcjhA.js';
+import { C as ClientOptions, B as BulkLoadDurability } from '../server-options-Dab_Jvd_.js';
+import { D as DatabaseClient, T as Transport, L as LiveHandlers, R as RemoteSubscription, a as RemoteSubscriptionBuilder, S as SubscribeOptions, b as RegistryDigestSource } from '../client-base-CmZO0v3m.js';
+export { c as LoadAllOptions, d as RemoteDatabase, e as RemoteError, f as SQL_REFUSED_MESSAGE, g as ServerCapabilities, h as ServerCapabilityCheck } from '../client-base-CmZO0v3m.js';
+import { a as LiveQuery, b as LiveQueryState, c as LiveUpdate } from '../types-BCejqzNA.js';
+import { e as DeviceSyncPort, D as Database } from '../database-B5Qv1-cU.js';
+import { C as ChangeEvent, P as Params, R as ReadConcern, W as WriteConcern } from '../query-types-DL3LtPvY.js';
+import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-rqANt-9Q.js';
+import '../operation-registry-hlbhqu7q.js';
+import '../types-rVZKnKN-.js';
 
+/**
+ * @public
+ *
+ * Connects to one sirannon-db server and hands out a {@link RemoteDatabase} per database.
+ */
 declare class SirannonClient extends DatabaseClient {
     private readonly baseUrl;
     constructor(url: string, options?: ClientOptions);
+    /**
+     * Builds the transport a database's requests travel over.
+     *
+     * @param databaseId - Identifier of the database.
+     * @returns A transport bound to that database.
+     */
     protected createTransport(databaseId: string): Transport;
+    /**
+     * Returns the address requests are sent to.
+     *
+     * @returns The server's base address.
+     */
     protected resolveServerUrl(): string;
 }
 
+/**
+ * @public
+ *
+ * A live query running against a remote server, which keeps its rows current as the tables behind it change.
+ */
 declare class RemoteLiveQuery<T> implements LiveQuery<T> {
     private state;
     private rows;
     private readonly listeners;
     private subscription;
     private closed;
+    /** @internal */
     static open<T>(subscribe: (handlers: LiveHandlers) => Promise<RemoteSubscription>): Promise<RemoteLiveQuery<T>>;
+    /**
+     * Returns the rows the query holds right now.
+     */
     getState(): LiveQueryState<T>;
+    /**
+     * Calls back on each update and returns a function that stops the listener.
+     *
+     * @param listener - Receives each update.
+     * @returns A function that removes the listener.
+     */
     subscribe(listener: (update: LiveUpdate<T>) => void): () => void;
+    /**
+     * Ends the query and releases its subscription.
+     */
     close(): Promise<void>;
     private handlers;
     private replace;
@@ -35,34 +70,75 @@ declare class RemoteLiveQuery<T> implements LiveQuery<T> {
     private publish;
 }
 
+/**
+ * How far a snapshot download has progressed, for the table in flight and overall.
+ *
+ * @public
+ */
 interface SnapshotProgress {
+    /** Table the download is reading right now. */
     table: string;
+    /** Rows loaded from that table so far. */
     tableLoadedRows: number;
+    /** Rows that table holds in total. */
     tableTotalRows: number;
+    /** Rows loaded across every table so far. */
     loadedRows: number;
+    /** Rows the whole snapshot holds. */
     totalRows: number;
 }
+/**
+ * Where a snapshot comes from and how it is read.
+ *
+ * @public
+ */
 interface SnapshotDownloadOptions {
+    /** Address of the server serving the snapshot. */
     url: string;
+    /** Identifier of the database to copy. */
     databaseId: string;
+    /** Headers attached to each snapshot request. */
     headers?: Record<string, string>;
+    /** Rows requested per page. Default: 500. */
     pageSize?: number;
+    /** Milliseconds a single page request may take. */
     requestTimeoutMs?: number;
+    /** Called as each page arrives. */
     onProgress?: (progress: SnapshotProgress) => void;
 }
+/**
+ * What one snapshot download produced.
+ *
+ * @public
+ */
 interface SnapshotDownloadResult {
+    /** Change-log position the device resumes its subscription from. */
     startSeq: bigint;
+    /** Sequence space that position belongs to. */
     epoch: string;
+    /** Tables the snapshot carried. */
     tables: string[];
+    /** Rows the download wrote. */
     loadedRows: number;
 }
+/**
+ * @public
+ *
+ * Copies a database from a server into a local one, replacing what the local database holds.
+ *
+ * @param port - The local database the snapshot is written into.
+ * @param options - Where the snapshot comes from and how it is read.
+ * @returns The change-log position and sequence space to resume from, the tables copied, and the rows written.
+ */
 declare function downloadDatabaseSnapshot(port: DeviceSyncPort, options: SnapshotDownloadOptions): Promise<SnapshotDownloadResult>;
 
 /**
  * Builds a remote CDC subscription with optional row-level filters.
- * Mirrors the core {@link SubscriptionBuilder} interface but returns
+ * Mirrors the core `SubscriptionBuilder` interface but returns
  * a promise from `subscribe()` since confirming the subscription
  * requires a server round-trip.
+ *
+ * @internal
  */
 declare class RemoteSubscriptionBuilderImpl implements RemoteSubscriptionBuilder {
     private readonly table;
@@ -73,27 +149,56 @@ declare class RemoteSubscriptionBuilderImpl implements RemoteSubscriptionBuilder
     subscribe(callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
 }
 
+/**
+ * How a device keeps its local database in step with a server.
+ *
+ * @public
+ */
 interface SyncControllerOptions {
+    /** Address of the server this device syncs with. */
     url: string;
+    /** Identifier of the database on that server. */
     databaseId: string;
+    /** Tables this device syncs. */
     tables: readonly string[];
+    /** Headers attached to every request and to the WebSocket upgrade. */
     headers?: Record<string, string>;
+    /** Changes sent in one push. */
     batchSize?: number;
+    /** Milliseconds between pushes of locally recorded changes. */
     pushIntervalMs?: number;
+    /** Milliseconds between acknowledgements of pulled changes. */
     ackIntervalMs?: number;
+    /** Longest delay, in milliseconds, between retries of a failed push. */
     maxPushRetryDelayMs?: number;
+    /** Milliseconds a single request may take. */
     requestTimeout?: number;
+    /** Downloads a fresh snapshot on its own when the server says the cursor is too old. Default: true. */
     autoResync?: boolean;
+    /** Milliseconds before the first retry of a failed snapshot download. */
     snapshotRetryDelayMs?: number;
+    /** Longest delay, in milliseconds, between snapshot retries. */
     maxSnapshotRetryDelayMs?: number;
+    /** Rows requested per snapshot page. */
     snapshotPageSize?: number;
+    /** Changes after which the device acknowledges at once instead of waiting for the interval. */
     immediateAckAfterChanges?: number;
+    /** Resolves which version of a row wins when a pulled change meets a local one. */
     resolver?: ConflictResolver | ((table: string) => ConflictResolver);
+    /** Called for each change this device pulls. */
     onChange?: (event: ChangeEvent) => void;
+    /** Called when the server says the device must download a fresh snapshot. */
     onResyncRequired?: () => void;
+    /** Called as each snapshot page arrives. */
     onSnapshotProgress?: (progress: SnapshotProgress) => void;
+    /** Called once a snapshot download settles, whether it succeeded or failed. */
     onSnapshotComplete?: (outcome: SnapshotOutcome) => void;
 }
+/**
+ * How a snapshot download settled, and whether the local database is usable afterwards.
+ *
+ * @public
+ */
 type SnapshotOutcome = {
     ok: true;
     error: null;
@@ -108,27 +213,59 @@ type SnapshotOutcome = {
     databaseUsable: boolean;
     retrying: boolean;
 };
+/**
+ * What a sync controller is doing right now.
+ *
+ * @public
+ */
 type SyncState = 'stopped' | 'starting' | 'running' | 'paused' | 'snapshotting';
+/**
+ * Settings for one snapshot download.
+ *
+ * @public
+ */
 interface SnapshotOptions {
+    /** Rows requested per page. */
     pageSize?: number;
+    /** Called as each page arrives. */
     onProgress?: (progress: SnapshotProgress) => void;
 }
+/**
+ * Where a device stands against its server.
+ *
+ * @public
+ */
 interface SyncStatus {
+    /** What the controller is doing right now. */
     state: SyncState;
+    /** Identifier this device is known by on the server. */
     deviceId: string | null;
+    /** Capabilities the server announced, or null before the device has asked. */
     serverCapabilities: string[] | null;
+    /** Schema version the local database is at. */
     schemaVersion: number | null;
+    /** Local changes waiting to be pushed. */
     pendingPushCount: number;
+    /** Highest local change-log position the server has accepted. */
     lastPushedSeq: bigint;
+    /** Highest server change-log position this device has applied. */
     lastPulledSeq: bigint | null;
+    /** Whether every local change has reached the server. */
     pushCaughtUp: boolean;
+    /** Whether the server has told this device to download a fresh snapshot. */
     resyncRequired: boolean;
+    /** The most recent failure, or null when the last try succeeded. */
     lastError: {
         code: string;
         message: string;
     } | null;
 }
 
+/**
+ * @public
+ *
+ * Keeps one device's local database in step with a server: it pushes local changes, pulls the server's, and downloads a fresh snapshot when the device falls too far behind.
+ */
 declare class SyncController {
     private readonly db;
     private readonly options;
@@ -147,16 +284,41 @@ declare class SyncController {
     private consecutivePullFailures;
     private lastError;
     constructor(db: Database, options: SyncControllerOptions);
+    /**
+     * Connects to the server and starts pushing and pulling changes.
+     */
     start(): Promise<void>;
+    /**
+     * Holds pushing and pulling without disconnecting.
+     */
     pause(): void;
+    /**
+     * Resumes pushing and pulling after a pause.
+     */
     resume(): Promise<void>;
+    /**
+     * Stops syncing and closes the connection to the server.
+     */
     stop(): Promise<void>;
+    /**
+     * Reports where this device stands against the server.
+     *
+     * @returns The device's state, cursors, pending push count, and last failure.
+     */
     status(): Promise<SyncStatus>;
+    /**
+     * Pushes local changes now instead of waiting for the next interval.
+     */
     triggerPush(): void;
     private verifyCapabilities;
     private localSchemaVersion;
     private reconcileSchema;
     private markResyncRequired;
+    /**
+     * Replaces the local database with a fresh copy from the server and resumes syncing from it.
+     *
+     * @param options - Page size and the progress callback for this download.
+     */
     downloadSnapshot(options?: SnapshotOptions): Promise<void>;
     /**
      * Answers whether the local database serves reads and writes again. A failure
@@ -210,7 +372,17 @@ interface ChangesResponse {
     conflicts: number;
 }
 
+/**
+ * Encodes a device-sync batch into the shape the changes route accepts.
+ *
+ * @internal
+ */
 declare function encodeSyncBatch(batch: ReplicationBatch): ChangesRequest['batch'];
+/**
+ * Sends a device-sync batch to the server and returns what the server applied.
+ *
+ * @internal
+ */
 declare function pushSyncBatch(baseUrl: string, databaseId: string, batch: ReplicationBatch, headers?: Record<string, string>, timeoutMs?: number, schemaVersion?: number): Promise<ChangesResponse>;
 
 /**
@@ -218,25 +390,38 @@ declare function pushSyncBatch(baseUrl: string, databaseId: string, batch: Repli
  * 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.
+ *
+ * @public
  */
 declare class HttpTransport implements Transport {
+    /** @internal */
     readonly carriesReadConcern = true;
     private readonly baseUrl;
     private readonly headers;
     private closed;
     constructor(baseUrl: string, headers?: Record<string, string>);
+    /** Sends a read and returns its rows. */
     query(sql: string, params?: Params, readConcern?: ReadConcern): Promise<QueryResponse>;
+    /** Sends one write. */
     execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    /** Sends several statements the server runs in one transaction. */
     transaction(statements: Array<{
         sql: string;
         params?: Params;
     }>): Promise<TransactionResponse>;
+    /** Sends one statement over many parameter sets, which the server runs in one transaction. */
     batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    /** Sends a bulk load, which the server runs at relaxed durability. */
     load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
+    /** Runs a registered read by name and returns its rows. */
     queryNamed(name: string, args?: Record<string, unknown>, readConcern?: ReadConcern): Promise<QueryResponse>;
+    /** Runs a registered write by name. */
     executeNamed(name: string, args?: Record<string, unknown>, writeConcern?: WriteConcern): Promise<TransactionResponse>;
+    /** Opens a live query on a registered read and delivers its updates to the handlers. */
     liveSubscribe(): Promise<RemoteSubscription>;
+    /** Opens a change subscription on a watched table. */
     subscribe(_table: string, _filter: Record<string, unknown> | undefined, _callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    /** Closes the transport and every subscription running on it. */
     close(): void;
     private post;
 }
@@ -250,8 +435,11 @@ declare class HttpTransport implements Transport {
  * Connections are established lazily on first use and will
  * auto-reconnect (with subscription restoration) when
  * `autoReconnect` is enabled.
+ *
+ * @public
  */
 declare class WebSocketTransport implements Transport {
+    /** @internal */
     readonly carriesReadConcern = true;
     private ws;
     private readonly url;
@@ -275,20 +463,31 @@ declare class WebSocketTransport implements Transport {
         protocols?: string | string[];
         headers?: Record<string, string>;
     });
+    /** Sends a read and returns its rows. */
     query(sql: string, params?: Params, readConcern?: ReadConcern): Promise<QueryResponse>;
+    /** Sends one write. */
     execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    /** Sends several statements the server runs in one transaction. */
     transaction(statements: Array<{
         sql: string;
         params?: Params;
     }>): Promise<TransactionResponse>;
+    /** Sends one statement over many parameter sets, which the server runs in one transaction. */
     batch(sql: string, paramsBatch: Params[], writeConcern?: WriteConcern): Promise<BatchResponse>;
+    /** Sends a bulk load, which the server runs at relaxed durability. */
     load(sql: string, paramsBatch: Params[], durability?: BulkLoadDurability, checkpoint?: boolean): Promise<LoadResponse>;
+    /** Runs a registered read by name and returns its rows. */
     queryNamed(name: string, args?: Record<string, unknown>, readConcern?: ReadConcern): Promise<QueryResponse>;
+    /** Runs a registered write by name. */
     executeNamed(name: string, args?: Record<string, unknown>, writeConcern?: WriteConcern): Promise<TransactionResponse>;
+    /** Opens a live query on a registered read and delivers its updates to the handlers. */
     liveSubscribe(name: string, args: Record<string, unknown> | undefined, handlers: LiveHandlers, registryDigest?: RegistryDigestSource): Promise<RemoteSubscription>;
+    /** Opens a change subscription on a watched table. */
     subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void, options?: SubscribeOptions): Promise<RemoteSubscription>;
     private sendUnsubscribe;
+    /** @internal */
     ack(deviceId: string, seq: bigint): Promise<AckResponse>;
+    /** Closes the transport and every subscription running on it. */
     close(): void;
     private nextId;
     private ensureConnected;