@ecodrix/erix-client 1.0.5 → 1.3.0

package/dist/index.js

@@ -19,9 +19,152 @@
  * const session = await store.get<{ role: string }>('session:user1')
  * ```
  */
+import { HttpTransport } from "./transports/HttpTransport.js";
+import { WebSocketTransport } from "./transports/WebSocketTransport.js";
+export { HttpTransport } from "./transports/HttpTransport.js";
+export { WebSocketTransport } from "./transports/WebSocketTransport.js";
 // ─── Client ─────────────────────────────────────────────────────────────────
 export class ErixClient {
     constructor(options) {
+        // ─── Server Commands (Redis-style) ────────────────────────────────────
+        this.server = {
+            /** Round-trip ping. Resolves to `true` on success. */
+            ping: async () => {
+                const res = await this.req("GET", "/server/ping");
+                return res.pong === true;
+            },
+            /**
+             * Server-wide info — version, memory, total keys, and a per-tenant
+             * key breakdown for the calling tenant.
+             */
+            info: async () => {
+                return this.req("GET", "/server/info");
+            },
+            /** Number of keys in the calling tenant's namespace. */
+            dbsize: async () => {
+                const res = await this.req("GET", "/server/dbsize");
+                return res.size;
+            },
+            /** Whether `key` exists in the calling tenant's namespace. */
+            exists: async (key) => {
+                const res = await this.req("GET", "/server/exists", undefined, { key });
+                return res.exists;
+            },
+            /** The data type of `key`, or `null` if it does not exist. */
+            type: async (key) => {
+                const res = await this.req("GET", "/server/type", undefined, { key });
+                return res.type;
+            },
+            /**
+             * 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: async (pattern = "*") => {
+                const res = await this.req("GET", "/server/keys", undefined, { pattern });
+                return res.keys;
+            },
+            /**
+             * 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: async () => {
+                const res = await this.req("POST", "/server/flushdb");
+                return res.flushed;
+            },
+            /**
+             * Set a TTL (in seconds) on an existing key.
+             * @returns true if the TTL was applied, false if the key didn't exist.
+             */
+            expire: async (key, ttlSeconds) => {
+                const res = await this.req("POST", "/server/expire", {
+                    key,
+                    ttl: ttlSeconds,
+                });
+                return res.applied;
+            },
+            /**
+             * Remaining TTL in seconds. Redis convention:
+             *   -2 → key does not exist
+             *   -1 → key exists but has no TTL
+             *   >0 → seconds remaining
+             */
+            ttl: async (key) => {
+                const res = await this.req("GET", "/server/ttl", undefined, { key });
+                return res.ttl;
+            },
+            /**
+             * 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: async (key) => {
+                const res = await this.req("POST", "/server/persist", { key });
+                return res.removed;
+            },
+            /**
+             * 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: async (count = 128) => {
+                return this.cmd("SLOWLOG", "GET", count);
+            },
+            /** Number of slowlog entries currently stored for this tenant. */
+            slowlogLen: async () => {
+                return this.cmd("SLOWLOG", "LEN");
+            },
+            /** Drop this tenant's slowlog entries. Returns the number dropped. */
+            slowlogReset: async () => {
+                return this.cmd("SLOWLOG", "RESET");
+            },
+            /**
+             * 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: async (pattern = "*") => {
+                return this.cmd("CONFIG", "GET", pattern);
+            },
+            /**
+             * 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: async (name, value) => {
+                await this.cmd("CONFIG", "SET", name, String(value));
+                return 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: async () => {
+                return this.cmd("BGSAVE");
+            },
+            /**
+             * 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: async () => {
+                return this.cmd("BGREWRITEAOF");
+            },
+        };
         // ─── Hash ─────────────────────────────────────────────────────────────
         this.hash = {
             /** Set a field in a hash */
@@ -49,22 +192,74 @@ export class ErixClient {
                 const data = await this.req("GET", "/hash/hgetall", undefined, { key });
                 return data.data;
             },
+            /** Set multiple fields atomically (HMSET). */
+            hmset: async (key, fields) => {
+                const args = [key];
+                for (const [f, v] of Object.entries(fields)) {
+                    args.push(f, JSON.stringify(v));
+                }
+                await this.cmd("HMSET", ...args);
+            },
+            /** Get multiple fields at once. Missing fields return `null`. */
+            hmget: async (key, fields) => {
+                const raw = await this.cmd("HMGET", key, ...fields);
+                return raw.map((v) => {
+                    if (v === null)
+                        return null;
+                    try {
+                        return JSON.parse(v);
+                    }
+                    catch {
+                        return v;
+                    }
+                });
+            },
+            /** Whether `field` exists in the hash. */
+            hexists: async (key, field) => {
+                const r = await this.cmd("HEXISTS", key, field);
+                return r === 1;
+            },
+            /** All field names in the hash (no order guarantee). */
+            hkeys: async (key) => {
+                return this.cmd("HKEYS", key);
+            },
+            /** All field values in the hash (no order guarantee). */
+            hvals: async (key) => {
+                return this.cmd("HVALS", key);
+            },
+            /** Number of fields in the hash. */
+            hlen: async (key) => {
+                return this.cmd("HLEN", key);
+            },
+            /** Delete one or more fields. Returns the count actually removed. */
+            hdel: async (key, ...fields) => {
+                return this.cmd("HDEL", key, ...fields);
+            },
+            /**
+             * Atomic increment of a hash field by `delta`. Creates the field
+             * at `delta` when missing. Throws on non-integer values.
+             */
+            hincrBy: async (key, field, delta) => {
+                return this.cmd("HINCRBY", key, field, delta);
+            },
         };
         // ─── List ─────────────────────────────────────────────────────────────
         this.list = {
-            /** Prepend a value to a list */
+            /** Prepend a value to a list. Returns the new list length. */
             lpush: async (key, value) => {
-                await this.req("POST", "/list/lpush", {
+                const res = await this.req("POST", "/list/lpush", {
                     key,
                     value: JSON.stringify(value),
                 });
+                return res.length;
             },
-            /** Append a value to a list */
+            /** Append a value to a list. Returns the new list length. */
             rpush: async (key, value) => {
-                await this.req("POST", "/list/rpush", {
+                const res = await this.req("POST", "/list/rpush", {
                     key,
                     value: JSON.stringify(value),
                 });
+                return res.length;
             },
             /** Pop from the left (FIFO front) */
             lpop: async (key) => {
@@ -78,16 +273,148 @@ export class ErixClient {
                     return data.value;
                 }
             },
+            /** Pop from the right (LIFO back) */
+            rpop: async (key) => {
+                const data = await this.req("GET", "/list/rpop", undefined, { key });
+                if (!data.value)
+                    return null;
+                try {
+                    return JSON.parse(data.value);
+                }
+                catch {
+                    return data.value;
+                }
+            },
+            /** List length. Returns 0 for missing keys. */
+            llen: async (key) => {
+                const data = await this.req("GET", "/list/llen", undefined, { key });
+                return data.length;
+            },
+            /**
+             * Element at `index` (negative indices count from the tail).
+             * Returns `null` if out of bounds.
+             */
+            lindex: async (key, index) => {
+                const data = await this.req("GET", "/list/lindex", undefined, { key, index: String(index) });
+                if (!data.value)
+                    return null;
+                try {
+                    return JSON.parse(data.value);
+                }
+                catch {
+                    return data.value;
+                }
+            },
+            /**
+             * 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: async (key, start, stop) => {
+                const data = await this.req("GET", "/list/lrange", undefined, { key, start: String(start), stop: String(stop) });
+                return data.values.map((v) => {
+                    try {
+                        return JSON.parse(v);
+                    }
+                    catch {
+                        return v;
+                    }
+                });
+            },
+            /**
+             * 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: async (key, count, value) => {
+                const data = await this.req("POST", "/list/lrem", {
+                    key,
+                    count,
+                    value: JSON.stringify(value),
+                });
+                return data.removed;
+            },
+            /**
+             * 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: async (key, start, stop) => {
+                await this.req("POST", "/list/ltrim", { key, start, stop });
+            },
         };
         // ─── Queue (FIFO job queue, built on List) ────────────────────────────
         this.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: async (name, value, priority = 0) => {
+                const res = await this.req("POST", "/q/enqueue", { name, value: JSON.stringify(value), priority });
+                return res.length;
+            },
+            /**
+             * Pop the highest-priority entry. Returns `null` when the queue is empty.
+             */
+            dequeue: async (name) => {
+                const res = await this.req("POST", "/q/dequeue", { name });
+                if (res.value === null)
+                    return null;
+                try {
+                    return JSON.parse(res.value);
+                }
+                catch {
+                    return res.value;
+                }
+            },
+            /** Inspect the next entry without removing it. */
+            peek: async (name) => {
+                const res = await this.req("GET", "/q/peek", undefined, { name });
+                if (res.value === null)
+                    return null;
+                try {
+                    return JSON.parse(res.value);
+                }
+                catch {
+                    return res.value;
+                }
+            },
+            /** Number of entries in the queue. 0 for empty/missing queues. */
+            len: async (name) => {
+                const res = await this.req("GET", "/q/len", undefined, { name });
+                return res.length;
+            },
+            /** Drop every entry. Returns the number cleared. */
+            clear: async (name) => {
+                const res = await this.req("POST", "/q/clear", { name });
+                return res.cleared;
+            },
+            /**
+             * 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: async (name, data) => {
-                await this.list.rpush(`q:${name}`, data);
+                await this.req("POST", "/q/enqueue", {
+                    name,
+                    value: JSON.stringify(data),
+                    priority: 0,
+                });
             },
-            /** 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: async (name) => {
-                return this.list.lpop(`q:${name}`);
+                return this.queue.dequeue(name);
             },
         };
         /** Advanced Queue (v2) — supports priority, delay, retries, heartbeat, and SSE push */
@@ -160,9 +487,14 @@ export class ErixClient {
         };
         // ─── PubSub ───────────────────────────────────────────────────────────
         this.pubsub = {
-            /** Publish a message to a channel */
+            /**
+             * Publish a message to a channel.
+             * @returns the number of subscribers that received the message
+             *          (exact + pattern combined).
+             */
             publish: async (channel, message) => {
-                await this.req("POST", "/pubsub/publish", { channel, message });
+                const res = await this.req("POST", "/pubsub/publish", { channel, message });
+                return res.delivered;
             },
             /**
              * Subscribe to a pub/sub channel via Server-Sent Events.
@@ -175,6 +507,43 @@ export class ErixClient {
             subscribe: (channel, onMessage, onError) => {
                 return this.openEventStream(`/pubsub/${encodeURIComponent(channel)}/stream`, (_event, data) => onMessage(data), onError);
             },
+            /**
+             * 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, onMessage, onError) => {
+                return this.openEventStream(`/pubsub/p/${encodeURIComponent(pattern)}/stream`, (_event, data) => {
+                    const payload = data;
+                    onMessage(payload.message, payload.channel);
+                }, onError);
+            },
+            /**
+             * List exact-subscriber channels in this tenant's namespace,
+             * optionally filtered by a glob pattern (default `*`).
+             */
+            channels: async (pattern = "*") => {
+                const res = await this.req("GET", "/pubsub/channels", undefined, { pattern });
+                return res.channels;
+            },
+            /** Per-channel exact-subscriber counts (0 for channels with none). */
+            numsub: async (channels) => {
+                const res = await this.req("POST", "/pubsub/numsub", { channels });
+                return res.counts;
+            },
+            /** Number of distinct active patterns (server-wide; matches Redis). */
+            numpat: async () => {
+                const res = await this.req("GET", "/pubsub/numpat");
+                return res.count;
+            },
         };
         // ─── Set ──────────────────────────────────────────────────────────────
         this.set_ = {
@@ -187,6 +556,74 @@ export class ErixClient {
                 const data = await this.req("GET", "/set/smembers", undefined, { key });
                 return data.members;
             },
+            /** Remove one or more members. Returns the count actually removed. */
+            srem: async (key, ...members) => {
+                return this.cmd("SREM", key, ...members);
+            },
+            /** Whether `member` is in the set. */
+            sismember: async (key, member) => {
+                const r = await this.cmd("SISMEMBER", key, member);
+                return r === 1;
+            },
+            /** Number of members in the set. */
+            scard: async (key) => {
+                return this.cmd("SCARD", key);
+            },
+            /** Intersection across the supplied sets. */
+            sinter: async (...keys) => {
+                return this.cmd("SINTER", ...keys);
+            },
+            /** Union across the supplied sets. */
+            sunion: async (...keys) => {
+                return this.cmd("SUNION", ...keys);
+            },
+            /** Members in the first set that are not in any of the others. */
+            sdiff: async (...keys) => {
+                return this.cmd("SDIFF", ...keys);
+            },
+        };
+        // ─── Sorted Set ───────────────────────────────────────────────────────
+        this.zset = {
+            /** Add or update a member's score. Returns the count of newly added members. */
+            zadd: async (key, score, member) => {
+                return this.cmd("ZADD", key, score, member);
+            },
+            /** Inclusive range by 0-based rank (lowest score first). Negative indices supported. */
+            zrange: async (key, start, stop) => {
+                return this.cmd("ZRANGE", key, start, stop);
+            },
+            /** Same as zrange but in descending score order. */
+            zrevrange: async (key, start, stop) => {
+                return this.cmd("ZREVRANGE", key, start, stop);
+            },
+            /** Members whose score is in [min, max], ascending. */
+            zrangeByScore: async (key, min, max) => {
+                return this.cmd("ZRANGEBYSCORE", key, min, max);
+            },
+            /** Score for a member; `null` if missing. */
+            zscore: async (key, member) => {
+                return this.cmd("ZSCORE", key, member);
+            },
+            /** 0-based rank of `member`; `null` if missing. */
+            zrank: async (key, member) => {
+                return this.cmd("ZRANK", key, member);
+            },
+            /** Number of members in the sorted set. */
+            zcard: async (key) => {
+                return this.cmd("ZCARD", key);
+            },
+            /** Number of members whose score is in [min, max]. */
+            zcount: async (key, min, max) => {
+                return this.cmd("ZCOUNT", key, min, max);
+            },
+            /** Increment a member's score by `delta`. Returns the new score. */
+            zincrBy: async (key, delta, member) => {
+                return this.cmd("ZINCRBY", key, delta, member);
+            },
+            /** Remove one or more members. Returns the count actually removed. */
+            zrem: async (key, ...members) => {
+                return this.cmd("ZREM", key, ...members);
+            },
         };
         // ─── Cache (advanced) ────────────────────────────────────────────────
         this.cache = {
@@ -323,39 +760,137 @@ export class ErixClient {
         };
         this.baseUrl = options.baseUrl.replace(/\/$/, ""); // strip trailing slash
         this.timeoutMs = options.timeoutMs ?? 5000;
+        this.transportMode = options.transport ?? "auto";
         this.headers = {
             "x-erix-key": options.apiKey,
             "x-tenant-id": options.tenantId,
             "Content-Type": "application/json",
         };
+        // Initialize transport based on mode
+        this.transport = this.createTransport();
     }
-    // ── 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);
-            }
+    /**
+     * Create the appropriate transport based on the configured mode.
+     * In "auto" mode, starts with WebSocket and falls back to HTTP on failure.
+     */
+    createTransport() {
+        const httpTransport = new HttpTransport({
+            baseUrl: this.baseUrl,
+            headers: this.headers,
+            timeoutMs: this.timeoutMs,
+        });
+        if (this.transportMode === "http") {
+            return httpTransport;
         }
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        // For "ws" and "auto" modes, create a WebSocket transport
+        const wsUrl = this.baseUrl
+            .replace(/^https:/, "wss:")
+            .replace(/^http:/, "ws:");
         try {
-            const res = await fetch(url.toString(), {
-                method,
+            const wsTransport = new WebSocketTransport({
+                url: wsUrl,
                 headers: this.headers,
-                body: body !== undefined ? JSON.stringify(body) : undefined,
-                signal: controller.signal,
+                timeoutMs: this.timeoutMs,
+                reconnect: {
+                    initialDelayMs: 1000,
+                    maxDelayMs: 30000,
+                    backoffFactor: 2,
+                },
             });
-            if (!res.ok) {
-                const err = (await res.json().catch(() => ({})));
-                throw new Error(`[erix-store] ${method} ${path} → ${res.status}: ${err.error ?? res.statusText}`);
+            if (this.transportMode === "ws") {
+                return wsTransport;
             }
-            return (await res.json());
+            // "auto" mode: use WebSocket with HTTP as fallback
+            return new AutoTransport(wsTransport, httpTransport);
         }
-        finally {
-            clearTimeout(timer);
+        catch {
+            // If WebSocket creation fails in "auto" mode, fall back to HTTP
+            if (this.transportMode === "auto") {
+                return httpTransport;
+            }
+            throw new Error("[erix-store] Failed to create WebSocket transport in 'ws' mode");
         }
     }
+    // ── Internal fetch helper ─────────────────────────────────────────────
+    async req(method, path, body, params) {
+        return this.transport.request(method, path, body, params);
+    }
+    /**
+     * 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.
+     */
+    async pipeline(requests) {
+        return this.transport.pipeline(requests);
+    }
+    /**
+     * 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() {
+        return new Transaction(this);
+    }
+    /** Alias for {@link multi}. */
+    tx() {
+        return this.multi();
+    }
+    /** @internal — called by Transaction.exec(). Keeps tx wire format private. */
+    async _execTransaction(commands) {
+        const res = await this.req("POST", "/tx/exec", { commands });
+        return res.results;
+    }
+    /**
+     * 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");
+     * ```
+     */
+    async cmd(name, ...args) {
+        const [result] = await this._execTransaction([{ name, args }]);
+        if (!result.ok) {
+            const err = new Error(`[erix-store] ${name}: ${result.error}`);
+            if (result.code)
+                err.code = result.code;
+            throw err;
+        }
+        return result.value;
+    }
+    /**
+     * Close the transport and release resources.
+     */
+    close() {
+        this.transport.close();
+    }
     // ─── Health ───────────────────────────────────────────────────────────
     /** Check if the erix-store instance is reachable */
     async ping() {
@@ -391,6 +926,81 @@ export class ErixClient {
     async del(key) {
         await this.req("DELETE", "/core/del", { key });
     }
+    /**
+     * Atomic increment. Creates the counter at 1 when missing.
+     * Throws on non-integer values or overflow.
+     */
+    async incr(key) {
+        return this.cmd("INCR", key);
+    }
+    /** Atomic decrement. Creates the counter at -1 when missing. */
+    async decr(key) {
+        return this.cmd("DECR", key);
+    }
+    /** Atomic increment by `delta`. */
+    async incrBy(key, delta) {
+        return this.cmd("INCRBY", key, delta);
+    }
+    /** Atomic decrement by `delta`. */
+    async decrBy(key, delta) {
+        return this.cmd("DECRBY", key, delta);
+    }
+    /** Append `value` to the existing string at `key`. Returns the new length. */
+    async append(key, value) {
+        return this.cmd("APPEND", key, value);
+    }
+    /** Length of the string at `key`. 0 for missing keys. */
+    async strlen(key) {
+        return this.cmd("STRLEN", key);
+    }
+    /**
+     * 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.
+     */
+    async mset(entries) {
+        const args = [];
+        for (const [k, v] of Object.entries(entries)) {
+            args.push(k, JSON.stringify(v));
+        }
+        await this.cmd("MSET", ...args);
+    }
+    /** Get multiple keys at once. Missing/non-string keys come back as `null`. */
+    async mget(keys) {
+        const raw = await this.cmd("MGET", ...keys);
+        return raw.map((v) => {
+            if (v === null)
+                return null;
+            try {
+                return JSON.parse(v);
+            }
+            catch {
+                return v;
+            }
+        });
+    }
+    /**
+     * Atomic compare-and-set: returns the previous value (or `null`) and
+     * stores `value`. Clears any prior TTL.
+     */
+    async getSet(key, value) {
+        const prev = await this.cmd("GETSET", key, JSON.stringify(value));
+        if (prev === null)
+            return null;
+        try {
+            return JSON.parse(prev);
+        }
+        catch {
+            return prev;
+        }
+    }
+    /**
+     * Set only if the key does not already exist. Returns true on success,
+     * false when the key was already taken (any type — no WRONGTYPE).
+     */
+    async setNx(key, value) {
+        const r = await this.cmd("SETNX", key, JSON.stringify(value));
+        return r === 1;
+    }
     // ─── Rate Limiter ─────────────────────────────────────────────────────
     /**
      * Check if an operation is within rate limits.
@@ -462,3 +1072,96 @@ export class ErixClient {
         return { close: () => controller.abort() };
     }
 }
+/**
+ * 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 class Transaction {
+    constructor(client) {
+        this.client = client;
+        this.commands = [];
+        this.finalized = false;
+    }
+    /** Number of commands queued. */
+    get size() {
+        return this.commands.length;
+    }
+    /**
+     * 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, ...args) {
+        if (this.finalized) {
+            throw new Error("[erix-store] Transaction already finalized — create a new one with client.multi()");
+        }
+        this.commands.push({ name, args });
+        return this;
+    }
+    /** Drop the queued commands locally. No server request is issued. */
+    discard() {
+        this.finalized = true;
+        this.commands = [];
+    }
+    /**
+     * 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.
+     */
+    async exec() {
+        if (this.finalized) {
+            throw new Error("[erix-store] Transaction already finalized");
+        }
+        this.finalized = true;
+        return this.client._execTransaction(this.commands);
+    }
+}
+// ─── AutoTransport (internal) ────────────────────────────────────────────
+/**
+ * Internal transport that tries WebSocket first and falls back to HTTP
+ * if the WebSocket is not connected. Used in "auto" mode.
+ */
+class AutoTransport {
+    constructor(ws, http) {
+        this.ws = ws;
+        this.http = http;
+    }
+    get isConnected() {
+        return this.ws.isConnected || this.http.isConnected;
+    }
+    async request(method, path, body, params) {
+        // If WebSocket is connected, use it
+        if (this.ws.isConnected) {
+            try {
+                return await this.ws.request(method, path, body, params);
+            }
+            catch {
+                // Fall back to HTTP on WebSocket failure
+                return this.http.request(method, path, body, params);
+            }
+        }
+        // Otherwise use HTTP
+        return this.http.request(method, path, body, params);
+    }
+    async pipeline(requests) {
+        if (this.ws.isConnected) {
+            try {
+                return await this.ws.pipeline(requests);
+            }
+            catch {
+                return this.http.pipeline(requests);
+            }
+        }
+        return this.http.pipeline(requests);
+    }
+    close() {
+        this.ws.close();
+        this.http.close();
+    }
+}