@ecodrix/erix-client 1.0.5 → 1.3.0

package/dist/index.d.ts

@@ -19,6 +19,10 @@
  * const session = await store.get<{ role: string }>('session:user1')
  * ```
  */
+import type { TransportLayer, TransportMode } from "./transports/TransportLayer.js";
+export { HttpTransport } from "./transports/HttpTransport.js";
+export { WebSocketTransport } from "./transports/WebSocketTransport.js";
+export type { TransportLayer, TransportMode };
 /** Any value that can be serialized to and from JSON */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -32,6 +36,13 @@ export interface ErixClientOptions {
     tenantId: string;
     /** Optional request timeout in milliseconds (default: 5000) */
     timeoutMs?: number;
+    /**
+     * Transport mode:
+     * - "http": Use HTTP only (original behavior)
+     * - "ws": Use WebSocket only
+     * - "auto": Attempt WebSocket first, fall back to HTTP if unavailable (default)
+     */
+    transport?: "http" | "ws" | "auto";
 }
 export interface RateLimitResult {
     allowed: boolean;
@@ -91,13 +102,213 @@ export declare class ErixClient {
     private readonly baseUrl;
     private readonly headers;
     private readonly timeoutMs;
+    private readonly transportMode;
+    private transport;
     constructor(options: ErixClientOptions);
+    /**
+     * Create the appropriate transport based on the configured mode.
+     * In "auto" mode, starts with WebSocket and falls back to HTTP on failure.
+     */
+    private createTransport;
     private req;
+    /**
+     * Execute multiple operations in a single round-trip (pipeline).
+     * Over WebSocket, this sends all requests in one frame.
+     * Over HTTP, requests are executed concurrently via Promise.all.
+     */
+    pipeline(requests: Array<{
+        method: string;
+        path: string;
+        body?: unknown;
+        params?: Record<string, string>;
+    }>): Promise<unknown[]>;
+    /**
+     * Begin a new transaction.
+     *
+     * Returns a builder you can queue commands onto with `.cmd(name, ...args)`,
+     * then send with `.exec()`. Every queued command runs atomically inside
+     * a single event-loop tick on the server — no other client request can
+     * interleave between them.
+     *
+     * Per-command failures are captured into the result array but do not
+     * abort the batch (matching Redis MULTI/EXEC).
+     *
+     * @example
+     * ```ts
+     * const results = await client
+     *   .multi()
+     *   .cmd("SET", "k", "v")
+     *   .cmd("EXPIRE", "k", 60)
+     *   .cmd("GET", "k")
+     *   .exec();
+     * // → [{ ok: true, value: "OK" }, { ok: true, value: 1 }, { ok: true, value: "v" }]
+     * ```
+     */
+    multi(): Transaction;
+    /** Alias for {@link multi}. */
+    tx(): Transaction;
+    /** @internal — called by Transaction.exec(). Keeps tx wire format private. */
+    _execTransaction(commands: TransactionCommand[]): Promise<TransactionResult[]>;
+    /**
+     * Run a single Redis-style command synchronously.
+     *
+     * Lightweight escape hatch for verbs we have not surfaced as named
+     * methods. Forwards the call through `/tx/exec` as a one-element
+     * transaction and unwraps the per-command result.
+     *
+     * Throws on per-command errors (`WRONGTYPE`, unknown verb, validation)
+     * so it composes naturally with `try`/`catch`. For multi-command
+     * batches use {@link multi} instead — that surface keeps each command's
+     * error isolated.
+     *
+     * @example
+     * ```ts
+     * const newLen = await client.cmd<number>("APPEND", "log", "entry");
+     * const all = await client.cmd<Record<string,string>>("HGETALL", "user");
+     * ```
+     */
+    cmd<T = unknown>(name: string, ...args: unknown[]): Promise<T>;
+    /**
+     * Close the transport and release resources.
+     */
+    close(): void;
     /** Check if the erix-store instance is reachable */
     ping(): Promise<{
         status: string;
         uptime: number;
     }>;
+    server: {
+        /** Round-trip ping. Resolves to `true` on success. */
+        ping: () => Promise<boolean>;
+        /**
+         * Server-wide info — version, memory, total keys, and a per-tenant
+         * key breakdown for the calling tenant.
+         */
+        info: () => Promise<{
+            server: {
+                version: string;
+                node: string;
+                uptime_seconds: number;
+            };
+            memory: {
+                rss: number;
+                heap_used: number;
+                heap_total: number;
+                external: number;
+                /** Approximate accounted bytes (not RSS). See server INFO docs. */
+                used_memory: number;
+                /** Configured cap; 0 = disabled. */
+                maxmemory: number;
+                maxmemory_policy: "noeviction" | "allkeys-lru" | "volatile-lru";
+                evicted_keys: number;
+            };
+            keyspace: {
+                total_keys: number;
+                tenant: {
+                    id: string;
+                    keys: {
+                        string: number;
+                        hash: number;
+                        list: number;
+                        set: number;
+                        zset: number;
+                    };
+                };
+            };
+        }>;
+        /** Number of keys in the calling tenant's namespace. */
+        dbsize: () => Promise<number>;
+        /** Whether `key` exists in the calling tenant's namespace. */
+        exists: (key: string) => Promise<boolean>;
+        /** The data type of `key`, or `null` if it does not exist. */
+        type: (key: string) => Promise<"string" | "hash" | "list" | "set" | "zset" | null>;
+        /**
+         * List keys matching a glob pattern. Tenant-scoped — never returns
+         * keys from other tenants. Default pattern `*` returns every key.
+         *
+         * Supported glob syntax: `*`, `?`, `[abc]`, `[^abc]`, `[a-z]`, `\\<char>`.
+         */
+        keys: (pattern?: string) => Promise<string[]>;
+        /**
+         * Wipe every key in the calling tenant's namespace.
+         * Returns the number of keys deleted. There is intentionally no
+         * `flushall` — tenants cannot affect each other.
+         */
+        flushdb: () => Promise<number>;
+        /**
+         * Set a TTL (in seconds) on an existing key.
+         * @returns true if the TTL was applied, false if the key didn't exist.
+         */
+        expire: (key: string, ttlSeconds: number) => Promise<boolean>;
+        /**
+         * Remaining TTL in seconds. Redis convention:
+         *   -2 → key does not exist
+         *   -1 → key exists but has no TTL
+         *   >0 → seconds remaining
+         */
+        ttl: (key: string) => Promise<number>;
+        /**
+         * Remove the TTL from a key. Returns true if a TTL was removed,
+         * false if the key did not exist or had no TTL.
+         */
+        persist: (key: string) => Promise<boolean>;
+        /**
+         * Read the slow-command log for the calling tenant. Newest entries
+         * first. Pass `count` to cap the result.
+         *
+         * Each entry's `args` are truncated server-side (max 32 args, 128
+         * chars each) so an MSET/HSET with a giant payload doesn't bloat
+         * the log buffer.
+         */
+        slowlogGet: (count?: number) => Promise<Array<{
+            id: number;
+            timestamp: number;
+            durationUs: number;
+            command: string;
+            args: string[];
+            source: "single" | "transaction";
+        }>>;
+        /** Number of slowlog entries currently stored for this tenant. */
+        slowlogLen: () => Promise<number>;
+        /** Drop this tenant's slowlog entries. Returns the number dropped. */
+        slowlogReset: () => Promise<number>;
+        /**
+         * Read runtime tunables. Pass a glob pattern to filter; default `*`
+         * returns every registered parameter.
+         *
+         * @example
+         * const all = await client.server.configGet();
+         * const memory = await client.server.configGet("max*");
+         */
+        configGet: (pattern?: string) => Promise<Array<{
+            name: string;
+            value: string;
+        }>>;
+        /**
+         * Update a runtime tunable.
+         *
+         * Server-side, this command is only accepted from the calling tenant
+         * if it matches the server's `ERIX_ADMIN_TENANT_ID`. Other tenants
+         * receive an error result. Resolves to `true` on success and throws
+         * on failure (matching `client.cmd` semantics).
+         */
+        configSet: (name: string, value: string | number) => Promise<true>;
+        /**
+         * Trigger a non-blocking snapshot save (admin tenant only).
+         * Resolves immediately with the server's reply once the work is
+         * dispatched — actual persistence happens in the background.
+         */
+        bgsave: () => Promise<string>;
+        /**
+         * Rewrite the AOF in place (admin tenant only).
+         *
+         * The server walks the live in-memory state and emits a compact
+         * sequence of writes equivalent to it, then atomically replaces
+         * the on-disk log. The verb is admin-gated because the rewrite
+         * cost is bounded by the number of live keys.
+         */
+        bgrewriteaof: () => Promise<string>;
+    };
     /**
      * Store any JSON value under a key.
      * @param ttlSeconds  Optional expiry in seconds. Omit for no expiry.
@@ -109,6 +320,38 @@ export declare class ErixClient {
     get<T = JsonValue>(key: string): Promise<T | null>;
     /** Delete a key */
     del(key: string): Promise<void>;
+    /**
+     * Atomic increment. Creates the counter at 1 when missing.
+     * Throws on non-integer values or overflow.
+     */
+    incr(key: string): Promise<number>;
+    /** Atomic decrement. Creates the counter at -1 when missing. */
+    decr(key: string): Promise<number>;
+    /** Atomic increment by `delta`. */
+    incrBy(key: string, delta: number): Promise<number>;
+    /** Atomic decrement by `delta`. */
+    decrBy(key: string, delta: number): Promise<number>;
+    /** Append `value` to the existing string at `key`. Returns the new length. */
+    append(key: string, value: string): Promise<number>;
+    /** Length of the string at `key`. 0 for missing keys. */
+    strlen(key: string): Promise<number>;
+    /**
+     * Set multiple keys atomically. Either all writes succeed or none do
+     * (e.g. on WRONGTYPE for any of the target keys). Clears any prior TTL.
+     */
+    mset(entries: Record<string, JsonValue>): Promise<void>;
+    /** Get multiple keys at once. Missing/non-string keys come back as `null`. */
+    mget<T = JsonValue>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * Atomic compare-and-set: returns the previous value (or `null`) and
+     * stores `value`. Clears any prior TTL.
+     */
+    getSet<T = JsonValue>(key: string, value: JsonValue): Promise<T | null>;
+    /**
+     * Set only if the key does not already exist. Returns true on success,
+     * false when the key was already taken (any type — no WRONGTYPE).
+     */
+    setNx(key: string, value: JsonValue): Promise<boolean>;
     hash: {
         /** Set a field in a hash */
         hset: (key: string, field: string, value: JsonValue) => Promise<void>;
@@ -116,19 +359,95 @@ export declare class ErixClient {
         hget: <T = JsonValue>(key: string, field: string) => Promise<T | null>;
         /** Get all fields of a hash */
         hgetall: (key: string) => Promise<Record<string, string>>;
+        /** Set multiple fields atomically (HMSET). */
+        hmset: (key: string, fields: Record<string, JsonValue>) => Promise<void>;
+        /** Get multiple fields at once. Missing fields return `null`. */
+        hmget: <T = JsonValue>(key: string, fields: string[]) => Promise<Array<T | null>>;
+        /** Whether `field` exists in the hash. */
+        hexists: (key: string, field: string) => Promise<boolean>;
+        /** All field names in the hash (no order guarantee). */
+        hkeys: (key: string) => Promise<string[]>;
+        /** All field values in the hash (no order guarantee). */
+        hvals: (key: string) => Promise<string[]>;
+        /** Number of fields in the hash. */
+        hlen: (key: string) => Promise<number>;
+        /** Delete one or more fields. Returns the count actually removed. */
+        hdel: (key: string, ...fields: string[]) => Promise<number>;
+        /**
+         * Atomic increment of a hash field by `delta`. Creates the field
+         * at `delta` when missing. Throws on non-integer values.
+         */
+        hincrBy: (key: string, field: string, delta: number) => Promise<number>;
     };
     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>;
+        /** Prepend a value to a list. Returns the new list length. */
+        lpush: (key: string, value: JsonValue) => Promise<number>;
+        /** Append a value to a list. Returns the new list length. */
+        rpush: (key: string, value: JsonValue) => Promise<number>;
         /** Pop from the left (FIFO front) */
         lpop: <T = JsonValue>(key: string) => Promise<T | null>;
+        /** Pop from the right (LIFO back) */
+        rpop: <T = JsonValue>(key: string) => Promise<T | null>;
+        /** List length. Returns 0 for missing keys. */
+        llen: (key: string) => Promise<number>;
+        /**
+         * Element at `index` (negative indices count from the tail).
+         * Returns `null` if out of bounds.
+         */
+        lindex: <T = JsonValue>(key: string, index: number) => Promise<T | null>;
+        /**
+         * Inclusive range from `start` to `stop`, supporting negative indices
+         * (e.g. -1 = last element). Values stored as JSON are parsed; raw strings
+         * pass through unchanged.
+         */
+        lrange: <T = JsonValue>(key: string, start: number, stop: number) => Promise<T[]>;
+        /**
+         * Remove up to `count` occurrences of `value`.
+         *   count > 0 → remove from head
+         *   count < 0 → remove from tail
+         *   count = 0 → remove all
+         * Returns the number of elements removed.
+         */
+        lrem: (key: string, count: number, value: JsonValue) => Promise<number>;
+        /**
+         * Trim the list to the inclusive range [start, stop].
+         * Negative indices count from the tail. Drops the key if the range
+         * leaves the list empty.
+         */
+        ltrim: (key: string, start: number, stop: number) => Promise<void>;
     };
     queue: {
-        /** Enqueue a job payload into a named queue (simple list-based) */
+        /**
+         * Enqueue a value with optional priority. Higher priority dequeues first;
+         * ties resolve FIFO.
+         *
+         * The value is JSON-serialized server-side; pass any JSON-compatible
+         * shape and `dequeue` returns the parsed result.
+         *
+         * @returns the new queue length
+         */
+        enqueue: (name: string, value: JsonValue, priority?: number) => Promise<number>;
+        /**
+         * Pop the highest-priority entry. Returns `null` when the queue is empty.
+         */
+        dequeue: <T = JsonValue>(name: string) => Promise<T | null>;
+        /** Inspect the next entry without removing it. */
+        peek: <T = JsonValue>(name: string) => Promise<T | null>;
+        /** Number of entries in the queue. 0 for empty/missing queues. */
+        len: (name: string) => Promise<number>;
+        /** Drop every entry. Returns the number cleared. */
+        clear: (name: string) => Promise<number>;
+        /**
+         * Legacy push — kept for source compatibility with SDK 1.2.x. Forwards
+         * to {@link enqueue} with priority 0. Prefer `enqueue` in new code.
+         * @deprecated Use `enqueue` instead.
+         */
         push: (name: string, data: JsonValue) => Promise<void>;
-        /** Dequeue the oldest job from a named queue. Returns `null` if empty. */
+        /**
+         * Legacy pop — kept for source compatibility with SDK 1.2.x. Forwards
+         * to {@link dequeue}. Prefer `dequeue` in new code.
+         * @deprecated Use `dequeue` instead.
+         */
         pop: <T = JsonValue>(name: string) => Promise<T | null>;
     };
     /** Advanced Queue (v2) — supports priority, delay, retries, heartbeat, and SSE push */
@@ -171,8 +490,12 @@ export declare class ErixClient {
         };
     };
     pubsub: {
-        /** Publish a message to a channel */
-        publish: (channel: string, message: JsonValue) => Promise<void>;
+        /**
+         * Publish a message to a channel.
+         * @returns the number of subscribers that received the message
+         *          (exact + pattern combined).
+         */
+        publish: (channel: string, message: JsonValue) => Promise<number>;
         /**
          * Subscribe to a pub/sub channel via Server-Sent Events.
          * Returns a controller with a `.close()` method.
@@ -184,6 +507,31 @@ export declare class ErixClient {
         subscribe: (channel: string, onMessage: (message: JsonValue) => void, onError?: (err: Error) => void) => {
             close: () => void;
         };
+        /**
+         * Pattern subscribe (PSUBSCRIBE). The handler is invoked once per
+         * message, with the matched channel name (tenant prefix stripped).
+         *
+         * Supports the same glob syntax as `client.server.keys`:
+         * `*`, `?`, `[abc]`, `[^abc]`, `[a-z]`, `\\<char>`.
+         *
+         * @example
+         * const sub = client.pubsub.psubscribe("alerts:*", (msg, channel) => {
+         *   console.log(`[${channel}]`, msg);
+         * });
+         * sub.close();
+         */
+        psubscribe: (pattern: string, onMessage: (message: JsonValue, channel: string) => void, onError?: (err: Error) => void) => {
+            close: () => void;
+        };
+        /**
+         * List exact-subscriber channels in this tenant's namespace,
+         * optionally filtered by a glob pattern (default `*`).
+         */
+        channels: (pattern?: string) => Promise<string[]>;
+        /** Per-channel exact-subscriber counts (0 for channels with none). */
+        numsub: (channels: string[]) => Promise<Record<string, number>>;
+        /** Number of distinct active patterns (server-wide; matches Redis). */
+        numpat: () => Promise<number>;
     };
     /**
      * Check if an operation is within rate limits.
@@ -199,6 +547,40 @@ export declare class ErixClient {
         }>;
         /** Get all members of a set */
         smembers: (key: string) => Promise<string[]>;
+        /** Remove one or more members. Returns the count actually removed. */
+        srem: (key: string, ...members: string[]) => Promise<number>;
+        /** Whether `member` is in the set. */
+        sismember: (key: string, member: string) => Promise<boolean>;
+        /** Number of members in the set. */
+        scard: (key: string) => Promise<number>;
+        /** Intersection across the supplied sets. */
+        sinter: (...keys: string[]) => Promise<string[]>;
+        /** Union across the supplied sets. */
+        sunion: (...keys: string[]) => Promise<string[]>;
+        /** Members in the first set that are not in any of the others. */
+        sdiff: (...keys: string[]) => Promise<string[]>;
+    };
+    zset: {
+        /** Add or update a member's score. Returns the count of newly added members. */
+        zadd: (key: string, score: number, member: string) => Promise<number>;
+        /** Inclusive range by 0-based rank (lowest score first). Negative indices supported. */
+        zrange: (key: string, start: number, stop: number) => Promise<string[]>;
+        /** Same as zrange but in descending score order. */
+        zrevrange: (key: string, start: number, stop: number) => Promise<string[]>;
+        /** Members whose score is in [min, max], ascending. */
+        zrangeByScore: (key: string, min: number, max: number) => Promise<string[]>;
+        /** Score for a member; `null` if missing. */
+        zscore: (key: string, member: string) => Promise<number | null>;
+        /** 0-based rank of `member`; `null` if missing. */
+        zrank: (key: string, member: string) => Promise<number | null>;
+        /** Number of members in the sorted set. */
+        zcard: (key: string) => Promise<number>;
+        /** Number of members whose score is in [min, max]. */
+        zcount: (key: string, min: number, max: number) => Promise<number>;
+        /** Increment a member's score by `delta`. Returns the new score. */
+        zincrBy: (key: string, delta: number, member: string) => Promise<number>;
+        /** Remove one or more members. Returns the count actually removed. */
+        zrem: (key: string, ...members: string[]) => Promise<number>;
     };
     cache: {
         /** Get a cached value */
@@ -297,3 +679,51 @@ export declare class ErixClient {
      */
     private openEventStream;
 }
+/** Wire shape for a single command inside a transaction. */
+export interface TransactionCommand {
+    /** Verb name, case-insensitive. */
+    name: string;
+    /** Positional arguments, mostly mirroring Redis's argument order. */
+    args: unknown[];
+}
+/** Result of a single command — `ok: true` carries the return value. */
+export type TransactionResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/**
+ * Builder returned by {@link ErixClient.multi}.
+ *
+ * Chain `.cmd(name, ...args)` for each command, then `.exec()` to run
+ * them atomically server-side, or `.discard()` to drop the batch
+ * locally without sending a request.
+ */
+export declare class Transaction {
+    private readonly client;
+    private commands;
+    private finalized;
+    constructor(client: ErixClient);
+    /** Number of commands queued. */
+    get size(): number;
+    /**
+     * Queue a command. Returns `this` for chaining.
+     *
+     * The verb is validated server-side; unknown verbs come back as a
+     * per-command error in the result array, not a thrown exception.
+     */
+    cmd(name: string, ...args: unknown[]): this;
+    /** Drop the queued commands locally. No server request is issued. */
+    discard(): void;
+    /**
+     * Send the queued commands to the server and run them atomically.
+     *
+     * Per-command errors are captured into the result array; the call as
+     * a whole still resolves successfully unless the network or auth
+     * layer fails.
+     */
+    exec(): Promise<TransactionResult[]>;
+}