@delali/sirannon-db 0.1.4 → 0.1.5

package/dist/chunk-UVMVN3OT.mjs

@@ -0,0 +1,111 @@
+import { SirannonError } from './chunk-O7BHI3CF.mjs';
+
+// src/replication/errors.ts
+var ReplicationError = class extends SirannonError {
+  constructor(message, code = "REPLICATION_ERROR", details) {
+    super(message, code);
+    this.details = details;
+    this.name = "ReplicationError";
+  }
+};
+var ConflictError = class extends ReplicationError {
+  constructor(message, table, rowId) {
+    super(message, "CONFLICT_ERROR");
+    this.table = table;
+    this.rowId = rowId;
+    this.name = "ConflictError";
+  }
+};
+var TransportError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "TRANSPORT_ERROR");
+    this.name = "TransportError";
+  }
+};
+var BatchValidationError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "BATCH_VALIDATION_ERROR");
+    this.name = "BatchValidationError";
+  }
+};
+var WriteConcernError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "WRITE_CONCERN_ERROR");
+    this.name = "WriteConcernError";
+  }
+};
+var ReadConcernError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "READ_CONCERN_ERROR", details);
+    this.name = "ReadConcernError";
+  }
+};
+var TopologyError = class extends ReplicationError {
+  constructor(message) {
+    super(message, "TOPOLOGY_ERROR");
+    this.name = "TopologyError";
+  }
+};
+var CoordinatorError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "COORDINATOR_UNAVAILABLE", details);
+    this.name = "CoordinatorError";
+  }
+};
+var AuthorityError = class extends ReplicationError {
+  constructor(message, code = "AUTHORITY_LOST", details) {
+    super(message, code, details);
+    this.name = "AuthorityError";
+  }
+};
+var StalePrimaryError = class extends AuthorityError {
+  constructor(message, details) {
+    super(message, "STALE_PRIMARY", details);
+    this.name = "StalePrimaryError";
+  }
+};
+var FailoverError = class extends ReplicationError {
+  constructor(message, code = "NO_SAFE_PRIMARY", details) {
+    super(message, code, details);
+    this.name = "FailoverError";
+  }
+};
+var NoSafePrimaryError = class extends FailoverError {
+  constructor(message, details) {
+    super(message, "NO_SAFE_PRIMARY", details);
+    this.name = "NoSafePrimaryError";
+  }
+};
+var NodeNotInSyncError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "NODE_NOT_IN_SYNC", details);
+    this.name = "NodeNotInSyncError";
+  }
+};
+var NodeDrainingError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "NODE_DRAINING", details);
+    this.name = "NodeDrainingError";
+  }
+};
+var ProtocolVersionMismatchError = class extends ReplicationError {
+  constructor(message, details) {
+    super(message, "PROTOCOL_VERSION_MISMATCH", details);
+    this.name = "ProtocolVersionMismatchError";
+  }
+};
+var UnsafeRecoveryRequiredError = class extends FailoverError {
+  constructor(message, details) {
+    super(message, "UNSAFE_RECOVERY_REQUIRED", details);
+    this.name = "UnsafeRecoveryRequiredError";
+  }
+};
+var SyncError = class extends ReplicationError {
+  constructor(message, requestId) {
+    super(message, "SYNC_ERROR");
+    this.requestId = requestId;
+    this.name = "SyncError";
+  }
+};
+
+export { AuthorityError, BatchValidationError, ConflictError, CoordinatorError, FailoverError, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, ProtocolVersionMismatchError, ReadConcernError, ReplicationError, StalePrimaryError, SyncError, TopologyError, TransportError, UnsafeRecoveryRequiredError, WriteConcernError };

package/dist/client/index.d.ts

@@ -1,5 +1,18 @@
 /** 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. */
@@ -17,6 +30,8 @@ interface ClientOptions {
     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. */
@@ -42,7 +57,7 @@ interface TransactionResponse {
  * 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;
@@ -89,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.
@@ -129,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;
 }
 
 /**
@@ -196,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;
@@ -207,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;
@@ -235,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>;
@@ -256,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 };