@ekodb/ekodb-client 0.19.0 → 0.20.0

package/README.md

@@ -269,7 +269,6 @@ const joinResults = await client.find("users", multiQuery);
 - `.contains(field, value)` - String contains
 - `.startsWith(field, value)` - String starts with
 - `.endsWith(field, value)` - String ends with
-- `.regex(field, pattern)` - Regex match
 - `.sortAsc(field)` / `.sortDesc(field)` - Sorting
 - `.limit(n)` / `.skip(n)` - Pagination
 - `.join(joinConfig)` - Add join configuration

package/dist/client.d.ts

@@ -374,6 +374,20 @@ export declare class EkoDBClient {
      * Sleep for a specified number of seconds
      */
     private sleep;
+    /**
+     * Parse a `Retry-After` header into a non-negative delay in seconds.
+     *
+     * Per RFC 9110 the value is either delay-seconds (an integer) or an
+     * HTTP-date. Anything that doesn't resolve to a finite, non-negative number
+     * (missing header, garbage, a past date) falls back to `defaultSecs`.
+     */
+    private parseRetryAfter;
+    /**
+     * Backoff delay (in seconds) for a 0-indexed retry attempt: a capped
+     * exponential schedule (0.2s → 5s) with full jitter, so concurrent clients
+     * don't retry in lockstep. Returns a value in [d/2, d].
+     */
+    private backoffSeconds;
     /**
      * Helper to determine if a path should use JSON
      * Only CRUD operations (insert/update/delete/batch) use MessagePack
@@ -1090,9 +1104,17 @@ export declare class EkoDBClient {
         filterValue?: string;
     }): EventStream<MutationNotification>;
     /**
-     * Create a WebSocket client
+     * Create a WebSocket client.
+     *
+     * The token is supplied as a provider bound to this client's
+     * {@link getToken}, so every (re)connect re-evaluates (and proactively
+     * refreshes) the auth token instead of snapshotting it once. This means a
+     * reconnect after a token rotation uses the current token.
+     *
+     * @param wsURL - The WebSocket URL (e.g. `wss://host`); `/api/ws` is appended if absent.
+     * @param options - Optional reconnect/timeout tunables.
      */
-    websocket(wsURL: string): WebSocketClient;
+    websocket(wsURL: string, options?: WebSocketClientOptions): WebSocketClient;
     /**
      * Generate embeddings for a single text
      *
@@ -1236,6 +1258,35 @@ export interface SubscribeOptions {
     filterField?: string;
     filterValue?: string;
 }
+/**
+ * A token provider: either a static token string, or a (possibly async)
+ * function that returns a fresh token. When a function is supplied it is
+ * re-invoked on every (re)connect, so a rotated/refreshed token is always
+ * used for the new socket instead of a stale snapshot captured once.
+ */
+export type TokenProvider = string | (() => string | null | Promise<string | null>);
+/** Tunables for the WebSocket client's reconnect + request-timeout behavior. */
+export interface WebSocketClientOptions {
+    /**
+     * Auto-reconnect after an unexpected socket close/error (not an explicit
+     * `close()`/unsubscribe). Defaults to true.
+     */
+    autoReconnect?: boolean;
+    /** Initial backoff delay in ms before the first reconnect attempt. Default 200. */
+    reconnectInitialDelayMs?: number;
+    /** Maximum backoff delay in ms (the cap for exponential growth). Default 5000. */
+    reconnectMaxDelayMs?: number;
+    /**
+     * Maximum number of consecutive reconnect attempts before giving up.
+     * 0 or undefined means unlimited. Default unlimited.
+     */
+    reconnectMaxAttempts?: number;
+    /**
+     * Per-request timeout in ms for request/response WS calls. If no response
+     * arrives in this window the pending promise rejects. Default 30000.
+     */
+    requestTimeoutMs?: number;
+}
 /** EventEmitter-like interface for subscriptions and chat streams. */
 export declare class EventStream<_T = unknown> {
     private listeners;
@@ -1280,24 +1331,67 @@ export declare class SchemaCache {
 export declare function extractRecordId(record: Record, extraCandidates?: string[]): string | undefined;
 export declare class WebSocketClient {
     private wsURL;
-    private token;
+    private tokenProvider;
     private ws;
     private dispatcherRunning;
     private schemaCache;
+    private autoReconnect;
+    private reconnectInitialDelayMs;
+    private reconnectMaxDelayMs;
+    private reconnectMaxAttempts;
+    private requestTimeoutMs;
+    /** Set while close() is in progress so the close handler doesn't reconnect. */
+    private closed;
+    private reconnectAttempts;
+    private reconnecting;
+    private connectPromise;
     private pendingRequests;
     private subscriptions;
+    /** Bookkeeping so subscriptions can be replayed on reconnect. */
+    private subscriptionParams;
     private chatStreams;
     private registerToolsAck;
-    constructor(wsURL: string, token: string);
+    /**
+     * @param wsURL - WebSocket URL; `/api/ws` is appended if absent.
+     * @param token - A static token string OR a {@link TokenProvider} function
+     *   re-evaluated on every (re)connect (so a refreshed token is used after a drop).
+     * @param options - Optional reconnect/timeout tunables.
+     */
+    constructor(wsURL: string, token: TokenProvider, options?: WebSocketClientOptions);
     private messageCounter;
     private genMessageId;
     /**
-     * Connect and start the dispatcher.
+     * Compute the capped exponential backoff (with jitter) for a reconnect
+     * attempt. attempt 0 -> ~initial, growing x2 each time up to the max cap.
+     * Jitter is +/-25% to avoid thundering-herd reconnect storms.
+     * @internal exposed for testing
+     */
+    computeBackoff(attempt: number): number;
+    /**
+     * Connect and start the dispatcher. Re-evaluates the token provider so the
+     * current/refreshed token is used for this socket.
      */
     private ensureConnected;
+    private openSocket;
     private spawnDispatcher;
+    /**
+     * Reject in-flight requests and tear down the dead socket. If the close was
+     * unexpected (not an explicit `close()`) and auto-reconnect is enabled,
+     * schedule a reconnect that re-sends the active subscriptions.
+     */
+    private handleDisconnect;
+    /**
+     * Reconnect with capped exponential backoff + jitter, then re-send the
+     * subscribe messages for every active subscription so the SAME EventStream
+     * keeps delivering mutations after a transient drop.
+     */
+    private scheduleReconnect;
+    /** Re-send Subscribe frames for every tracked subscription after a reconnect. */
+    private resubscribeAll;
     private routeMessage;
     private sendRequest;
+    /** Resolve/reject a pending request, clearing its timeout timer. */
+    private settlePending;
     /**
      * Find all records in a collection via WebSocket.
      */
@@ -1307,6 +1401,11 @@ export declare class WebSocketClient {
      * Returns an EventStream that emits "mutation" events.
      */
     subscribe(collection: string, options?: SubscribeOptions): Promise<EventStream<MutationNotification>>;
+    /**
+     * Unsubscribe from a collection's mutation notifications. This is an
+     * intentional teardown, so the subscription is NOT replayed on reconnect.
+     */
+    unsubscribe(collection: string): void;
     /**
      * Send a chat message and receive a streaming response.
      * Returns an EventStream that emits "event" with ChatStreamEvent objects.
@@ -1369,6 +1468,10 @@ export declare class WebSocketClient {
     deleteCollection(name: string): Promise<void>;
     /**
      * Close the WebSocket connection.
+     *
+     * This is an INTENTIONAL close: it disables auto-reconnect, rejects any
+     * in-flight requests, and tears down all subscriptions/chat streams so
+     * nothing is replayed afterward.
      */
     close(): void;
 }