ts-server-lib 0.0.17

package/db/TSRQW.js

@@ -0,0 +1,699 @@
+"use strict";
+/**
+ * TSRQW — Redis Queue Worker (standalone / sentinel / cluster).
+ *
+ * R = Redis · Q = Queue · W = Worker
+ *
+ * Single class unifying queue storage (Redis Streams) + worker lifecycle
+ * (events, retry, dead-letter, cron schedule, thread pool).
+ *
+ * Backend: Redis Streams (XADD / XREADGROUP / XAUTOCLAIM / XACK).
+ *   - All keys hash-tagged → zero CROSSSLOT on any topology.
+ *   - No Lua scripts, no EVALSHA, no SCRIPT LOAD broadcast.
+ *   - Consumer-group model: crashed consumers recovered automatically via XAUTOCLAIM.
+ *   - Built-in dead-letter stream (`{ns:name}:dlq`).
+ *
+ * Performance:
+ *   - send:    1 roundtrip (XADD MAXLEN ~)
+ *   - receive: 1 roundtrip (XREADGROUP); XAUTOCLAIM throttled to reclaimIntervalMs
+ *   - node-redis v5 auto-pipelines concurrent callers → linear throughput scaling
+ *
+ * Events: new · ready · completed · retry · exceeded · failed · deleted · error
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSRQW = exports.TSRQWPool = exports.TSRQWEvents = void 0;
+const events_1 = require("events");
+const async_hooks_1 = require("async_hooks");
+const cron_1 = require("cron");
+const os_1 = require("os");
+const worker_threads_1 = require("worker_threads");
+// ─── Events ──────────────────────────────────────────────────────────────────
+var TSRQWEvents;
+(function (TSRQWEvents) {
+    TSRQWEvents["new"] = "new";
+    TSRQWEvents["ready"] = "ready";
+    TSRQWEvents["deleted"] = "deleted";
+    TSRQWEvents["completed"] = "completed";
+    TSRQWEvents["retry"] = "retry";
+    TSRQWEvents["exceeded"] = "exceeded";
+    TSRQWEvents["failed"] = "failed";
+    TSRQWEvents["error"] = "error";
+})(TSRQWEvents || (exports.TSRQWEvents = TSRQWEvents = {}));
+// ─── Shared error-detection helpers ─────────────────────────────────────────
+const NOGROUP_PATTERN = 'NOGROUP';
+const NO_SUCH_KEY_PATTERN = 'no such key';
+function isNoGroupError(msg) {
+    return msg.includes(NOGROUP_PATTERN) || msg.includes(NO_SUCH_KEY_PATTERN);
+}
+// ─── Thread pool ──────────────────────────────────────────────────────────────
+const kTaskInfo = Symbol('kTaskInfo');
+const kWorkerFreedEvent = Symbol('kWorkerFreedEvent');
+class TSRQWPoolTask extends async_hooks_1.AsyncResource {
+    callback;
+    constructor(callback) {
+        super('TSRQWPoolTask');
+        this.callback = callback;
+    }
+    done(err, result) {
+        this.runInAsyncScope(this.callback, null, err, result);
+        this.emitDestroy();
+    }
+}
+class TSRQWPool extends events_1.EventEmitter {
+    factor;
+    callback;
+    wd;
+    workers = [];
+    freeWorkers = [];
+    tasks = [];
+    constructor(factor = 1, callback, wd) {
+        super();
+        this.factor = factor;
+        this.callback = callback;
+        this.wd = wd;
+        const threads = Math.max(1, Math.floor((0, os_1.availableParallelism)() / factor));
+        for (let i = 0; i < threads; i++)
+            this._addWorker();
+        this.on(kWorkerFreedEvent, () => {
+            const item = this.tasks.shift();
+            if (item)
+                this._runTask(item.task, item.callback);
+        });
+    }
+    work = (data) => new Promise((resolve, reject) => this._runTask(data, (err, result) => err ? reject(err) : resolve(result)));
+    update(data) {
+        data._wd_updated = Date.now();
+        this.workers.forEach(w => w.postMessage(data));
+    }
+    close() { for (const w of this.workers)
+        void w.terminate(); }
+    _runTask(task, callback) {
+        if (this.freeWorkers.length === 0) {
+            this.tasks.push({ task, callback });
+            return;
+        }
+        const worker = this.freeWorkers.pop();
+        worker[kTaskInfo] = new TSRQWPoolTask(callback);
+        worker.postMessage(task);
+    }
+    _addWorker() {
+        let ep = `if (task?._wd_updated) { workerData = task; }`;
+        ep += `else { fn(task).then(data => pp.postMessage({ data, threadId })); }`;
+        let em = `import('worker_threads').then(({ threadId, isMainThread, parentPort: pp, workerData}) => { if(!isMainThread) {`;
+        em += `const cb = ${this.callback.toString()};`;
+        em += `cb(workerData).then(fn => pp.on('message', task => {${ep}} ));`;
+        em += `} });`;
+        if (this.wd?._debug)
+            console.log('TSRQWPool:worker', em);
+        const worker = new worker_threads_1.Worker(em, { eval: true, workerData: this.wd });
+        worker.on('message', result => {
+            worker[kTaskInfo].done(null, result);
+            worker[kTaskInfo] = null;
+            this.freeWorkers.push(worker);
+            this.emit(kWorkerFreedEvent);
+        });
+        worker.on('error', (err) => {
+            if (worker[kTaskInfo])
+                worker[kTaskInfo].done(err, null);
+            else
+                this.emit('error', err);
+            this.workers.splice(this.workers.indexOf(worker), 1);
+            void worker.terminate();
+            this._addWorker();
+        });
+        this.workers.push(worker);
+        this.freeWorkers.push(worker);
+        this.emit(kWorkerFreedEvent);
+    }
+}
+exports.TSRQWPool = TSRQWPool;
+// ─── TSRQW ────────────────────────────────────────────────────────────────────
+class TSRQW extends events_1.EventEmitter {
+    redis;
+    qname;
+    rawNs;
+    ns;
+    group;
+    consumer;
+    maxLen;
+    attempts;
+    reclaimIntervalMs;
+    connected = false;
+    offlineBuffer = [];
+    ensured = false;
+    ensurePromise = null;
+    lastReclaimAt = 0;
+    /** Resolves when the consumer group is ready and the first offline drain completes. */
+    initialized;
+    constructor(redis, options = {}) {
+        super();
+        this.redis = redis;
+        this.qname = options.name ?? 'queue';
+        this.rawNs = options.ns ?? 'tsq';
+        this.ns = this.rawNs + ':';
+        this.group = options.group ?? this.rawNs;
+        this.consumer = options.consumer ?? `${this.rawNs}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+        this.maxLen = options.maxLen ?? 100_000;
+        this.attempts = options.attempts ?? 3;
+        this.reclaimIntervalMs = options.reclaimIntervalMs ?? 2_000;
+        this.connected = true;
+        this.initialized = this._init();
+    }
+    // ─── Key helpers ─────────────────────────────────────────────────────────────
+    _streamKey() { return `{${this.ns}${this.qname}}:stream`; }
+    _dlqKey() { return `{${this.ns}${this.qname}}:dlq`; }
+    // ─── Lifecycle ────────────────────────────────────────────────────────────────
+    async _init() {
+        await this._ensureGroup();
+        if (this.listenerCount(TSRQWEvents.ready) > 0)
+            this.emit(TSRQWEvents.ready);
+        await this._drainOffline();
+    }
+    _ensureGroup() {
+        if (this.ensured)
+            return Promise.resolve();
+        if (!this.ensurePromise) {
+            this.ensurePromise = this._createGroup().finally(() => { this.ensurePromise = null; });
+        }
+        return this.ensurePromise;
+    }
+    async _createGroup() {
+        try {
+            await this.redis.xGroupCreate(this._streamKey(), this.group, '$', { MKSTREAM: true });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes('BUSYGROUP'))
+                throw err;
+        }
+        // Register in the namespace discovery index every time the group is (re)created —
+        // including NOGROUP self-heal after Redis flush. SADD is idempotent so this is safe
+        // to call repeatedly. Swallowed on error so a transient Redis hiccup cannot block startup.
+        await this.redis.sAdd(`{${this.rawNs}:QUEUES}`, this.qname).catch(() => { });
+        this.ensured = true;
+    }
+    /** Reset the ensured flag so the next receive call recreates stream+group.
+     *  Call this when XREADGROUP returns NOGROUP (stream/group wiped, e.g. after Redis flush). */
+    resetEnsured() {
+        this.ensured = false;
+    }
+    // ─── Send — 1 roundtrip ───────────────────────────────────────────────────────
+    /**
+     * Append a message. Returns the stream entry ID for immediate sends;
+     * undefined for buffered (pre-connect) or delayed sends.
+     */
+    async send(message, delay = 0) {
+        if (!this.connected) {
+            this.offlineBuffer.push({ message, delay });
+            return;
+        }
+        await this._ensureGroup();
+        if (delay > 0) {
+            setTimeout(() => void this._xadd(message), delay * 1000);
+            return;
+        }
+        const id = await this._xadd(message);
+        if (this.listenerCount(TSRQWEvents.new) > 0)
+            this.emit(TSRQWEvents.new, message);
+        return id;
+    }
+    _xadd(message) {
+        return this.redis.xAdd(this._streamKey(), '*', { p: message }, { TRIM: { strategy: 'MAXLEN', strategyModifier: '~', threshold: this.maxLen } });
+    }
+    // ─── Receive with handler (hot path) ─────────────────────────────────────────
+    async receiveWithStatus({ handle, visibility: vt = 30, }) {
+        await this._ensureGroup();
+        let raw = null;
+        const now = Date.now();
+        if (now - this.lastReclaimAt >= this.reclaimIntervalMs) {
+            this.lastReclaimAt = now;
+            raw = await this._reclaimOne(vt);
+        }
+        if (!raw)
+            raw = await this._readOne();
+        if (!raw)
+            return { status: 'idle' };
+        const { id, message, rc } = raw;
+        const meta = { id, rc, fr: this._msFromId(id) };
+        const ok = await handle(message, meta);
+        if (ok) {
+            await this._ack(id);
+            if (this.listenerCount(TSRQWEvents.completed) > 0)
+                this.emit(TSRQWEvents.completed, { message, meta });
+            if (this.listenerCount(TSRQWEvents.deleted) > 0)
+                this.emit(TSRQWEvents.deleted, { message, meta });
+            return { status: 'completed', message, meta };
+        }
+        if (rc > this.attempts) {
+            await this._moveToDeadLetter(id, message, rc);
+            await this._ack(id);
+            if (this.listenerCount(TSRQWEvents.exceeded) > 0)
+                this.emit(TSRQWEvents.exceeded, { message, meta });
+            if (this.listenerCount(TSRQWEvents.failed) > 0)
+                this.emit(TSRQWEvents.failed, { message, meta });
+            if (this.listenerCount(TSRQWEvents.deleted) > 0)
+                this.emit(TSRQWEvents.deleted, { message, meta });
+            return { status: 'failed', message, meta };
+        }
+        if (this.listenerCount(TSRQWEvents.retry) > 0)
+            this.emit(TSRQWEvents.retry, { message, meta });
+        return { status: 'retry', message, meta };
+    }
+    async receive(opts) {
+        await this.receiveWithStatus(opts);
+    }
+    /**
+     * Blocking receive — XREADGROUP with BLOCK so the connection sleeps until a message
+     * arrives, then wakes immediately. Zero polling overhead vs CronJob polling.
+     *
+     * Preferred consumer pattern for durable/recovery consumers (e.g. integration event
+     * streams). Each call blocks for up to `blockMs` ms. On timeout: returns null (no
+     * message). On message: calls `handler`, ACKs on success, leaves in PEL on failure.
+     *
+     * Run in a `while (running) { await q.receiveBlocking(handler) }` loop per channel.
+     * The loop is woken by Redis as soon as a message is written — no polling overhead.
+     *
+     * @param handler   - Return true to ACK, false to leave in PEL (retry after vt).
+     * @param vt        - Visibility timeout seconds.
+     * @param blockMs   - Max ms to wait for a message (Redis BLOCK option). Default 2 000.
+     *                   Keep short (≤5s) when using a shared cluster client — BLOCK holds
+     *                   the master socket and prevents other commands from executing on it.
+     */
+    async receiveBlocking(handler, vt = 30, blockMs = 2_000) {
+        try {
+            await this._ensureGroup();
+        }
+        catch {
+            return; // group creation failed — caller loop will retry
+        }
+        let result;
+        try {
+            result = await this.redis.xReadGroup(this.group, this.consumer, [{ key: this._streamKey(), id: '>' }], { COUNT: 1, BLOCK: blockMs });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isNoGroupError(msg)) {
+                this.ensured = false; // stream/group wiped — recreate on next call
+            }
+            return; // transient error — caller loop will retry
+        }
+        const entries = result?.[0]?.messages ?? [];
+        if (!entries.length)
+            return; // BLOCK timeout — no message
+        const e = entries[0];
+        const fr = this._msFromId(e.id);
+        const message = String(e.message['p'] ?? '');
+        const ok = await handler(message, { id: e.id, rc: 1, fr }).catch(() => false);
+        if (ok) {
+            await this._ack(e.id).catch(() => { });
+        }
+        // On false/error: message stays in PEL; XAUTOCLAIM picks it up after vt seconds
+        void vt; // vt is used by XAUTOCLAIM in receiveRawBatch — documented for callers
+    }
+    // ─── Low-level API (adaptive consumers owning their own ack cycle) ────────────
+    /** Pull one raw message without calling a handler or auto-acking. */
+    async receiveRaw(vt = 30) {
+        await this._ensureGroup();
+        let raw = null;
+        const now = Date.now();
+        if (now - this.lastReclaimAt >= this.reclaimIntervalMs) {
+            this.lastReclaimAt = now;
+            raw = await this._reclaimOne(vt);
+        }
+        if (!raw)
+            raw = await this._readOne();
+        if (!raw)
+            return null;
+        const fr = this._msFromId(raw.id);
+        return { id: raw.id, message: raw.message, rc: raw.rc, fr, sent: fr };
+    }
+    /** XACK a message by ID. Returns true when the PEL entry was removed. */
+    async ack(id) {
+        return (await this._ack(id)) > 0;
+    }
+    /**
+     * XACK multiple messages in one roundtrip.
+     * All IDs must belong to this stream — guaranteed by the caller holding them from receiveRaw/receiveRawBatch.
+     * Returns the number of entries removed from the PEL.
+     */
+    async ackBatch(ids) {
+        if (ids.length === 0)
+            return 0;
+        return Number(await this.redis.xAck(this._streamKey(), this.group, ids)) || 0;
+    }
+    /**
+     * Pull up to `count` messages in one roundtrip (XREADGROUP COUNT N).
+     * Reclaim path uses a single XPENDING RANGE for all stale entries — no per-message round-trips.
+     * Returns an empty array when the queue is idle. Caller owns ack/deadLetter for each message.
+     */
+    async receiveRawBatch(vt = 30, count = 10) {
+        try {
+            return await this._receiveRawBatchImpl(vt, count);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isNoGroupError(msg)) {
+                // Stream or consumer group was wiped (e.g. Redis flush). Reset ensured flag
+                // so the next poll recreates stream+group via _ensureGroup(), then retry once.
+                this.ensured = false;
+                return this._receiveRawBatchImpl(vt, count);
+            }
+            throw err;
+        }
+    }
+    // eslint-disable-next-line complexity
+    async _receiveRawBatchImpl(vt = 30, count = 10) {
+        await this._ensureGroup();
+        const results = [];
+        // Throttled reclaim — one XAUTOCLAIM COUNT N for all stale entries
+        const now = Date.now();
+        if (now - this.lastReclaimAt >= this.reclaimIntervalMs) {
+            this.lastReclaimAt = now;
+            const claimed = await this.redis.xAutoClaim(this._streamKey(), this.group, this.consumer, vt * 1000, '0-0', { COUNT: count });
+            const messages = claimed?.messages ?? [];
+            if (messages.length > 0) {
+                // One XPENDING RANGE for all reclaimed IDs — single roundtrip for delivery counts
+                const sortedIds = messages.map(m => m.id).sort();
+                const deliveryMap = new Map();
+                try {
+                    const details = await this.redis.xPendingRange(this._streamKey(), this.group, sortedIds[0], sortedIds[sortedIds.length - 1], messages.length);
+                    for (const d of details) {
+                        deliveryMap.set(String(d.id ?? ''), Number(d.deliveriesCounter ?? 2));
+                    }
+                }
+                catch { /* defaults to 2 below */ }
+                for (const e of messages) {
+                    const fr = this._msFromId(e.id);
+                    results.push({
+                        id: e.id,
+                        message: String(e.message?.['p'] ?? ''),
+                        rc: deliveryMap.get(e.id) ?? 2,
+                        fr,
+                        sent: fr,
+                    });
+                }
+            }
+        }
+        // XREADGROUP COUNT (remaining) for new messages — one roundtrip
+        const remaining = count - results.length;
+        if (remaining > 0) {
+            const readResult = await this.redis.xReadGroup(this.group, this.consumer, [{ key: this._streamKey(), id: '>' }], { COUNT: remaining });
+            const entries = readResult?.[0]?.messages ?? [];
+            for (const e of entries) {
+                const fr = this._msFromId(e.id);
+                results.push({ id: e.id, message: String(e.message['p'] ?? ''), rc: 1, fr, sent: fr });
+            }
+        }
+        return results;
+    }
+    /** Move a message to the `:dlq` stream and XACK the source. */
+    async deadLetter(id, message, rc) {
+        await this._moveToDeadLetter(id, message, rc);
+        await this._ack(id);
+    }
+    // ─── Internal primitives ─────────────────────────────────────────────────────
+    async _readOne() {
+        try {
+            const result = await this.redis.xReadGroup(this.group, this.consumer, [{ key: this._streamKey(), id: '>' }], { COUNT: 1 });
+            if (!result?.length)
+                return null;
+            const entries = result[0]?.messages ?? [];
+            if (!entries.length)
+                return null;
+            const e = entries[0];
+            return { id: e.id, message: String(e.message['p'] ?? ''), rc: 1 };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isNoGroupError(msg)) {
+                this.ensured = false;
+                await this._ensureGroup();
+                return null; // idle — caller retries next poll
+            }
+            throw err;
+        }
+    }
+    async _reclaimOne(vt) {
+        try {
+            const result = await this.redis.xAutoClaim(this._streamKey(), this.group, this.consumer, vt * 1000, '0-0', { COUNT: 1 });
+            const messages = result?.messages;
+            if (!messages?.length)
+                return null;
+            const e = messages[0];
+            const rc = await this._deliveryCount(e.id);
+            return { id: e.id, message: String(e.message?.['p'] ?? ''), rc };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isNoGroupError(msg)) {
+                this.ensured = false;
+                await this._ensureGroup();
+                return null; // idle — caller retries next poll
+            }
+            throw err;
+        }
+    }
+    async _deliveryCount(id) {
+        try {
+            const detail = await this.redis.xPendingRange(this._streamKey(), this.group, id, id, 1);
+            return Number(detail?.[0]?.deliveriesCounter ?? 2);
+        }
+        catch {
+            return 2;
+        }
+    }
+    _ack(id) {
+        return this.redis.xAck(this._streamKey(), this.group, id);
+    }
+    _moveToDeadLetter(id, message, rc) {
+        return this.redis.xAdd(this._dlqKey(), '*', { p: message, src: id, rc: String(rc) }, { TRIM: { strategy: 'MAXLEN', strategyModifier: '~', threshold: this.maxLen } });
+    }
+    _msFromId(id) {
+        const dash = id.indexOf('-');
+        if (dash < 1)
+            return 0;
+        const ms = Number(id.slice(0, dash));
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    // ─── Attributes ──────────────────────────────────────────────────────────────
+    async attributes() {
+        try {
+            const [len, groups] = await Promise.all([
+                this.redis.xLen(this._streamKey()),
+                this.redis.xInfoGroups(this._streamKey()),
+            ]);
+            const g = groups.find((x) => x.name === this.group);
+            const totalsent = Number(len) || 0;
+            return {
+                msgs: totalsent,
+                hiddenmsgs: Number(g?.pending ?? 0),
+                totalsent,
+                totalrecv: Number(g?.['entries-read'] ?? g?.entriesRead ?? 0),
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isNoGroupError(msg) || msg.includes('ERR no such key'))
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Rich Streams-native snapshot — for dashboards, platform stats, admin UI.
+     * 4–5 parallel roundtrips (XLEN×2 + XINFO STREAM + XINFO GROUPS + optional XPENDING).
+     * Do NOT call on the hot message path — use attributes() there.
+     */
+    // eslint-disable-next-line complexity
+    async snapshot() {
+        try {
+            const [len, dlqLen, info, groups] = await Promise.all([
+                this.redis.xLen(this._streamKey()),
+                this.redis.xLen(this._dlqKey()).catch(() => 0),
+                this.redis.xInfoStream(this._streamKey()),
+                this.redis.xInfoGroups(this._streamKey()),
+            ]);
+            const g = groups.find((x) => x.name === this.group);
+            // totalsent: prefer entries-added (monotonic, survives TRIM, Redis 7.2+)
+            const totalsentExact = Number(info?.['entries-added'] ?? info?.entriesAdded ?? len) || 0;
+            // lag: messages not yet delivered (Redis 7.0+ native field, else compute from length - entries-read)
+            const lag = Number(g?.lag ?? Math.max(0, (Number(len) || 0) - Number(g?.['entries-read'] ?? g?.entriesRead ?? 0)));
+            // last-delivered-id ms component (e.g. "1717000000000-0" → 1717000000000)
+            const lastDeliveredId = g?.['last-delivered-id'] ?? g?.lastDeliveredId ?? '0-0';
+            const lastDeliveredMs = this._msFromId(lastDeliveredId);
+            // oldest pending: one extra roundtrip only when there's something in the PEL
+            let oldestPendingMs = 0;
+            const pendingCount = Number(g?.pending ?? 0);
+            if (pendingCount > 0) {
+                try {
+                    const oldest = await this.redis.xPendingRange(this._streamKey(), this.group, '-', '+', 1);
+                    if (oldest?.length > 0) {
+                        oldestPendingMs = this._msFromId(String(oldest[0]?.id ?? '0'));
+                    }
+                }
+                catch { /* non-fatal — oldest stays 0 */ }
+            }
+            // lastAddedMs: ms component of last-generated-id (last XADD)
+            const lastGeneratedId = info?.['last-generated-id'] ?? info?.lastGeneratedId ?? '0-0';
+            const lastAddedMs = this._msFromId(lastGeneratedId);
+            const msgs = Number(len) || 0;
+            const hiddenmsgs = pendingCount;
+            const totalrecv = Number(g?.['entries-read'] ?? g?.entriesRead ?? 0);
+            const dlqDepth = Number(dlqLen) || 0;
+            // ─── Derived (zero extra Redis calls) ───────────────────────────────────
+            const backpressure = lag + hiddenmsgs;
+            const consumptionRate = totalsentExact > 0 ? (totalrecv / totalsentExact) * 100 : 100;
+            const dlqRate = totalsentExact > 0 ? (dlqDepth / totalsentExact) * 100 : 0;
+            let health;
+            if (totalsentExact === 0 && dlqDepth === 0)
+                health = 'empty';
+            else if (oldestPendingMs > 0 && (Date.now() - oldestPendingMs) > 120_000)
+                health = 'stuck';
+            else if (lag > 0)
+                health = 'lagging';
+            else
+                health = 'healthy';
+            return {
+                msgs,
+                hiddenmsgs,
+                totalsent: msgs,
+                totalrecv,
+                lag,
+                consumers: Number(g?.consumers ?? 0),
+                dlqDepth,
+                totalsentExact,
+                lastDeliveredMs,
+                oldestPendingMs,
+                lastAddedMs,
+                backpressure,
+                consumptionRate,
+                dlqRate,
+                health,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isNoGroupError(msg) || msg.includes('ERR no such key'))
+                return null;
+            throw err;
+        }
+    }
+    // ─── Offline buffer ───────────────────────────────────────────────────────────
+    async _drainOffline() {
+        while (this.offlineBuffer.length > 0) {
+            const item = this.offlineBuffer.shift();
+            await this.send(item.message, item.delay);
+        }
+    }
+    // ─── Statics: schedule + thread pool ─────────────────────────────────────────
+    /** List all queue names registered in a namespace (reads from `{ns:QUEUES}` index set). */
+    static async listQueues(redis, ns) {
+        return ((await redis.sMembers(`{${ns}:QUEUES}`)) ?? []).sort();
+    }
+    /**
+     * Read-only aggregate snapshot across ALL consumer groups on a stream — no XGROUP CREATE.
+     * Use from dashboards instead of `new TSRQW(...).snapshot()` to avoid creating phantom groups.
+     *
+     * Aggregation rules (correct for fan-out / multi-group topologies):
+     *  - lag        : max across groups (worst consumer defines backpressure)
+     *  - consumers  : sum across groups (total workers active)
+     *  - totalrecv  : max entries-read across groups (how far the fastest consumer has reached)
+     *  - lastDeliveredMs: max last-delivered-id ms (most-recently-delivered across groups)
+     *  - dlqRate    : dlqDepth / totalsentExact capped at entries-read by the most-advanced group
+     *                 (avoids 100% false-positive when DLQ accumulated across stream recreations)
+     *
+     * Returns null when the stream does not exist.
+     */
+    // eslint-disable-next-line complexity
+    static async snapshotFromGroups(redis, ns, name) {
+        const streamKey = `{${ns}:${name}}:stream`;
+        const dlqKey = `{${ns}:${name}}:dlq`;
+        try {
+            const [len, dlqLen, info, groups] = await Promise.all([
+                redis.xLen(streamKey),
+                redis.xLen(dlqKey).catch(() => 0),
+                redis.xInfoStream(streamKey),
+                redis.xInfoGroups(streamKey).catch(() => []),
+            ]);
+            const gs = groups;
+            const msgs = Number(len) || 0;
+            const dlqDepth = Number(dlqLen) || 0;
+            const totalsentExact = Number(info?.['entries-added'] ?? info?.entriesAdded ?? msgs) || 0;
+            const lastGeneratedId = String(info?.['last-generated-id'] ?? info?.lastGeneratedId ?? '0-0');
+            const lastAddedMs = TSRQW._msFromIdStatic(lastGeneratedId);
+            // Exclude zero-activity groups (entries-read=0, pending=0) from the aggregate when
+            // active groups exist. These are either phantom monitoring groups created at $ that
+            // never consumed, or producer-only groups. Keeping them would inflate lag to the full
+            // stream length even though real consumers are current.
+            const activeGs = gs.filter((g) => Number(g?.['entries-read'] ?? g?.entriesRead ?? 0) > 0 || Number(g.pending ?? 0) > 0);
+            const effectiveGs = activeGs.length > 0 ? activeGs : gs;
+            // Aggregate across effective groups
+            let lag = 0;
+            let consumers = 0;
+            let totalrecv = 0;
+            let lastDeliveredMs = 0;
+            const oldestPendingMs = 0;
+            let hiddenmsgs = 0;
+            for (const g of effectiveGs) {
+                const gLag = Number(g.lag ?? Math.max(0, msgs - Number(g?.['entries-read'] ?? g?.entriesRead ?? 0)));
+                const gConsumers = Number(g.consumers ?? 0);
+                const gEntriesRead = Number(g?.['entries-read'] ?? g?.entriesRead ?? 0);
+                const gPending = Number(g.pending ?? 0);
+                const gLastId = String(g?.['last-delivered-id'] ?? g?.lastDeliveredId ?? '0-0');
+                const gLastMs = TSRQW._msFromIdStatic(gLastId);
+                lag = Math.max(lag, gLag);
+                consumers += gConsumers;
+                totalrecv = Math.max(totalrecv, gEntriesRead);
+                lastDeliveredMs = Math.max(lastDeliveredMs, gLastMs);
+                hiddenmsgs += gPending;
+            }
+            // dlqRate against entries-read by the most-advanced group to avoid false 100% when
+            // DLQ accumulated across stream recreations (entries-added resets, DLQ does not)
+            const dlqBase = totalrecv > 0 ? totalrecv : totalsentExact;
+            const consumptionRate = totalsentExact > 0 ? (totalrecv / totalsentExact) * 100 : 100;
+            const dlqRate = dlqBase > 0 ? (dlqDepth / dlqBase) * 100 : 0;
+            const backpressure = lag + hiddenmsgs;
+            let health;
+            if (totalsentExact === 0 && dlqDepth === 0)
+                health = 'empty';
+            else if (oldestPendingMs > 0 && (Date.now() - oldestPendingMs) > 120_000)
+                health = 'stuck';
+            else if (lag > 0)
+                health = 'lagging';
+            else
+                health = 'healthy';
+            return {
+                msgs, hiddenmsgs,
+                totalsent: msgs,
+                totalrecv,
+                lag,
+                consumers,
+                dlqDepth,
+                totalsentExact,
+                lastDeliveredMs,
+                oldestPendingMs,
+                lastAddedMs,
+                backpressure,
+                consumptionRate,
+                dlqRate,
+                health,
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('ERR no such key') || msg.includes('WRONGTYPE'))
+                return null;
+            throw err;
+        }
+    }
+    static _msFromIdStatic(id) {
+        const ms = parseInt(id.split('-')[0] ?? '0', 10);
+        return isNaN(ms) ? 0 : ms;
+    }
+    static schedule({ onTick = () => { }, onComplete = null, runOnInit = false, cronTime = '*/9 * * * * *', context = null, start = false, timeZone = 'utc', }) {
+        return new cron_1.CronJob(cronTime, onTick, onComplete, start, timeZone, context, runOnInit);
+    }
+    static worker(cb, factor = 1, wd) {
+        return new TSRQWPool(factor, cb, wd);
+    }
+}
+exports.TSRQW = TSRQW;