@topgunbuild/client 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, SearchOptions, HybridQueryRespPayload, HybridQueryDeltaPayload, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
+import { LWWRecord, ORMapRecord, PredicateNode, ConflictResolverDef, MergeRejection, Timestamp, LWWMap, ORMap, HLC, EntryProcessorDef, EntryProcessorResult, SearchOptions, PNCounter, PNCounterState, JournalEvent, JournalEventType, NodeHealth, ConnectionPoolConfig, PartitionRouterConfig, PartitionMap, ClusterClientConfig } from '@topgunbuild/core';
 export { LWWMap, LWWRecord, PredicateNode, Predicates } from '@topgunbuild/core';
 import pino from 'pino';
 
@@ -101,6 +101,8 @@ interface QueryFilter {
     limit?: number;
     /** Cursor for pagination */
     cursor?: string;
+    /** Optional field projection — only these fields will be returned by the server */
+    fields?: string[];
 }
 /** Cursor status for debugging */
 type CursorStatus = 'valid' | 'expired' | 'invalid' | 'none';
@@ -131,6 +133,10 @@ declare class QueryHandle<T> {
     private changeListeners;
     private _paginationInfo;
     private paginationListeners;
+    /** Field projection list — only these fields are returned by the server when set */
+    readonly fields: string[] | undefined;
+    /** Merkle root hash from last server QUERY_RESP — used for delta reconnect */
+    merkleRootHash: number;
     constructor(syncEngine: SyncEngine, mapName: string, filter?: QueryFilter);
     subscribe(callback: (results: QueryResultItem<T>[]) => void): () => void;
     private loadInitialLocalData;
@@ -150,7 +156,7 @@ declare class QueryHandle<T> {
     onResult(items: {
         key: string;
         value: T;
-    }[], source?: QueryResultSource): void;
+    }[], source?: QueryResultSource, merkleRootHash?: number): void;
     /**
      * Called by SyncEngine when server sends a live update
      */
@@ -606,9 +612,18 @@ interface OperationDroppedEvent {
 /**
  * Connection Provider Types
  *
- * IConnectionProvider abstracts WebSocket connection handling to support
- * both single-server and cluster modes.
+ * IConnectionProvider abstracts connection handling to support
+ * both single-server and cluster modes across WebSocket and HTTP transports.
  */
+/**
+ * Minimal connection interface capturing the actual usage pattern.
+ * Allows transport-agnostic code without depending on the WebSocket global.
+ */
+interface IConnection {
+    send(data: ArrayBuffer | Uint8Array | string): void;
+    close(): void;
+    readonly readyState: number;
+}
 /**
  * Events emitted by IConnectionProvider.
  */
@@ -618,11 +633,13 @@ type ConnectionProviderEvent = 'connected' | 'disconnected' | 'reconnected' | 'm
  */
 type ConnectionEventHandler = (...args: any[]) => void;
 /**
- * Abstract interface for WebSocket connection providers.
+ * Abstract interface for connection providers.
  *
  * Implementations:
  * - SingleServerProvider: Direct connection to a single server
  * - ClusterClient: Multi-node connection pool with partition routing
+ * - HttpSyncProvider: HTTP polling for serverless environments
+ * - AutoConnectionProvider: WebSocket-to-HTTP fallback
  */
 interface IConnectionProvider {
     /**
@@ -638,14 +655,14 @@ interface IConnectionProvider {
      * @param key - The key to route (used for partition-aware routing)
      * @throws Error if not connected
      */
-    getConnection(key: string): WebSocket;
+    getConnection(key: string): IConnection;
     /**
      * Get any available connection.
      * Used for subscriptions, metadata requests, and non-key-specific operations.
      *
      * @throws Error if not connected
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
      * Check if at least one connection is active and ready.
      */
@@ -680,6 +697,25 @@ interface IConnectionProvider {
      * @param key - Optional key for routing (cluster mode)
      */
     send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Send a batch of keyed operations with per-key routing.
+     * Optional -- when implemented (e.g. by ClusterClient), SyncEngine delegates
+     * batch sending here so each operation is routed to the correct partition owner.
+     * When absent, SyncEngine falls back to sending all ops in a single OP_BATCH.
+     *
+     * @param operations - Array of { key, message } pairs where key is the routing key
+     * @returns Map of key -> success boolean
+     */
+    sendBatch?(operations: Array<{
+        key: string;
+        message: any;
+    }>): Map<string, boolean>;
+    /**
+     * Force-close the current connection to trigger reconnection.
+     * Unlike close(), this preserves reconnect behavior so the provider
+     * will automatically attempt to re-establish the connection.
+     */
+    forceReconnect(): void;
     /**
      * Close all connections gracefully.
      */
@@ -691,7 +727,7 @@ interface IConnectionProvider {
 interface SingleServerProviderConfig {
     /** WebSocket URL to connect to */
     url: string;
-    /** Maximum reconnection attempts (default: 10) */
+    /** Maximum reconnection attempts (default: 10). Use Infinity for unlimited. */
     maxReconnectAttempts?: number;
     /** Initial reconnect delay in ms (default: 1000) */
     reconnectDelayMs?: number;
@@ -699,6 +735,8 @@ interface SingleServerProviderConfig {
     backoffMultiplier?: number;
     /** Maximum reconnect delay in ms (default: 30000) */
     maxReconnectDelayMs?: number;
+    /** Listen for browser online/offline events to trigger instant reconnect (default: true) */
+    listenNetworkEvents?: boolean;
 }
 
 /**
@@ -1241,13 +1279,13 @@ declare class SyncEngine {
         matchedTerms?: string[];
     }>>;
     /**
-     * Handle hybrid query response from server.
+     * Handle operation rejected by server (permission denied, validation failure, etc.).
      */
-    handleHybridQueryResponse(payload: HybridQueryRespPayload): void;
+    private handleOpRejected;
     /**
-     * Handle hybrid query delta update from server.
+     * Handle generic error message from server.
      */
-    handleHybridQueryDelta(payload: HybridQueryDeltaPayload): void;
+    private handleError;
 }
 
 interface ILock {
@@ -2150,6 +2188,7 @@ interface ConnectionPoolEvents {
     'node:disconnected': (nodeId: string, reason: string) => void;
     'node:healthy': (nodeId: string) => void;
     'node:unhealthy': (nodeId: string, reason: string) => void;
+    'node:remapped': (oldId: string, newId: string) => void;
     'message': (nodeId: string, message: any) => void;
     'error': (nodeId: string, error: Error) => void;
 }
@@ -2177,20 +2216,25 @@ declare class ConnectionPool {
      * Remove a node from the connection pool
      */
     removeNode(nodeId: string): Promise<void>;
+    /**
+     * Remap a node from one ID to another, preserving the existing connection.
+     * Used when the server-assigned node ID differs from the temporary seed ID.
+     */
+    remapNodeId(oldId: string, newId: string): void;
     /**
      * Get connection for a specific node
      */
-    getConnection(nodeId: string): WebSocket | null;
+    getConnection(nodeId: string): IConnection | null;
     /**
      * Get primary connection (first/seed node)
      */
-    getPrimaryConnection(): WebSocket | null;
+    getPrimaryConnection(): IConnection | null;
     /**
      * Get any healthy connection
      */
     getAnyHealthyConnection(): {
         nodeId: string;
-        socket: WebSocket;
+        connection: IConnection;
     } | null;
     /**
      * Send message to a specific node
@@ -2213,7 +2257,7 @@ declare class ConnectionPool {
      */
     getAllNodes(): string[];
     /**
-     * Check if node is connected and authenticated
+     * Check if node has an open WebSocket connection
      */
     isNodeConnected(nodeId: string): boolean;
     /**
@@ -2290,7 +2334,7 @@ declare class PartitionRouter {
      */
     routeToConnection(key: string): {
         nodeId: string;
-        socket: WebSocket;
+        connection: IConnection;
     } | null;
     /**
      * Get routing info for multiple keys (batch routing)
@@ -2431,6 +2475,8 @@ declare class ClusterClient implements IConnectionProvider {
     private readonly routingMetrics;
     private readonly circuits;
     private readonly circuitBreakerConfig;
+    private partitionMapRequestTimer;
+    private static readonly PARTITION_MAP_REQUEST_DEBOUNCE_MS;
     constructor(config: ClusterClientConfig);
     on(event: string, listener: (...args: any[]) => void): this;
     off(event: string, listener: (...args: any[]) => void): this;
@@ -2446,7 +2492,7 @@ declare class ClusterClient implements IConnectionProvider {
      * Routes to partition owner based on key hash when smart routing is enabled.
      * @throws Error if not connected
      */
-    getConnection(key: string): WebSocket;
+    getConnection(key: string): IConnection;
     /**
      * Get fallback connection when owner is unavailable.
      * @throws Error if no connection available
@@ -2457,9 +2503,15 @@ declare class ClusterClient implements IConnectionProvider {
      * Called when routing to an unknown/disconnected owner.
      */
     private requestPartitionMapRefresh;
+    /**
+     * Debounce partition map requests to prevent flooding when multiple nodes
+     * reconnect simultaneously. Coalesces rapid requests into a single request
+     * sent to the most recently connected node.
+     */
+    private debouncedPartitionMapRequest;
     /**
      * Request partition map from a specific node.
-     * Called on first node connection.
+     * Called on node connection via debounced handler.
      */
     private requestPartitionMapFromNode;
     /**
@@ -2555,6 +2607,10 @@ declare class ClusterClient implements IConnectionProvider {
      * Force refresh of partition map
      */
     refreshPartitionMap(): Promise<void>;
+    /**
+     * Force reconnect all connections in the pool.
+     */
+    forceReconnect(): void;
     /**
      * Shutdown cluster client (IConnectionProvider interface).
      */
@@ -2568,15 +2624,15 @@ declare class ClusterClient implements IConnectionProvider {
      */
     getPartitionRouter(): PartitionRouter;
     /**
-     * Get any healthy WebSocket connection (IConnectionProvider interface).
+     * Get any healthy connection (IConnectionProvider interface).
      * @throws Error if not connected
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
-     * Get any healthy WebSocket connection, or null if none available.
+     * Get any healthy connection, or null if none available.
      * Use this for optional connection checks.
      */
-    getAnyConnectionOrNull(): WebSocket | null;
+    getAnyConnectionOrNull(): IConnection | null;
     /**
      * Get circuit breaker state for a node.
      */
@@ -2625,6 +2681,8 @@ declare class SingleServerProvider implements IConnectionProvider {
     private reconnectTimer;
     private isClosing;
     private listeners;
+    private onlineHandler;
+    private offlineHandler;
     constructor(config: SingleServerProviderConfig);
     /**
      * Connect to the WebSocket server.
@@ -2634,11 +2692,11 @@ declare class SingleServerProvider implements IConnectionProvider {
      * Get connection for a specific key.
      * In single-server mode, key is ignored.
      */
-    getConnection(_key: string): WebSocket;
+    getConnection(_key: string): IConnection;
     /**
      * Get any available connection.
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
      * Check if connected.
      */
@@ -2677,6 +2735,17 @@ declare class SingleServerProvider implements IConnectionProvider {
      * Calculate backoff delay with exponential increase.
      */
     private calculateBackoffDelay;
+    /**
+     * Force-close the current WebSocket and immediately schedule reconnection.
+     * Unlike close(), this does NOT set isClosing and preserves reconnect behavior.
+     * Resets the reconnect counter so the full backoff budget is available.
+     *
+     * Critically, this does NOT wait for the TCP close handshake (which can
+     * hang 20+ seconds on a dead network). Instead it strips all handlers from
+     * the old WebSocket, fires a best-effort close(), nulls the reference, and
+     * schedules reconnect right away.
+     */
+    forceReconnect(): void;
     /**
      * Get the WebSocket URL this provider connects to.
      */
@@ -2690,6 +2759,15 @@ declare class SingleServerProvider implements IConnectionProvider {
      * Called externally after successful authentication.
      */
     resetReconnectAttempts(): void;
+    /**
+     * Listen for browser 'online' event to trigger instant reconnect
+     * when network comes back. Only active in browser environments.
+     */
+    private setupNetworkListeners;
+    /**
+     * Remove browser network event listeners.
+     */
+    private teardownNetworkListeners;
 }
 
 /**
@@ -2753,14 +2831,14 @@ declare class HttpSyncProvider implements IConnectionProvider {
     connect(): Promise<void>;
     /**
      * Get connection for a specific key.
-     * HTTP mode does not expose raw WebSocket connections.
+     * Returns an HttpConnection that queues operations for the next poll cycle.
      */
-    getConnection(_key: string): WebSocket;
+    getConnection(_key: string): IConnection;
     /**
      * Get any available connection.
-     * HTTP mode does not expose raw WebSocket connections.
+     * Returns an HttpConnection that queues operations for the next poll cycle.
      */
-    getAnyConnection(): WebSocket;
+    getAnyConnection(): IConnection;
     /**
      * Check if connected (last HTTP request succeeded).
      */
@@ -2789,6 +2867,10 @@ declare class HttpSyncProvider implements IConnectionProvider {
      * - All other types: silently dropped with debug log
      */
     send(data: ArrayBuffer | Uint8Array, _key?: string): void;
+    /**
+     * Force reconnect by restarting the polling loop.
+     */
+    forceReconnect(): void;
     /**
      * Close the HTTP sync provider.
      * Stops the polling loop, clears queued operations, and sets disconnected state.
@@ -2864,13 +2946,17 @@ declare class AutoConnectionProvider implements IConnectionProvider {
      * Connect using HTTP sync provider.
      */
     private connectHttp;
-    getConnection(key: string): WebSocket;
-    getAnyConnection(): WebSocket;
+    getConnection(key: string): IConnection;
+    getAnyConnection(): IConnection;
     isConnected(): boolean;
     getConnectedNodes(): string[];
     on(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
     off(event: ConnectionProviderEvent, handler: ConnectionEventHandler): void;
     send(data: ArrayBuffer | Uint8Array, key?: string): void;
+    /**
+     * Force reconnect by delegating to the active provider.
+     */
+    forceReconnect(): void;
     /**
      * Close the active underlying provider.
      */
@@ -2893,6 +2979,29 @@ declare class AutoConnectionProvider implements IConnectionProvider {
     private toHttpUrl;
 }
 
+/**
+ * Ready-state constants matching the WebSocket spec values.
+ * Allows callers to compare readyState without depending on the WebSocket global.
+ */
+declare const ConnectionReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/**
+ * Thin adapter that wraps a raw WebSocket and exposes only the IConnection
+ * surface. This keeps the concrete WebSocket type out of public return types
+ * while adding zero overhead.
+ */
+declare class WebSocketConnection implements IConnection {
+    private readonly ws;
+    constructor(ws: WebSocket);
+    send(data: ArrayBuffer | Uint8Array | string): void;
+    close(): void;
+    get readyState(): number;
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { AutoConnectionProvider, type AutoConnectionProviderConfig, type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, HttpSyncProvider, type HttpSyncProviderConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };
+export { AutoConnectionProvider, type AutoConnectionProviderConfig, type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, type ChangeEvent, ChangeTracker, type CircuitState, ClusterClient, type ClusterClientEvents, type ClusterRoutingMode, ConflictResolverClient, type ConnectionEventHandler, ConnectionPool, type ConnectionPoolEvents, type ConnectionProviderEvent, ConnectionReadyState, type CursorStatus, DEFAULT_BACKPRESSURE_CONFIG, DEFAULT_CLUSTER_CONFIG, EncryptedStorageAdapter, EventJournalReader, type HeartbeatConfig, HttpSyncProvider, type HttpSyncProviderConfig, type HybridQueryFilter, HybridQueryHandle, type HybridResultItem, type HybridResultSource, type IConnection, type IConnectionProvider, IDBAdapter, type IStorageAdapter, type JournalEventData, type JournalSubscribeOptions, type OpLogEntry, type OperationDroppedEvent, PNCounterHandle, type PaginationInfo, PartitionRouter, type PartitionRouterEvents, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type RegisterResult, type ResolverInfo, type RoutingMetrics, type RoutingResult, SearchHandle, type SearchResult, type SearchResultsCallback, SingleServerProvider, type SingleServerProviderConfig, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopGunClientConfig, type TopGunClusterConfig, type TopicCallback, TopicHandle, VALID_TRANSITIONS, WebSocketConnection, isValidTransition, logger };