@ekodb/ekodb-client 0.19.0 → 0.21.0

package/README.md

@@ -254,6 +254,7 @@ const joinResults = await client.find("users", multiQuery);
 - `kvSet(key: string, value: any): Promise<void>`
 - `kvGet(key: string): Promise<any>`
 - `kvDelete(key: string): Promise<void>`
+- `kvClear(): Promise<void>` - Clear the entire KV store
 
 #### Query Builder
 
@@ -269,7 +270,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
@@ -298,6 +298,8 @@ const joinResults = await client.find("users", multiQuery);
 #### Collection Management
 
 - `listCollections(): Promise<string[]>`
+- `listUserCollections(): Promise<string[]>` - List collections excluding
+  internal chat/system collections
 - `deleteCollection(collection: string): Promise<void>`
 - `collectionExists(collection: string): Promise<boolean>` - Check if collection
   exists
@@ -347,6 +349,14 @@ const joinResults = await client.find("users", multiQuery);
 - `deleteCollection(name): Promise<void>`
 - `close(): void`
 
+**Subscriptions & chat:**
+
+- `subscribe(collection, options?): Promise<EventStream<MutationNotification>>`
+  - Subscribe to a collection's mutation notifications
+- `unsubscribe(collection): void` - Tear down a subscription (not replayed on
+  reconnect)
+- `cancelChat(chatId): Promise<void>` - Cancel an in-flight streaming chat
+
 **Schema Cache:**
 
 ```typescript
@@ -360,6 +370,23 @@ const id = extractRecordId(record); // tries "id", "_id"
 const id2 = ws.extractId("users", record); // uses cache
 ```
 
+### Transactions
+
+Buffered, read-your-writes transactions. Statements issued with a
+`transactionId` are staged and applied atomically at commit.
+
+- `beginTransaction(isolationLevel?): Promise<string>` - Start a transaction and
+  return its id
+- `commitTransaction(transactionId): Promise<void>` - Apply staged writes. May
+  reject with a retryable conflict (HTTP 409)
+- `rollbackTransaction(transactionId): Promise<void>` - Discard staged writes
+- `createSavepoint(transactionId, name): Promise<void>`
+- `rollbackToSavepoint(transactionId, name): Promise<void>`
+- `releaseSavepoint(transactionId, name): Promise<void>`
+
+Pass `transactionId` in the options of `insert` / `update` / `delete` / `find` /
+`findById` to read and write within the transaction (read-your-writes).
+
 ## Examples
 
 See the

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 /**
  * ekoDB TypeScript Client
  */
-import { QueryBuilder } from "./query-builder";
+import { QueryBuilder, Query } from "./query-builder";
 import { SearchQuery, SearchResponse } from "./search";
 import { Schema, SchemaBuilder, CollectionMetadata } from "./schema";
 import { UserFunction, FunctionResult } from "./functions";
@@ -50,11 +50,7 @@ export declare class RateLimitError extends Error {
     retryAfterSecs: number;
     constructor(retryAfterSecs: number, message?: string);
 }
-export interface Query {
-    limit?: number;
-    offset?: number;
-    filter?: Record;
-}
+export type { Query };
 export interface BatchOperationResult {
     successful: string[];
     failed: Array<{
@@ -95,6 +91,23 @@ export interface FindOptions {
     bypassCache?: boolean;
     selectFields?: string[];
     excludeFields?: string[];
+    /**
+     * Read within a transaction (read-your-writes). When set, the read is served
+     * from the transaction's own view — its uncommitted staged writes, else the
+     * committed store — and recorded in the transaction's read set for
+     * commit-time conflict detection. Omit for an ordinary committed read.
+     */
+    transactionId?: string;
+}
+/**
+ * Options for a point read by id. `transactionId` enables read-your-writes
+ * within a transaction (see {@link FindOptions.transactionId}).
+ */
+export interface FindByIdOptions {
+    selectFields?: string[];
+    excludeFields?: string[];
+    bypassRipple?: boolean;
+    transactionId?: string;
 }
 export interface BatchInsertOptions {
     bypassRipple?: boolean;
@@ -374,6 +387,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
@@ -413,19 +440,25 @@ export declare class EkoDBClient {
      * const results = await client.find("users", { limit: 10 });
      * ```
      */
-    find(collection: string, query?: Query | QueryBuilder): Promise<Record[]>;
+    find(collection: string, query?: Query | QueryBuilder, options?: {
+        bypassRipple?: boolean;
+        transactionId?: string;
+    }): Promise<Record[]>;
     /**
-     * Find a document by ID
+     * Find a document by ID.
+     * @param options - Optional read options. `transactionId` reads within a
+     *   transaction (read-your-writes); see {@link FindByIdOptions}.
      */
-    findById(collection: string, id: string): Promise<Record>;
+    findById(collection: string, id: string, options?: FindByIdOptions): Promise<Record>;
     /**
      * Find a document by ID with field projection
      * @param collection - Collection name
      * @param id - Document ID
      * @param selectFields - Fields to include in the result
      * @param excludeFields - Fields to exclude from the result
+     * @param transactionId - Read within a transaction (read-your-writes)
      */
-    findByIdWithProjection(collection: string, id: string, selectFields?: string[], excludeFields?: string[]): Promise<Record>;
+    findByIdWithProjection(collection: string, id: string, selectFields?: string[], excludeFields?: string[], transactionId?: string): Promise<Record>;
     /**
      * Update a document
      * @param collection - Collection name
@@ -500,6 +533,10 @@ export declare class EkoDBClient {
      * Delete a key
      */
     kvDelete(key: string): Promise<void>;
+    /**
+     * Clear the entire KV store (all keys in the namespace).
+     */
+    kvClear(): Promise<void>;
     /**
      * Batch get multiple keys
      * @param keys - Array of keys to retrieve
@@ -546,7 +583,18 @@ export declare class EkoDBClient {
         include_expired?: boolean;
     }): Promise<any[]>;
     /**
-     * Begin a new transaction
+     * Begin a new transaction.
+     *
+     * Transactions are buffered: statements issued with this `transactionId`
+     * (passed via the `transactionId` option on insert/update/delete/find/…) are
+     * staged and applied atomically only at {@link commitTransaction}. They are
+     * invisible to everyone else until commit, and visible to this transaction's
+     * own reads (read-your-writes) only when those reads also carry the
+     * `transactionId`. {@link rollbackTransaction} discards the staged writes.
+     * `commitTransaction` may reject with a conflict (HTTP 409) if a record this
+     * transaction read or wrote was changed by another committed transaction —
+     * retry the transaction in that case.
+     *
      * @param isolationLevel - Transaction isolation level (default: "ReadCommitted")
      * @returns Transaction ID
      */
@@ -566,10 +614,23 @@ export declare class EkoDBClient {
      */
     commitTransaction(transactionId: string): Promise<void>;
     /**
-     * Rollback a transaction
+     * Rollback a transaction (discards all staged writes; nothing was applied).
      * @param transactionId - The transaction ID to rollback
      */
     rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * Create a savepoint within a transaction. A later
+     * {@link rollbackToSavepoint} discards everything staged after it.
+     */
+    createSavepoint(transactionId: string, name: string): Promise<void>;
+    /**
+     * Roll the transaction back to a savepoint, discarding writes staged after it.
+     */
+    rollbackToSavepoint(transactionId: string, name: string): Promise<void>;
+    /**
+     * Release (forget) a savepoint. Staged work is unaffected.
+     */
+    releaseSavepoint(transactionId: string, name: string): Promise<void>;
     /**
      * Insert or update a record (upsert operation)
      *
@@ -658,6 +719,10 @@ export declare class EkoDBClient {
      * List all collections
      */
     listCollections(): Promise<string[]>;
+    /**
+     * List collections, excluding internal chat/system collections.
+     */
+    listUserCollections(): Promise<string[]>;
     /**
      * Delete a collection
      */
@@ -1090,9 +1155,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 +1309,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 +1382,89 @@ 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;
+    /**
+     * Per-connection wire format, set by negotiateFormat() on every (re)connect:
+     * true once the server has Welcomed msgpack, so frames are sent/received as
+     * binary msgpack; false (JSON text) otherwise, including against an older
+     * server that never Welcomes. Keeps the transport fully back-compatible.
+     */
+    private binary;
+    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;
+    /**
+     * Additive capability handshake: offer msgpack and, if the server Welcomes
+     * it, switch this connection to binary msgpack frames; otherwise stay on JSON
+     * text. The Welcome (a text frame) is read with a one-shot listener and a
+     * timeout so an older server that never answers — or answers with an Error —
+     * simply leaves the connection on JSON. Best-effort and never throws: JSON
+     * always works.
+     */
+    private negotiateFormat;
+    /**
+     * Send a request object on the active socket using the negotiated format:
+     * binary msgpack when the server Welcomed it, JSON text otherwise. The single
+     * write point so every request honors the negotiated transport.
+     */
+    private sendFrame;
     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 +1474,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.
@@ -1320,6 +1492,11 @@ export declare class WebSocketClient {
      * Send a tool result back to the server during a chat stream.
      */
     sendToolResult(chatId: string, callId: string, success: boolean, result?: any, error?: string): Promise<void>;
+    /**
+     * Cancel an in-flight streaming chat. Fire-and-forget: tells the server to
+     * stop generating tokens for the given chat.
+     */
+    cancelChat(chatId: string): Promise<void>;
     /**
      * Stateless raw LLM completion via WebSocket.
      *
@@ -1369,6 +1546,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;
 }