@babelqueue/redis 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# @babelqueue/redis
+
+Redis adapter for [BabelQueue](https://babelqueue.com) — a canonical-envelope **publisher** and a
+URN-routed **consumer** over the §1 reliable-queue pattern, so a Redis-based Node service speaks
+the same wire contract as the PHP, Python and Go SDKs. Implements
+[§1 of the broker-bindings contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#redis).
+
+Redis lists carry **no native metadata** — the list element **is** the canonical envelope JSON,
+byte-for-byte, with **no wrapping** (unlike `@babelqueue/bullmq`, which uses BullMQ's own job
+layout). Produce is `RPUSH`; consume reserves the head into a `<queue>:processing` list
+(`BRPOPLPUSH`, so an in-flight message survives a crash), routes by URN, and `LREM`s it on success.
+
+> This is a Node-owned reliable queue. Full parity with Laravel's reserved-sorted-set reservation
+> on a *shared* Redis queue is a separate task — for a mixed PHP+Node fleet, prefer a queue this
+> consumer owns end-to-end.
+
+## Install
+
+```bash
+npm install @babelqueue/redis ioredis
+```
+
+`ioredis` is an optional peer — you provide the client; an `ioredis` instance satisfies the
+adapter structurally.
+
+## Produce
+
+```ts
+import Redis from "ioredis";
+import { RedisPublisher } from "@babelqueue/redis";
+
+const client = new Redis("redis://localhost:6379/0");
+const id = await RedisPublisher.create(client, "orders").publish("urn:babel:orders:created", { order_id: 1042 });
+```
+
+`publish(urn, data, { traceId? })` returns the message `meta.id`.
+
+## Consume
+
+```ts
+import { RedisConsumer, type BabelHandlers } from "@babelqueue/redis";
+
+const handlers: BabelHandlers = {
+  "urn:babel:orders:created": (envelope, raw) => {
+    // envelope.data, envelope.trace_id, envelope.attempts ...
+  },
+};
+
+const consumer = new RedisConsumer(client, "orders", handlers, {
+  maxTries: 3,            // requeue with attempts+1, then <queue>.dlq
+  onError: (err) => console.error(err),
+});
+
+await consumer.run(() => true); // reserve → process → LREM, until you stop it
+```
+
+A successful handler `LREM`s the element from `<queue>:processing`. A throwing handler requeues
+the envelope with `attempts + 1` (at-least-once) up to `maxTries`, then dead-letters to
+`<queue>.dlq` with a `dead_letter` block. Unknown-URN strategy is one of
+`fail` / `delete` / `release` / `dead_letter`. `poll()` and `handle(raw)` are exposed for testing.
+
+## Contract mapping (§1)
+
+| Envelope | Redis |
+| :--- | :--- |
+| body | the list element — the canonical envelope JSON, **verbatim** (no wrapping) |
+| produce | `RPUSH <queue> <envelope>` |
+| reserve | `BRPOPLPUSH <queue> <queue>:processing` (crash-safe) |
+| ack | `LREM <queue>:processing 1 <element>` |
+| retry | requeue with `attempts + 1` (the body owns the count) |
+| dead-letter | `RPUSH <queue>.dlq` + `dead_letter` block |
+
+The envelope is unchanged (`schema_version` stays `1`). The `ioredis` client is replaced with a
+fake in the unit suite — no Redis, no network.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RedisConsumer: () => RedisConsumer,
+  RedisPublisher: () => RedisPublisher,
+  redisValue: () => redisValue
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@babelqueue/core");
+function redisValue(envelope) {
+  return import_core.EnvelopeCodec.encode(envelope);
+}
+var RedisPublisher = class _RedisPublisher {
+  constructor(client, queue) {
+    this.client = client;
+    this.queue = queue;
+  }
+  client;
+  queue;
+  /** A publisher over `client`, producing to the list named `queue`. */
+  static create(client, queue) {
+    return new _RedisPublisher(client, queue);
+  }
+  /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */
+  async publish(urn, data, options = {}) {
+    const envelope = import_core.EnvelopeCodec.make(urn, data, { queue: this.queue, traceId: options.traceId });
+    await this.client.rpush(this.queue, redisValue(envelope));
+    return envelope.meta.id;
+  }
+};
+var RedisConsumer = class {
+  constructor(client, queue, handlers, options = {}) {
+    this.client = client;
+    this.queue = queue;
+    this.handlers = handlers;
+    this.options = options;
+    this.processing = queue + (options.processingSuffix ?? ":processing");
+    this.blockTimeout = options.blockTimeout ?? 5;
+    this.maxTries = options.maxTries ?? 3;
+    this.dlq = options.deadLetterQueue === void 0 ? `${queue}.dlq` : options.deadLetterQueue;
+    this.unknownUrn = options.unknownUrn ?? import_core.UnknownUrnStrategy.FAIL;
+  }
+  client;
+  queue;
+  handlers;
+  options;
+  processing;
+  blockTimeout;
+  maxTries;
+  dlq;
+  unknownUrn;
+  /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */
+  async poll() {
+    const raw = await this.client.brpoplpush(this.queue, this.processing, this.blockTimeout);
+    if (raw == null) return false;
+    await this.handle(raw);
+    return true;
+  }
+  /** Poll while `shouldContinue` returns true. */
+  async run(shouldContinue) {
+    while (shouldContinue()) {
+      await this.poll();
+    }
+  }
+  /** Route + settle one reserved element. Exposed for testing. */
+  async handle(raw) {
+    const decoded = import_core.EnvelopeCodec.decode(raw);
+    if (!import_core.EnvelopeCodec.accepts(decoded)) {
+      this.report(new import_core.BabelQueueError("Rejected a non-conformant BabelQueue envelope from Redis."), decoded, raw);
+      await this.deadLetterRaw(raw);
+      await this.settle(raw);
+      return;
+    }
+    const envelope = decoded;
+    const urn = import_core.EnvelopeCodec.urn(envelope);
+    const handler = this.handlers[urn];
+    if (!handler) {
+      await this.onUnknownUrn(envelope, urn, raw);
+      return;
+    }
+    try {
+      await handler(envelope, raw);
+      await this.settle(raw);
+    } catch (error) {
+      this.report(error, envelope, raw);
+      await this.retryOrDeadLetter(envelope, raw, error);
+    }
+  }
+  async onUnknownUrn(envelope, urn, raw) {
+    switch (this.unknownUrn) {
+      case import_core.UnknownUrnStrategy.DELETE:
+        await this.settle(raw);
+        return;
+      case import_core.UnknownUrnStrategy.DEAD_LETTER:
+        await this.deadLetter(envelope, "unknown_urn");
+        await this.settle(raw);
+        return;
+      case import_core.UnknownUrnStrategy.RELEASE:
+        await this.requeue(envelope);
+        await this.settle(raw);
+        return;
+      default: {
+        const error = new import_core.UnknownUrnError(urn);
+        this.report(error, envelope, raw);
+        throw error;
+      }
+    }
+  }
+  async retryOrDeadLetter(envelope, raw, error) {
+    if ((envelope.attempts ?? 0) + 1 < this.maxTries) {
+      await this.requeue(envelope);
+    } else {
+      await this.deadLetter(envelope, "failed", error);
+    }
+    await this.settle(raw);
+  }
+  /** Republish with `attempts + 1` onto the work list (at-least-once retry). */
+  async requeue(envelope) {
+    const bumped = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };
+    await this.client.rpush(this.queue, redisValue(bumped));
+  }
+  async deadLetter(envelope, reason, error) {
+    if (!this.dlq) return;
+    const annotated = (0, import_core.annotate)(envelope, reason, envelope.meta?.queue ?? this.queue, {
+      attempts: envelope.attempts ?? 0,
+      error: error instanceof Error ? error.message : null,
+      exception: error instanceof Error ? error.name : null
+    });
+    await this.client.rpush(this.dlq, redisValue(annotated));
+  }
+  async deadLetterRaw(raw) {
+    if (!this.dlq) return;
+    await this.client.rpush(this.dlq, raw);
+  }
+  /** Remove the element from the reservation list (acknowledge). */
+  async settle(raw) {
+    await this.client.lrem(this.processing, 1, raw);
+  }
+  report(error, envelope, raw) {
+    this.options.onError?.(error, envelope, raw);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RedisConsumer,
+  RedisPublisher,
+  redisValue
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Redis adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed **consumer** over the §1 reliable-queue\n * pattern (`RPUSH` to produce, `BRPOPLPUSH` the head to a `<queue>:processing` list to reserve so\n * an in-flight message survives a crash, `LREM` to acknowledge), so a Redis-based Node service\n * speaks the same wire contract as the PHP, Python and Go SDKs.\n *\n * Redis lists carry **no native metadata** — the list element **is** the canonical envelope JSON,\n * byte-for-byte, with **no wrapping** (unlike `@babelqueue/bullmq`, which uses BullMQ's own job\n * layout). Routing and tracing read the body's `job` / `trace_id`. This is a Node-owned reliable\n * queue; full parity with Laravel's reserved-sorted-set reservation on a *shared* Redis queue is a\n * separate task — for a mixed PHP+Node fleet on one queue, prefer a queue this consumer owns\n * end-to-end.\n *\n * This implements §1 of the broker-bindings contract. `ioredis` is an optional peer — you provide\n * the client (an `ioredis` instance satisfies the adapter structurally).\n */\n\nimport { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal Redis shape (a structural subset of ioredis) ----------------------\n\n/** The subset of an ioredis client this adapter calls. */\nexport interface RedisClient {\n  /** Append a value to the tail of a list; returns the new length. */\n  rpush(key: string, value: string): Promise<number>;\n  /** Atomically pop the head of `source` and push it to the tail of `destination`, blocking up\n   *  to `timeout` seconds; resolves to the value, or `null` on timeout. */\n  brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;\n  /** Remove `count` occurrences of `value` from a list; returns how many were removed. */\n  lrem(key: string, count: number, value: string): Promise<number>;\n}\n\n// --- Payload (contract §1) -----------------------------------------------------\n\n/** The list element for an envelope: the canonical JSON, verbatim — no wrapping (§1). */\nexport function redisValue(envelope: Envelope): string {\n  return EnvelopeCodec.encode(envelope);\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link RedisPublisher.publish}. */\nexport interface PublishOptions {\n  traceId?: string;\n}\n\n/** Sends canonical-envelope messages to one Redis list (§1 reliable-queue). */\nexport class RedisPublisher {\n  private constructor(\n    private readonly client: RedisClient,\n    private readonly queue: string,\n  ) {}\n\n  /** A publisher over `client`, producing to the list named `queue`. */\n  static create(client: RedisClient, queue: string): RedisPublisher {\n    return new RedisPublisher(client, queue);\n  }\n\n  /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */\n  async publish(urn: string, data: Record<string, unknown>, options: PublishOptions = {}): Promise<string> {\n    const envelope = EnvelopeCodec.make(urn, data, { queue: this.queue, traceId: options.traceId });\n    await this.client.rpush(this.queue, redisValue(envelope));\n    return envelope.meta.id;\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw list element. */\nexport type BabelHandler = (envelope: Envelope, raw: string) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link RedisConsumer}. */\nexport interface RedisConsumerOptions {\n  /** Suffix for the per-queue reservation list (default `\":processing\"`). */\n  processingSuffix?: string;\n  /** Block timeout (seconds) for a single reserve (default 5). */\n  blockTimeout?: number;\n  /** Attempts before terminal dead-lettering (default 3). */\n  maxTries?: number;\n  /** The dead-letter list (default `<queue>.dlq`); set to `null` to drop on terminal failure. */\n  deadLetterQueue?: string | null;\n  /** Strategy for a URN with no handler (default `fail`). */\n  unknownUrn?: string;\n  /** Called for a non-conformant message, an unmapped URN, or a throwing handler. */\n  onError?: (error: unknown, envelope: IncomingEnvelope | null, raw: string) => void;\n}\n\n/**\n * Consumes a Redis list: reserve the head into `<queue>:processing` (`BRPOPLPUSH`), decode +\n * validate, route to the handler for its URN, then `LREM` it from the reservation list on success.\n * A throwing handler requeues the envelope with `attempts + 1` (at-least-once) up to `maxTries`,\n * then dead-letters to `<queue>.dlq`. Redis has no native delivery count, so `attempts` lives in\n * the body and the runtime owns retry.\n */\nexport class RedisConsumer {\n  private readonly processing: string;\n  private readonly blockTimeout: number;\n  private readonly maxTries: number;\n  private readonly dlq: string | null;\n  private readonly unknownUrn: string;\n\n  constructor(\n    private readonly client: RedisClient,\n    private readonly queue: string,\n    private readonly handlers: BabelHandlers,\n    private readonly options: RedisConsumerOptions = {},\n  ) {\n    this.processing = queue + (options.processingSuffix ?? \":processing\");\n    this.blockTimeout = options.blockTimeout ?? 5;\n    this.maxTries = options.maxTries ?? 3;\n    this.dlq = options.deadLetterQueue === undefined ? `${queue}.dlq` : options.deadLetterQueue;\n    this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;\n  }\n\n  /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */\n  async poll(): Promise<boolean> {\n    const raw = await this.client.brpoplpush(this.queue, this.processing, this.blockTimeout);\n    if (raw == null) return false;\n    await this.handle(raw);\n    return true;\n  }\n\n  /** Poll while `shouldContinue` returns true. */\n  async run(shouldContinue: () => boolean): Promise<void> {\n    while (shouldContinue()) {\n      await this.poll();\n    }\n  }\n\n  /** Route + settle one reserved element. Exposed for testing. */\n  async handle(raw: string): Promise<void> {\n    const decoded = EnvelopeCodec.decode(raw);\n\n    if (!EnvelopeCodec.accepts(decoded)) {\n      this.report(new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from Redis.\"), decoded, raw);\n      await this.deadLetterRaw(raw);\n      await this.settle(raw);\n      return;\n    }\n\n    const envelope = decoded as Envelope;\n    const urn = EnvelopeCodec.urn(envelope);\n    const handler = this.handlers[urn];\n    if (!handler) {\n      await this.onUnknownUrn(envelope, urn, raw);\n      return;\n    }\n\n    try {\n      await handler(envelope, raw);\n      await this.settle(raw);\n    } catch (error) {\n      this.report(error, envelope, raw);\n      await this.retryOrDeadLetter(envelope, raw, error);\n    }\n  }\n\n  private async onUnknownUrn(envelope: Envelope, urn: string, raw: string): Promise<void> {\n    switch (this.unknownUrn) {\n      case UnknownUrnStrategy.DELETE:\n        await this.settle(raw);\n        return;\n      case UnknownUrnStrategy.DEAD_LETTER:\n        await this.deadLetter(envelope, \"unknown_urn\");\n        await this.settle(raw);\n        return;\n      case UnknownUrnStrategy.RELEASE:\n        await this.requeue(envelope);\n        await this.settle(raw);\n        return;\n      default: {\n        // FAIL: surface and leave the element in the reservation list (recoverable).\n        const error = new UnknownUrnError(urn);\n        this.report(error, envelope, raw);\n        throw error;\n      }\n    }\n  }\n\n  private async retryOrDeadLetter(envelope: Envelope, raw: string, error: unknown): Promise<void> {\n    if ((envelope.attempts ?? 0) + 1 < this.maxTries) {\n      await this.requeue(envelope);\n    } else {\n      await this.deadLetter(envelope, \"failed\", error);\n    }\n    await this.settle(raw);\n  }\n\n  /** Republish with `attempts + 1` onto the work list (at-least-once retry). */\n  private async requeue(envelope: Envelope): Promise<void> {\n    const bumped: Envelope = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };\n    await this.client.rpush(this.queue, redisValue(bumped));\n  }\n\n  private async deadLetter(envelope: Envelope, reason: string, error?: unknown): Promise<void> {\n    if (!this.dlq) return; // dead-lettering disabled → drop\n    const annotated = annotate(envelope, reason, envelope.meta?.queue ?? this.queue, {\n      attempts: envelope.attempts ?? 0,\n      error: error instanceof Error ? error.message : null,\n      exception: error instanceof Error ? error.name : null,\n    });\n    await this.client.rpush(this.dlq, redisValue(annotated));\n  }\n\n  private async deadLetterRaw(raw: string): Promise<void> {\n    if (!this.dlq) return;\n    await this.client.rpush(this.dlq, raw);\n  }\n\n  /** Remove the element from the reservation list (acknowledge). */\n  private async settle(raw: string): Promise<void> {\n    await this.client.lrem(this.processing, 1, raw);\n  }\n\n  private report(error: unknown, envelope: IncomingEnvelope | null, raw: string): void {\n    this.options.onError?.(error, envelope, raw);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,102 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Redis adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over the §1 reliable-queue
+ * pattern (`RPUSH` to produce, `BRPOPLPUSH` the head to a `<queue>:processing` list to reserve so
+ * an in-flight message survives a crash, `LREM` to acknowledge), so a Redis-based Node service
+ * speaks the same wire contract as the PHP, Python and Go SDKs.
+ *
+ * Redis lists carry **no native metadata** — the list element **is** the canonical envelope JSON,
+ * byte-for-byte, with **no wrapping** (unlike `@babelqueue/bullmq`, which uses BullMQ's own job
+ * layout). Routing and tracing read the body's `job` / `trace_id`. This is a Node-owned reliable
+ * queue; full parity with Laravel's reserved-sorted-set reservation on a *shared* Redis queue is a
+ * separate task — for a mixed PHP+Node fleet on one queue, prefer a queue this consumer owns
+ * end-to-end.
+ *
+ * This implements §1 of the broker-bindings contract. `ioredis` is an optional peer — you provide
+ * the client (an `ioredis` instance satisfies the adapter structurally).
+ */
+
+/** The subset of an ioredis client this adapter calls. */
+interface RedisClient {
+    /** Append a value to the tail of a list; returns the new length. */
+    rpush(key: string, value: string): Promise<number>;
+    /** Atomically pop the head of `source` and push it to the tail of `destination`, blocking up
+     *  to `timeout` seconds; resolves to the value, or `null` on timeout. */
+    brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;
+    /** Remove `count` occurrences of `value` from a list; returns how many were removed. */
+    lrem(key: string, count: number, value: string): Promise<number>;
+}
+/** The list element for an envelope: the canonical JSON, verbatim — no wrapping (§1). */
+declare function redisValue(envelope: Envelope): string;
+/** Options for {@link RedisPublisher.publish}. */
+interface PublishOptions {
+    traceId?: string;
+}
+/** Sends canonical-envelope messages to one Redis list (§1 reliable-queue). */
+declare class RedisPublisher {
+    private readonly client;
+    private readonly queue;
+    private constructor();
+    /** A publisher over `client`, producing to the list named `queue`. */
+    static create(client: RedisClient, queue: string): RedisPublisher;
+    /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+}
+/** A URN handler. Receives the validated envelope and the raw list element. */
+type BabelHandler = (envelope: Envelope, raw: string) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link RedisConsumer}. */
+interface RedisConsumerOptions {
+    /** Suffix for the per-queue reservation list (default `":processing"`). */
+    processingSuffix?: string;
+    /** Block timeout (seconds) for a single reserve (default 5). */
+    blockTimeout?: number;
+    /** Attempts before terminal dead-lettering (default 3). */
+    maxTries?: number;
+    /** The dead-letter list (default `<queue>.dlq`); set to `null` to drop on terminal failure. */
+    deadLetterQueue?: string | null;
+    /** Strategy for a URN with no handler (default `fail`). */
+    unknownUrn?: string;
+    /** Called for a non-conformant message, an unmapped URN, or a throwing handler. */
+    onError?: (error: unknown, envelope: IncomingEnvelope | null, raw: string) => void;
+}
+/**
+ * Consumes a Redis list: reserve the head into `<queue>:processing` (`BRPOPLPUSH`), decode +
+ * validate, route to the handler for its URN, then `LREM` it from the reservation list on success.
+ * A throwing handler requeues the envelope with `attempts + 1` (at-least-once) up to `maxTries`,
+ * then dead-letters to `<queue>.dlq`. Redis has no native delivery count, so `attempts` lives in
+ * the body and the runtime owns retry.
+ */
+declare class RedisConsumer {
+    private readonly client;
+    private readonly queue;
+    private readonly handlers;
+    private readonly options;
+    private readonly processing;
+    private readonly blockTimeout;
+    private readonly maxTries;
+    private readonly dlq;
+    private readonly unknownUrn;
+    constructor(client: RedisClient, queue: string, handlers: BabelHandlers, options?: RedisConsumerOptions);
+    /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */
+    poll(): Promise<boolean>;
+    /** Poll while `shouldContinue` returns true. */
+    run(shouldContinue: () => boolean): Promise<void>;
+    /** Route + settle one reserved element. Exposed for testing. */
+    handle(raw: string): Promise<void>;
+    private onUnknownUrn;
+    private retryOrDeadLetter;
+    /** Republish with `attempts + 1` onto the work list (at-least-once retry). */
+    private requeue;
+    private deadLetter;
+    private deadLetterRaw;
+    /** Remove the element from the reservation list (acknowledge). */
+    private settle;
+    private report;
+}
+
+export { type BabelHandler, type BabelHandlers, type PublishOptions, type RedisClient, RedisConsumer, type RedisConsumerOptions, RedisPublisher, redisValue };

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Redis adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over the §1 reliable-queue
+ * pattern (`RPUSH` to produce, `BRPOPLPUSH` the head to a `<queue>:processing` list to reserve so
+ * an in-flight message survives a crash, `LREM` to acknowledge), so a Redis-based Node service
+ * speaks the same wire contract as the PHP, Python and Go SDKs.
+ *
+ * Redis lists carry **no native metadata** — the list element **is** the canonical envelope JSON,
+ * byte-for-byte, with **no wrapping** (unlike `@babelqueue/bullmq`, which uses BullMQ's own job
+ * layout). Routing and tracing read the body's `job` / `trace_id`. This is a Node-owned reliable
+ * queue; full parity with Laravel's reserved-sorted-set reservation on a *shared* Redis queue is a
+ * separate task — for a mixed PHP+Node fleet on one queue, prefer a queue this consumer owns
+ * end-to-end.
+ *
+ * This implements §1 of the broker-bindings contract. `ioredis` is an optional peer — you provide
+ * the client (an `ioredis` instance satisfies the adapter structurally).
+ */
+
+/** The subset of an ioredis client this adapter calls. */
+interface RedisClient {
+    /** Append a value to the tail of a list; returns the new length. */
+    rpush(key: string, value: string): Promise<number>;
+    /** Atomically pop the head of `source` and push it to the tail of `destination`, blocking up
+     *  to `timeout` seconds; resolves to the value, or `null` on timeout. */
+    brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;
+    /** Remove `count` occurrences of `value` from a list; returns how many were removed. */
+    lrem(key: string, count: number, value: string): Promise<number>;
+}
+/** The list element for an envelope: the canonical JSON, verbatim — no wrapping (§1). */
+declare function redisValue(envelope: Envelope): string;
+/** Options for {@link RedisPublisher.publish}. */
+interface PublishOptions {
+    traceId?: string;
+}
+/** Sends canonical-envelope messages to one Redis list (§1 reliable-queue). */
+declare class RedisPublisher {
+    private readonly client;
+    private readonly queue;
+    private constructor();
+    /** A publisher over `client`, producing to the list named `queue`. */
+    static create(client: RedisClient, queue: string): RedisPublisher;
+    /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+}
+/** A URN handler. Receives the validated envelope and the raw list element. */
+type BabelHandler = (envelope: Envelope, raw: string) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link RedisConsumer}. */
+interface RedisConsumerOptions {
+    /** Suffix for the per-queue reservation list (default `":processing"`). */
+    processingSuffix?: string;
+    /** Block timeout (seconds) for a single reserve (default 5). */
+    blockTimeout?: number;
+    /** Attempts before terminal dead-lettering (default 3). */
+    maxTries?: number;
+    /** The dead-letter list (default `<queue>.dlq`); set to `null` to drop on terminal failure. */
+    deadLetterQueue?: string | null;
+    /** Strategy for a URN with no handler (default `fail`). */
+    unknownUrn?: string;
+    /** Called for a non-conformant message, an unmapped URN, or a throwing handler. */
+    onError?: (error: unknown, envelope: IncomingEnvelope | null, raw: string) => void;
+}
+/**
+ * Consumes a Redis list: reserve the head into `<queue>:processing` (`BRPOPLPUSH`), decode +
+ * validate, route to the handler for its URN, then `LREM` it from the reservation list on success.
+ * A throwing handler requeues the envelope with `attempts + 1` (at-least-once) up to `maxTries`,
+ * then dead-letters to `<queue>.dlq`. Redis has no native delivery count, so `attempts` lives in
+ * the body and the runtime owns retry.
+ */
+declare class RedisConsumer {
+    private readonly client;
+    private readonly queue;
+    private readonly handlers;
+    private readonly options;
+    private readonly processing;
+    private readonly blockTimeout;
+    private readonly maxTries;
+    private readonly dlq;
+    private readonly unknownUrn;
+    constructor(client: RedisClient, queue: string, handlers: BabelHandlers, options?: RedisConsumerOptions);
+    /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */
+    poll(): Promise<boolean>;
+    /** Poll while `shouldContinue` returns true. */
+    run(shouldContinue: () => boolean): Promise<void>;
+    /** Route + settle one reserved element. Exposed for testing. */
+    handle(raw: string): Promise<void>;
+    private onUnknownUrn;
+    private retryOrDeadLetter;
+    /** Republish with `attempts + 1` onto the work list (at-least-once retry). */
+    private requeue;
+    private deadLetter;
+    private deadLetterRaw;
+    /** Remove the element from the reservation list (acknowledge). */
+    private settle;
+    private report;
+}
+
+export { type BabelHandler, type BabelHandlers, type PublishOptions, type RedisClient, RedisConsumer, type RedisConsumerOptions, RedisPublisher, redisValue };

package/dist/index.js

@@ -0,0 +1,141 @@
+// src/index.ts
+import { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from "@babelqueue/core";
+function redisValue(envelope) {
+  return EnvelopeCodec.encode(envelope);
+}
+var RedisPublisher = class _RedisPublisher {
+  constructor(client, queue) {
+    this.client = client;
+    this.queue = queue;
+  }
+  client;
+  queue;
+  /** A publisher over `client`, producing to the list named `queue`. */
+  static create(client, queue) {
+    return new _RedisPublisher(client, queue);
+  }
+  /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */
+  async publish(urn, data, options = {}) {
+    const envelope = EnvelopeCodec.make(urn, data, { queue: this.queue, traceId: options.traceId });
+    await this.client.rpush(this.queue, redisValue(envelope));
+    return envelope.meta.id;
+  }
+};
+var RedisConsumer = class {
+  constructor(client, queue, handlers, options = {}) {
+    this.client = client;
+    this.queue = queue;
+    this.handlers = handlers;
+    this.options = options;
+    this.processing = queue + (options.processingSuffix ?? ":processing");
+    this.blockTimeout = options.blockTimeout ?? 5;
+    this.maxTries = options.maxTries ?? 3;
+    this.dlq = options.deadLetterQueue === void 0 ? `${queue}.dlq` : options.deadLetterQueue;
+    this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;
+  }
+  client;
+  queue;
+  handlers;
+  options;
+  processing;
+  blockTimeout;
+  maxTries;
+  dlq;
+  unknownUrn;
+  /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */
+  async poll() {
+    const raw = await this.client.brpoplpush(this.queue, this.processing, this.blockTimeout);
+    if (raw == null) return false;
+    await this.handle(raw);
+    return true;
+  }
+  /** Poll while `shouldContinue` returns true. */
+  async run(shouldContinue) {
+    while (shouldContinue()) {
+      await this.poll();
+    }
+  }
+  /** Route + settle one reserved element. Exposed for testing. */
+  async handle(raw) {
+    const decoded = EnvelopeCodec.decode(raw);
+    if (!EnvelopeCodec.accepts(decoded)) {
+      this.report(new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Redis."), decoded, raw);
+      await this.deadLetterRaw(raw);
+      await this.settle(raw);
+      return;
+    }
+    const envelope = decoded;
+    const urn = EnvelopeCodec.urn(envelope);
+    const handler = this.handlers[urn];
+    if (!handler) {
+      await this.onUnknownUrn(envelope, urn, raw);
+      return;
+    }
+    try {
+      await handler(envelope, raw);
+      await this.settle(raw);
+    } catch (error) {
+      this.report(error, envelope, raw);
+      await this.retryOrDeadLetter(envelope, raw, error);
+    }
+  }
+  async onUnknownUrn(envelope, urn, raw) {
+    switch (this.unknownUrn) {
+      case UnknownUrnStrategy.DELETE:
+        await this.settle(raw);
+        return;
+      case UnknownUrnStrategy.DEAD_LETTER:
+        await this.deadLetter(envelope, "unknown_urn");
+        await this.settle(raw);
+        return;
+      case UnknownUrnStrategy.RELEASE:
+        await this.requeue(envelope);
+        await this.settle(raw);
+        return;
+      default: {
+        const error = new UnknownUrnError(urn);
+        this.report(error, envelope, raw);
+        throw error;
+      }
+    }
+  }
+  async retryOrDeadLetter(envelope, raw, error) {
+    if ((envelope.attempts ?? 0) + 1 < this.maxTries) {
+      await this.requeue(envelope);
+    } else {
+      await this.deadLetter(envelope, "failed", error);
+    }
+    await this.settle(raw);
+  }
+  /** Republish with `attempts + 1` onto the work list (at-least-once retry). */
+  async requeue(envelope) {
+    const bumped = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };
+    await this.client.rpush(this.queue, redisValue(bumped));
+  }
+  async deadLetter(envelope, reason, error) {
+    if (!this.dlq) return;
+    const annotated = annotate(envelope, reason, envelope.meta?.queue ?? this.queue, {
+      attempts: envelope.attempts ?? 0,
+      error: error instanceof Error ? error.message : null,
+      exception: error instanceof Error ? error.name : null
+    });
+    await this.client.rpush(this.dlq, redisValue(annotated));
+  }
+  async deadLetterRaw(raw) {
+    if (!this.dlq) return;
+    await this.client.rpush(this.dlq, raw);
+  }
+  /** Remove the element from the reservation list (acknowledge). */
+  async settle(raw) {
+    await this.client.lrem(this.processing, 1, raw);
+  }
+  report(error, envelope, raw) {
+    this.options.onError?.(error, envelope, raw);
+  }
+};
+export {
+  RedisConsumer,
+  RedisPublisher,
+  redisValue
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Redis adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed **consumer** over the §1 reliable-queue\n * pattern (`RPUSH` to produce, `BRPOPLPUSH` the head to a `<queue>:processing` list to reserve so\n * an in-flight message survives a crash, `LREM` to acknowledge), so a Redis-based Node service\n * speaks the same wire contract as the PHP, Python and Go SDKs.\n *\n * Redis lists carry **no native metadata** — the list element **is** the canonical envelope JSON,\n * byte-for-byte, with **no wrapping** (unlike `@babelqueue/bullmq`, which uses BullMQ's own job\n * layout). Routing and tracing read the body's `job` / `trace_id`. This is a Node-owned reliable\n * queue; full parity with Laravel's reserved-sorted-set reservation on a *shared* Redis queue is a\n * separate task — for a mixed PHP+Node fleet on one queue, prefer a queue this consumer owns\n * end-to-end.\n *\n * This implements §1 of the broker-bindings contract. `ioredis` is an optional peer — you provide\n * the client (an `ioredis` instance satisfies the adapter structurally).\n */\n\nimport { annotate, BabelQueueError, EnvelopeCodec, UnknownUrnError, UnknownUrnStrategy } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal Redis shape (a structural subset of ioredis) ----------------------\n\n/** The subset of an ioredis client this adapter calls. */\nexport interface RedisClient {\n  /** Append a value to the tail of a list; returns the new length. */\n  rpush(key: string, value: string): Promise<number>;\n  /** Atomically pop the head of `source` and push it to the tail of `destination`, blocking up\n   *  to `timeout` seconds; resolves to the value, or `null` on timeout. */\n  brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;\n  /** Remove `count` occurrences of `value` from a list; returns how many were removed. */\n  lrem(key: string, count: number, value: string): Promise<number>;\n}\n\n// --- Payload (contract §1) -----------------------------------------------------\n\n/** The list element for an envelope: the canonical JSON, verbatim — no wrapping (§1). */\nexport function redisValue(envelope: Envelope): string {\n  return EnvelopeCodec.encode(envelope);\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link RedisPublisher.publish}. */\nexport interface PublishOptions {\n  traceId?: string;\n}\n\n/** Sends canonical-envelope messages to one Redis list (§1 reliable-queue). */\nexport class RedisPublisher {\n  private constructor(\n    private readonly client: RedisClient,\n    private readonly queue: string,\n  ) {}\n\n  /** A publisher over `client`, producing to the list named `queue`. */\n  static create(client: RedisClient, queue: string): RedisPublisher {\n    return new RedisPublisher(client, queue);\n  }\n\n  /** Build + `RPUSH` the canonical envelope; returns the message id (`meta.id`). */\n  async publish(urn: string, data: Record<string, unknown>, options: PublishOptions = {}): Promise<string> {\n    const envelope = EnvelopeCodec.make(urn, data, { queue: this.queue, traceId: options.traceId });\n    await this.client.rpush(this.queue, redisValue(envelope));\n    return envelope.meta.id;\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw list element. */\nexport type BabelHandler = (envelope: Envelope, raw: string) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link RedisConsumer}. */\nexport interface RedisConsumerOptions {\n  /** Suffix for the per-queue reservation list (default `\":processing\"`). */\n  processingSuffix?: string;\n  /** Block timeout (seconds) for a single reserve (default 5). */\n  blockTimeout?: number;\n  /** Attempts before terminal dead-lettering (default 3). */\n  maxTries?: number;\n  /** The dead-letter list (default `<queue>.dlq`); set to `null` to drop on terminal failure. */\n  deadLetterQueue?: string | null;\n  /** Strategy for a URN with no handler (default `fail`). */\n  unknownUrn?: string;\n  /** Called for a non-conformant message, an unmapped URN, or a throwing handler. */\n  onError?: (error: unknown, envelope: IncomingEnvelope | null, raw: string) => void;\n}\n\n/**\n * Consumes a Redis list: reserve the head into `<queue>:processing` (`BRPOPLPUSH`), decode +\n * validate, route to the handler for its URN, then `LREM` it from the reservation list on success.\n * A throwing handler requeues the envelope with `attempts + 1` (at-least-once) up to `maxTries`,\n * then dead-letters to `<queue>.dlq`. Redis has no native delivery count, so `attempts` lives in\n * the body and the runtime owns retry.\n */\nexport class RedisConsumer {\n  private readonly processing: string;\n  private readonly blockTimeout: number;\n  private readonly maxTries: number;\n  private readonly dlq: string | null;\n  private readonly unknownUrn: string;\n\n  constructor(\n    private readonly client: RedisClient,\n    private readonly queue: string,\n    private readonly handlers: BabelHandlers,\n    private readonly options: RedisConsumerOptions = {},\n  ) {\n    this.processing = queue + (options.processingSuffix ?? \":processing\");\n    this.blockTimeout = options.blockTimeout ?? 5;\n    this.maxTries = options.maxTries ?? 3;\n    this.dlq = options.deadLetterQueue === undefined ? `${queue}.dlq` : options.deadLetterQueue;\n    this.unknownUrn = options.unknownUrn ?? UnknownUrnStrategy.FAIL;\n  }\n\n  /** Reserve + route + settle one message. Returns true if one was handled, false on timeout. */\n  async poll(): Promise<boolean> {\n    const raw = await this.client.brpoplpush(this.queue, this.processing, this.blockTimeout);\n    if (raw == null) return false;\n    await this.handle(raw);\n    return true;\n  }\n\n  /** Poll while `shouldContinue` returns true. */\n  async run(shouldContinue: () => boolean): Promise<void> {\n    while (shouldContinue()) {\n      await this.poll();\n    }\n  }\n\n  /** Route + settle one reserved element. Exposed for testing. */\n  async handle(raw: string): Promise<void> {\n    const decoded = EnvelopeCodec.decode(raw);\n\n    if (!EnvelopeCodec.accepts(decoded)) {\n      this.report(new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from Redis.\"), decoded, raw);\n      await this.deadLetterRaw(raw);\n      await this.settle(raw);\n      return;\n    }\n\n    const envelope = decoded as Envelope;\n    const urn = EnvelopeCodec.urn(envelope);\n    const handler = this.handlers[urn];\n    if (!handler) {\n      await this.onUnknownUrn(envelope, urn, raw);\n      return;\n    }\n\n    try {\n      await handler(envelope, raw);\n      await this.settle(raw);\n    } catch (error) {\n      this.report(error, envelope, raw);\n      await this.retryOrDeadLetter(envelope, raw, error);\n    }\n  }\n\n  private async onUnknownUrn(envelope: Envelope, urn: string, raw: string): Promise<void> {\n    switch (this.unknownUrn) {\n      case UnknownUrnStrategy.DELETE:\n        await this.settle(raw);\n        return;\n      case UnknownUrnStrategy.DEAD_LETTER:\n        await this.deadLetter(envelope, \"unknown_urn\");\n        await this.settle(raw);\n        return;\n      case UnknownUrnStrategy.RELEASE:\n        await this.requeue(envelope);\n        await this.settle(raw);\n        return;\n      default: {\n        // FAIL: surface and leave the element in the reservation list (recoverable).\n        const error = new UnknownUrnError(urn);\n        this.report(error, envelope, raw);\n        throw error;\n      }\n    }\n  }\n\n  private async retryOrDeadLetter(envelope: Envelope, raw: string, error: unknown): Promise<void> {\n    if ((envelope.attempts ?? 0) + 1 < this.maxTries) {\n      await this.requeue(envelope);\n    } else {\n      await this.deadLetter(envelope, \"failed\", error);\n    }\n    await this.settle(raw);\n  }\n\n  /** Republish with `attempts + 1` onto the work list (at-least-once retry). */\n  private async requeue(envelope: Envelope): Promise<void> {\n    const bumped: Envelope = { ...envelope, attempts: (envelope.attempts ?? 0) + 1 };\n    await this.client.rpush(this.queue, redisValue(bumped));\n  }\n\n  private async deadLetter(envelope: Envelope, reason: string, error?: unknown): Promise<void> {\n    if (!this.dlq) return; // dead-lettering disabled → drop\n    const annotated = annotate(envelope, reason, envelope.meta?.queue ?? this.queue, {\n      attempts: envelope.attempts ?? 0,\n      error: error instanceof Error ? error.message : null,\n      exception: error instanceof Error ? error.name : null,\n    });\n    await this.client.rpush(this.dlq, redisValue(annotated));\n  }\n\n  private async deadLetterRaw(raw: string): Promise<void> {\n    if (!this.dlq) return;\n    await this.client.rpush(this.dlq, raw);\n  }\n\n  /** Remove the element from the reservation list (acknowledge). */\n  private async settle(raw: string): Promise<void> {\n    await this.client.lrem(this.processing, 1, raw);\n  }\n\n  private report(error: unknown, envelope: IncomingEnvelope | null, raw: string): void {\n    this.options.onError?.(error, envelope, raw);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@babelqueue/redis",
+  "version": "1.0.0",
+  "description": "Redis adapter for BabelQueue — a canonical-envelope publisher and a URN-routed consumer over the §1 reliable-queue pattern (RPUSH / BRPOPLPUSH-reserve / LREM-ack) on ioredis.",
+  "keywords": ["babelqueue", "redis", "ioredis", "queue", "polyglot", "messaging"],
+  "homepage": "https://babelqueue.com",
+  "bugs": {
+    "url": "https://github.com/BabelQueue/babelqueue-node-adapters/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BabelQueue/babelqueue-node-adapters.git",
+    "directory": "packages/redis"
+  },
+  "license": "MIT",
+  "author": "Muhammet Şafak <info@muhammetsafak.com.tr>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@babelqueue/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}