@vercube/queue 1.3.0

package/dist/index.d.mts

@@ -0,0 +1,953 @@
+import { n as QueueTypes, t as QueueStrategy } from "./QueueStrategy-saWSBeU6.mjs";
+import { BaseDecorator, Container } from "@vercube/di";
+import { Logger } from "@vercube/logger";
+import { App, BasePlugin, ValidationProvider } from "@vercube/core";
+//#region src/Decorators/AnyJob.d.ts
+/**
+ * Declares the decorated method as the handler of every job of the queue that no
+ * `@Job()` claims.
+ *
+ * A handler registered for a job name always wins, so `@AnyJob()` is the fallback
+ * rather than a replacement. It is what makes a queue somebody else fills
+ * consumable: messages produced outside this module carry no job name, and would
+ * otherwise be reported as unhandled.
+ *
+ * The real job name is on the context, so the handler can still branch on it.
+ * Only one `@AnyJob()` per queue is allowed, like any other handler.
+ *
+ * @param {QueueTypes.HandlerOptions} [options] - Retries, timeout and payload schema of this handler
+ * @returns {Function} The method decorator
+ *
+ * @example
+ * ```ts
+ * // a queue filled by another application, whose messages carry no job name
+ * @Consumer({ queue: 'legacy-events' })
+ * export class LegacyConsumer {
+ *   @AnyJob({ attempts: 3 })
+ *   public async handle(payload: unknown, context: QueueTypes.JobContext): Promise<void> {
+ *     await this.gEvents.ingest(payload, context.job);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // known jobs handled on their own, everything else swept up
+ * @Consumer({ queue: 'emails' })
+ * export class EmailConsumer {
+ *   @Job('welcome')
+ *   public async welcome(payload: Welcome): Promise<void> {}
+ *
+ *   @AnyJob()
+ *   public async rest(payload: unknown, context: QueueTypes.JobContext): Promise<void> {
+ *     context.logger?.warn(`unrecognised job ${context.job}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function AnyJob(options?: QueueTypes.HandlerOptions): Function;
+//#endregion
+//#region src/Decorators/Consumer.d.ts
+/**
+ * Declares a class as the consumer of a queue.
+ *
+ * The class itself does nothing until it is bound in the container: that is when
+ * its `@Job()` methods register themselves and the queue starts being consumed.
+ * Options declared here become the defaults of every handler in the class.
+ *
+ * @param {QueueTypes.ConsumerOptions} options - Queue to consume, its concurrency and the handler defaults
+ * @returns {Function} The class decorator
+ *
+ * @example
+ * ```ts
+ * @Consumer({ queue: 'emails', concurrency: 5 })
+ * export class EmailConsumer {
+ *   @Job('welcome')
+ *   public async welcome(payload: { userId: string }): Promise<void> {
+ *     await this.mailer.sendWelcome(payload.userId);
+ *   }
+ * }
+ *
+ * // in the container setup
+ * container.bind(EmailConsumer);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // defaults for every handler of the class, overridable per job
+ * @Consumer({ queue: 'reports', strategy: 'kafka', attempts: 3, timeout: 30_000 })
+ * export class ReportConsumer {}
+ * ```
+ */
+export declare function Consumer(options: QueueTypes.ConsumerOptions): Function;
+//#endregion
+//#region src/Decorators/Job.d.ts
+/** Options the `@Job()` decorator is created with. */
+interface JobDecoratorOptions {
+  /** Name of the job the method handles. */
+  name: string;
+  /** Consumer-side options of this handler. */
+  options: QueueTypes.HandlerOptions;
+}
+/**
+ * Registers the decorated method as the handler of a single job.
+ * Runs when the container instantiates the consumer class.
+ */
+export declare class JobDecorator extends BaseDecorator<JobDecoratorOptions> {
+  /** Queue manager the handler is registered with */
+  private gQueueManager;
+  /** Logger instance */
+  private gLogger;
+  /** The registration handed to the manager, kept so it can be removed again */
+  private fRegistration;
+  /**
+   * Registers the handler with the queue manager.
+   *
+   * @returns {void}
+   */
+  created(): void;
+  /**
+   * Removes the handler again, so rebinding the consumer class does not collide
+   * with the handler its previous instance registered.
+   *
+   * @returns {void}
+   */
+  destroyed(): void;
+  /**
+   * Reports a consumer that cannot be wired up.
+   *
+   * @param {string} message - What is wrong
+   * @returns {void}
+   */
+  private warn;
+}
+/**
+ * Declares the decorated method as the handler of a job.
+ *
+ * The method receives the job payload as its first argument and a
+ * {@link QueueTypes.JobContext} as its second. Returning marks the job as done,
+ * throwing marks the attempt as failed and hands it to the retry policy.
+ *
+ * Options given here override the defaults of the `@Consumer()` class. To handle
+ * everything the queue carries beyond the named jobs, see `@AnyJob()`.
+ *
+ * @param {string} name - Name of the job, as used when adding it to the queue
+ * @param {QueueTypes.HandlerOptions} [options] - Retries, timeout and payload schema of this handler
+ * @returns {Function} The method decorator
+ *
+ * @example
+ * ```ts
+ * @Consumer({ queue: 'emails' })
+ * export class EmailConsumer {
+ *   @Job('welcome')
+ *   public async welcome(payload: { userId: string }): Promise<void> {
+ *     await this.mailer.sendWelcome(payload.userId);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // three attempts with a growing delay, a validated payload and a hard time limit
+ * @Job('digest', {
+ *   attempts: 3,
+ *   backoff: { type: 'exponential', delay: 1000 },
+ *   timeout: 30_000,
+ *   schema: DigestSchema,
+ * })
+ * public async digest(payload: Digest, context: QueueTypes.JobContext<Digest>): Promise<void> {
+ *   context.logger?.info(`attempt ${context.attempt} of ${context.attempts}`);
+ *   await context.updateProgress(50);
+ * }
+ * ```
+ */
+export declare function Job(name: string, options?: QueueTypes.HandlerOptions): Function;
+//#endregion
+//#region src/Decorators/OnJobCompleted.d.ts
+/**
+ * Runs the decorated method after a job of the consumer's queue completed.
+ *
+ * The hook receives the {@link QueueTypes.JobContext} of the finished job. It
+ * never changes the outcome of that job: a throwing hook is logged and forgotten.
+ *
+ * @param {object} [options] - Narrows the hook down to a single job
+ * @param {string} [options.job] - Name of the only job to listen for, every job of the queue by default
+ * @returns {Function} The method decorator
+ *
+ * @example
+ * ```ts
+ * @Consumer({ queue: 'emails' })
+ * export class EmailConsumer {
+ *   @Job('welcome')
+ *   public async welcome(payload: { userId: string }): Promise<void> {}
+ *
+ *   @OnJobCompleted()
+ *   public async sent(context: QueueTypes.JobContext): Promise<void> {
+ *     this.metrics.increment(`emails.${context.job}.sent`);
+ *   }
+ * }
+ * ```
+ */
+export declare function OnJobCompleted(options?: {
+  job?: string;
+}): Function;
+//#endregion
+//#region src/Decorators/OnJobFailed.d.ts
+/**
+ * Runs the decorated method after an attempt of a job of the consumer's queue threw.
+ *
+ * The hook receives the error and the {@link QueueTypes.JobContext} of the failed
+ * attempt, so it can tell a retry from a final failure by comparing
+ * `context.attempt` with `context.attempts`. It never changes the outcome of the
+ * job: a throwing hook is logged and forgotten.
+ *
+ * @param {object} [options] - Narrows the hook down to a single job
+ * @param {string} [options.job] - Name of the only job to listen for, every job of the queue by default
+ * @returns {Function} The method decorator
+ *
+ * @example
+ * ```ts
+ * @Consumer({ queue: 'emails' })
+ * export class EmailConsumer {
+ *   @Job('welcome', { attempts: 3 })
+ *   public async welcome(payload: { userId: string }): Promise<void> {}
+ *
+ *   @OnJobFailed()
+ *   public async failed(error: Error, context: QueueTypes.JobContext): Promise<void> {
+ *     if (context.attempt === context.attempts) {
+ *       await this.alerts.report(error, context.id);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function OnJobFailed(options?: {
+  job?: string;
+}): Function;
+//#endregion
+//#region src/Plugins/QueuePlugin.d.ts
+/**
+ * Queue Plugin for Vercube framework
+ *
+ * Binds the {@link QueueManager}, mounts the strategies it is given and lets the
+ * `@Consumer()` classes bound in the container start consuming once the
+ * application is up. Consumer classes themselves stay in your hands: bind them
+ * where you bind your controllers.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@vercube/core';
+ * import { QueuePlugin } from '@vercube/queue';
+ * import { BullMQStrategy } from '@vercube/queue/strategies/BullMQStrategy';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     [QueuePlugin, {
+ *       strategies: [{ strategy: BullMQStrategy, initOptions: { connection: { host: '127.0.0.1', port: 6379 } } }],
+ *     }],
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // a web process that only publishes jobs
+ * app.addPlugin(QueuePlugin, {
+ *   autoStart: false,
+ *   strategies: [{ strategy: MemoryStrategy }],
+ * });
+ * ```
+ *
+ * @see {@link https://vercube.dev} for full documentation
+ */
+export declare class QueuePlugin extends BasePlugin<QueueTypes.PluginOptions> {
+  /**
+   * The name of the plugin.
+   * @override
+   */
+  name: string;
+  /**
+   * Binds the queue manager and mounts every configured strategy.
+   *
+   * Registering the plugin more than once, which happens as soon as it is listed
+   * both in the config and in `app.addPlugin()`, is harmless: the manager is
+   * bound once, settings are merged, and a name that is already mounted is left
+   * alone. Rebinding it would drop the settings and the strategies of whoever
+   * registered first.
+   *
+   * @param {App} app - The application instance
+   * @param {QueueTypes.PluginOptions} [options] - Strategies to mount and manager-wide settings
+   * @returns {Promise<void>} Resolves once every strategy is mounted
+   * @override
+   */
+  use(app: App, options?: QueueTypes.PluginOptions): Promise<void>;
+}
+//#endregion
+//#region src/Errors/QueueError.d.ts
+/**
+ * Error thrown by the queue module.
+ * Wraps transport errors with a stable shape so callers can tell what failed
+ * and whether the job is worth retrying.
+ */
+export declare class QueueError extends Error {
+  /** The original error that caused this one. */
+  readonly cause?: Error;
+  /** The queue operation that failed, for example `publish` or `consume`. */
+  readonly operation: string;
+  /** Whether processing the job again could succeed. */
+  readonly retryable: boolean;
+  /** Additional non-sensitive context about the failure. */
+  readonly metadata?: Record<string, unknown>;
+  /**
+   * @param message - Human readable description of the failure.
+   * @param operation - Queue operation that failed.
+   * @param cause - Underlying error, when there is one.
+   * @param metadata - Additional non-sensitive context.
+   * @param retryable - Whether processing the job again could succeed, defaults to true.
+   */
+  constructor(message: string, operation: string, cause?: Error, metadata?: Record<string, unknown>, retryable?: boolean);
+}
+//#endregion
+//#region src/Services/QueueManager.d.ts
+/**
+ * Central entry point of the queue module.
+ *
+ * The manager owns the mounted strategies, the handlers registered by the
+ * decorators and everything that has to behave the same across transports:
+ * routing a job to its handler, validating payloads, retries, timeouts,
+ * lifecycle hooks and the counters the devtools read.
+ *
+ * @example
+ * ```ts
+ * container.bind(QueueManager);
+ *
+ * const queue = container.get(QueueManager);
+ * await queue.mount({ strategy: MemoryStrategy });
+ *
+ * await queue.add({ queue: 'emails', job: 'welcome', payload: { userId: '1' } });
+ * ```
+ */
+export declare class QueueManager {
+  /** Container instance */
+  protected gContainer: Container;
+  /** Logger instance */
+  protected gLogger: Logger | null;
+  /** Validation provider, needed only by handlers declaring a schema */
+  protected gValidation: ValidationProvider | null;
+  /** Mounted strategies, indexed by mount name */
+  protected fStrategies: Map<string, QueueTypes.MountedStrategy<any>>;
+  /** Registered handlers, indexed by strategy, queue and job name */
+  protected fRegistrations: Map<string, QueueTypes.Registration>;
+  /** Registered lifecycle hooks */
+  protected fHooks: {
+    completed: QueueTypes.HookRegistration[];
+    failed: QueueTypes.HookRegistration[];
+  };
+  /** Running consumers, indexed by strategy and queue */
+  protected fConsumers: Map<string, {
+    handle: QueueTypes.ConsumerHandle;
+    concurrency: number;
+  }>;
+  /** Per-queue counters, indexed by strategy and queue */
+  protected fMetrics: Map<string, QueueTypes.QueueMetrics>;
+  /** Recently processed jobs, newest first */
+  protected fEvents: QueueTypes.JobEvent[];
+  /** Manager-wide settings */
+  protected fDefaults: Required<QueueTypes.Defaults>;
+  /** Whether consumers should be running */
+  protected fStarted: boolean;
+  /** Serializes start, stop and mount work so consumers are never started twice */
+  protected fTail: Promise<void>;
+  /** Retries waiting for their backoff to elapse */
+  protected fPendingRetries: Set<Promise<void>>;
+  /** Listeners following the jobs this manager processes */
+  protected fListeners: Set<QueueTypes.JobListener>;
+  /**
+   * Whether consumers have been started.
+   *
+   * @returns {boolean} True once {@link QueueManager.start} ran
+   */
+  get started(): boolean;
+  /**
+   * Currently configured settings.
+   *
+   * @returns {Required<QueueTypes.Defaults>} A copy of the active settings
+   */
+  get defaults(): Required<QueueTypes.Defaults>;
+  /**
+   * Sets manager-wide settings. Calling it repeatedly merges into the existing
+   * ones, and settings passed per job or per handler always win.
+   *
+   * @param {QueueTypes.Defaults} defaults - Settings to apply
+   * @returns {void}
+   */
+  configure(defaults: QueueTypes.Defaults): void;
+  /**
+   * Mounts a strategy under a name. Every other call refers to it by that name,
+   * so a single application can talk to several brokers at once.
+   *
+   * The strategy is resolved through the container, connects on first use, and
+   * starts consuming right away when the manager is already running.
+   *
+   * @template T - Strategy being mounted
+   * @param {QueueTypes.Mount<T>} params - Mount name, strategy class and its init options
+   * @returns {Promise<void>} Resolves once the strategy is mounted
+   */
+  mount<T extends QueueStrategy<unknown>>({ name, strategy, initOptions }: QueueTypes.Mount<T>): Promise<void>;
+  /**
+   * Stops and closes a mounted strategy, and forgets it.
+   * Handlers registered for it stay registered, so mounting it again resumes them.
+   *
+   * @param {string} [name] - Mount name, defaults to `default`
+   * @returns {Promise<void>} Resolves once the strategy is closed
+   */
+  unmount(name?: string): Promise<void>;
+  /**
+   * Returns a mounted strategy, for the rare case a transport-specific API is needed.
+   *
+   * @param {string} [name] - Mount name, defaults to `default`
+   * @returns {QueueStrategy<unknown> | undefined} The strategy, or undefined when nothing is mounted under that name
+   */
+  getStrategy(name?: string): QueueStrategy<unknown> | undefined;
+  /**
+   * Adds a single job to a queue.
+   *
+   * @template TQueue - Queue the job is added to
+   * @template TJob - Name of the job
+   * @param {QueueTypes.AddRequest<TQueue, TJob>} request - Queue, job name, payload and per-job options
+   * @returns {Promise<QueueTypes.JobRef>} Reference to the published job
+   * @throws {QueueError} When no strategy is mounted under the requested name, or the job cannot be published
+   */
+  add<TQueue extends QueueTypes.QueueName, TJob extends QueueTypes.JobName<TQueue>>(request: QueueTypes.AddRequest<TQueue, TJob>): Promise<QueueTypes.JobRef>;
+  /**
+   * Adds many jobs of the same kind to a queue, using the transport's batch API
+   * when it has one.
+   *
+   * @template TQueue - Queue the jobs are added to
+   * @template TJob - Name of the jobs
+   * @param {QueueTypes.AddManyRequest<TQueue, TJob>} request - Queue, job name, payloads and per-job options
+   * @returns {Promise<QueueTypes.JobRef[]>} References to the published jobs, in the same order
+   * @throws {QueueError} When no strategy is mounted under the requested name, or the jobs cannot be published
+   */
+  addMany<TQueue extends QueueTypes.QueueName, TJob extends QueueTypes.JobName<TQueue>>(request: QueueTypes.AddManyRequest<TQueue, TJob>): Promise<QueueTypes.JobRef[]>;
+  /**
+   * Registers a handler for a single job, or for every job the queue has no
+   * other handler for when registered under `*`. The decorators call this, and so
+   * can application code building its consumers dynamically.
+   *
+   * When the manager is already running, the queue starts being consumed right away.
+   *
+   * @param {QueueTypes.Registration} registration - Queue, job name, handler and its options
+   * @returns {void}
+   * @throws {QueueError} When a handler for the same job is already registered
+   */
+  registerConsumer(registration: QueueTypes.Registration): void;
+  /**
+   * Registers a lifecycle hook for a queue.
+   *
+   * @param {'completed' | 'failed'} event - Event to listen for
+   * @param {QueueTypes.HookRegistration} registration - Queue, optional job filter and the hook itself
+   * @returns {void}
+   */
+  registerHook(event: 'completed' | 'failed', registration: QueueTypes.HookRegistration): void;
+  /**
+   * Removes a registered handler. The queue stops being consumed once its last
+   * handler is gone.
+   *
+   * @param {Pick<QueueTypes.Registration, 'strategy' | 'queue' | 'job'>} registration - Handler to remove
+   * @returns {void}
+   */
+  unregisterConsumer(registration: Pick<QueueTypes.Registration, 'strategy' | 'queue' | 'job'>): void;
+  /**
+   * Removes a registered lifecycle hook.
+   *
+   * @param {'completed' | 'failed'} event - Event the hook listens for
+   * @param {QueueTypes.HookRegistration} registration - The very registration that was registered
+   * @returns {void}
+   */
+  unregisterHook(event: 'completed' | 'failed', registration: QueueTypes.HookRegistration): void;
+  /**
+   * Connects every mounted strategy and starts consuming every queue that has
+   * a handler. Safe to call more than once, queues already running are left alone.
+   *
+   * @returns {Promise<void>} Resolves once every consumer is running
+   */
+  start(): Promise<void>;
+  /**
+   * Stops every consumer while keeping the connections open, so the application
+   * can still publish. In-flight jobs are awaited.
+   *
+   * @returns {Promise<void>} Resolves once every consumer is stopped
+   */
+  stop(): Promise<void>;
+  /**
+   * Stops every consumer and closes every connection.
+   *
+   * @returns {Promise<void>} Resolves once everything is closed
+   */
+  close(): Promise<void>;
+  /**
+   * Waits for the work the manager scheduled in the background: starting or
+   * stopping consumers, and retries waiting for their backoff to elapse.
+   *
+   * @returns {Promise<void>} Resolves once nothing is pending
+   */
+  drain(): Promise<void>;
+  /**
+   * Reads live counters of a queue straight from the transport.
+   *
+   * @param {object} params - Queue to read and the strategy to read it from
+   * @param {string} params.queue - Queue to read
+   * @param {string} [params.strategy] - Mount name, defaults to `default`
+   * @returns {Promise<QueueTypes.QueueStats>} The counters the transport reports, empty when it reports none
+   */
+  stats({ queue, strategy }: {
+    queue: string;
+    strategy?: string;
+  }): Promise<QueueTypes.QueueStats>;
+  /**
+   * Follows every job this manager finishes, as it finishes it.
+   *
+   * The listener is called with the same event that goes into the inspection
+   * buffer, right after the job settled, so a listener sees a queue live instead
+   * of polling it. A listener that throws is reported and kept.
+   *
+   * @param {QueueTypes.JobListener} listener - Called once per processed job
+   * @returns {() => void} Removes the listener again
+   */
+  subscribe(listener: QueueTypes.JobListener): () => void;
+  /**
+   * Shows what a queue is holding, without consuming any of it.
+   *
+   * Only transports that can be read without side effects support this, which
+   * they report as the `peek` capability. Everything else returns nothing rather
+   * than perturbing the queue: taking delivery of a message to look at it would
+   * change delivery counts and compete with the running consumer.
+   *
+   * @param {object} params - Queue to look at and how much of it to read
+   * @param {string} params.queue - Queue to look at
+   * @param {string} [params.strategy] - Mount name, defaults to `default`
+   * @param {number} [params.limit] - How many messages to read, defaults to 20
+   * @param {QueueTypes.PeekState[]} [params.states] - States to read, defaults to waiting, delayed and failed
+   * @returns {Promise<QueueTypes.PeekedJob[]>} The messages found, with their payloads rendered
+   * @throws {QueueError} When the transport fails to answer
+   */
+  peek({ queue, strategy, limit, states }: {
+    queue: string;
+    strategy?: string;
+    limit?: number;
+    states?: QueueTypes.PeekState[];
+  }): Promise<QueueTypes.PeekedJob[]>;
+  /**
+   * Describes what the module currently holds: mounted strategies, registered
+   * handlers, per-queue counters and the last processed jobs. Used by the devtools.
+   *
+   * @returns {QueueTypes.Snapshot} The current state of the queue module
+   */
+  inspect(): QueueTypes.Snapshot;
+  /**
+   * Processes a single job: routes it to its handler, validates the payload,
+   * enforces the timeout, runs the lifecycle hooks and applies the retry policy.
+   *
+   * The handler registered for the job name wins, and a handler registered under
+   * `*` picks up whatever is left.
+   *
+   * Rejecting tells the strategy the job failed for good, so it can dead-letter it.
+   *
+   * @param {string} strategy - Mount name the job came from
+   * @param {string} queue - Queue the job came from
+   * @param {QueueTypes.IncomingJob} incoming - The job as received from the transport
+   * @returns {Promise<void>} Resolves when the job may be acknowledged
+   * @throws {Error} When the job failed and the transport has to deal with it
+   */
+  protected process(strategy: string, queue: string, incoming: QueueTypes.IncomingJob): Promise<void>;
+  /**
+   * Does the work {@link QueueManager.process} traces.
+   *
+   * @param {string} strategy - Mount name the job came from
+   * @param {string} queue - Queue the job came from
+   * @param {QueueTypes.IncomingJob} incoming - The job as received from the transport
+   * @returns {Promise<void>} Resolves when the job may be acknowledged
+   * @throws {Error} When the job failed and the transport has to deal with it
+   */
+  protected processJob(strategy: string, queue: string, incoming: QueueTypes.IncomingJob): Promise<void>;
+  /**
+   * Applies the failure policy of a job: hooks first, then either a retry the
+   * manager schedules itself, or a rejection handing the job back to the transport.
+   *
+   * @param {Error} error - Error the attempt failed with
+   * @param {QueueTypes.Registration} registration - Handler that failed
+   * @param {QueueTypes.JobContext} context - Context of the failed attempt
+   * @param {number} duration - How long the attempt took, in milliseconds
+   * @returns {Promise<void>} Resolves once a retry has been scheduled
+   * @throws {Error} The original error, when the transport has to deal with the failure
+   */
+  protected handleFailure(error: Error, registration: QueueTypes.Registration, context: QueueTypes.JobContext, duration: number): Promise<void>;
+  /**
+   * Publishes the job again for its next attempt, waiting for the backoff first.
+   *
+   * The wait is handed to the transport when it can delay jobs, and kept on a
+   * timer otherwise, so the handler slot is released immediately either way.
+   *
+   * @param {QueueTypes.Registration} registration - Handler that failed
+   * @param {QueueTypes.JobContext} context - Context of the failed attempt
+   * @param {Error} error - Error the attempt failed with, reported when the retry cannot be published
+   * @returns {Promise<void>} Resolves once the retry exists, or once it has been scheduled on a timer
+   * @throws {Error} When the retry could be published right away and the transport refused it
+   */
+  protected scheduleRetry(registration: QueueTypes.Registration, context: QueueTypes.JobContext, error: Error): Promise<void>;
+  /**
+   * Runs a handler, failing the attempt when it outlives its timeout.
+   * A timed out handler is not interrupted, it is only stopped being waited for.
+   *
+   * @param {QueueTypes.Registration} registration - Handler to run
+   * @param {QueueTypes.JobContext} context - Context of the attempt
+   * @returns {Promise<void>} Resolves once the handler returned
+   * @throws {QueueError} When the handler outlives its timeout
+   */
+  protected runHandler(registration: QueueTypes.Registration, context: QueueTypes.JobContext): Promise<void>;
+  /**
+   * Validates a payload against the handler's schema, when it declares one.
+   *
+   * @param {QueueTypes.Registration} registration - Handler the payload is meant for
+   * @param {unknown} payload - Payload as received from the transport
+   * @param {string} job - Name of the job being processed, which a wildcard handler does not know upfront
+   * @returns {Promise<unknown>} The validated payload, as returned by the schema
+   * @throws {QueueError} When the payload does not match the schema, or no validation provider is bound
+   */
+  protected validate(registration: QueueTypes.Registration, payload: unknown, job: string): Promise<unknown>;
+  /**
+   * Runs the hooks registered for a queue. A hook filtered by job name runs for
+   * that job only, unless the filter is `*`. A throwing hook is logged and never
+   * changes the outcome of the job.
+   *
+   * @param {'completed' | 'failed'} event - Event being reported
+   * @param {QueueTypes.Registration} registration - Handler the event belongs to
+   * @param {QueueTypes.JobContext} context - Context of the attempt
+   * @param {Error} [error] - Error of the attempt, for the `failed` event
+   * @returns {Promise<void>} Resolves once every hook settled
+   */
+  protected runHooks(event: 'completed' | 'failed', registration: QueueTypes.Registration, context: QueueTypes.JobContext, error?: Error): Promise<void>;
+  /**
+   * Connects a mounted strategy and starts consuming every queue it has handlers for.
+   * Failures are logged and leave the other mounts untouched.
+   *
+   * @param {string} name - Mount name
+   * @returns {Promise<void>} Resolves once the mount is running
+   */
+  protected startMount(name: string): Promise<void>;
+  /**
+   * Starts consuming a single queue, unless it is already being consumed.
+   *
+   * @param {string} strategy - Mount name
+   * @param {string} queue - Queue to consume
+   * @returns {Promise<void>} Resolves once the consumer is running
+   */
+  protected startQueue(strategy: string, queue: string): Promise<void>;
+  /**
+   * Starts consuming a queue at a given concurrency and records the handle.
+   *
+   * @param {QueueTypes.MountedStrategy} mount - Mount the queue lives on
+   * @param {string} queue - Queue to consume
+   * @param {number} concurrency - How many jobs the transport may hand over at once
+   * @returns {Promise<void>} Resolves once the transport is delivering
+   * @throws {Error} When the strategy cannot start consuming
+   */
+  private consumeQueue;
+  /**
+   * Stops every consumer of a mount.
+   *
+   * @param {string} strategy - Mount name
+   * @returns {Promise<void>} Resolves once every consumer is stopped
+   */
+  protected stopConsumers(strategy: string): Promise<void>;
+  /**
+   * Stops the consumer of a single queue, waiting for its in-flight jobs.
+   *
+   * @param {string} strategy - Mount name
+   * @param {string} queue - Queue whose consumer is stopped
+   * @returns {Promise<void>} Resolves once the consumer is stopped
+   */
+  protected stopQueue(strategy: string, queue: string): Promise<void>;
+  /**
+   * Closes a strategy, keeping a failure from breaking a shutdown sequence.
+   *
+   * @param {QueueTypes.MountedStrategy} mount - Mount to close
+   * @returns {Promise<void>} Resolves once the strategy is closed
+   */
+  protected closeStrategy(mount: QueueTypes.MountedStrategy<any>): Promise<void>;
+  /**
+   * Initializes a strategy once, reusing the same promise for every later call.
+   *
+   * @param {QueueTypes.MountedStrategy} mount - Mount to initialize
+   * @returns {Promise<void>} Resolves once the strategy is ready
+   * @throws {QueueError} When the strategy cannot be initialized
+   */
+  protected ensureReady(mount: QueueTypes.MountedStrategy<any>): Promise<void>;
+  /**
+   * Resolves a mount by name and makes sure it is connected.
+   *
+   * @param {string} [name] - Mount name, defaults to `default`
+   * @param {string} operation - Operation asking for the mount, reported in the error
+   * @returns {Promise<QueueTypes.MountedStrategy>} The ready mount
+   * @throws {QueueError} When nothing is mounted under that name, or it cannot connect
+   */
+  protected resolveMount(name: string | undefined, operation: string): Promise<QueueTypes.MountedStrategy<any>>;
+  /**
+   * Builds the transport-facing shape of a job, adding the headers the module
+   * needs to route and retry it.
+   *
+   * @param {string} queue - Queue the job goes to
+   * @param {string} job - Name of the job
+   * @param {unknown} payload - Payload of the job
+   * @param {QueueTypes.JobOptions} [options] - Per-job options
+   * @returns {QueueTypes.PublishRequest} The job as a strategy expects it
+   */
+  protected createPublishRequest(queue: string, job: string, payload: unknown, options?: QueueTypes.JobOptions): QueueTypes.PublishRequest;
+  /**
+   * Builds the context a handler and its hooks receive.
+   *
+   * @param {string} strategy - Mount name the job came from
+   * @param {string} queue - Queue the job came from
+   * @param {QueueTypes.IncomingJob} incoming - The job as received from the transport
+   * @param {number} attempts - Total attempts this job may take
+   * @returns {QueueTypes.JobContext} The context of this attempt
+   */
+  protected createContext(strategy: string, queue: string, incoming: QueueTypes.IncomingJob, attempts: number): QueueTypes.JobContext;
+  /**
+   * Returns the counters of a queue, creating them on first use.
+   *
+   * @param {string} strategy - Mount name
+   * @param {string} queue - Queue name
+   * @returns {QueueTypes.QueueMetrics} The mutable counters of that queue
+   */
+  protected metricsFor(strategy: string, queue: string): QueueTypes.QueueMetrics;
+  /**
+   * Appends a processed job to the inspection buffer, dropping the oldest entry
+   * once the buffer is full.
+   *
+   * The payload and headers of a failure are kept only while `capturePayloads`
+   * is on, and never for a job that completed: that is where the volume is, and
+   * a job that worked has nothing to diagnose.
+   *
+   * @param {Omit<QueueTypes.JobEvent, 'at'>} event - The processed job
+   * @param {unknown} [payload] - Payload of the attempt, kept when capturing is on
+   * @param {Record<string, string>} [headers] - Headers of the attempt, kept when capturing is on
+   * @returns {void}
+   */
+  protected record(event: Omit<QueueTypes.JobEvent, 'at'>, payload?: unknown, headers?: Record<string, string>): void;
+  /**
+   * Describes an error for the inspection buffer: its name, message and a capped
+   * stack, plus what this module knows about it when it raised the error itself.
+   *
+   * @param {Error} error - Error the attempt failed with
+   * @returns {QueueTypes.JobFailure} The failure, ready to be inspected
+   */
+  protected describeFailure(error: Error): QueueTypes.JobFailure;
+  /**
+   * Reports the state of a mount for the devtools.
+   *
+   * @param {QueueTypes.MountedStrategy} mount - Mount to describe
+   * @returns {QueueTypes.StrategyStatus} What the mount is currently doing
+   */
+  protected statusOf(mount: QueueTypes.MountedStrategy<any>): QueueTypes.StrategyStatus;
+  /**
+   * Runs a piece of lifecycle work after everything scheduled before it, so
+   * consumers are never started or stopped concurrently.
+   *
+   * @param {() => Promise<void>} task - Work to run
+   * @returns {Promise<void>} Resolves once this task ran
+   */
+  protected enqueue(task: () => Promise<void>): Promise<void>;
+  /**
+   * Key a handler is registered under.
+   *
+   * @param {string} strategy - Mount name
+   * @param {string} queue - Queue name
+   * @param {string} job - Job name
+   * @returns {string} The registration key
+   */
+  protected consumerKey(strategy: string, queue: string, job: string): string;
+  /**
+   * Key a queue is tracked under.
+   *
+   * @param {string} strategy - Mount name
+   * @param {string} queue - Queue name
+   * @returns {string} The queue key
+   */
+  protected queueKey(strategy: string, queue: string): string;
+  /**
+   * Starts the consumers once the container is initialized, so every handler
+   * registered by a decorator is known before the first job is received.
+   *
+   * @returns {void}
+   */
+  protected init(): void;
+  /**
+   * Closes every connection when the container is torn down.
+   *
+   * @returns {void}
+   */
+  protected destroy(): void;
+}
+//#endregion
+//#region src/Utils/Errors.d.ts
+/**
+ * Turns any thrown value into a {@link QueueError}, leaving queue errors alone so
+ * their operation and `retryable` flag survive.
+ *
+ * @param error - The value that was thrown.
+ * @param message - Message of the resulting error.
+ * @param operation - Queue operation that failed.
+ * @param metadata - Additional non-sensitive context.
+ * @returns The error to throw.
+ */
+export declare function toQueueError(error: unknown, message: string, operation: string, metadata?: Record<string, unknown>): QueueError;
+//#endregion
+//#region src/Utils/Job.d.ts
+/**
+ * Job name a handler registers under to receive every job of its queue that no
+ * other handler claims.
+ */
+export declare const WILDCARD_JOB = "*";
+/** Header carrying the job name across transports that have no native notion of one. */
+export declare const JOB_HEADER = "x-job";
+/** Header carrying the current attempt number. */
+export declare const ATTEMPT_HEADER = "x-attempt";
+/** Header carrying the total number of attempts the publisher asked for. */
+export declare const ATTEMPTS_HEADER = "x-attempts";
+/** Header carrying the partition or routing key a job was published with. */
+export declare const KEY_HEADER = "x-key";
+/** Header carrying the priority a job was published with. */
+export declare const PRIORITY_HEADER = "x-priority";
+/**
+ * Most attempts a job may ever take.
+ *
+ * On transports that do not retry natively the budget is read off the wire, so a
+ * producer could otherwise ask for an arbitrarily large one and turn a single
+ * poison message into an unbounded republish loop.
+ */
+export declare const MAX_ATTEMPTS = 50;
+/**
+ * Longest a retry may be held back, one day.
+ *
+ * An exponential backoff over a large attempt count overflows to `Infinity`,
+ * which `setTimeout` clamps to one millisecond: the backoff meant to slow
+ * retries down would make them as fast as the runtime allows.
+ */
+export declare const MAX_BACKOFF_MS = 86400000;
+/**
+ * Reads a positive integer from a raw header value.
+ *
+ * @param raw - Header value as received from the transport, in any shape.
+ * @param fallback - Value returned when the header is absent or unusable.
+ * @param max - Largest value accepted, so a value off the wire cannot be unbounded.
+ * @returns The parsed integer, or the fallback.
+ */
+export declare function readNumericHeader(raw: unknown, fallback: number, max?: number): number;
+/**
+ * Normalizes transport headers into plain strings, so handlers never have to deal
+ * with buffers or numbers coming from the wire.
+ *
+ * @param headers - Raw headers as received from the transport.
+ * @returns Headers with string values only.
+ */
+export declare function normalizeHeaders(headers: Record<string, unknown> | undefined | null): Record<string, string>;
+/**
+ * Computes how long to wait before the next attempt of a job.
+ *
+ * @param backoff - Backoff policy, a number being a fixed delay in milliseconds.
+ * @param attempt - Attempt that just failed, starting at 1.
+ * @returns Delay in milliseconds, zero when no backoff is configured and never above {@link MAX_BACKOFF_MS}.
+ */
+export declare function resolveBackoff(backoff: QueueTypes.Backoff | undefined, attempt: number): number;
+/**
+ * Serializes a payload for transports that only carry bytes.
+ *
+ * @param payload - Payload to serialize.
+ * @returns The payload as a UTF-8 JSON buffer.
+ * @throws {QueueError} When the payload cannot be serialized.
+ */
+export declare function encodePayload(payload: unknown): Buffer;
+/**
+ * Deserializes a payload received from a transport that only carries bytes.
+ * Content that is not JSON is returned as text, so foreign producers do not
+ * break the consumer.
+ *
+ * @param content - Raw bytes received from the transport.
+ * @returns The parsed payload, or the raw text when it is not JSON.
+ */
+export declare function decodePayload(content: Uint8Array | Buffer | string | null | undefined): unknown;
+/**
+ * Generates an id for transports that do not assign one themselves.
+ *
+ * @returns A unique job id.
+ */
+export declare function generateJobId(): string;
+/**
+ * Waits for the given number of milliseconds.
+ *
+ * @param ms - Milliseconds to wait, values below one resolve immediately.
+ * @returns Resolves once the delay elapsed.
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Drops the keys whose value is undefined.
+ *
+ * Options objects are built by spreading whatever the caller set, which leaves
+ * own properties holding `undefined` behind. A library that merges options with
+ * `Object.assign` cannot tell those apart from a deliberate value, so they have
+ * to go before the object is handed over.
+ *
+ * @param source - Object to clean up.
+ * @returns A copy without the undefined entries.
+ */
+export declare function prune<T extends Record<string, unknown>>(source: T): T;
+//#endregion
+//#region src/Utils/Mount.d.ts
+/**
+ * Type checks a single strategy mount and erases its options, so a list of
+ * mounts of different strategies stays checked.
+ *
+ * `QueueManager.mount()` infers the strategy from its argument and checks
+ * `initOptions` against it. A plain array in `QueuePlugin` options cannot do
+ * that, since there is no inference site per entry - this helper is that site.
+ *
+ * @param {QueueTypes.Mount<T>} mount - Mount name, strategy class and its init options
+ * @returns {QueueTypes.AnyMount} The very same mount, with its options type erased
+ *
+ * @example
+ * ```ts
+ * app.addPlugin(QueuePlugin, {
+ *   strategies: [
+ *     defineQueueStrategy({ strategy: RabbitMQStrategy, initOptions: { url: 'amqp://localhost' } }),
+ *     defineQueueStrategy({
+ *       name: 'events',
+ *       strategy: KafkaStrategy,
+ *       initOptions: { client: { brokers: ['localhost:9092'] }, groupId: 'workers' },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function defineQueueStrategy<T extends QueueStrategy<unknown>>(mount: QueueTypes.Mount<T>): QueueTypes.AnyMount;
+//#endregion
+//#region src/Utils/Metadata.d.ts
+/**
+ * Stores the options a `@Consumer()` class was declared with.
+ *
+ * @param prototype - Prototype of the decorated class.
+ * @param options - Options the class was declared with.
+ * @returns Nothing.
+ */
+export declare function setConsumerOptions(prototype: object, options: QueueTypes.ConsumerOptions): void;
+/**
+ * Reads the options of the closest `@Consumer()` class in the prototype chain,
+ * so a handler declared on a base class still finds its queue.
+ *
+ * @param prototype - Prototype to start looking at.
+ * @returns The options, or undefined when no class in the chain is a consumer.
+ */
+export declare function getConsumerOptions(prototype: object | null): QueueTypes.ConsumerOptions | undefined;
+//#endregion
+export { QueueStrategy, QueueTypes };