ts-prorm-orm 1.1.0

package/dist/nosql/redis/index.js

@@ -0,0 +1,607 @@
+"use strict";
+/**
+ * Redis store implementation.
+ *
+ * Redis is a key-value store with several typed data structures (strings,
+ * hashes, lists, sets, sorted sets, streams) plus pub/sub and pipelining. It has no
+ * query language and does not fit the SQL-shaped `Dialect` interface, so
+ * this class implements the minimal `NoSqlStore` marker interface and
+ * exposes Redis's real operations grouped by data structure instead of
+ * forcing everything into a `query(sql)` shape.
+ *
+ * Uses the `ioredis` driver.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStore = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Redis: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'redis', host });
+}
+/** Convert Redis's flat `[field, value, field, value, ...]` array into a record. */
+function fieldsToRecord(flat) {
+    const record = {};
+    for (let i = 0; i < flat.length; i += 2) {
+        record[flat[i]] = flat[i + 1];
+    }
+    return record;
+}
+/** Convert a raw `XRANGE`/`XREVRANGE`-shaped reply into `StreamEntry[]`. */
+function toStreamEntries(raw) {
+    if (!raw)
+        return [];
+    return raw.map(([id, fields]) => ({ id, fields: fieldsToRecord(fields) }));
+}
+/** Convert a raw `XREAD`/`XREADGROUP`-shaped reply into `StreamReadResult[]`. */
+function toStreamReadResults(raw) {
+    if (!raw)
+        return null;
+    return raw.map(([key, entries]) => ({ key, entries: toStreamEntries(entries) }));
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    // Keep the `action` context (e.g. "Redis GET failed") but don't discard the
+    // real underlying Redis error text (e.g. "WRONGTYPE Operation against a key
+    // holding the wrong kind of value") - append it so callers inspecting
+    // `err.message` still see what actually went wrong.
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `RedisStore` wraps an `ioredis` client and exposes Redis's data-structure
+ * commands (string/hash/list/set/sorted-set/stream), pub/sub, and
+ * pipelining as a typed, promise-based API.
+ */
+class RedisStore {
+    constructor(options = {}) {
+        this.name = 'redis';
+        this.library = 'ioredis';
+        this.client = null;
+        this.subscriber = null;
+        this.connected = false;
+        /**
+         * Per-channel handlers for the shared subscriber connection. A single
+         * `message` listener is attached once and dispatches to the handler
+         * registered for the incoming message's channel, so each `subscribe()`
+         * call's handler only ever receives messages for its own channel.
+         */
+        this.channelHandlers = new Map();
+        /**
+         * Per-pattern handlers for the shared subscriber connection, mirroring
+         * `channelHandlers` but for `PSUBSCRIBE`/`PUNSUBSCRIBE`.
+         */
+        this.patternHandlers = new Map();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    createClient() {
+        const { url, ...rest } = this.options;
+        // ioredis connects lazily by default when constructed this way, so we
+        // explicitly opt into eager connection and await `connect()` below to
+        // surface connection failures immediately.
+        const opts = { lazyConnect: true, ...rest };
+        return url ? new ioredis_1.default(url, opts) : new ioredis_1.default(opts);
+    }
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            this.client = this.createClient();
+            await this.client.connect();
+            this.connected = true;
+        }
+        catch (err) {
+            // Don't leak the failed client's socket - ioredis will otherwise keep
+            // retrying the connection in the background even though we're about
+            // to drop our only reference to it.
+            this.client?.disconnect();
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.host);
+        }
+    }
+    async disconnect() {
+        if (this.subscriber) {
+            this.subscriber.disconnect();
+            this.subscriber = null;
+        }
+        if (this.client) {
+            try {
+                await this.client.quit();
+            }
+            catch {
+                this.client.disconnect();
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null && this.client.status === 'ready';
+    }
+    /** Returns the underlying `ioredis` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Redis', { database: 'redis' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Redis ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // JSON helpers (opt-in convenience on top of the raw string API)
+    // ---------------------------------------------------------------------
+    /** Serialize a value with `JSON.stringify` and `SET` it. */
+    async setJSON(key, value, options) {
+        return this.set(key, JSON.stringify(value), options);
+    }
+    /** `GET` a key and `JSON.parse` it. Returns `null` if the key is missing. */
+    async getJSON(key) {
+        const raw = await this.get(key);
+        if (raw === null) {
+            return null;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Redis GETJSON failed (invalid JSON for key "${key}")`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // String commands
+    // ---------------------------------------------------------------------
+    async get(key) {
+        return this.exec((c) => c.get(key), 'GET');
+    }
+    async set(key, value, options = {}) {
+        return this.exec((c) => {
+            const args = [];
+            if (options.ex !== undefined)
+                args.push('EX', options.ex);
+            if (options.px !== undefined)
+                args.push('PX', options.px);
+            if (options.keepttl)
+                args.push('KEEPTTL');
+            if (options.nx)
+                args.push('NX');
+            if (options.xx)
+                args.push('XX');
+            return c.set(key, value, ...args);
+        }, 'SET');
+    }
+    async del(...keys) {
+        return this.exec((c) => c.del(...keys), 'DEL');
+    }
+    async exists(...keys) {
+        return this.exec((c) => c.exists(...keys), 'EXISTS');
+    }
+    async incr(key) {
+        return this.exec((c) => c.incr(key), 'INCR');
+    }
+    async incrby(key, amount) {
+        return this.exec((c) => c.incrby(key, amount), 'INCRBY');
+    }
+    async expire(key, seconds) {
+        return this.exec((c) => c.expire(key, seconds), 'EXPIRE');
+    }
+    async ttl(key) {
+        return this.exec((c) => c.ttl(key), 'TTL');
+    }
+    // ---------------------------------------------------------------------
+    // Hash commands
+    // ---------------------------------------------------------------------
+    async hget(key, field) {
+        return this.exec((c) => c.hget(key, field), 'HGET');
+    }
+    async hset(key, fields) {
+        return this.exec((c) => c.hset(key, fields), 'HSET');
+    }
+    async hgetall(key) {
+        return this.exec((c) => c.hgetall(key), 'HGETALL');
+    }
+    async hdel(key, ...fields) {
+        return this.exec((c) => c.hdel(key, ...fields), 'HDEL');
+    }
+    async hincrby(key, field, amount) {
+        return this.exec((c) => c.hincrby(key, field, amount), 'HINCRBY');
+    }
+    // ---------------------------------------------------------------------
+    // List commands
+    // ---------------------------------------------------------------------
+    async lpush(key, ...values) {
+        return this.exec((c) => c.lpush(key, ...values), 'LPUSH');
+    }
+    async rpush(key, ...values) {
+        return this.exec((c) => c.rpush(key, ...values), 'RPUSH');
+    }
+    async lrange(key, start, stop) {
+        return this.exec((c) => c.lrange(key, start, stop), 'LRANGE');
+    }
+    async lpop(key, count) {
+        return this.exec((c) => (count === undefined ? c.lpop(key) : c.lpop(key, count)), 'LPOP');
+    }
+    async rpop(key, count) {
+        return this.exec((c) => (count === undefined ? c.rpop(key) : c.rpop(key, count)), 'RPOP');
+    }
+    // ---------------------------------------------------------------------
+    // Set commands
+    // ---------------------------------------------------------------------
+    async sadd(key, ...members) {
+        return this.exec((c) => c.sadd(key, ...members), 'SADD');
+    }
+    async srem(key, ...members) {
+        return this.exec((c) => c.srem(key, ...members), 'SREM');
+    }
+    async smembers(key) {
+        return this.exec((c) => c.smembers(key), 'SMEMBERS');
+    }
+    async sismember(key, member) {
+        return this.exec(async (c) => (await c.sismember(key, member)) === 1, 'SISMEMBER');
+    }
+    // ---------------------------------------------------------------------
+    // Sorted set commands
+    // ---------------------------------------------------------------------
+    async zadd(key, ...members) {
+        return this.exec((c) => {
+            const args = [];
+            for (const { score, member } of members) {
+                args.push(score, member);
+            }
+            return c.zadd(key, ...args);
+        }, 'ZADD');
+    }
+    async zrange(key, start, stop, options = {}) {
+        return this.exec((c) => {
+            const args = [];
+            if (options.rev)
+                args.push('REV');
+            if (options.withScores)
+                args.push('WITHSCORES');
+            if (options.limit)
+                args.push('LIMIT', options.limit.offset, options.limit.count);
+            return c.zrange(key, start, stop, ...args);
+        }, 'ZRANGE');
+    }
+    async zrangebyscore(key, min, max, options = {}) {
+        return this.exec((c) => {
+            const args = [];
+            if (options.withScores)
+                args.push('WITHSCORES');
+            if (options.limit)
+                args.push('LIMIT', options.limit.offset, options.limit.count);
+            return c.zrangebyscore(key, min, max, ...args);
+        }, 'ZRANGEBYSCORE');
+    }
+    async zrem(key, ...members) {
+        return this.exec((c) => c.zrem(key, ...members), 'ZREM');
+    }
+    async zscore(key, member) {
+        return this.exec((c) => c.zscore(key, member), 'ZSCORE');
+    }
+    // ---------------------------------------------------------------------
+    // Stream commands
+    // ---------------------------------------------------------------------
+    /**
+     * `XADD` - append an entry to a stream, creating it if it doesn't exist.
+     * Pass `'*'` as `id` to let Redis auto-generate a monotonic
+     * `<ms>-<seq>` ID (the common case); returns the ID that was assigned.
+     */
+    async xadd(key, id, fields) {
+        return this.exec((c) => {
+            const args = [];
+            for (const [field, value] of Object.entries(fields)) {
+                args.push(field, value);
+            }
+            return c.xadd(key, id, ...args);
+        }, 'XADD');
+    }
+    /** `XRANGE` - read entries with IDs between `start` and `end` (inclusive), in ID order. Use `'-'`/`'+'` for the full range. */
+    async xrange(key, start, end, count) {
+        return this.exec(async (c) => {
+            const raw = count === undefined ? await c.xrange(key, start, end) : await c.xrange(key, start, end, 'COUNT', count);
+            return toStreamEntries(raw);
+        }, 'XRANGE');
+    }
+    /** `XREVRANGE` - like `xrange()` but in reverse ID order; `start` is the higher/first ID, `end` the lower/last. */
+    async xrevrange(key, start, end, count) {
+        return this.exec(async (c) => {
+            const raw = count === undefined
+                ? await c.xrevrange(key, start, end)
+                : await c.xrevrange(key, start, end, 'COUNT', count);
+            return toStreamEntries(raw);
+        }, 'XREVRANGE');
+    }
+    /**
+     * `XREAD` - read entries newer than `ids` from one or more streams.
+     * `keys[i]` is paired with `ids[i]`; pass `'$'` for an ID to only read
+     * entries added after the call starts, or `'0'` to read from the
+     * beginning. With `options.block`, blocks (up to that many ms, or
+     * forever if `0`) waiting for new entries instead of returning
+     * immediately. Returns `null` if nothing matched (e.g. a non-blocking
+     * read found nothing new).
+     */
+    async xread(keys, ids, options = {}) {
+        return this.exec(async (c) => {
+            const args = [];
+            if (options.count !== undefined)
+                args.push('COUNT', options.count);
+            if (options.block !== undefined)
+                args.push('BLOCK', options.block);
+            args.push('STREAMS', ...keys, ...ids);
+            const raw = (await c.xread(...args));
+            return toStreamReadResults(raw);
+        }, 'XREAD');
+    }
+    /** `XLEN` - number of entries in a stream. */
+    async xlen(key) {
+        return this.exec((c) => c.xlen(key), 'XLEN');
+    }
+    /** `XDEL` - remove specific entries from a stream by ID. Returns the number actually removed. */
+    async xdel(key, ids) {
+        return this.exec((c) => c.xdel(key, ...ids), 'XDEL');
+    }
+    /**
+     * `XTRIM` - trim a stream to (approximately) `threshold` entries
+     * (`'MAXLEN'`) or drop entries older than a given ID (`'MINID'`).
+     * Returns the number of entries removed.
+     */
+    async xtrim(key, strategy, threshold) {
+        return this.exec((c) => c.xtrim(key, strategy, threshold), 'XTRIM');
+    }
+    /**
+     * `XGROUP CREATE` - create a consumer group on a stream, starting
+     * delivery from `id` (default `'$'`, i.e. only new entries). Creates the
+     * stream first (via `MKSTREAM`) if it doesn't exist yet.
+     */
+    async xgroupCreate(key, groupName, id = '$') {
+        return this.exec((c) => c.xgroup('CREATE', key, groupName, id, 'MKSTREAM'), 'XGROUP CREATE');
+    }
+    /**
+     * `XREADGROUP` - read entries from one or more streams as a named
+     * consumer within a consumer group, so entries are tracked in the
+     * group's pending-entries list until `xack()`'d. Pass `'>'` for an ID to
+     * receive only entries never delivered to this group; any other ID
+     * re-reads this consumer's already-delivered-but-unacked entries.
+     */
+    async xreadgroup(groupName, consumerName, keys, ids, options = {}) {
+        return this.exec(async (c) => {
+            const args = ['GROUP', groupName, consumerName];
+            if (options.count !== undefined)
+                args.push('COUNT', options.count);
+            if (options.block !== undefined)
+                args.push('BLOCK', options.block);
+            args.push('STREAMS', ...keys, ...ids);
+            const raw = (await c.xreadgroup(...args));
+            return toStreamReadResults(raw);
+        }, 'XREADGROUP');
+    }
+    /** `XACK` - acknowledge that a consumer group has finished processing the given entry IDs. */
+    async xack(key, groupName, ids) {
+        return this.exec((c) => c.xack(key, groupName, ...ids), 'XACK');
+    }
+    // ---------------------------------------------------------------------
+    // Scripting (Lua)
+    // ---------------------------------------------------------------------
+    /**
+     * `EVAL` - run a Lua `script` server-side, atomically. `keys` are passed
+     * as Redis's `KEYS[1..N]` (and count toward the `numkeys` argument),
+     * `args` as `ARGV[1..N]`. Prefer `evalsha()` once a script has been
+     * cached (via `scriptLoad()` or a prior `eval()`) to avoid resending the
+     * source on every call.
+     */
+    async eval(script, keys = [], args = []) {
+        return this.exec((c) => c.eval(script, keys.length, ...keys, ...args), 'EVAL');
+    }
+    /**
+     * `EVALSHA` - run a previously cached Lua script by its SHA1 digest
+     * (see `scriptLoad()`), avoiding the cost of resending the script body.
+     * Redis replies with a `NOSCRIPT` error (surfaced here as a
+     * `DatabaseError`) if the script isn't cached on the server.
+     */
+    async evalsha(sha1, keys = [], args = []) {
+        return this.exec((c) => c.evalsha(sha1, keys.length, ...keys, ...args), 'EVALSHA');
+    }
+    /**
+     * `SCRIPT LOAD` - cache a Lua script on the server without executing it,
+     * returning its SHA1 digest for later `evalsha()` calls.
+     */
+    async scriptLoad(script) {
+        return this.exec((c) => c.script('LOAD', script), 'SCRIPT LOAD');
+    }
+    // ---------------------------------------------------------------------
+    // HyperLogLog (approximate cardinality)
+    // ---------------------------------------------------------------------
+    /** `PFADD` - add elements to a HyperLogLog. Returns `1` if the estimated cardinality changed, `0` otherwise. */
+    async pfadd(key, ...elements) {
+        return this.exec((c) => c.pfadd(key, ...elements), 'PFADD');
+    }
+    /** `PFCOUNT` - the approximate cardinality of one HyperLogLog, or the union of several. */
+    async pfcount(...keys) {
+        return this.exec((c) => c.pfcount(...keys), 'PFCOUNT');
+    }
+    /** `PFMERGE` - merge one or more source HyperLogLogs into `destKey` (created/overwritten as the union). */
+    async pfmerge(destKey, ...sourceKeys) {
+        return this.exec((c) => c.pfmerge(destKey, ...sourceKeys), 'PFMERGE');
+    }
+    // ---------------------------------------------------------------------
+    // Pub/sub
+    // ---------------------------------------------------------------------
+    async publish(channel, message) {
+        return this.exec((c) => c.publish(channel, message), 'PUBLISH');
+    }
+    /**
+     * Subscribe to a channel and invoke `handler` for each message received.
+     *
+     * Pub/sub requires a dedicated connection in Redis (a subscribed
+     * connection can't issue other commands), so this lazily creates a
+     * second `ioredis` client reusing the same connection options and keeps
+     * it alive for the lifetime of the store (or until `unsubscribe`/
+     * `disconnect` is called).
+     */
+    /**
+     * Lazily create the shared subscriber connection and attach the
+     * `message`/`pmessage` dispatch listeners exactly once. Both `subscribe()`
+     * and `psubscribe()` share this single connection (a subscribed Redis
+     * connection can't issue other commands, so both plain and pattern
+     * subscriptions ride the same dedicated socket).
+     */
+    async ensureSubscriber() {
+        if (this.subscriber) {
+            return this.subscriber;
+        }
+        const subscriber = this.createClient();
+        try {
+            await subscriber.connect();
+        }
+        catch (err) {
+            // Don't leak the failed subscriber's socket - same reasoning as
+            // `connect()` above.
+            subscriber.disconnect();
+            throw wrapConnectionError(err, this.options.host);
+        }
+        this.subscriber = subscriber;
+        // A single shared listener dispatches by channel so that each
+        // `subscribe(channel, handler)` call's handler only ever receives
+        // messages for its own channel, rather than every channel getting
+        // routed to whichever handler happened to be registered first.
+        this.subscriber.on('message', (ch, msg) => {
+            const channelHandler = this.channelHandlers.get(ch);
+            channelHandler?.(msg, ch);
+        });
+        // Same idea for pattern subscriptions, dispatched by the pattern that
+        // matched rather than the concrete channel.
+        this.subscriber.on('pmessage', (pattern, ch, msg) => {
+            const patternHandler = this.patternHandlers.get(pattern);
+            patternHandler?.(msg, ch, pattern);
+        });
+        return this.subscriber;
+    }
+    async subscribe(channel, handler) {
+        const subscriber = await this.ensureSubscriber();
+        this.channelHandlers.set(channel, handler);
+        try {
+            await subscriber.subscribe(channel);
+        }
+        catch (err) {
+            this.channelHandlers.delete(channel);
+            throw wrapDatabaseError(err, 'Redis SUBSCRIBE failed');
+        }
+    }
+    async unsubscribe(channel) {
+        if (!this.subscriber) {
+            return;
+        }
+        try {
+            if (channel) {
+                await this.subscriber.unsubscribe(channel);
+                this.channelHandlers.delete(channel);
+            }
+            else {
+                await this.subscriber.unsubscribe();
+                this.channelHandlers.clear();
+                this.closeSubscriberIfIdle();
+            }
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Redis UNSUBSCRIBE failed');
+        }
+    }
+    /**
+     * `PSUBSCRIBE` - subscribe to all channels matching a glob-style `pattern`
+     * (e.g. `news.*`, `__keyevent@0__:expired`) and invoke `handler` for each
+     * matching message. This is the standard mechanism for consuming Redis
+     * keyspace notifications (e.g. subscribing to
+     * `__keyevent@0__:expired` to react to key expirations), where the
+     * concrete channel name varies and only a pattern subscription can catch
+     * all of them. Shares the same lazily-created subscriber connection as
+     * `subscribe()`.
+     */
+    async psubscribe(pattern, handler) {
+        const subscriber = await this.ensureSubscriber();
+        this.patternHandlers.set(pattern, handler);
+        try {
+            await subscriber.psubscribe(pattern);
+        }
+        catch (err) {
+            this.patternHandlers.delete(pattern);
+            throw wrapDatabaseError(err, 'Redis PSUBSCRIBE failed');
+        }
+    }
+    /**
+     * `PUNSUBSCRIBE` - stop receiving messages for `pattern` (or every pattern
+     * subscription, if omitted). Closes the shared subscriber connection once
+     * both the channel and pattern handler sets are empty.
+     */
+    async punsubscribe(pattern) {
+        if (!this.subscriber) {
+            return;
+        }
+        try {
+            if (pattern) {
+                await this.subscriber.punsubscribe(pattern);
+                this.patternHandlers.delete(pattern);
+            }
+            else {
+                await this.subscriber.punsubscribe();
+                this.patternHandlers.clear();
+            }
+            this.closeSubscriberIfIdle();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Redis PUNSUBSCRIBE failed');
+        }
+    }
+    /** Tear down the shared subscriber connection once nothing is subscribed through it. */
+    closeSubscriberIfIdle() {
+        if (this.subscriber && this.channelHandlers.size === 0 && this.patternHandlers.size === 0) {
+            this.subscriber.disconnect();
+            this.subscriber = null;
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Pipelining / transactions
+    // ---------------------------------------------------------------------
+    /**
+     * Queue multiple commands and send them in a single round trip. Unlike
+     * `multi()`, commands are not guaranteed atomic — a failure in one
+     * command does not abort the others. Returns the ioredis chainable
+     * commander; call `.exec()` to run it.
+     */
+    pipeline() {
+        return this.requireClient().pipeline();
+    }
+    /**
+     * Queue multiple commands to run atomically (Redis `MULTI`/`EXEC`). This
+     * is Redis's substitute for cross-key transactions: all queued commands
+     * either all run or (if `.discard()` is called) none do, but there is no
+     * rollback of partial effects and no cross-command isolation the way a
+     * SQL transaction provides. Returns the ioredis chainable commander;
+     * call `.exec()` to run it.
+     */
+    multi() {
+        return this.requireClient().multi();
+    }
+}
+exports.RedisStore = RedisStore;
+exports.default = RedisStore;