@ecodrix/erix-client 1.0.5 → 1.3.0

package/dist/transports/HttpTransport.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file HttpTransport.ts
+ * @module ErixClient/Transports/HttpTransport
+ *
+ * HTTP transport for @ecodrix/erix-client.
+ *
+ * Wraps the existing fetch-based request logic into a TransportLayer
+ * implementation. This is the default/fallback transport that preserves
+ * the original behavior of the client.
+ */
+import type { TransportLayer } from "./TransportLayer.js";
+export interface HttpTransportOptions {
+    /** Full base URL of the erix-store instance */
+    baseUrl: string;
+    /** Headers to include on every request (auth, tenant, content-type) */
+    headers: Record<string, string>;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+export declare class HttpTransport implements TransportLayer {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeoutMs;
+    private closed;
+    constructor(options: HttpTransportOptions);
+    /**
+     * HTTP is always "connected" — each request is independent.
+     */
+    get isConnected(): boolean;
+    /**
+     * Send a single HTTP request using native fetch.
+     */
+    request(method: string, path: string, body?: unknown, params?: Record<string, string>): Promise<unknown>;
+    /**
+     * Pipeline over HTTP — executes requests sequentially since HTTP
+     * doesn't natively support multiplexing in a single connection.
+     * Still provides the same API contract as WebSocket pipeline.
+     */
+    pipeline(requests: Array<{
+        method: string;
+        path: string;
+        body?: unknown;
+        params?: Record<string, string>;
+    }>): Promise<unknown[]>;
+    /**
+     * Mark the transport as closed. Subsequent requests will throw.
+     */
+    close(): void;
+}

package/dist/transports/HttpTransport.js

@@ -0,0 +1,71 @@
+/**
+ * @file HttpTransport.ts
+ * @module ErixClient/Transports/HttpTransport
+ *
+ * HTTP transport for @ecodrix/erix-client.
+ *
+ * Wraps the existing fetch-based request logic into a TransportLayer
+ * implementation. This is the default/fallback transport that preserves
+ * the original behavior of the client.
+ */
+export class HttpTransport {
+    constructor(options) {
+        this.closed = false;
+        this.baseUrl = options.baseUrl;
+        this.headers = options.headers;
+        this.timeoutMs = options.timeoutMs ?? 5000;
+    }
+    /**
+     * HTTP is always "connected" — each request is independent.
+     */
+    get isConnected() {
+        return !this.closed;
+    }
+    /**
+     * Send a single HTTP request using native fetch.
+     */
+    async request(method, path, body, params) {
+        if (this.closed) {
+            throw new Error("[erix-store] HttpTransport has been closed");
+        }
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(url.toString(), {
+                method,
+                headers: this.headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({})));
+                throw new Error(`[erix-store] ${method} ${path} → ${res.status}: ${err.error ?? res.statusText}`);
+            }
+            return await res.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Pipeline over HTTP — executes requests sequentially since HTTP
+     * doesn't natively support multiplexing in a single connection.
+     * Still provides the same API contract as WebSocket pipeline.
+     */
+    async pipeline(requests) {
+        // Execute all requests concurrently via Promise.all
+        return Promise.all(requests.map((r) => this.request(r.method, r.path, r.body, r.params)));
+    }
+    /**
+     * Mark the transport as closed. Subsequent requests will throw.
+     */
+    close() {
+        this.closed = true;
+    }
+}

package/dist/transports/TransportLayer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file TransportLayer.ts
+ * @module ErixClient/Transports/TransportLayer
+ *
+ * Strategy interface for erix-client transports.
+ * Both HttpTransport and WebSocketTransport implement this interface,
+ * allowing the ErixClient to swap transports transparently.
+ */
+/**
+ * Common interface that all transport implementations must satisfy.
+ * Provides request/response semantics regardless of underlying protocol.
+ */
+export interface TransportLayer {
+    /**
+     * Send a request and await the response.
+     * @param method HTTP-like method (GET, POST, DELETE, PATCH)
+     * @param path   Route path (e.g. /core/get, /queue/v2/jobs)
+     * @param body   Optional request body
+     * @param params Optional query parameters
+     */
+    request(method: string, path: string, body?: unknown, params?: Record<string, string>): Promise<unknown>;
+    /**
+     * Send a batch of requests as a single round-trip (pipeline).
+     * Returns an array of results in the same order as the input requests.
+     */
+    pipeline(requests: Array<{
+        method: string;
+        path: string;
+        body?: unknown;
+        params?: Record<string, string>;
+    }>): Promise<unknown[]>;
+    /**
+     * Close the transport and release resources.
+     */
+    close(): void;
+    /**
+     * Whether the transport is currently connected/ready.
+     */
+    readonly isConnected: boolean;
+}
+/** Transport mode option for ErixClient */
+export type TransportMode = "http" | "ws" | "auto";

package/dist/transports/TransportLayer.js

@@ -0,0 +1,9 @@
+/**
+ * @file TransportLayer.ts
+ * @module ErixClient/Transports/TransportLayer
+ *
+ * Strategy interface for erix-client transports.
+ * Both HttpTransport and WebSocketTransport implement this interface,
+ * allowing the ErixClient to swap transports transparently.
+ */
+export {};

package/dist/transports/WebSocketTransport.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @file WebSocketTransport.ts
+ * @module ErixClient/Transports/WebSocket
+ *
+ * WebSocket transport for @ecodrix/erix-client.
+ *
+ * Provides persistent binary (MessagePack) communication with erix-store,
+ * supporting request/response multiplexing via correlation IDs, pipeline
+ * batching, automatic reconnection with exponential backoff, and request
+ * buffering during disconnection.
+ */
+import type { TransportLayer } from "./TransportLayer.js";
+export interface TransportOptions {
+    /** WebSocket URL, e.g. ws://localhost:9876 */
+    url: string;
+    /** Headers to send on connection (auth, tenant) */
+    headers: Record<string, string>;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+    /** Reconnection options */
+    reconnect?: {
+        /** Initial delay before first reconnect attempt (default: 1000) */
+        initialDelayMs?: number;
+        /** Maximum delay between reconnect attempts (default: 30000) */
+        maxDelayMs?: number;
+        /** Backoff multiplier (default: 2) */
+        backoffFactor?: number;
+    };
+}
+export declare class TimeoutError extends Error {
+    constructor(id: number, timeoutMs: number);
+}
+export declare class ConnectionLostError extends Error {
+    constructor();
+}
+export declare class TransportClosedError extends Error {
+    constructor();
+}
+export declare class WebSocketTransport implements TransportLayer {
+    private ws;
+    private pending;
+    private buffer;
+    private nextId;
+    private connected;
+    private closed;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private readonly url;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly initialDelayMs;
+    private readonly maxDelayMs;
+    private readonly backoffFactor;
+    constructor(options: TransportOptions);
+    /**
+     * Send a request and await the correlated response.
+     * If disconnected, the request is buffered and replayed on reconnect.
+     */
+    request(method: string, path: string, body?: unknown, params?: Record<string, string>): Promise<unknown>;
+    /**
+     * Send a pipeline batch and await all responses.
+     * All operations are sent in a single frame and resolved together.
+     */
+    pipeline(requests: Array<{
+        method: string;
+        path: string;
+        body?: unknown;
+        params?: Record<string, string>;
+    }>): Promise<unknown[]>;
+    /**
+     * Close the transport. Rejects all pending requests, clears timers,
+     * and closes the WebSocket connection.
+     */
+    close(): void;
+    /**
+     * Returns whether the transport is currently connected.
+     */
+    get isConnected(): boolean;
+    private connect;
+    private handleDisconnect;
+    private scheduleReconnect;
+    private replayBuffer;
+    private handleMessage;
+    private registerPending;
+    private registerPipelinePending;
+}

package/dist/transports/WebSocketTransport.js

@@ -0,0 +1,299 @@
+/**
+ * @file WebSocketTransport.ts
+ * @module ErixClient/Transports/WebSocket
+ *
+ * WebSocket transport for @ecodrix/erix-client.
+ *
+ * Provides persistent binary (MessagePack) communication with erix-store,
+ * supporting request/response multiplexing via correlation IDs, pipeline
+ * batching, automatic reconnection with exponential backoff, and request
+ * buffering during disconnection.
+ */
+import { pack, unpack } from "msgpackr";
+import WebSocket from "ws";
+// ─── Errors ─────────────────────────────────────────────────────────────────
+export class TimeoutError extends Error {
+    constructor(id, timeoutMs) {
+        super(`Request ${id} timed out after ${timeoutMs}ms`);
+        this.name = "TimeoutError";
+    }
+}
+export class ConnectionLostError extends Error {
+    constructor() {
+        super("WebSocket connection lost");
+        this.name = "ConnectionLostError";
+    }
+}
+export class TransportClosedError extends Error {
+    constructor() {
+        super("WebSocket transport has been closed");
+        this.name = "TransportClosedError";
+    }
+}
+// ─── WebSocketTransport ─────────────────────────────────────────────────────
+export class WebSocketTransport {
+    constructor(options) {
+        this.ws = null;
+        this.pending = new Map();
+        this.buffer = [];
+        this.nextId = 1;
+        this.connected = false;
+        this.closed = false;
+        this.reconnectAttempt = 0;
+        this.reconnectTimer = null;
+        this.url = options.url;
+        this.headers = options.headers;
+        this.timeoutMs = options.timeoutMs ?? 5000;
+        this.initialDelayMs = options.reconnect?.initialDelayMs ?? 1000;
+        this.maxDelayMs = options.reconnect?.maxDelayMs ?? 30000;
+        this.backoffFactor = options.reconnect?.backoffFactor ?? 2;
+        this.connect();
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────
+    /**
+     * Send a request and await the correlated response.
+     * If disconnected, the request is buffered and replayed on reconnect.
+     */
+    request(method, path, body, params) {
+        if (this.closed) {
+            return Promise.reject(new TransportClosedError());
+        }
+        const id = this.nextId++;
+        const frame = { id, method, path };
+        if (body !== undefined)
+            frame.body = body;
+        if (params !== undefined)
+            frame.params = params;
+        const encoded = pack(frame);
+        return new Promise((resolve, reject) => {
+            if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+                this.registerPending(id, resolve, reject);
+                this.ws.send(encoded);
+            }
+            else {
+                // Buffer for replay on reconnect
+                this.buffer.push({ frame: encoded, resolve, reject });
+            }
+        });
+    }
+    /**
+     * Send a pipeline batch and await all responses.
+     * All operations are sent in a single frame and resolved together.
+     */
+    pipeline(requests) {
+        if (this.closed) {
+            return Promise.reject(new TransportClosedError());
+        }
+        const pipelineId = this.nextId++;
+        const subRequests = requests.map((r) => {
+            const subId = this.nextId++;
+            const frame = { id: subId, method: r.method, path: r.path };
+            if (r.body !== undefined)
+                frame.body = r.body;
+            if (r.params !== undefined)
+                frame.params = r.params;
+            return frame;
+        });
+        const pipelineFrame = {
+            id: pipelineId,
+            pipeline: true,
+            requests: subRequests,
+        };
+        const encoded = pack(pipelineFrame);
+        return new Promise((resolve, reject) => {
+            if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+                this.registerPipelinePending(pipelineId, resolve, reject);
+                this.ws.send(encoded);
+            }
+            else {
+                // Buffer pipeline request — wrap resolve/reject to handle pipeline response
+                const wrappedResolve = (data) => {
+                    const pipelineResp = data;
+                    resolve(pipelineResp.responses.map((r) => r.data));
+                };
+                this.buffer.push({ frame: encoded, resolve: wrappedResolve, reject });
+            }
+        });
+    }
+    /**
+     * Close the transport. Rejects all pending requests, clears timers,
+     * and closes the WebSocket connection.
+     */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Clear reconnect timer
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Reject all pending requests
+        const closedError = new TransportClosedError();
+        for (const [_id, pending] of this.pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(closedError);
+        }
+        this.pending.clear();
+        // Reject all buffered requests
+        for (const buffered of this.buffer) {
+            buffered.reject(closedError);
+        }
+        this.buffer = [];
+        // Close WebSocket
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            if (this.ws.readyState === WebSocket.OPEN ||
+                this.ws.readyState === WebSocket.CONNECTING) {
+                this.ws.close(1000, "Client closing");
+            }
+            this.ws = null;
+        }
+        this.connected = false;
+    }
+    /**
+     * Returns whether the transport is currently connected.
+     */
+    get isConnected() {
+        return this.connected;
+    }
+    // ─── Connection Management ──────────────────────────────────────────────
+    connect() {
+        if (this.closed)
+            return;
+        this.ws = new WebSocket(this.url, {
+            headers: this.headers,
+        });
+        this.ws.binaryType = "nodebuffer";
+        this.ws.on("open", () => {
+            this.connected = true;
+            this.reconnectAttempt = 0;
+            this.replayBuffer();
+        });
+        this.ws.on("message", (data) => {
+            this.handleMessage(data);
+        });
+        this.ws.on("close", () => {
+            this.handleDisconnect();
+        });
+        this.ws.on("error", () => {
+            // Error is followed by close event, so we handle reconnect there
+        });
+    }
+    handleDisconnect() {
+        this.connected = false;
+        if (this.closed)
+            return;
+        // Reject pending requests that were in-flight (they won't get responses)
+        const lostError = new ConnectionLostError();
+        for (const [_id, pending] of this.pending) {
+            clearTimeout(pending.timeout);
+            pending.reject(lostError);
+        }
+        this.pending.clear();
+        // Schedule reconnect with exponential backoff
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        const delay = Math.min(this.initialDelayMs * this.backoffFactor ** this.reconnectAttempt, this.maxDelayMs);
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    // ─── Buffer Replay ──────────────────────────────────────────────────────
+    replayBuffer() {
+        const buffered = this.buffer.splice(0);
+        for (const entry of buffered) {
+            if (this.closed) {
+                entry.reject(new TransportClosedError());
+                continue;
+            }
+            // Decode the frame to get the ID for pending registration
+            const decoded = unpack(entry.frame);
+            if ("pipeline" in decoded && decoded.pipeline) {
+                // Pipeline frame
+                const _pipelineResolve = (data) => {
+                    const resp = data;
+                    entry.resolve(resp);
+                };
+                this.registerPipelinePending(decoded.id, (responses) => {
+                    entry.resolve(responses);
+                }, entry.reject);
+                this.ws?.send(entry.frame);
+            }
+            else {
+                // Single request frame
+                this.registerPending(decoded.id, entry.resolve, entry.reject);
+                this.ws?.send(entry.frame);
+            }
+        }
+    }
+    // ─── Message Handling ───────────────────────────────────────────────────
+    handleMessage(data) {
+        let decoded;
+        try {
+            decoded = unpack(data);
+        }
+        catch {
+            // Malformed response — ignore
+            return;
+        }
+        if (typeof decoded !== "object" || decoded === null)
+            return;
+        const msg = decoded;
+        // Check if it's a pipeline response
+        if (msg.pipeline === true && Array.isArray(msg.responses)) {
+            const pipelineResp = msg;
+            const pending = this.pending.get(pipelineResp.id);
+            if (pending) {
+                clearTimeout(pending.timeout);
+                this.pending.delete(pipelineResp.id);
+                pending.resolve(pipelineResp.responses.map((r) => r.data));
+            }
+            return;
+        }
+        // Single response
+        const response = msg;
+        if (typeof response.id !== "number")
+            return;
+        const pending = this.pending.get(response.id);
+        if (pending) {
+            clearTimeout(pending.timeout);
+            this.pending.delete(response.id);
+            if (response.status >= 400) {
+                const errData = response.data;
+                const errMsg = typeof errData === "object" && errData?.error
+                    ? errData.error
+                    : `Request failed with status ${response.status}`;
+                pending.reject(new Error(errMsg));
+            }
+            else {
+                pending.resolve(response.data);
+            }
+        }
+    }
+    // ─── Pending Request Registration ──────────────────────────────────────
+    registerPending(id, resolve, reject) {
+        const timeout = setTimeout(() => {
+            this.pending.delete(id);
+            reject(new TimeoutError(id, this.timeoutMs));
+        }, this.timeoutMs);
+        this.pending.set(id, { resolve, reject, timeout });
+    }
+    registerPipelinePending(id, resolve, reject) {
+        const timeout = setTimeout(() => {
+            this.pending.delete(id);
+            reject(new TimeoutError(id, this.timeoutMs));
+        }, this.timeoutMs);
+        // Store with a wrapped resolve that handles the pipeline response format
+        this.pending.set(id, {
+            resolve: resolve,
+            reject,
+            timeout,
+        });
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ecodrix/erix-client",
-  "version": "1.0.5",
-  "description": "Type-safe HTTP client for the erix-store in-memory data service. Zero dependencies — uses native fetch.",
+  "version": "1.3.0",
+  "description": "Type-safe HTTP client for ERIX Store — serverless cache, queues, and real-time messaging. Zero dependencies, uses native fetch.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,7 +22,7 @@
     "rate-limit",
     "pubsub",
     "ecodrix",
-    "redis-alternative",
+    "serverless-data",
     "in-memory"
   ],
   "author": "dhanesh125",
@@ -30,9 +30,13 @@
   "engines": {
     "node": ">=18"
   },
-  "dependencies": {},
+  "dependencies": {
+    "msgpackr": "^1.11.0",
+    "ws": "^8.18.0"
+  },
   "devDependencies": {
     "@types/node": "^20.12.7",
+    "@types/ws": "^8.5.10",
     "typescript": "^5.4.5"
   },
   "repository": {