@oneunit/redis 0.0.0-stage → 1.0.0

package/dist/pipeline/builder.js

@@ -0,0 +1,197 @@
+import {} from "ioredis";
+import { normalizeLogger } from "../logger.js";
+import { redactError } from "../client/events.js";
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Whether a value is promise-like, i.e. something a caller forgot to await. */
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.then === "function");
+}
+export class PipelineTimeoutError extends Error {
+    steps;
+    constructor(timeout, steps) {
+        super(`Redis pipeline of ${steps} command${steps === 1 ? "" : "s"} did not complete within ${timeout}ms`);
+        this.name = "PipelineTimeoutError";
+        this.steps = steps;
+    }
+}
+/**
+ * Thrown when `throwOnError` is set and a command failed.
+ *
+ * Carries the per-step results so the caller can see which command broke
+ * without re-running the batch. The `message` lists labels only — ioredis
+ * attaches command arguments to its errors, and a pipeline that batched an
+ * `AUTH` would otherwise put the password in an exception message.
+ */
+export class PipelineCommandError extends Error {
+    results;
+    constructor(results) {
+        const failed = results.filter((result) => result.error);
+        super(`Redis pipeline: ${failed.length} of ${results.length} commands failed (${failed
+            .map((result) => result.label)
+            .join(", ")})`);
+        this.name = "PipelineCommandError";
+        this.results = results;
+    }
+}
+/**
+ * Thrown when a step does not queue exactly one command.
+ *
+ * `PipelineStep.run` is typed as returning `void`, and TypeScript allows any
+ * value to be returned from a `void` signature — so a step that queues two
+ * commands, or an `async` step whose command is only queued after `runPipeline`
+ * has already called `exec`, compiles without complaint. Both shift the
+ * positional pairing between `steps` and the result tuples, which is the one
+ * thing the label exists to prevent, so the batch is rejected rather than
+ * returned with a value against the wrong label.
+ */
+export class PipelineStepError extends Error {
+    label;
+    queued;
+    constructor(label, queued) {
+        super(`Redis pipeline step "${label}" queued ${queued} command${queued === 1 ? "" : "s"}, expected exactly 1`);
+        this.name = "PipelineStepError";
+        this.label = label;
+        this.queued = queued;
+    }
+}
+/**
+ * Run a batch of commands in one round trip.
+ *
+ * Wraps `client.pipeline()` rather than reimplementing it. The value is in the
+ * four sharp edges this closes, all of which are silent in ioredis itself:
+ *
+ * 1. **A failed command does not fail the pipeline.** EXEC resolves with a
+ *    `[error, null]` tuple for the command that failed. Code that reads
+ *    `results.map(([, value]) => value)` gets `null` and carries on as if the
+ *    write landed. Every result here carries an explicit `error` field.
+ * 2. **EXEC can hang forever.** ioredis parks queued commands while
+ *    reconnecting. `timeout` bounds that.
+ * 3. **Command errors carry their arguments.** Redacted via `redactError`
+ *    before they reach a logger or an exception — on both the per-command
+ *    results and a rejected `exec()`.
+ * 4. **Results are positional.** Each step must queue exactly one command, or
+ *    every later label is paired with the wrong value. A step that does not
+ *    raises `PipelineStepError`.
+ */
+export async function runPipeline(client, steps, options = {}) {
+    const logger = normalizeLogger(options.logger);
+    const requested = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    // setTimeout coerces a negative or NaN budget to 1ms and prints a warning for
+    // each; treat any invalid value as "no bound configured" instead.
+    const timeout = Number.isFinite(requested) && requested > 0
+        ? requested
+        : DEFAULT_TIMEOUT_MS;
+    if (steps.length === 0) {
+        // No round trip is needed, and building a pipeline just to exec an empty
+        // one is a wasted allocation.
+        return { results: [], durationMs: 0, failed: 0 };
+    }
+    const pipeline = client.pipeline();
+    for (const step of steps) {
+        // Results are paired with steps by position, so the queue has to grow by
+        // exactly one per step. `length` is ioredis's own queue length, and it is
+        // read before and after rather than counted here so the check is against
+        // what was actually queued, not against what `run` appears to have done.
+        const before = pipeline.length;
+        let returned;
+        try {
+            returned = step.run(pipeline);
+        }
+        catch (error) {
+            // A throwing `run` means the command was never queued, so the batch is
+            // already malformed. Fail the whole pipeline: silently dropping the
+            // command would shift every later result by one and return the wrong
+            // value against the wrong label.
+            logger?.error(`Redis pipeline step failed to queue: ${step.label}`, {
+                err: redactError(error),
+            });
+            throw error;
+        }
+        const queued = pipeline.length - before;
+        if (isThenable(returned)) {
+            // An `async` step is invisible to the count below: it queues nothing
+            // synchronously, so `exec()` runs first and the command it was going to
+            // queue lands in a pipeline that has already been sent. TypeScript
+            // permits returning a value from a `void`-typed signature, so this is
+            // not a compile error either.
+            //
+            // The step's promise is abandoned here, so its eventual rejection is
+            // nobody's to handle — which on Node 20 is a process-level crash that
+            // would mask the error naming the actual fault. Swallow it; the throw
+            // below is the real diagnosis.
+            void Promise.resolve(returned).catch(() => undefined);
+            logger?.error(`Redis pipeline step returned a promise instead of queuing: ${step.label}`);
+            throw new PipelineStepError(step.label, queued);
+        }
+        if (queued !== 1) {
+            logger?.error(`Redis pipeline step queued ${queued} commands: ${step.label}`);
+            throw new PipelineStepError(step.label, queued);
+        }
+    }
+    const started = performance.now();
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), timeout);
+    });
+    let raw;
+    try {
+        const outcome = await Promise.race([pipeline.exec(), expiry]);
+        if (outcome === "timeout") {
+            throw new PipelineTimeoutError(timeout, steps.length);
+        }
+        raw = outcome;
+    }
+    catch (error) {
+        if (error instanceof PipelineTimeoutError) {
+            throw error;
+        }
+        // A rejected `exec()` is a connection-level failure, and it bypasses the
+        // per-tuple redaction below entirely. The module documents that errors are
+        // redacted, so the rejection goes through the same path rather than
+        // reaching the caller — and from there a logger — as ioredis built it.
+        throw redactError(error);
+    }
+    finally {
+        // A pending timeout keeps the event loop alive. Always clear it, including
+        // on the timeout path where it has already fired.
+        clearTimeout(timer);
+    }
+    const results = raw.map(([error, value], index) => {
+        const step = steps[index];
+        return {
+            label: step?.label ?? `#${index}`,
+            value,
+            // Redacted here rather than at each call site so a caller that logs a
+            // whole result array cannot leak credentials by accident.
+            ...(error ? { error: redactError(error) } : {}),
+        };
+    });
+    const failed = results.filter((result) => result.error).length;
+    const durationMs = Math.round(performance.now() - started);
+    if (failed > 0) {
+        logger?.warn(`Redis pipeline: ${failed} of ${results.length} commands failed`);
+    }
+    logger?.debug?.(`Redis pipeline completed ${results.length} command${results.length === 1 ? "" : "s"} in ${durationMs}ms`);
+    if (failed > 0 && options.throwOnError) {
+        throw new PipelineCommandError(results);
+    }
+    return { results, durationMs, failed };
+}
+/**
+ * Values of the successful results, in order.
+ *
+ * Throws if any command failed, because the alternative is handing back a
+ * sparse array whose length matches the batch but whose contents silently
+ * include a failed write. Use `results` directly when a partial batch is
+ * expected and worth handling.
+ */
+export function pipelineValues(results) {
+    const failed = results.find((result) => result.error);
+    if (failed) {
+        throw new PipelineCommandError(results);
+    }
+    return results.map((result) => result.value);
+}
+//# sourceMappingURL=builder.js.map

package/dist/pipeline/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/pipeline/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsD,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAe,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAqDlD,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,gFAAgF;AAChF,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,UAAU,CACzD,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,KAAK,CAAS;IAEvB,YAAY,OAAe,EAAE,KAAa;QACxC,KAAK,CACH,qBAAqB,KAAK,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,4BAA4B,OAAO,IAAI,CACnG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,OAAO,CAAuB;IAEvC,YAAY,OAA6B;QACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxD,KAAK,CACH,mBAAmB,MAAM,CAAC,MAAM,OAAO,OAAO,CAAC,MAAM,qBAAqB,MAAM;aAC7E,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC;aAC7B,IAAI,CAAC,IAAI,CAAC,GAAG,CACjB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,KAAK,CAAS;IACd,MAAM,CAAS;IAExB,YAAY,KAAa,EAAE,MAAc;QACvC,KAAK,CACH,wBAAwB,KAAK,YAAY,MAAM,WAC7C,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACtB,sBAAsB,CACvB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAmB,EACnB,KAAqB,EACrB,UAA2B,EAAE;IAE7B,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,IAAI,kBAAkB,CAAC;IACxD,8EAA8E;IAC9E,kEAAkE;IAClE,MAAM,OAAO,GACX,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC;QACzC,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,kBAAkB,CAAC;IAEzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,yEAAyE;QACzE,8BAA8B;QAC9B,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACnD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,yEAAyE;QACzE,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAE/B,IAAI,QAAiB,CAAC;QAEtB,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,uEAAuE;YACvE,oEAAoE;YACpE,qEAAqE;YACrE,iCAAiC;YACjC,MAAM,EAAE,KAAK,CAAC,wCAAwC,IAAI,CAAC,KAAK,EAAE,EAAE;gBAClE,GAAG,EAAE,WAAW,CAAC,KAAK,CAAC;aACxB,CAAC,CAAC;YAEH,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;QAExC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,qEAAqE;YACrE,wEAAwE;YACxE,mEAAmE;YACnE,sEAAsE;YACtE,8BAA8B;YAC9B,EAAE;YACF,qEAAqE;YACrE,sEAAsE;YACtE,sEAAsE;YACtE,+BAA+B;YAC/B,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAEtD,MAAM,EAAE,KAAK,CACX,8DAA8D,IAAI,CAAC,KAAK,EAAE,CAC3E,CAAC;YAEF,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;YACjB,MAAM,EAAE,KAAK,CACX,8BAA8B,MAAM,cAAc,IAAI,CAAC,KAAK,EAAE,CAC/D,CAAC;YAEF,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAElC,IAAI,KAAiC,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE;QAChD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,IAAI,GAAmC,CAAC;IAExC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QAE9D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;QAED,GAAG,GAAG,OAAyC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;YAC1C,MAAM,KAAK,CAAC;QACd,CAAC;QAED,yEAAyE;QACzE,2EAA2E;QAC3E,oEAAoE;QACpE,uEAAuE;QACvE,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,2EAA2E;QAC3E,kDAAkD;QAClD,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,MAAM,OAAO,GAAyB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE;QACtE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAE1B,OAAO;YACL,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,IAAI,KAAK,EAAE;YACjC,KAAK;YACL,sEAAsE;YACtE,0DAA0D;YAC1D,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;IAE3D,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,EAAE,IAAI,CACV,mBAAmB,MAAM,OAAO,OAAO,CAAC,MAAM,kBAAkB,CACjE,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,CACb,4BAA4B,OAAO,CAAC,MAAM,WACxC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC9B,OAAO,UAAU,IAAI,CACtB,CAAC;IAEF,IAAI,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACvC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,OAA6B;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/pipeline/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./builder.js";
+export type { PipelineStep, PipelineOptions, PipelineResult, PipelineStepResult, } from "./builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/pipeline/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,YAAY,EACV,YAAY,EACZ,eAAe,EACf,cAAc,EACd,kBAAkB,GACnB,MAAM,cAAc,CAAC"}

package/dist/pipeline/index.js

@@ -0,0 +1,2 @@
+export * from "./builder.js";
+//# sourceMappingURL=index.js.map

package/dist/pipeline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/queue/events.d.ts

@@ -0,0 +1,13 @@
+import { QueueEvents, type QueueEventsOptions } from "bullmq";
+import { Queue } from "bullmq";
+import type { Logger } from "../logger.js";
+export interface QueueEventsConfig {
+    queue: Queue;
+    logger?: Logger;
+    prefix?: string;
+    connection?: QueueEventsOptions["connection"];
+}
+export declare function attachQueueEvents(config: QueueEventsConfig): QueueEvents;
+export type { QueueEventsOptions } from "bullmq";
+export { QueueEvents } from "bullmq";
+//# sourceMappingURL=events.d.ts.map

package/dist/queue/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/queue/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,KAAK,kBAAkB,EACxB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAC/B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAK3C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;CAC/C;AAmFD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAuDxE;AAED,YAAY,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC"}

package/dist/queue/events.js

@@ -0,0 +1,109 @@
+import { ConnectionClosedError, QueueEvents, } from "bullmq";
+import { Queue } from "bullmq";
+import { normalizeLogger } from "../logger.js";
+import { redactError } from "../client/events.js";
+/**
+ * QueueEvents that can be closed after a failed startup.
+ *
+ * BullMQ's own `close()` awaits `this.client` before disconnecting, and that
+ * getter resolves to the connection's `initializing` promise. When the
+ * connection never became ready that promise has already rejected with
+ * "Connection is closed.", so `close()` throws before it reaches
+ * `connection.close()` and the duplicated ioredis client is left running its
+ * reconnect loop. Nothing else in the process can stop it, because the caller
+ * has no reference to the duplicate, so the process never exits.
+ *
+ * `Queue` does not have this problem: `RedisConnection.close()` handles
+ * `status === "initializing"` itself.
+ *
+ * Disconnecting the duplicate first is safe in both directions. When the
+ * connection is healthy, `disconnect()` ends it and the subsequent
+ * `connection.close()` sees a client already at `end` and skips its own quit.
+ */
+class ManagedQueueEvents extends QueueEvents {
+    async close() {
+        const connection = this.connection;
+        // A duplicate that is already gone does not need disconnecting, and
+        // `disconnect()` is a no-op at `end`.
+        connection._client?.disconnect();
+        try {
+            await super.close();
+        }
+        catch (error) {
+            // `super.close()` propagates the rejection from the failed startup
+            // instead of reporting that the connection is now closed. The connection
+            // itself does know how to close from `initializing`, so drive it directly
+            // and only rethrow errors that are not about the connection being gone.
+            await connection.close(true).catch(() => undefined);
+            if (!isConnectionGone(error)) {
+                throw error;
+            }
+        }
+    }
+}
+/**
+ * True for the "this connection is already gone" family of errors.
+ *
+ * `ConnectionClosedError` is checked first and structurally, because BullMQ
+ * introduced it for exactly this reason — its own comment on the class says it
+ * exists so `isNotConnectionError` can "do a structural `instanceof` check
+ * rather than fragile message-substring matching". Matching the message cannot
+ * work here: only some of BullMQ's construction sites pass ioredis's
+ * `CONNECTION_CLOSED_ERROR_MSG`, and the others pass their own wording or no
+ * message at all, in which case the class default (`"Connection is closed"`,
+ * with no trailing period) applies. An exact string comparison therefore
+ * rethrows precisely the failures this function exists to absorb, and the
+ * caller gets an exception from teardown instead of a clean close.
+ *
+ * The string clauses stay as a fallback: they still cover a `bullmq` error that
+ * predates the class, and an error forwarded from another adapter. `instanceof`
+ * is identity-based, so a consumer with two copies of `bullmq` in one tree
+ * would miss the class check — the fallbacks catch the ioredis wording, and
+ * missing them is the safe direction to fail.
+ */
+function isConnectionGone(error) {
+    if (error instanceof ConnectionClosedError) {
+        return true;
+    }
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return (error.message === "Connection is closed." ||
+        error.message.includes("ECONNREFUSED") ||
+        error.code === "ECONNREFUSED");
+}
+export function attachQueueEvents(config) {
+    const { queue, connection } = config;
+    // BullMQ swallows a throwing event listener and re-emits the failure as an
+    // "error" event, which then throws again and lands on console.error. A logger
+    // missing `info` would trigger that on every completed job.
+    const logger = normalizeLogger(config.logger);
+    // QueueEvents subscribes to a key derived from the prefix. Defaulting to a
+    // literal "queue" here silently dropped every event for a queue created
+    // with a custom prefix, so inherit the queue's own prefix instead.
+    const prefix = config.prefix ?? queue.opts.prefix ?? "queue";
+    const queueEvents = new ManagedQueueEvents(queue.name, {
+        prefix,
+        connection: connection ?? queue.opts.connection,
+    });
+    queueEvents.on("completed", (args, _id) => {
+        logger?.info(`Job ${args.jobId} completed`);
+    });
+    queueEvents.on("failed", (args, _id) => {
+        logger?.error(`Job ${args.jobId} failed`, args.failedReason);
+    });
+    queueEvents.on("progress", (args, _id) => {
+        logger?.info(`Job ${args.jobId} progress`, args.data);
+    });
+    queueEvents.on("error", (error) => {
+        // QueueEvents duplicates the caller's client, so it authenticates with the
+        // same password and BullMQ re-emits any AUTH failure here. ioredis attaches
+        // the failing command to that error, and for AUTH its args are the password
+        // in plaintext — logging it as-is would write the credential to the app's
+        // log on every reconnect attempt against a misconfigured server.
+        logger?.error(`Queue "${queue.name}" events error`, redactError(error));
+    });
+    return queueEvents;
+}
+export { QueueEvents } from "bullmq";
+//# sourceMappingURL=events.js.map

package/dist/queue/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/queue/events.ts"],"names":[],"mappings":"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"}

package/dist/queue/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./queue.js";
+export * from "./worker.js";
+export * from "./events.js";
+export type { QueueConfig } from "./queue.js";
+export type { WorkerConfig } from "./worker.js";
+export type { QueueEventsConfig } from "./events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/queue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/queue/index.js

@@ -0,0 +1,4 @@
+export * from "./queue.js";
+export * from "./worker.js";
+export * from "./events.js";
+//# sourceMappingURL=index.js.map

package/dist/queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/queue/queue.d.ts

@@ -0,0 +1,13 @@
+import { Queue, type QueueOptions, type JobsOptions } from "bullmq";
+import { type Redis as RedisClient } from "ioredis";
+export interface QueueConfig {
+    name: string;
+    connection: RedisClient;
+    prefix?: string;
+    defaultJobOptions?: JobsOptions;
+    settings?: QueueOptions["settings"];
+}
+export declare function createQueue(config: QueueConfig): Queue;
+export type { QueueOptions, JobsOptions } from "bullmq";
+export { Queue } from "bullmq";
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/queue/queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,KAAK,KAAK,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,WAAW,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CA6CtD;AAED,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC"}

package/dist/queue/queue.js

@@ -0,0 +1,37 @@
+import { Queue } from "bullmq";
+import {} from "ioredis";
+export function createQueue(config) {
+    const { name, connection, prefix = "queue", defaultJobOptions, settings, ...options } = config;
+    const defaults = {
+        removeOnComplete: 100,
+        removeOnFail: 1000,
+        attempts: 3,
+        backoff: {
+            type: "exponential",
+            delay: 1000,
+        },
+    };
+    // Merged key by key rather than by spreading. A spread writes `undefined` for
+    // every key the caller left unset, which erases the default instead of falling
+    // through to it — and that is how a config built by spreading another object
+    // (`{ ...base, attempts: maybeUndefined }`) quietly loses the package default.
+    // `null` is a deliberate value rather than a missing one, so it passes
+    // through: `removeOnComplete: null` is how BullMQ is told to keep a job.
+    const merged = { ...defaults };
+    for (const [key, value] of Object.entries(defaultJobOptions ?? {})) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    const queueOptions = {
+        prefix,
+        connection,
+        defaultJobOptions: merged,
+        ...(settings === undefined ? {} : { settings }),
+        ...options,
+    };
+    const queue = new Queue(name, queueOptions);
+    return queue;
+}
+export { Queue } from "bullmq";
+//# sourceMappingURL=queue.js.map

package/dist/queue/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/queue/queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAuC,MAAM,QAAQ,CAAC;AACpE,OAAO,EAA6B,MAAM,SAAS,CAAC;AAUpD,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,MAAM,EACJ,IAAI,EACJ,UAAU,EACV,MAAM,GAAG,OAAO,EAChB,iBAAiB,EACjB,QAAQ,EACR,GAAG,OAAO,EACX,GAAG,MAAM,CAAC;IAEX,MAAM,QAAQ,GAAgB;QAC5B,gBAAgB,EAAE,GAAG;QACrB,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE;YACP,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,IAAI;SACZ;KACF,CAAC;IAEF,8EAA8E;IAC9E,+EAA+E;IAC/E,6EAA6E;IAC7E,+EAA+E;IAC/E,uEAAuE;IACvE,yEAAyE;IACzE,MAAM,MAAM,GAA4B,EAAE,GAAG,QAAQ,EAAE,CAAC;IAExD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,IAAI,EAAE,CAAC,EAAE,CAAC;QACnE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAiB;QACjC,MAAM;QACN,UAAU;QACV,iBAAiB,EAAE,MAAqB;QACxC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC/C,GAAG,OAAO;KACX,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAE5C,OAAO,KAAK,CAAC;AACf,CAAC;AAGD,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC"}

package/dist/queue/worker.d.ts

@@ -0,0 +1,15 @@
+import { Worker, type WorkerOptions, type Processor } from "bullmq";
+import { type Redis as RedisClient } from "ioredis";
+export interface WorkerConfig<T = unknown> {
+    name: string;
+    processor: Processor<T>;
+    connection: RedisClient;
+    prefix?: string;
+    concurrency?: number;
+    limiter?: WorkerOptions["limiter"];
+    settings?: WorkerOptions["settings"];
+}
+export declare function createWorker<T = unknown>(config: WorkerConfig<T>): Worker<T>;
+export type { WorkerOptions, Job, Processor } from "bullmq";
+export { Worker } from "bullmq";
+//# sourceMappingURL=worker.d.ts.map

package/dist/queue/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/queue/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,KAAK,KAAK,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACxB,UAAU,EAAE,WAAW,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACtC;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CA2B5E;AAED,YAAY,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC"}

package/dist/queue/worker.js

@@ -0,0 +1,20 @@
+import { Worker } from "bullmq";
+import {} from "ioredis";
+export function createWorker(config) {
+    const { name, processor, connection, prefix = "queue", concurrency, limiter, settings, ...options } = config;
+    // BullMQ only falls back to its own defaults for keys that are absent.
+    // Spreading an explicit `undefined` overrides `concurrency: 1` and trips
+    // its `concurrency must be a finite number greater than 0` setter.
+    const workerOptions = {
+        prefix,
+        connection,
+        ...(concurrency === undefined ? {} : { concurrency }),
+        ...(limiter === undefined ? {} : { limiter }),
+        ...(settings === undefined ? {} : { settings }),
+        ...options,
+    };
+    const worker = new Worker(name, processor, workerOptions);
+    return worker;
+}
+export { Worker } from "bullmq";
+//# sourceMappingURL=worker.js.map

package/dist/queue/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/queue/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAsC,MAAM,QAAQ,CAAC;AACpE,OAAO,EAA6B,MAAM,SAAS,CAAC;AAYpD,MAAM,UAAU,YAAY,CAAc,MAAuB;IAC/D,MAAM,EACJ,IAAI,EACJ,SAAS,EACT,UAAU,EACV,MAAM,GAAG,OAAO,EAChB,WAAW,EACX,OAAO,EACP,QAAQ,EACR,GAAG,OAAO,EACX,GAAG,MAAM,CAAC;IAEX,uEAAuE;IACvE,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,aAAa,GAAkB;QACnC,MAAM;QACN,UAAU;QACV,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;QACrD,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;QAC7C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC/C,GAAG,OAAO;KACX,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,MAAM,CAAI,IAAI,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAE7D,OAAO,MAAM,CAAC;AAChB,CAAC;AAGD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC"}

package/examples/README.md

@@ -0,0 +1,86 @@
+# Examples
+
+Runnable scripts for `@oneunit/redis`. Each one is standalone and needs nothing
+but a Redis server and the package built.
+
+```bash
+cd packages/redis
+npm install
+npm run build        # the example scripts import the package by name, which
+                     # resolves through the exports map to dist/
+```
+
+Then start Redis (any 6.x or 7.x server) and run one:
+
+```bash
+npm run example:standalone      # client: health, read/write, TTL
+npm run example:cache           # read-through cache with TTL and invalidation
+npm run example:session         # session store: create, update, expire, delete
+npm run example:pubsub          # publish/subscribe across two clients
+npm run example:queue-worker    # BullMQ queue, worker, retries, queue events
+npm run example:pipeline        # batching many commands into one round trip
+```
+
+`example:queue-worker` finishes on its own once the demo jobs settle. The others
+exit immediately.
+
+## Environment
+
+| Variable             | Default                  | Purpose                                            |
+| :------------------- | :----------------------- | :------------------------------------------------- |
+| `REDIS_URL`          | `redis://localhost:6379` | Connection URL                                     |
+| `REDIS_SILENT`       | unset                    | Set to `true` to suppress connection-event logging |
+| `EXAMPLE_TIMEOUT_MS` | `5000`                   | Bound for the pub/sub subscription check           |
+
+## What each one covers
+
+**`standalone.js`** — the client on its own. Health check, `SET`/`GET`, the
+atomic `INCRBY`, and `EXPIRE`/`TTL`. Shows the defaults that make one client work
+for both plain commands and BullMQ.
+
+**`cache.js`** — read-through caching. The same read served in ~1ms from Redis
+versus ~50ms from the "database", plus cache invalidation and why `SCAN` is
+preferred over `KEYS`.
+
+**`session.js`** — a session store. Create, read, update, extend, and destroy,
+including the sliding-TTL pattern and how to refresh a TTL without rewriting the
+payload.
+
+**`pubsub.js`** — two clients, because a Redis connection in subscriber mode
+cannot issue other commands. Also shows why you confirm the subscription count
+before publishing: pub/sub does not queue for a subscriber that is not attached.
+
+**`queue-worker.js`** — the full BullMQ surface. Job defaults from `createQueue`,
+a worker with retries and exponential backoff (one job deliberately fails all
+three attempts), and `attachQueueEvents` observing completion and failure over
+its own connection. Shows the shutdown order.
+
+**`pipeline.js`** — `runPipeline` for batch work. Writes and reads 100 keys in
+one round trip, then deliberately includes an `INCR` on a string key so a single
+command fails: the batch still resolves, and the example prints which command
+failed. That is the case a bare `client.pipeline()` hides. Also shows
+`pipelineValues` and `throwOnError`.
+
+Note the shape of every step: one command, and the step returns nothing. That is
+the contract, not a style preference — `runPipeline` matches results to steps by
+position, so a step that queued two commands would report a real value against
+the wrong label, and it raises `PipelineStepError` rather than letting that
+through. Each entry here is a single `void pipeline.<cmd>(...)`.
+
+## Things the examples avoid
+
+Queue names contain no `:` — BullMQ rejects them, which is what stops one queue
+addressing another's keys.
+
+`attachQueueEvents` takes no `prefix` here so it inherits the queue's. Setting a
+prefix on the queue and worker but not the listener is the easy way to end up
+with a worker polling one key and a listener subscribed to another, receiving no
+events and no error.
+
+Pub/sub uses explicit `sleep` between publishes instead of nesting `setTimeout`
+callbacks, so an error in one publish is caught rather than becoming an unhandled
+rejection after the script has already claimed success.
+
+Every example reports failure through `run()` in `_setup.js`, which sets a
+non-zero exit code. `catch(console.error)` on its own leaves the process exiting
+`0`, so a broken example passes any check that looks at the exit status.