@ekodb/ekodb-client 0.23.0 → 0.24.0

package/dist/client.d.ts

@@ -31,6 +31,12 @@ export interface RateLimitInfo {
 /**
  * Client configuration options
  */
+/**
+ * Default per-request timeout (ms) for REST calls, matching the Rust and Go
+ * clients' 30s default. Applied to every non-streaming request; long-lived
+ * streaming/SSE calls are intentionally not bounded by it.
+ */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 export interface ClientConfig {
     /** Base URL of the ekoDB server */
     baseURL: string;
@@ -42,6 +48,13 @@ export interface ClientConfig {
     maxRetries?: number;
     /** Serialization format (default: MessagePack for best performance, use Json for debugging) */
     format?: SerializationFormat;
+    /**
+     * Per-request timeout in milliseconds for REST calls (default: 30000).
+     * A slow or unreachable server aborts with a timeout error instead of hanging
+     * the caller. Streaming/SSE calls are not bounded by it. Matches the Rust and
+     * Go clients.
+     */
+    timeout?: number;
 }
 /**
  * Rate limit error
@@ -342,6 +355,7 @@ export declare class EkoDBClient {
     private shouldRetry;
     private maxRetries;
     private format;
+    private requestTimeoutMs;
     private rateLimitInfo;
     constructor(config: string | ClientConfig, apiKey?: string);
     /**

package/dist/client.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.SerializationFormat = void 0;
+exports.WebSocketClient = exports.SchemaCache = exports.EventStream = exports.EkoDBClient = exports.MergeStrategy = exports.RateLimitError = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.SerializationFormat = void 0;
 exports.extractRecordId = extractRecordId;
 const msgpack_1 = require("@msgpack/msgpack");
 const query_builder_1 = require("./query-builder");
@@ -51,6 +51,15 @@ var SerializationFormat;
     /** MessagePack format (binary, 2-3x faster) */
     SerializationFormat["MessagePack"] = "MessagePack";
 })(SerializationFormat || (exports.SerializationFormat = SerializationFormat = {}));
+/**
+ * Client configuration options
+ */
+/**
+ * Default per-request timeout (ms) for REST calls, matching the Rust and Go
+ * clients' 30s default. Applied to every non-streaming request; long-lived
+ * streaming/SSE calls are intentionally not bounded by it.
+ */
+exports.DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 /**
  * Rate limit error
  */
@@ -96,6 +105,7 @@ class EkoDBClient {
             this.shouldRetry = true;
             this.maxRetries = 3;
             this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+            this.requestTimeoutMs = exports.DEFAULT_REQUEST_TIMEOUT_MS;
         }
         else {
             this.baseURL = stripTrailingSlashes(config.baseURL);
@@ -103,6 +113,7 @@ class EkoDBClient {
             this.shouldRetry = config.shouldRetry ?? true;
             this.maxRetries = config.maxRetries ?? 3;
             this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+            this.requestTimeoutMs = config.timeout ?? exports.DEFAULT_REQUEST_TIMEOUT_MS;
         }
     }
     /**
@@ -134,6 +145,7 @@ class EkoDBClient {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ api_key: this.apiKey }),
+            signal: AbortSignal.timeout(this.requestTimeoutMs),
         });
         if (!response.ok) {
             let errorMsg = `Auth failed with status: ${response.status}`;
@@ -317,6 +329,10 @@ class EkoDBClient {
                 "Content-Type": contentType,
                 Accept: contentType,
             },
+            // Bound every REST request so a slow/unreachable server aborts instead of
+            // hanging the caller. A fresh signal per attempt is correct here because
+            // makeRequest recurses on retry, rebuilding `options` each time.
+            signal: AbortSignal.timeout(this.requestTimeoutMs),
         };
         if (data) {
             options.body = isMessagePack
@@ -371,6 +387,16 @@ class EkoDBClient {
             throw new Error(`Request failed with status ${response.status}: ${text}`);
         }
         catch (error) {
+            // A fired request-timeout (AbortSignal.timeout) surfaces as a DOMException
+            // named "TimeoutError" (or "AbortError" in some runtimes). Convert it to a
+            // clear error and do NOT retry — retrying would multiply the wait beyond
+            // the configured bound.
+            const errName = error && typeof error === "object" && "name" in error
+                ? error.name
+                : undefined;
+            if (errName === "TimeoutError" || errName === "AbortError") {
+                throw new Error(`Request timed out after ${this.requestTimeoutMs}ms: ${method} ${path}`);
+            }
             // Handle network errors with retry
             if (error instanceof TypeError &&
                 this.shouldRetry &&

package/dist/client.test.js

@@ -2645,3 +2645,29 @@ function mockErrorResponse(status, message) {
         (0, vitest_1.expect)(url).toContain("/api/chat/sess%231/messages");
     });
 });
+(0, vitest_1.describe)("request timeout", () => {
+    (0, vitest_1.it)("defaults to a 30s request timeout", () => {
+        (0, vitest_1.expect)(client_1.DEFAULT_REQUEST_TIMEOUT_MS).toBe(30000);
+    });
+    (0, vitest_1.it)("aborts a request that exceeds the configured timeout", async () => {
+        const client = new client_1.EkoDBClient({
+            baseURL: "http://localhost:8080",
+            apiKey: "test-api-key",
+            format: client_1.SerializationFormat.Json,
+            shouldRetry: false,
+            timeout: 20,
+        });
+        // Token fetch resolves immediately...
+        mockTokenResponse();
+        // ...but the actual request hangs until the request-timeout signal aborts
+        // it. The mock honors the AbortSignal the client attaches, rejecting with
+        // its reason (a "TimeoutError" DOMException) exactly like real fetch.
+        mockFetch.mockImplementationOnce((_url, opts) => new Promise((_resolve, reject) => {
+            const signal = opts.signal;
+            signal?.addEventListener("abort", () => {
+                reject(signal.reason ?? new DOMException("timed out", "TimeoutError"));
+            });
+        }));
+        await (0, vitest_1.expect)(client.find("users")).rejects.toThrow(/timed out after 20ms/);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekodb/ekodb-client",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Official TypeScript/JavaScript client for ekoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   "author": "ekoDB",
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^25.3.5",
+    "@types/node": "^24.13.2",
     "@types/ws": "^8.18.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/client.test.ts

@@ -6,7 +6,12 @@
  */
 
 import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
-import { EkoDBClient, SerializationFormat, extractRecordId } from "./client";
+import {
+  EkoDBClient,
+  SerializationFormat,
+  extractRecordId,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+} from "./client";
 import { SearchQueryBuilder } from "./search";
 
 // Mock fetch globally
@@ -3478,3 +3483,38 @@ describe("EkoDBClient URL path segment encoding", () => {
     expect(url as string).toContain("/api/chat/sess%231/messages");
   });
 });
+
+describe("request timeout", () => {
+  it("defaults to a 30s request timeout", () => {
+    expect(DEFAULT_REQUEST_TIMEOUT_MS).toBe(30000);
+  });
+
+  it("aborts a request that exceeds the configured timeout", async () => {
+    const client = new EkoDBClient({
+      baseURL: "http://localhost:8080",
+      apiKey: "test-api-key",
+      format: SerializationFormat.Json,
+      shouldRetry: false,
+      timeout: 20,
+    });
+
+    // Token fetch resolves immediately...
+    mockTokenResponse();
+    // ...but the actual request hangs until the request-timeout signal aborts
+    // it. The mock honors the AbortSignal the client attaches, rejecting with
+    // its reason (a "TimeoutError" DOMException) exactly like real fetch.
+    mockFetch.mockImplementationOnce(
+      (_url: string, opts: RequestInit) =>
+        new Promise((_resolve, reject) => {
+          const signal = opts.signal as AbortSignal | undefined;
+          signal?.addEventListener("abort", () => {
+            reject(
+              signal.reason ?? new DOMException("timed out", "TimeoutError"),
+            );
+          });
+        }),
+    );
+
+    await expect(client.find("users")).rejects.toThrow(/timed out after 20ms/);
+  });
+});

package/src/client.ts

@@ -37,6 +37,13 @@ export interface RateLimitInfo {
 /**
  * Client configuration options
  */
+/**
+ * Default per-request timeout (ms) for REST calls, matching the Rust and Go
+ * clients' 30s default. Applied to every non-streaming request; long-lived
+ * streaming/SSE calls are intentionally not bounded by it.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
 export interface ClientConfig {
   /** Base URL of the ekoDB server */
   baseURL: string;
@@ -48,6 +55,13 @@ export interface ClientConfig {
   maxRetries?: number;
   /** Serialization format (default: MessagePack for best performance, use Json for debugging) */
   format?: SerializationFormat;
+  /**
+   * Per-request timeout in milliseconds for REST calls (default: 30000).
+   * A slow or unreachable server aborts with a timeout error instead of hanging
+   * the caller. Streaming/SSE calls are not bounded by it. Matches the Rust and
+   * Go clients.
+   */
+  timeout?: number;
 }
 
 /**
@@ -419,6 +433,7 @@ export class EkoDBClient {
   private shouldRetry: boolean;
   private maxRetries: number;
   private format: SerializationFormat;
+  private requestTimeoutMs: number;
   private rateLimitInfo: RateLimitInfo | null = null;
 
   constructor(config: string | ClientConfig, apiKey?: string) {
@@ -431,12 +446,14 @@ export class EkoDBClient {
       this.shouldRetry = true;
       this.maxRetries = 3;
       this.format = SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+      this.requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
     } else {
       this.baseURL = stripTrailingSlashes(config.baseURL);
       this.apiKey = config.apiKey;
       this.shouldRetry = config.shouldRetry ?? true;
       this.maxRetries = config.maxRetries ?? 3;
       this.format = config.format ?? SerializationFormat.MessagePack; // Default to MessagePack for 2-3x performance
+      this.requestTimeoutMs = config.timeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
     }
   }
 
@@ -471,6 +488,7 @@ export class EkoDBClient {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ api_key: this.apiKey }),
+      signal: AbortSignal.timeout(this.requestTimeoutMs),
     });
 
     if (!response.ok) {
@@ -683,6 +701,10 @@ export class EkoDBClient {
         "Content-Type": contentType,
         Accept: contentType,
       },
+      // Bound every REST request so a slow/unreachable server aborts instead of
+      // hanging the caller. A fresh signal per attempt is correct here because
+      // makeRequest recurses on retry, rebuilding `options` each time.
+      signal: AbortSignal.timeout(this.requestTimeoutMs),
     };
 
     if (data) {
@@ -757,6 +779,20 @@ export class EkoDBClient {
       const text = await response.text();
       throw new Error(`Request failed with status ${response.status}: ${text}`);
     } catch (error) {
+      // A fired request-timeout (AbortSignal.timeout) surfaces as a DOMException
+      // named "TimeoutError" (or "AbortError" in some runtimes). Convert it to a
+      // clear error and do NOT retry — retrying would multiply the wait beyond
+      // the configured bound.
+      const errName =
+        error && typeof error === "object" && "name" in error
+          ? (error as { name?: string }).name
+          : undefined;
+      if (errName === "TimeoutError" || errName === "AbortError") {
+        throw new Error(
+          `Request timed out after ${this.requestTimeoutMs}ms: ${method} ${path}`,
+        );
+      }
+
       // Handle network errors with retry
       if (
         error instanceof TypeError &&