@haatlabs-core/queue 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Haatlabs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @haatlabs-core/queue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+BullMQ work queues on Redis: the publisher, the retrying consumer (with a priority lane) and
+the outbox relay. A project supplies its topology, meaning its queue names, the routing-key
+prefixes each takes, and its key prefix, through its own `connectQueue`:
+
+    const route = routeByPrefix<QueueName>({ 'shopify-sync': ['shopify.'], imports: ['import.'] });
+    export const connectQueue = (url: string, options: { prefix?: string } = {}) =>
+      connect(url, { prefix: options.prefix ?? 'shop:queue', route });
+
+ioredis is a peer dependency.
+
+## Install
+
+    pnpm add @haatlabs-core/queue
+
+It leaves one package to your app, so the app holds one copy: `ioredis`.
+
+## Polling without holding a worker slot
+
+A handler that waits on something external (a bulk operation, media processing) calls
+`pollAgain(message, { delayMs, deadlineMs, state, onDeadline })`. The job is put back as a
+delayed job, its worker slot is free meanwhile, it keeps its attempt count and its lane, and
+`message.poll` (`round`, `startedAt`, `deadlineAt`, `state`) is there on the next round.
+
+- `delayMs` is 250 ms to 15 min a round. Every poll has a deadline, set on the first round and
+  shared by all later rounds and phases; a round can shorten it, never extend it. Once it has
+  passed, `onDeadline()` is thrown and the job fails.
+- Each round runs the handler again from the top. The work before `pollAgain` must be
+  idempotent, or branch on `message.poll.state`.
+- `state` is JSON of at most 16 KiB; more is a `RangeError`.
+- `onDeadline()`'s error decides what happens next: a transient one fails the attempt and the
+  retry starts the flow afresh (the poll is cleared); a permanent one keeps the job as failed. A
+  `PollAgain` thrown directly past the deadline fails as `POLL_TIMED_OUT` (`QUEUE_ERRORS`),
+  which is transient.
+- `RestartPoll` fails the attempt as transient and clears the poll, so the retry starts afresh.
+- A poll round is logged at debug and its `queue.process` span ends with outcome `poll`, not as
+  an error.
+
+## Delayed and de-duplicated publishes
+
+`publish(key, payload, { delayMs, deduplication: { id } })` delays a message, or coalesces the
+publishes that share an id. The job holds the id until it completes or fails for good:
+
+- waiting for its first run (delayed or not), a later publish is dropped: the job has not
+  started, so it will see the newer state;
+- running, the newest later publish is kept and queued when it finishes or fails;
+- delayed again, by a `PollAgain` round or a retry's backoff, a later publish is **dropped**,
+  though the job has already read the state.
+
+So use `deduplication` only for handlers that never poll and recompute from scratch on every
+attempt. The consumer warns, once a poll, when a de-duplicated job polls.
+
+Such publishes are direct, never through the outbox: an outbox row carries no `delayMs` and no
+`deduplication`. If the process dies between the commit and the publish, the message is lost.
+A caller that needs it to survive publishes through the outbox, without them, and coalesces in
+the handler instead.
+
+Failed jobs are kept 1,000 per queue for 14 days.

package/dist/cjs/codes.d.ts

@@ -0,0 +1,14 @@
+import type { AppError } from '@haatlabs-core/errors';
+/** The code this package throws beyond the core ones: a project spreads it into defineErrors. */
+export declare const QUEUE_ERRORS: {
+    readonly POLL_TIMED_OUT: {
+        readonly httpStatus: 503;
+        readonly transient: true;
+    };
+};
+export declare const QueueErrorCode: {
+    readonly POLL_TIMED_OUT: "POLL_TIMED_OUT";
+};
+export declare const createQueueError: (code: "POLL_TIMED_OUT", message: string, options?: import("@haatlabs-core/errors").AppErrorOptions) => AppError<"POLL_TIMED_OUT">;
+/** The error this package throws: a project that spreads in QUEUE_ERRORS takes it as its own. */
+export type QueueError = AppError<keyof typeof QUEUE_ERRORS>;

package/dist/cjs/codes.js

@@ -0,0 +1,38 @@
+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);
+var codes_exports = {};
+__export(codes_exports, {
+  QUEUE_ERRORS: () => QUEUE_ERRORS,
+  QueueErrorCode: () => QueueErrorCode,
+  createQueueError: () => createQueueError
+});
+module.exports = __toCommonJS(codes_exports);
+var import_errors = require("@haatlabs-core/errors");
+const QUEUE_ERRORS = {
+  // A poll that ran past its deadline: a timeout, so the job's retry starts the flow afresh.
+  POLL_TIMED_OUT: { httpStatus: 503, transient: true }
+};
+const queue = (0, import_errors.domainErrors)(QUEUE_ERRORS);
+const QueueErrorCode = queue.codes;
+const createQueueError = queue.create;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  QUEUE_ERRORS,
+  QueueErrorCode,
+  createQueueError
+});

package/dist/cjs/consumer.d.ts

@@ -0,0 +1,79 @@
+import type { PollState } from './poll.js';
+import type { QueueConnection } from './topology.js';
+export interface QueueLogger {
+    info(obj: object, msg: string): void;
+    warn(obj: object, msg: string): void;
+    error(obj: object, msg: string): void;
+    /** PollAgain is logged here when the logger has it. */
+    debug?(obj: object, msg: string): void;
+}
+export interface ConsumedMessage {
+    routingKey: string;
+    payload: unknown;
+    attempt: number;
+    messageId: string | undefined;
+    /** The traceparent the message arrived with, if it had a usable one. */
+    traceContext?: string | null;
+    /** What the last PollAgain left; null when none. Always set by the consumer. */
+    poll?: PollState | null;
+}
+export interface ConsumerOptions {
+    queue: string;
+    /** How many jobs of this queue one worker handles at a time. */
+    concurrency: number;
+    maxAttempts: number;
+    handler(message: ConsumedMessage): Promise<void>;
+    logger: QueueLogger;
+    /** How long a failed job waits before each further attempt; the last is used from then on. */
+    retryDelaysMs?: readonly number[];
+}
+/** A failure worth another attempt, and how long to wait before it. */
+export declare class RetryLater extends Error {
+    readonly delayMs: number;
+    constructor(message: string, delayMs: number);
+}
+/**
+ * How long a failed attempt waits. Attempt 1 waits the first delay, attempt 2 the second,
+ * and attempts beyond the last reuse it. A failure that says how long to wait (a
+ * provider's "slow down", our own limit) is never brought back sooner than it asked.
+ */
+export declare function retryDelayMs(error: unknown, attempt: number, delays: readonly number[]): number;
+/** What of a job the handling of it reads. */
+export interface IncomingJob {
+    id?: string;
+    name: string;
+    data: unknown;
+    attemptsMade: number;
+    /** BullMQ's; a job without them cannot be put back (a test's plain object). */
+    updateData?(data: unknown): Promise<void>;
+    moveToDelayed?(timestamp: number, token?: string): Promise<void>;
+    /** BullMQ's: what it was published with. */
+    opts?: {
+        deduplication?: {
+            id: string;
+        };
+    };
+}
+/**
+ * Handles one job. Returning means it is done. A failure that may pass throws
+ * `RetryLater`; one that will not, or that has been tried often enough, throws
+ * `UnrecoverableError`, and the job is kept as failed. Only a safe description of the
+ * failure leaves here: what is thrown is stored with the job.
+ */
+export declare function handleJob(job: IncomingJob, options: Omit<ConsumerOptions, 'concurrency'>, token?: string): Promise<void>;
+/** How an attempt at a job ended, as its finished line says. */
+export type JobOutcome = 'ok' | 'poll' | 'retry' | 'failed';
+export interface Consumer {
+    /** Takes no more work, and resolves once the work in hand is finished. */
+    stop(): Promise<void>;
+    /** False once it has stopped taking work, whether asked to or not. */
+    running(): boolean;
+}
+export declare function startConsumer(connection: QueueConnection, options: ConsumerOptions): Promise<Consumer>;
+/**
+ * Consumes a kind of work from both its lanes: the ordinary one and the one for work that
+ * goes first, each with the same handler and its own share of the worker (`concurrency`
+ * each). Work that goes first is therefore never behind ordinary work, and ordinary work
+ * is never held up until the other lane is empty.
+ */
+export declare function startConsumers(connection: QueueConnection, options: ConsumerOptions): Promise<Consumer>;

package/dist/cjs/consumer.js

@@ -0,0 +1,200 @@
+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);
+var consumer_exports = {};
+__export(consumer_exports, {
+  RetryLater: () => RetryLater,
+  handleJob: () => handleJob,
+  retryDelayMs: () => retryDelayMs,
+  startConsumer: () => startConsumer,
+  startConsumers: () => startConsumers
+});
+module.exports = __toCommonJS(consumer_exports);
+var import_errors = require("@haatlabs-core/errors");
+var import_observability = require("@haatlabs-core/observability");
+var import_api = require("@opentelemetry/api");
+var import_bullmq = require("bullmq");
+var import_codes = require("./codes.js");
+var import_poll = require("./poll.js");
+var import_topology = require("./topology.js");
+const MAX_ERROR_LENGTH = 500;
+const describeError = import_errors.safeErrorMessage;
+class RetryLater extends Error {
+  delayMs;
+  constructor(message, delayMs) {
+    super(message);
+    this.delayMs = delayMs;
+    this.name = "RetryLater";
+  }
+}
+function retryDelayMs(error, attempt, delays) {
+  const byAttempt = delays[Math.min(attempt, delays.length) - 1] ?? 0;
+  const asked = error instanceof import_errors.AppError ? error.retryAfterMs ?? 0 : 0;
+  return Math.max(byAttempt, asked);
+}
+const isJobData = (data) => typeof data === "object" && data !== null && "payload" in data;
+async function handleJob(job, options, token) {
+  const attempt = job.attemptsMade + 1;
+  const routingKey = job.name;
+  const context = { queue: options.queue, routingKey, attempt, messageId: job.id };
+  if (!isJobData(job.data)) {
+    options.logger.error(context, "Discarding a job that is not one of ours");
+    throw new import_bullmq.UnrecoverableError("unparseable");
+  }
+  const startedAt = Date.now();
+  const lines = { traceId: void 0 };
+  let outcome = "failed";
+  try {
+    await processJob(job, job.data, options, context, lines, token);
+    outcome = "ok";
+  } catch (error) {
+    outcome = error instanceof import_bullmq.DelayedError ? "poll" : error instanceof RetryLater ? "retry" : "failed";
+    throw error;
+  } finally {
+    options.logger.info({
+      ...context,
+      ...lines.traceId ? { trace_id: lines.traceId } : {},
+      outcome,
+      durationMs: Date.now() - startedAt
+    }, "Job finished");
+  }
+}
+async function processJob(job, data, options, context, lines, token) {
+  const { attempt, routingKey } = context;
+  const { payload } = data;
+  const traceContext = typeof data.traceContext === "string" ? data.traceContext : null;
+  const poll = (0, import_poll.pollStateOf)(data);
+  const clearPoll = async () => {
+    if (!poll || !job.updateData)
+      return;
+    const rest = { ...data };
+    delete rest.poll;
+    await job.updateData(rest).catch((error) => {
+      options.logger.warn({ ...context, err: describeError(error) }, "Could not clear the poll; the next attempt may still see it");
+    });
+  };
+  let failure;
+  try {
+    const asked = await (0, import_observability.runWithTraceContext)(traceContext, "queue.process", { routing_key: routingKey, attempt, ...job.id !== void 0 ? { "job.id": job.id } : {} }, async () => {
+      lines.traceId = import_api.trace.getActiveSpan()?.spanContext().traceId;
+      options.logger.info(context, "Job started");
+      try {
+        await options.handler({
+          routingKey,
+          payload,
+          attempt,
+          messageId: job.id,
+          traceContext,
+          poll
+        });
+        return null;
+      } catch (error) {
+        if (!(error instanceof import_poll.PollAgain))
+          throw error;
+        import_api.trace.getActiveSpan()?.setAttributes({ outcome: "poll", poll_round: (poll?.round ?? 0) + 1 });
+        return error;
+      }
+    });
+    if (!asked)
+      return;
+    failure = asked;
+  } catch (error) {
+    failure = error;
+  }
+  if (failure instanceof import_poll.PollAgain) {
+    const deadlineAt = poll ? Math.min(poll.deadlineAt, failure.deadlineAt) : failure.deadlineAt;
+    if (Date.now() >= deadlineAt) {
+      failure = (0, import_codes.createQueueError)(import_codes.QueueErrorCode.POLL_TIMED_OUT, "The poll took too long");
+    }
+  }
+  if (failure instanceof import_poll.PollAgain) {
+    const next = {
+      round: (poll?.round ?? 0) + 1,
+      startedAt: poll?.startedAt ?? Date.now(),
+      deadlineAt: poll ? Math.min(poll.deadlineAt, failure.deadlineAt) : failure.deadlineAt,
+      state: failure.state ?? null
+    };
+    const deduplicationId = job.opts?.deduplication?.id;
+    if (deduplicationId !== void 0 && next.round === 1) {
+      options.logger.warn({ ...context, deduplicationId }, "A de-duplicated job is polling: publishes with its id are dropped until it finishes");
+    }
+    try {
+      if (!job.updateData || !job.moveToDelayed)
+        throw new Error("This job cannot be put back");
+      await job.updateData({ ...data, poll: next });
+      await job.moveToDelayed(Date.now() + failure.delayMs, token);
+      options.logger.debug?.({ ...context, round: next.round, delayMs: failure.delayMs }, "Waiting; the slot is handed back");
+      throw new import_bullmq.DelayedError();
+    } catch (error) {
+      if (error instanceof import_bullmq.DelayedError)
+        throw error;
+      failure = error;
+    }
+  } else if (failure instanceof import_poll.RestartPoll || poll && Date.now() >= poll.deadlineAt) {
+    await clearPoll();
+  }
+  const message = describeError(failure);
+  const kept = message.slice(0, MAX_ERROR_LENGTH);
+  if ((failure instanceof import_poll.RestartPoll || (0, import_errors.isTransientError)(failure)) && attempt < options.maxAttempts) {
+    options.logger.warn({ ...context, err: message }, "Handler failed; scheduling retry");
+    throw new RetryLater(kept, retryDelayMs(failure, attempt, options.retryDelaysMs ?? import_topology.DEFAULT_RETRY_DELAYS_MS));
+  }
+  options.logger.error({ ...context, err: message }, "Handler failed permanently; keeping as failed");
+  throw new import_bullmq.UnrecoverableError(kept);
+}
+async function startConsumer(connection, options) {
+  if (!Number.isInteger(options.concurrency) || options.concurrency < 1)
+    throw new Error("concurrency must be a positive integer");
+  const worker = new import_bullmq.Worker(options.queue, (job, token) => handleJob(job, options, token), {
+    connection: connection.redis,
+    prefix: connection.prefix,
+    concurrency: options.concurrency,
+    settings: {
+      backoffStrategy: (_attemptsMade, _type, error) => error instanceof RetryLater ? error.delayMs : 0
+    }
+  });
+  worker.on("error", (error) => {
+    options.logger.error({ queue: options.queue, err: describeError(error) }, "Queue worker error");
+  });
+  await worker.waitUntilReady();
+  return {
+    stop: async () => {
+      await worker.close();
+    },
+    running: () => worker.isRunning()
+  };
+}
+async function startConsumers(connection, options) {
+  const lanes = [
+    await startConsumer(connection, options),
+    await startConsumer(connection, { ...options, queue: (0, import_topology.priorityQueueName)(options.queue) })
+  ];
+  return {
+    stop: async () => {
+      await Promise.all(lanes.map((lane) => lane.stop()));
+    },
+    running: () => lanes.every((lane) => lane.running())
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RetryLater,
+  handleJob,
+  retryDelayMs,
+  startConsumer,
+  startConsumers
+});

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export * from './topology.js';
+export * from './publisher.js';
+export * from './consumer.js';
+export * from './outbox-relay.js';
+export * from './poll.js';
+export * from './codes.js';

package/dist/cjs/index.js

@@ -0,0 +1,31 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);
+__reExport(index_exports, require("./topology.js"), module.exports);
+__reExport(index_exports, require("./publisher.js"), module.exports);
+__reExport(index_exports, require("./consumer.js"), module.exports);
+__reExport(index_exports, require("./outbox-relay.js"), module.exports);
+__reExport(index_exports, require("./poll.js"), module.exports);
+__reExport(index_exports, require("./codes.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./topology.js"),
+  ...require("./publisher.js"),
+  ...require("./consumer.js"),
+  ...require("./outbox-relay.js"),
+  ...require("./poll.js"),
+  ...require("./codes.js")
+});

package/dist/cjs/outbox-relay.d.ts

@@ -0,0 +1,34 @@
+import type { QueueLogger } from './consumer.js';
+import type { Publisher } from './publisher.js';
+/** Structurally identical to a project's `OutboxRepository.processBatch`. */
+export interface OutboxStore {
+    processBatch(limit: number, publish: (message: {
+        id: string;
+        routingKey: string;
+        payload: unknown;
+        traceContext?: string | null;
+        priority?: boolean;
+    }) => Promise<void>): Promise<number>;
+}
+export declare class OutboxRelay {
+    private readonly store;
+    private readonly publisher;
+    private readonly logger;
+    private running;
+    private loop;
+    private readonly batchSize;
+    private readonly idleDelayMs;
+    constructor(store: OutboxStore, publisher: Publisher, logger: QueueLogger, options?: {
+        batchSize?: number;
+        idleDelayMs?: number;
+    });
+    /**
+     * Publishes one batch. An unroutable message is poison, not an outage: it is logged at error
+     * level and treated as handled, so one bad row cannot block the messages behind it. Any other
+     * publish error propagates to the store, stops the batch, and is logged here with tick
+     * reporting zero so the loop keeps running.
+     */
+    tick(): Promise<number>;
+    start(): void;
+    stop(): Promise<void>;
+}