@delali/sirannon-db 0.1.3 → 0.1.5

package/dist/client/index.d.ts

@@ -1,12 +1,63 @@
-import { P as Params, d as ChangeEvent, f as ClientOptions } from '../types-DArCObcu.js';
-import { c as QueryResponse, b as ExecuteResponse, d as TransactionResponse } from '../protocol-BX1H-_Mz.js';
+/** 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;
+}
+/** 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;
+}
+/** 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;
+}
+
+/** 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[];
+}
 
 /**
  * Transport layer for communicating with a sirannon-db server.
  * Each transport instance is bound to a specific database.
  */
 interface Transport {
-    query(sql: string, params?: Params): Promise<QueryResponse>;
+    query(sql: string, params?: Params, readConcern?: ReadConcern): Promise<QueryResponse>;
     execute(sql: string, params?: Params): Promise<ExecuteResponse>;
     transaction(statements: Array<{
         sql: string;
@@ -53,7 +104,7 @@ declare class RemoteDatabase {
      * )
      * ```
      */
-    query<T = Record<string, unknown>>(sql: string, params?: Params): Promise<T[]>;
+    query<T = Record<string, unknown>>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
     /**
      * Execute a mutation (INSERT, UPDATE, DELETE) and return
      * the number of affected rows and last insert row ID.
@@ -93,45 +144,97 @@ declare class RemoteDatabase {
     close(): void;
 }
 
-/**
- * Client for a remote sirannon-db server. Creates {@link RemoteDatabase}
- * instances that communicate with the server over HTTP or WebSocket.
- *
- * ```ts
- * const client = new SirannonClient('http://localhost:9876', {
- *   transport: 'websocket',
- * })
- *
- * const db = client.database('main')
- * const rows = await db.query('SELECT * FROM users')
- *
- * client.close()
- * ```
- */
+interface TopologyAwareClientOptions extends ClientOptions {
+    endpoints?: string[];
+    primary?: string;
+    replicas?: string[];
+    readPreference?: 'primary' | 'replica' | 'nearest';
+    discovery?: 'static' | 'coordinator';
+    readConcern?: ReadConcernLevel;
+}
 declare class SirannonClient {
     private readonly baseUrl;
     private readonly wsBaseUrl;
     private readonly transport;
     private readonly headers;
+    private readonly webSocketProtocols;
     private readonly autoReconnect;
     private readonly reconnectInterval;
     private readonly databases;
     private closed;
+    private readonly topologyEnabled;
+    private readonly primaryUrl;
+    private readonly replicaUrls;
+    private readonly readPreference;
+    private readonly discovery;
+    private readonly readConcern;
+    private readonly starterEndpoints;
+    private readonly clusterRouting;
+    private readonly topologyTransports;
+    private latencies;
+    private latencyMeasuredAt;
+    private latencyMeasuring;
+    private readonly LATENCY_TTL_MS;
+    private removedReplicas;
     constructor(url: string, options?: ClientOptions);
-    /**
-     * Get a {@link RemoteDatabase} proxy for the given database ID.
-     * Returns a cached instance if one already exists for this ID.
-     *
-     * The underlying transport connection is established lazily on
-     * the first operation (query, execute, or subscribe).
-     */
+    constructor(options: TopologyAwareClientOptions);
     database(id: string): RemoteDatabase;
-    /**
-     * Close all database connections and release resources.
-     * After calling `close()`, new calls to `database()` will throw.
-     */
     close(): void;
     private createTransport;
+    private createTransportForUrl;
+    _createTransportForEndpoint(url: string, databaseId: string): Transport;
+    _getReadEndpoint(databaseId?: string, readConcern?: ReadConcernLevel): Promise<string>;
+    _getWriteEndpoint(databaseId?: string): Promise<string>;
+    _getReadConcern(): ReadConcernLevel | undefined;
+    _usesCoordinatorDiscovery(): boolean;
+    _removeReplica(url: string): void;
+    private ensureLatencyMeasured;
+    private measureLatencies;
+    _refreshClusterRouting(databaseId: string): Promise<void>;
+    private ensureClusterRouting;
+    private clusterDiscoveryCandidates;
+    _unregisterTopologyTransport(databaseId: string, transport: TopologyAwareTransport): void;
+    private notifyClusterRoutingChanged;
+}
+
+declare class TopologyAwareTransport implements Transport {
+    private readonly databaseId;
+    private readonly client;
+    private closed;
+    private readTransport;
+    private writeTransport;
+    private subscriptionTransport;
+    private readTransportRequest;
+    private writeTransportRequest;
+    private subscriptionTransportRequest;
+    private subscriptionOperation;
+    private activeSubscriptions;
+    private nextSubscriptionId;
+    private currentReadUrl;
+    private currentWriteUrl;
+    private currentSubscriptionUrl;
+    constructor(databaseId: string, client: SirannonClient);
+    query(sql: string, params?: Params): Promise<QueryResponse>;
+    execute(sql: string, params?: Params): Promise<ExecuteResponse>;
+    transaction(statements: Array<{
+        sql: string;
+        params?: Params;
+    }>): Promise<TransactionResponse>;
+    subscribe(table: string, filter: Record<string, unknown> | undefined, callback: (event: ChangeEvent) => void): Promise<RemoteSubscription>;
+    _handleClusterRoutingChanged(): Promise<void>;
+    close(): void;
+    private subscribeOnCurrentEndpoint;
+    private createSubscriptionHandle;
+    private migrateSubscriptionsToCurrentEndpoint;
+    private getReadTransport;
+    private resolveReadTransport;
+    private getWriteTransport;
+    private resolveWriteTransport;
+    private getSubscriptionTransport;
+    private resolveSubscriptionTransport;
+    private closeSubscriptionTransport;
+    private withSubscriptionOperation;
+    private assertOpen;
 }
 
 /**
@@ -160,7 +263,7 @@ declare class HttpTransport implements Transport {
     private readonly headers;
     private closed;
     constructor(baseUrl: string, headers?: Record<string, string>);
-    query(sql: string, params?: Params): Promise<QueryResponse>;
+    query(sql: string, params?: Params, readConcern?: ReadConcern): Promise<QueryResponse>;
     execute(sql: string, params?: Params): Promise<ExecuteResponse>;
     transaction(statements: Array<{
         sql: string;
@@ -171,24 +274,13 @@ declare class HttpTransport implements Transport {
     private post;
 }
 
-/**
- * WebSocket transport for sirannon-db. Connects to
- * `ws(s)://host:port/db/{id}` and supports query, execute,
- * and real-time CDC subscriptions over a single persistent connection.
- *
- * Connections are established lazily on first use and will
- * auto-reconnect (with subscription restoration) when
- * `autoReconnect` is enabled.
- *
- * Transactions are not supported over WebSocket; use
- * {@link HttpTransport} for batch transactions.
- */
 declare class WebSocketTransport implements Transport {
     private ws;
     private readonly url;
     private readonly autoReconnect;
     private readonly reconnectInterval;
     private readonly requestTimeout;
+    private readonly protocols;
     private pendingRequests;
     private activeSubscriptions;
     private idCounter;
@@ -199,6 +291,7 @@ declare class WebSocketTransport implements Transport {
         autoReconnect?: boolean;
         reconnectInterval?: number;
         requestTimeout?: number;
+        protocols?: string | string[];
     });
     query(sql: string, params?: Params): Promise<QueryResponse>;
     execute(sql: string, params?: Params): Promise<ExecuteResponse>;
@@ -220,4 +313,4 @@ declare class WebSocketTransport implements Transport {
     private cancelReconnect;
 }
 
-export { HttpTransport, RemoteDatabase, RemoteError, type RemoteSubscription, type RemoteSubscriptionBuilder, RemoteSubscriptionBuilderImpl, SirannonClient, type Transport, WebSocketTransport };
+export { HttpTransport, RemoteDatabase, RemoteError, type RemoteSubscription, type RemoteSubscriptionBuilder, RemoteSubscriptionBuilderImpl, SirannonClient, type TopologyAwareClientOptions, type Transport, WebSocketTransport };