@topgunbuild/client 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -113,21 +113,231 @@ declare class TopicHandle {
     }): void;
 }
 
+/**
+ * Defines the possible states for the SyncEngine connection state machine.
+ */
+declare enum SyncState {
+    /** Initial state before any connection attempt */
+    INITIAL = "INITIAL",
+    /** WebSocket connection is being established */
+    CONNECTING = "CONNECTING",
+    /** Connected, waiting for authentication response */
+    AUTHENTICATING = "AUTHENTICATING",
+    /** Authenticated, performing initial data sync */
+    SYNCING = "SYNCING",
+    /** Fully connected and synchronized */
+    CONNECTED = "CONNECTED",
+    /** Intentionally or unexpectedly disconnected */
+    DISCONNECTED = "DISCONNECTED",
+    /** Waiting before retry (exponential backoff) */
+    BACKOFF = "BACKOFF",
+    /** Fatal error requiring manual intervention or reset */
+    ERROR = "ERROR"
+}
+/**
+ * Defines valid state transitions for the SyncEngine FSM.
+ * Each key is a current state, and the value is an array of valid target states.
+ */
+declare const VALID_TRANSITIONS: Record<SyncState, SyncState[]>;
+/**
+ * Helper function to check if a transition is valid
+ */
+declare function isValidTransition(from: SyncState, to: SyncState): boolean;
+
+/**
+ * Event emitted when the state machine transitions between states.
+ */
+interface StateChangeEvent {
+    /** The state before the transition */
+    from: SyncState;
+    /** The state after the transition */
+    to: SyncState;
+    /** Unix timestamp (ms) when the transition occurred */
+    timestamp: number;
+}
+/**
+ * Listener callback for state change events.
+ */
+type StateChangeListener = (event: StateChangeEvent) => void;
+/**
+ * Configuration options for the state machine.
+ */
+interface SyncStateMachineConfig {
+    /** Maximum number of state transitions to keep in history (default: 50) */
+    maxHistorySize?: number;
+}
+/**
+ * A finite state machine for managing SyncEngine connection states.
+ *
+ * Features:
+ * - Validates all state transitions against allowed paths
+ * - Emits events on state changes for observability
+ * - Maintains a history of transitions for debugging
+ * - Logs invalid transition attempts (graceful degradation)
+ */
+declare class SyncStateMachine {
+    private state;
+    private readonly listeners;
+    private history;
+    private readonly maxHistorySize;
+    constructor(config?: SyncStateMachineConfig);
+    /**
+     * Attempt to transition to a new state.
+     * @param to The target state
+     * @returns true if the transition was valid and executed, false otherwise
+     */
+    transition(to: SyncState): boolean;
+    /**
+     * Get the current state.
+     */
+    getState(): SyncState;
+    /**
+     * Check if a transition from the current state to the target state is valid.
+     * @param to The target state to check
+     */
+    canTransition(to: SyncState): boolean;
+    /**
+     * Subscribe to state change events.
+     * @param listener Callback function to be called on each state change
+     * @returns An unsubscribe function
+     */
+    onStateChange(listener: StateChangeListener): () => void;
+    /**
+     * Get the state transition history.
+     * @param limit Maximum number of entries to return (default: all)
+     * @returns Array of state change events, oldest first
+     */
+    getHistory(limit?: number): StateChangeEvent[];
+    /**
+     * Reset the state machine to INITIAL state.
+     * This is a forced reset that bypasses normal transition validation.
+     * Use for testing or hard resets after fatal errors.
+     * @param clearHistory If true, also clears the transition history (default: true)
+     */
+    reset(clearHistory?: boolean): void;
+    /**
+     * Check if the state machine is in a "connected" state
+     * (either SYNCING or CONNECTED)
+     */
+    isConnected(): boolean;
+    /**
+     * Check if the state machine is in a state where operations can be sent
+     * (authenticated and connected)
+     */
+    isReady(): boolean;
+    /**
+     * Check if the state machine is currently attempting to connect
+     */
+    isConnecting(): boolean;
+}
+
+/**
+ * Backpressure strategy when maxPendingOps is reached.
+ */
+type BackpressureStrategy = 'pause' | 'throw' | 'drop-oldest';
+/**
+ * Configuration for backpressure control on SyncEngine.
+ */
+interface BackpressureConfig {
+    /**
+     * Maximum number of operations waiting for server acknowledgment.
+     * When this limit is reached, the configured strategy will be applied.
+     * @default 1000
+     */
+    maxPendingOps: number;
+    /**
+     * Strategy when maxPendingOps is reached:
+     * - 'pause': Wait for capacity (returns Promise that resolves when space available)
+     * - 'throw': Throw BackpressureError immediately
+     * - 'drop-oldest': Remove oldest pending op to make room (data loss!)
+     * @default 'pause'
+     */
+    strategy: BackpressureStrategy;
+    /**
+     * High water mark (percentage of maxPendingOps).
+     * Emit 'backpressure:high' event when reached.
+     * Value should be between 0 and 1.
+     * @default 0.8 (80%)
+     */
+    highWaterMark: number;
+    /**
+     * Low water mark (percentage of maxPendingOps).
+     * Resume paused writes and emit 'backpressure:low' when pending ops drop below this.
+     * Value should be between 0 and 1.
+     * @default 0.5 (50%)
+     */
+    lowWaterMark: number;
+}
+/**
+ * Default backpressure configuration.
+ */
+declare const DEFAULT_BACKPRESSURE_CONFIG: BackpressureConfig;
+/**
+ * Status of backpressure mechanism.
+ */
+interface BackpressureStatus {
+    /** Current number of pending (unacknowledged) operations */
+    pending: number;
+    /** Maximum allowed pending operations */
+    max: number;
+    /** Percentage of capacity used (0-1) */
+    percentage: number;
+    /** Whether writes are currently paused due to backpressure */
+    isPaused: boolean;
+    /** Current backpressure strategy */
+    strategy: BackpressureStrategy;
+}
+/**
+ * Event data for backpressure:high and backpressure:low events.
+ */
+interface BackpressureThresholdEvent {
+    pending: number;
+    max: number;
+}
+/**
+ * Event data for operation:dropped event.
+ */
+interface OperationDroppedEvent {
+    opId: string;
+    mapName: string;
+    opType: string;
+    key: string;
+}
+
+interface HeartbeatConfig {
+    intervalMs: number;
+    timeoutMs: number;
+    enabled: boolean;
+}
+interface BackoffConfig {
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    multiplier: number;
+    /** Whether to add random jitter to delay (default: true) */
+    jitter: boolean;
+    /** Maximum number of retry attempts before entering ERROR state (default: 10) */
+    maxRetries: number;
+}
 interface SyncEngineConfig {
     nodeId: string;
     serverUrl: string;
     storageAdapter: IStorageAdapter;
     reconnectInterval?: number;
+    heartbeat?: Partial<HeartbeatConfig>;
+    backoff?: Partial<BackoffConfig>;
+    backpressure?: Partial<BackpressureConfig>;
 }
 declare class SyncEngine {
     private readonly nodeId;
     private readonly serverUrl;
     private readonly storageAdapter;
-    private readonly reconnectInterval;
     private readonly hlc;
+    private readonly stateMachine;
+    private readonly backoffConfig;
     private websocket;
-    private isOnline;
-    private isAuthenticated;
     private opLog;
     private maps;
     private queries;
@@ -137,9 +347,49 @@ declare class SyncEngine {
     private reconnectTimer;
     private authToken;
     private tokenProvider;
+    private backoffAttempt;
+    private readonly heartbeatConfig;
+    private heartbeatInterval;
+    private lastPongReceived;
+    private lastRoundTripTime;
+    private readonly backpressureConfig;
+    private backpressurePaused;
+    private waitingForCapacity;
+    private highWaterMarkEmitted;
+    private backpressureListeners;
     constructor(config: SyncEngineConfig);
+    /**
+     * Get the current connection state
+     */
+    getConnectionState(): SyncState;
+    /**
+     * Subscribe to connection state changes
+     * @returns Unsubscribe function
+     */
+    onConnectionStateChange(listener: (event: StateChangeEvent) => void): () => void;
+    /**
+     * Get state machine history for debugging
+     */
+    getStateHistory(limit?: number): StateChangeEvent[];
+    /**
+     * Check if WebSocket is connected (but may not be authenticated yet)
+     */
+    private isOnline;
+    /**
+     * Check if fully authenticated and ready for operations
+     */
+    private isAuthenticated;
+    /**
+     * Check if fully connected and synced
+     */
+    private isConnected;
     private initConnection;
     private scheduleReconnect;
+    private calculateBackoffDelay;
+    /**
+     * Reset backoff counter (called on successful connection)
+     */
+    private resetBackoff;
     private loadOpLog;
     private saveOpLog;
     registerMap(mapName: string, map: LWWMap<any, any> | ORMap<any, any>): void;
@@ -148,7 +398,7 @@ declare class SyncEngine {
         orRecord?: ORMapRecord<any>;
         orTag?: string;
         timestamp: Timestamp;
-    }): Promise<void>;
+    }): Promise<string>;
     private syncPendingOperations;
     private startMerkleSync;
     setAuthToken(token: string): void;
@@ -178,7 +428,92 @@ declare class SyncEngine {
      * Closes the WebSocket connection and cleans up resources.
      */
     close(): void;
+    /**
+     * Reset the state machine and connection.
+     * Use after fatal errors to start fresh.
+     */
+    resetConnection(): void;
     private resetMap;
+    /**
+     * Starts the heartbeat mechanism after successful connection.
+     */
+    private startHeartbeat;
+    /**
+     * Stops the heartbeat mechanism.
+     */
+    private stopHeartbeat;
+    /**
+     * Sends a PING message to the server.
+     */
+    private sendPing;
+    /**
+     * Handles incoming PONG message from server.
+     */
+    private handlePong;
+    /**
+     * Checks if heartbeat has timed out and triggers reconnection if needed.
+     */
+    private checkHeartbeatTimeout;
+    /**
+     * Returns the last measured round-trip time in milliseconds.
+     * Returns null if no PONG has been received yet.
+     */
+    getLastRoundTripTime(): number | null;
+    /**
+     * Returns true if the connection is considered healthy based on heartbeat.
+     * A connection is healthy if it's online, authenticated, and has received
+     * a PONG within the timeout window.
+     */
+    isConnectionHealthy(): boolean;
+    /**
+     * Push local ORMap diff to server for the given keys.
+     * Sends local records and tombstones that the server might not have.
+     */
+    private pushORMapDiff;
+    /**
+     * Get the current number of pending (unsynced) operations.
+     */
+    getPendingOpsCount(): number;
+    /**
+     * Get the current backpressure status.
+     */
+    getBackpressureStatus(): BackpressureStatus;
+    /**
+     * Returns true if writes are currently paused due to backpressure.
+     */
+    isBackpressurePaused(): boolean;
+    /**
+     * Subscribe to backpressure events.
+     * @param event Event name: 'backpressure:high', 'backpressure:low', 'backpressure:paused', 'backpressure:resumed', 'operation:dropped'
+     * @param listener Callback function
+     * @returns Unsubscribe function
+     */
+    onBackpressure(event: 'backpressure:high' | 'backpressure:low' | 'backpressure:paused' | 'backpressure:resumed' | 'operation:dropped', listener: (data?: BackpressureThresholdEvent | OperationDroppedEvent) => void): () => void;
+    /**
+     * Emit a backpressure event to all listeners.
+     */
+    private emitBackpressureEvent;
+    /**
+     * Check backpressure before adding a new operation.
+     * May pause, throw, or drop depending on strategy.
+     */
+    private checkBackpressure;
+    /**
+     * Check high water mark and emit event if threshold reached.
+     */
+    private checkHighWaterMark;
+    /**
+     * Check low water mark and resume paused writes if threshold reached.
+     */
+    private checkLowWaterMark;
+    /**
+     * Wait for capacity to become available (used by 'pause' strategy).
+     */
+    private waitForCapacity;
+    /**
+     * Drop the oldest pending operation (used by 'drop-oldest' strategy).
+     */
+    private dropOldestOp;
 }
 
 interface ILock {
@@ -207,6 +542,8 @@ declare class TopGunClient {
         nodeId?: string;
         serverUrl: string;
         storage: IStorageAdapter;
+        backoff?: Partial<BackoffConfig>;
+        backpressure?: Partial<BackpressureConfig>;
     });
     start(): Promise<void>;
     setAuthToken(token: string): void;
@@ -244,6 +581,68 @@ declare class TopGunClient {
      * Closes the client, disconnecting from the server and cleaning up resources.
      */
     close(): void;
+    /**
+     * Get the current connection state
+     */
+    getConnectionState(): SyncState;
+    /**
+     * Subscribe to connection state changes
+     * @param listener Callback function called on each state change
+     * @returns Unsubscribe function
+     */
+    onConnectionStateChange(listener: (event: StateChangeEvent) => void): () => void;
+    /**
+     * Get state machine history for debugging
+     * @param limit Maximum number of entries to return
+     */
+    getStateHistory(limit?: number): StateChangeEvent[];
+    /**
+     * Reset the connection and state machine.
+     * Use after fatal errors to start fresh.
+     */
+    resetConnection(): void;
+    /**
+     * Get the current number of pending (unacknowledged) operations.
+     */
+    getPendingOpsCount(): number;
+    /**
+     * Get the current backpressure status.
+     */
+    getBackpressureStatus(): BackpressureStatus;
+    /**
+     * Returns true if writes are currently paused due to backpressure.
+     */
+    isBackpressurePaused(): boolean;
+    /**
+     * Subscribe to backpressure events.
+     *
+     * Available events:
+     * - 'backpressure:high': Emitted when pending ops reach high water mark
+     * - 'backpressure:low': Emitted when pending ops drop below low water mark
+     * - 'backpressure:paused': Emitted when writes are paused (pause strategy)
+     * - 'backpressure:resumed': Emitted when writes resume after being paused
+     * - 'operation:dropped': Emitted when an operation is dropped (drop-oldest strategy)
+     *
+     * @param event Event name
+     * @param listener Callback function
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * client.onBackpressure('backpressure:high', ({ pending, max }) => {
+     *   console.warn(`Warning: ${pending}/${max} pending ops`);
+     * });
+     *
+     * client.onBackpressure('backpressure:paused', () => {
+     *   showLoadingSpinner();
+     * });
+     *
+     * client.onBackpressure('backpressure:resumed', () => {
+     *   hideLoadingSpinner();
+     * });
+     * ```
+     */
+    onBackpressure(event: 'backpressure:high' | 'backpressure:low' | 'backpressure:paused' | 'backpressure:resumed' | 'operation:dropped', listener: (data?: BackpressureThresholdEvent | OperationDroppedEvent) => void): () => void;
 }
 
 interface TopGunConfig {
@@ -362,6 +761,16 @@ declare class EncryptedStorageAdapter implements IStorageAdapter {
     private isEncryptedRecord;
 }
 
+/**
+ * Error thrown when backpressure limit is reached and strategy is 'throw'.
+ */
+declare class BackpressureError extends Error {
+    readonly pendingCount: number;
+    readonly maxPending: number;
+    readonly name = "BackpressureError";
+    constructor(pendingCount: number, maxPending: number);
+}
+
 declare const logger: pino.Logger<never, boolean>;
 
-export { EncryptedStorageAdapter, IDBAdapter, type IStorageAdapter, type OpLogEntry, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, SyncEngine, TopGun, TopGunClient, type TopicCallback, TopicHandle, logger };
+export { type BackoffConfig, type BackpressureConfig, BackpressureError, type BackpressureStatus, type BackpressureStrategy, type BackpressureThresholdEvent, DEFAULT_BACKPRESSURE_CONFIG, EncryptedStorageAdapter, type HeartbeatConfig, IDBAdapter, type IStorageAdapter, type OpLogEntry, type OperationDroppedEvent, type QueryFilter, QueryHandle, type QueryResultItem, type QueryResultSource, type StateChangeEvent, type StateChangeListener, SyncEngine, type SyncEngineConfig, SyncState, SyncStateMachine, type SyncStateMachineConfig, TopGun, TopGunClient, type TopicCallback, TopicHandle, VALID_TRANSITIONS, isValidTransition, logger };