@ecodrix/erix-client 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# @ecodrix/erix-client
+
+Type-safe HTTP client for [erix-store](../README.md) — the ECODrIx in-memory data sidecar.
+
+**Zero extra dependencies.** Uses native `fetch` (Node 18+).
+
+## Install
+
+```bash
+npm install @ecodrix/erix-client
+# or: copy client/src/index.ts directly into your project
+```
+
+## Quick start
+
+```ts
+import { ErixClient } from '@ecodrix/erix-client'
+
+const store = new ErixClient({
+  baseUrl:  process.env.ERIX_STORE_URL!,      // https://erix-store.onrender.com
+  apiKey:   process.env.ERIX_STORE_API_KEY!,  // erix_xxxxxxxxxxxxxxxx
+  tenantId: req.user.orgId,                   // your tenant namespace
+})
+
+// Key / Value
+await store.set('user:42', { name: 'Dhanesh' }, 3600)  // TTL optional
+const user = await store.get<User>('user:42')
+
+// Queue
+await store.queue.push('send-email', { to: 'a@b.com', template: 'welcome' })
+const job = await store.queue.pop<EmailJob>('send-email')
+
+// Rate limiter
+const { allowed } = await store.rateLimit(`api:${orgId}`, 100, 60)
+
+// Hash
+await store.hash.hset('settings:org1', 'theme', 'dark')
+const theme = await store.hash.hget<string>('settings:org1', 'theme')
+
+// Health
+const { status } = await store.ping()
+```
+
+See [PRODUCTION.md](../PRODUCTION.md) for full patterns, multi-tenant setup, and troubleshooting.
+
+## API
+
+| Method | Description |
+|---|---|
+| `store.set(key, value, ttl?)` | Store a JSON value with optional TTL in seconds |
+| `store.get<T>(key)` | Retrieve value or `null` if missing/expired |
+| `store.del(key)` | Delete a key |
+| `store.hash.hset(key, field, value)` | Set a hash field |
+| `store.hash.hget<T>(key, field)` | Get one hash field |
+| `store.hash.hgetall(key)` | Get all fields of a hash |
+| `store.list.lpush(key, value)` | Prepend to a list |
+| `store.list.rpush(key, value)` | Append to a list |
+| `store.list.lpop<T>(key)` | Pop from list front |
+| `store.queue.push(name, data)` | Enqueue a job |
+| `store.queue.pop<T>(name)` | Dequeue a job (`null` if empty) |
+| `store.pubsub.publish(channel, msg)` | Publish an event |
+| `store.rateLimit(key, limit, window)` | Check rate limit |
+| `store.set_.sadd(key, member)` | Add to a set |
+| `store.set_.smembers(key)` | Get all set members |
+| `store.ping()` | Health check |

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @ecodrix/erix-client
+ *
+ * Type-safe HTTP client for the erix-store in-memory data service.
+ * Connects to a running erix-store instance without requiring the
+ * consumer to know any of the underlying HTTP route structure.
+ *
+ * @example
+ * ```ts
+ * import { ErixClient } from '@ecodrix/erix-client'
+ *
+ * const store = new ErixClient({
+ *   baseUrl: 'https://erix-store.onrender.com',
+ *   apiKey: process.env.ERIX_API_KEY!,
+ *   tenantId: 'org_abc123',
+ * })
+ *
+ * await store.set('session:user1', { role: 'admin' }, 3600)
+ * const session = await store.get<{ role: string }>('session:user1')
+ * ```
+ */
+/** Any value that can be serialized to and from JSON */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface ErixClientOptions {
+    /** Full URL of the deployed erix-store instance, e.g. https://erix-store.onrender.com */
+    baseUrl: string;
+    /** Shared secret generated at deploy time — must match ERIX_API_KEY on the server */
+    apiKey: string;
+    /** Tenant namespace — all keys are automatically namespaced under this prefix */
+    tenantId: string;
+    /** Optional request timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+}
+export declare class ErixClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeoutMs;
+    constructor(options: ErixClientOptions);
+    private req;
+    /** Check if the erix-store instance is reachable */
+    ping(): Promise<{
+        status: string;
+        uptime: number;
+    }>;
+    /**
+     * Store any JSON value under a key.
+     * @param ttlSeconds  Optional expiry in seconds. Omit for no expiry.
+     */
+    set(key: string, value: JsonValue, ttlSeconds?: number): Promise<void>;
+    /**
+     * Retrieve a value by key. Returns `null` if the key doesn't exist or has expired.
+     */
+    get<T = JsonValue>(key: string): Promise<T | null>;
+    /** Delete a key */
+    del(key: string): Promise<void>;
+    hash: {
+        /** Set a field in a hash */
+        hset: (key: string, field: string, value: JsonValue) => Promise<void>;
+        /** Get a single field from a hash */
+        hget: <T = JsonValue>(key: string, field: string) => Promise<T | null>;
+        /** Get all fields of a hash */
+        hgetall: (key: string) => Promise<Record<string, string>>;
+    };
+    list: {
+        /** Prepend a value to a list */
+        lpush: (key: string, value: JsonValue) => Promise<void>;
+        /** Append a value to a list */
+        rpush: (key: string, value: JsonValue) => Promise<void>;
+        /** Pop from the left (FIFO front) */
+        lpop: <T = JsonValue>(key: string) => Promise<T | null>;
+    };
+    queue: {
+        /** Enqueue a job payload into a named queue */
+        push: (name: string, data: JsonValue) => Promise<void>;
+        /** Dequeue the oldest job from a named queue. Returns `null` if empty. */
+        pop: <T = JsonValue>(name: string) => Promise<T | null>;
+    };
+    pubsub: {
+        /** Publish a message to a channel */
+        publish: (channel: string, message: JsonValue) => Promise<void>;
+    };
+    /**
+     * Check if an operation is within rate limits.
+     * @param key     Identifier (e.g. `"api:org_123"`)
+     * @param limit   Maximum allowed operations in the window
+     * @param window  Window duration in seconds
+     */
+    rateLimit(key: string, limit: number, window: number): Promise<RateLimitResult>;
+    set_: {
+        /** Add a member to a set */
+        sadd: (key: string, value: string) => Promise<{
+            added: number;
+        }>;
+        /** Get all members of a set */
+        smembers: (key: string) => Promise<string[]>;
+    };
+}

package/dist/index.js

@@ -0,0 +1,196 @@
+/**
+ * @ecodrix/erix-client
+ *
+ * Type-safe HTTP client for the erix-store in-memory data service.
+ * Connects to a running erix-store instance without requiring the
+ * consumer to know any of the underlying HTTP route structure.
+ *
+ * @example
+ * ```ts
+ * import { ErixClient } from '@ecodrix/erix-client'
+ *
+ * const store = new ErixClient({
+ *   baseUrl: 'https://erix-store.onrender.com',
+ *   apiKey: process.env.ERIX_API_KEY!,
+ *   tenantId: 'org_abc123',
+ * })
+ *
+ * await store.set('session:user1', { role: 'admin' }, 3600)
+ * const session = await store.get<{ role: string }>('session:user1')
+ * ```
+ */
+// ─── Client ─────────────────────────────────────────────────────────────────
+export class ErixClient {
+    constructor(options) {
+        // ─── Hash ─────────────────────────────────────────────────────────────
+        this.hash = {
+            /** Set a field in a hash */
+            hset: async (key, field, value) => {
+                await this.req("POST", "/hash/hset", {
+                    key,
+                    field,
+                    value: JSON.stringify(value),
+                });
+            },
+            /** Get a single field from a hash */
+            hget: async (key, field) => {
+                const data = await this.req("GET", "/hash/hget", undefined, { key, field });
+                if (!data.value)
+                    return null;
+                try {
+                    return JSON.parse(data.value);
+                }
+                catch {
+                    return data.value;
+                }
+            },
+            /** Get all fields of a hash */
+            hgetall: async (key) => {
+                const data = await this.req("GET", "/hash/hgetall", undefined, { key });
+                return data.data;
+            },
+        };
+        // ─── List ─────────────────────────────────────────────────────────────
+        this.list = {
+            /** Prepend a value to a list */
+            lpush: async (key, value) => {
+                await this.req("POST", "/list/lpush", {
+                    key,
+                    value: JSON.stringify(value),
+                });
+            },
+            /** Append a value to a list */
+            rpush: async (key, value) => {
+                await this.req("POST", "/list/rpush", {
+                    key,
+                    value: JSON.stringify(value),
+                });
+            },
+            /** Pop from the left (FIFO front) */
+            lpop: async (key) => {
+                const data = await this.req("GET", "/list/lpop", undefined, { key });
+                if (!data.value)
+                    return null;
+                try {
+                    return JSON.parse(data.value);
+                }
+                catch {
+                    return data.value;
+                }
+            },
+        };
+        // ─── Queue (FIFO job queue, built on List) ────────────────────────────
+        this.queue = {
+            /** Enqueue a job payload into a named queue */
+            push: async (name, data) => {
+                await this.list.rpush(`q:${name}`, data);
+            },
+            /** Dequeue the oldest job from a named queue. Returns `null` if empty. */
+            pop: async (name) => {
+                return this.list.lpop(`q:${name}`);
+            },
+        };
+        // ─── PubSub ───────────────────────────────────────────────────────────
+        this.pubsub = {
+            /** Publish a message to a channel */
+            publish: async (channel, message) => {
+                await this.req("POST", "/pubsub/publish", { channel, message });
+            },
+        };
+        // ─── Set ──────────────────────────────────────────────────────────────
+        this.set_ = {
+            /** Add a member to a set */
+            sadd: async (key, value) => {
+                return this.req("POST", "/set/sadd", { key, value });
+            },
+            /** Get all members of a set */
+            smembers: async (key) => {
+                const data = await this.req("GET", "/set/smembers", undefined, { key });
+                return data.members;
+            },
+        };
+        this.baseUrl = options.baseUrl.replace(/\/$/, ""); // strip trailing slash
+        this.timeoutMs = options.timeoutMs ?? 5000;
+        this.headers = {
+            "x-erix-key": options.apiKey,
+            "x-tenant-id": options.tenantId,
+            "Content-Type": "application/json",
+        };
+    }
+    // ── Internal fetch helper ─────────────────────────────────────────────
+    async req(method, path, body, params) {
+        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);
+        }
+    }
+    // ─── Health ───────────────────────────────────────────────────────────
+    /** Check if the erix-store instance is reachable */
+    async ping() {
+        return this.req("GET", "/health");
+    }
+    // ─── Core: Key / Value ────────────────────────────────────────────────
+    /**
+     * Store any JSON value under a key.
+     * @param ttlSeconds  Optional expiry in seconds. Omit for no expiry.
+     */
+    async set(key, value, ttlSeconds) {
+        await this.req("POST", "/core/set", {
+            key,
+            value: JSON.stringify(value),
+            ttl: ttlSeconds,
+        });
+    }
+    /**
+     * Retrieve a value by key. Returns `null` if the key doesn't exist or has expired.
+     */
+    async get(key) {
+        const data = await this.req("GET", "/core/get", undefined, { key });
+        if (!data.value)
+            return null;
+        try {
+            return JSON.parse(data.value);
+        }
+        catch {
+            return data.value;
+        }
+    }
+    /** Delete a key */
+    async del(key) {
+        await this.req("DELETE", "/core/del", { key });
+    }
+    // ─── Rate Limiter ─────────────────────────────────────────────────────
+    /**
+     * Check if an operation is within rate limits.
+     * @param key     Identifier (e.g. `"api:org_123"`)
+     * @param limit   Maximum allowed operations in the window
+     * @param window  Window duration in seconds
+     */
+    async rateLimit(key, limit, window) {
+        return this.req("POST", "/ratelimit", {
+            key,
+            limit,
+            window,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ecodrix/erix-client",
+  "version": "1.0.0",
+  "description": "Type-safe HTTP client for the erix-store in-memory data service. Zero dependencies — uses native fetch.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "erix-store",
+    "cache",
+    "queue",
+    "rate-limit",
+    "pubsub",
+    "ecodrix",
+    "redis-alternative",
+    "in-memory"
+  ],
+  "author": "dhanesh125",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "typescript": "^5.4.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dhanesh125/erix-store"
+  }
+}