@bymax-one/nest-queue 1.0.0

package/dist/server/index.d.cts

@@ -0,0 +1,1386 @@
+import * as _nestjs_common from '@nestjs/common';
+import { ModuleMetadata, Type, DynamicModule, OnModuleDestroy, HttpException, HttpStatus } from '@nestjs/common';
+import { JobsOptions, QueueOptions, Telemetry, BulkJobOptions, Queue, Job, FlowJob, JobNode, FlowProducer, Worker, QueueEvents } from 'bullmq';
+export { FlowJob, FlowProducer, Job, JobNode, JobSchedulerJson, JobsOptions, Queue, QueueEvents, SandboxedJob, Telemetry, Worker } from 'bullmq';
+import { Redis, RedisOptions } from 'ioredis';
+
+/**
+ * @fileoverview Dual-mode Redis connection configuration contract.
+ * @layer server/interfaces
+ */
+
+/**
+ * Connection configuration — Mode A (bring your own client) or Mode B
+ * (library-owned), discriminated by the presence of `client`, `url`, or
+ * `options`. The three arms are mutually exclusive.
+ *
+ * Mode A: the caller passes a `Redis` already configured for BullMQ (typically
+ * obtained from `@bymax-one/nest-cache`). The library uses it AS-IS for the
+ * Queue and FlowProducer role and never closes it; Worker/QueueEvents roles get
+ * a duplicated connection forced to `maxRetriesPerRequest: null`.
+ *
+ * Mode B: the library opens its own `ioredis` from a URL or options object. The
+ * Queue/FlowProducer connection keeps ioredis' default retries (so enqueue
+ * fails fast during a Redis outage); the library closes it on shutdown.
+ *
+ * @example Mode A
+ * const config: QueueConnectionConfig = { client: queueRedis }
+ * @example Mode B (url)
+ * const config: QueueConnectionConfig = { url: 'redis://localhost:6379', options: { db: 1 } }
+ * @example Mode B (options only)
+ * const config: QueueConnectionConfig = { options: { host: 'localhost', port: 6379, db: 1 } }
+ */
+type QueueConnectionConfig = {
+    client: Redis;
+    ownsConnection?: false;
+} | {
+    url: string;
+    options?: Partial<RedisOptions>;
+} | {
+    options: RedisOptions;
+};
+/** Internal discriminator the ConnectionResolver uses to tag the active mode. */
+type QueueConnectionMode = 'mode-a-byo' | 'mode-b-owned';
+
+/**
+ * @fileoverview Synchronous and asynchronous module configuration contracts.
+ * @layer server/interfaces
+ */
+
+/**
+ * Synchronous configuration for `BymaxQueueModule.forRoot()`.
+ *
+ * @example
+ * BymaxQueueModule.forRoot({ connection: { url: 'redis://localhost:6379' } })
+ */
+interface BymaxQueueModuleOptions {
+    /** Redis connection configuration. Required. */
+    connection: QueueConnectionConfig;
+    /** Default options applied to every job enqueued through the service. */
+    defaultJobOptions?: JobsOptions;
+    /** Prefix for all Redis keys (multi-tenant isolation). Default: 'bull'. */
+    prefix?: string;
+    /** Default options applied to every Queue, merged with the job/prefix defaults. */
+    queueOptions?: Partial<Omit<QueueOptions, 'connection' | 'defaultJobOptions' | 'prefix'>>;
+    /** Flow Producer configuration. Opt-in. */
+    flows?: {
+        enabled?: boolean;
+    };
+    /** Metrics collection configuration. Opt-in. */
+    metrics?: {
+        enabled?: boolean;
+        cacheTtlMs?: number;
+    };
+    /**
+     * Opt-in OpenTelemetry — a BullMQ `Telemetry` (typically `new BullMQOtel(...)`
+     * from the optional peer `bullmq-otel`); attached to every Queue and Worker.
+     */
+    telemetry?: Telemetry;
+    /** Behavior on application shutdown. */
+    shutdown?: {
+        drainTimeoutMs?: number;
+        drainOnShutdown?: boolean;
+    };
+    /**
+     * Register the module globally. Mapped to `DynamicModule.global` by the
+     * configurable module builder's `setExtras` (no hand-written `@Global`).
+     * Default: true.
+     */
+    isGlobal?: boolean;
+    /** Mode B only: milliseconds to wait for Redis `ready` before throwing. Default: 10_000. */
+    connectionReadyTimeoutMs?: number;
+}
+/** A factory that produces module options, for async configuration. */
+interface BymaxQueueOptionsFactory {
+    /** Build the module options synchronously or asynchronously. */
+    createQueueOptions(): Promise<BymaxQueueModuleOptions> | BymaxQueueModuleOptions;
+}
+/** Asynchronous configuration mirroring the NestJS async dynamic-module pattern. */
+interface BymaxQueueModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    /** Factory returning the module options. */
+    useFactory?: (...args: unknown[]) => Promise<BymaxQueueModuleOptions> | BymaxQueueModuleOptions;
+    /** Class implementing the options factory. */
+    useClass?: Type<BymaxQueueOptionsFactory>;
+    /** Existing provider implementing the options factory. */
+    useExisting?: Type<BymaxQueueOptionsFactory>;
+    /** Providers injected into the factory. */
+    inject?: readonly (Type<unknown> | string | symbol)[];
+}
+
+/** Generated configurable-module artifacts; `forRoot`/`forRootAsync` register the module. */
+declare const ConfigurableModuleClass: _nestjs_common.ConfigurableModuleCls<BymaxQueueModuleOptions, "forRoot", "createQueueOptions", {
+    isGlobal: boolean;
+}>;
+declare const OPTIONS_TYPE: BymaxQueueModuleOptions & Partial<{
+    isGlobal: boolean;
+}>;
+declare const ASYNC_OPTIONS_TYPE: _nestjs_common.ConfigurableModuleAsyncOptions<BymaxQueueModuleOptions, "createQueueOptions"> & Partial<{
+    isGlobal: boolean;
+}>;
+/**
+ * Root module for the queue library. Use `forRoot` for synchronous registration
+ * or `forRootAsync` when the options depend on other modules.
+ *
+ * @example Synchronous
+ * BymaxQueueModule.forRoot({ connection: { url: 'redis://localhost:6379' } })
+ * @example Asynchronous (Mode A — bring your own client)
+ * BymaxQueueModule.forRootAsync({
+ *   inject: [REDIS_CLIENT],
+ *   useFactory: (client: Redis) => ({ connection: { client } }),
+ * })
+ */
+declare class BymaxQueueModule extends ConfigurableModuleClass {
+    /**
+     * Synchronous registration. Validates options, resolves defaults, and wires the
+     * connection resolver (initialized via async factory), the queue service, the
+     * worker registry, the queue-events registry, processor discovery, and the
+     * graceful-shutdown lifecycle.
+     *
+     * @param options - Static module options.
+     * @returns The configured dynamic module.
+     */
+    static forRoot(options: typeof OPTIONS_TYPE): DynamicModule;
+    /**
+     * Asynchronous registration. Use when options depend on other modules
+     * (ConfigService, BymaxCacheModule, etc.). Mirrors the NestJS standard async
+     * dynamic-module pattern (`useFactory` | `useClass` | `useExisting` + `inject`)
+     * and registers the same provider graph and exports as {@link forRoot}, with
+     * `global` applied from the `isGlobal` extra. The resolved options and the
+     * initialized connection are derived from the async-resolved options at runtime.
+     *
+     * @param options - Asynchronous module options.
+     * @returns The configured dynamic module.
+     */
+    static forRootAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule;
+    /**
+     * Providers shared verbatim by both registration paths: the options alias, the
+     * initialized connection resolver, the resolved client/mode tokens, and the
+     * singleton services. `BYMAX_QUEUE_RESOLVED_OPTIONS`, `FlowService`, and
+     * `MetricsService` are intentionally omitted — they differ per path.
+     *
+     * @returns The shared provider list.
+     */
+    private static buildCoreProviders;
+    /**
+     * The public exports shared by both registration paths.
+     *
+     * @returns A fresh exports list (services and injection tokens).
+     */
+    private static buildExports;
+}
+
+/**
+ * @fileoverview Symbol injection tokens for the module's providers.
+ * @layer server/constants
+ */
+/** Token for the raw, user-supplied module options. */
+declare const BYMAX_QUEUE_OPTIONS: unique symbol;
+/** Token for the resolved Redis client used by the Queue role. */
+declare const BYMAX_QUEUE_REDIS_CLIENT: unique symbol;
+/** Token for the resolved connection mode (`mode-a-byo` or `mode-b-owned`). */
+declare const BYMAX_QUEUE_CONNECTION_MODE: unique symbol;
+/** Token for the frozen, defaults-applied module options. */
+declare const BYMAX_QUEUE_RESOLVED_OPTIONS: unique symbol;
+
+/**
+ * @fileoverview Fully-resolved module options with defaults applied.
+ * @layer server/config
+ */
+
+/** Fully-resolved options — every optional field of the input is filled. */
+interface ResolvedQueueOptions {
+    /** Connection configuration, passed through untouched. */
+    connection: QueueConnectionConfig;
+    /** Default job options, merged over the library defaults. */
+    defaultJobOptions: JobsOptions;
+    /** Redis key prefix. */
+    prefix: string;
+    /** Extra Queue options applied to every queue. */
+    queueOptions: Partial<Omit<QueueOptions, 'connection' | 'defaultJobOptions' | 'prefix'>>;
+    /** Flow support configuration. */
+    flows: {
+        enabled: boolean;
+    };
+    /** Metrics support configuration. */
+    metrics: {
+        enabled: boolean;
+        cacheTtlMs: number;
+    };
+    /** Shutdown behavior configuration. */
+    shutdown: {
+        drainTimeoutMs: number;
+        drainOnShutdown: boolean;
+    };
+    /** Optional OpenTelemetry instance, attached to every Queue/Worker when present. */
+    telemetry?: Telemetry;
+    /** Mode B ready timeout in milliseconds. */
+    connectionReadyTimeoutMs: number;
+}
+
+/**
+ * @fileoverview Job descriptor used by the bulk-enqueue API.
+ * @layer server/interfaces
+ */
+
+/**
+ * A single job descriptor used by `enqueueBulk`.
+ *
+ * @example
+ * const job: BulkJob<{ to: string }> = { name: 'send', data: { to: 'a@b.com' } }
+ */
+interface BulkJob<TData = unknown> {
+    /** Job name used by handlers to dispatch. */
+    name: string;
+    /** Typed job payload. */
+    data: TData;
+    /** Per-job BullMQ options (priority, delay, jobId, deduplication, ...). */
+    options?: BulkJobOptions;
+}
+
+/**
+ * @fileoverview Job status union shared across runtimes.
+ * @layer shared/types
+ */
+/**
+ * Snapshot statuses BullMQ exposes via `Queue.getJobCounts()`.
+ * Kept in sync with BullMQ's internal status set.
+ *
+ * @example
+ * const status: JobStatus = 'waiting'
+ */
+type JobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
+
+/**
+ * @fileoverview Instantaneous queue metrics snapshot type.
+ * @layer shared/types
+ */
+
+/**
+ * Instantaneous snapshot of a queue's job counts grouped by status.
+ *
+ * @example
+ * const metrics: QueueMetrics = {
+ *   queue: 'email',
+ *   counts: { waiting: 3, active: 1, completed: 120, failed: 2, delayed: 0, paused: 0 },
+ *   collectedAt: '2026-06-26T12:00:00.000Z',
+ * }
+ */
+interface QueueMetrics {
+    /** Queue name the snapshot was taken from. */
+    queue: string;
+    /** Number of jobs in each of the six BullMQ statuses. */
+    counts: Record<JobStatus, number>;
+    /** ISO 8601 UTC timestamp when the snapshot was collected. */
+    collectedAt: string;
+}
+
+/**
+ * @fileoverview Discriminated union for the BullMQ Job Schedulers (recurring jobs) API.
+ * @layer shared/types
+ */
+/**
+ * Discriminated union for the BullMQ Job Schedulers API — the current
+ * recurring-jobs surface (the legacy repeatable API is removed in BullMQ v6).
+ * Either `pattern` (cron) OR `every` (ms interval) is provided, never both.
+ *
+ * A thin, validated projection of BullMQ's `RepeatOptions` minus the internal
+ * scheduler `key`.
+ *
+ * @example Cron schedule
+ * const daily: JobSchedulerRepeatOptions = { pattern: '0 3 * * *', tz: 'America/Sao_Paulo' }
+ * @example Fixed interval
+ * const everyMinute: JobSchedulerRepeatOptions = { every: 60_000 }
+ */
+type JobSchedulerRepeatOptions = {
+    /** Crontab expression (5-field, or 6-field with seconds). */
+    pattern: string;
+    /** IANA timezone (e.g. 'America/Sao_Paulo'). Default: UTC. */
+    tz?: string;
+    /** Optional cap on the number of runs. */
+    limit?: number;
+    /** Start time (epoch ms or ISO string). */
+    startDate?: number | string;
+    /** Stop time (epoch ms or ISO string). Must be in the future or BullMQ throws. */
+    endDate?: number | string;
+} | {
+    /** Interval in milliseconds between runs. */
+    every: number;
+    /** Optional cap on the number of runs. */
+    limit?: number;
+    /** Phase offset (ms) applied to interval schedulers. */
+    offset?: number;
+    /** Start time (epoch ms or ISO string). */
+    startDate?: number | string;
+    /** Stop time (epoch ms or ISO string). */
+    endDate?: number | string;
+};
+
+/**
+ * @fileoverview Dual-mode Redis connection resolver. Resolves a BYO client
+ * (Mode A) or opens a library-owned ioredis with a ready timeout (Mode B), and
+ * enforces the per-role `maxRetriesPerRequest` policy.
+ * @layer server/services
+ */
+
+/**
+ * Resolves the Queue-role Redis connection and tracks ownership so the lifecycle
+ * knows whether to close it on shutdown.
+ *
+ * - Mode A (BYO): the received client is used as-is for the Queue/FlowProducer
+ *   role and never closed; a duplicated probe verifies that the blocking-role
+ *   override resolves to `maxRetriesPerRequest: null`.
+ * - Mode B (owned): the library opens its own client (URL or options) and waits
+ *   for `ready`, closing it on shutdown.
+ */
+declare class ConnectionResolver {
+    private readonly options;
+    private client;
+    private mode;
+    constructor(options: BymaxQueueModuleOptions);
+    /** Resolve and validate the connection. Call once during module bootstrap. */
+    init(): Promise<void>;
+    /** The resolved Queue-role client. */
+    getClient(): Redis;
+    /** The resolved connection mode. */
+    getMode(): QueueConnectionMode;
+    /** Whether the library owns (and must close) the connection. */
+    isOwned(): boolean;
+    /** Close the library-owned connection on shutdown; never touch a BYO client. */
+    teardown(): Promise<void>;
+    /** Validate and adopt a bring-your-own client for the Queue role. */
+    private initModeA;
+    /** Resolve when the owned client reaches `ready`, or reject on timeout/error. */
+    private waitReady;
+}
+
+/**
+ * @fileoverview Base queue service — per-name Queue cache, typed enqueue/inspect,
+ * uncached metrics, and control helpers over BullMQ.
+ * @layer server/services
+ */
+
+/** A typed job in the library's public shape. */
+type TypedJob<TData, TResult> = Job<TData, TResult>;
+/** Status filter accepted by {@link QueueService.cleanQueue}, matching BullMQ. */
+type CleanableStatus = 'completed' | 'failed' | 'delayed' | 'wait' | 'active' | 'paused';
+/**
+ * The central interaction point with BullMQ queues. Maintains a per-name `Queue`
+ * cache, applies module defaults to every queue, and exposes typed helpers for
+ * enqueueing, inspection, metrics, and lifecycle control.
+ */
+declare class QueueService {
+    private readonly connection;
+    private readonly options;
+    private readonly logger;
+    private readonly queues;
+    constructor(connection: ConnectionResolver, options: ResolvedQueueOptions);
+    /**
+     * Return the cached `Queue` for `queueName`, or create one with the module
+     * defaults applied. Subsequent calls with the same name return the same
+     * instance.
+     *
+     * @param queueName - Unique queue name (used as the Redis key prefix).
+     * @param overrides - Optional per-queue option overrides.
+     */
+    getOrCreateQueue<TData = unknown, TResult = unknown>(queueName: string, overrides?: Partial<Omit<QueueOptions, 'connection' | 'prefix'>>): Queue<TData, TResult>;
+    /** Resolve the raw cached queue (default generics) for internal delegation. */
+    private queueFor;
+    /**
+     * Add a single job to a queue. The queue is created lazily if needed.
+     *
+     * Delivery is **at-least-once** — a handler may run more than once for the same
+     * job (worker crash, lock expiry, or a shutdown force-close). Make handlers
+     * idempotent: use an idempotency key on writes, prefer upserts over inserts, or
+     * keep an "already-processed" marker keyed by `job.id`.
+     *
+     * `options` surfaces BullMQ natives directly — including `jobId` (idempotent
+     * insert: a second add with the same id is a no-op while the first exists) and
+     * `deduplication` (windowed deduplication). The library writes no deduplication
+     * code; BullMQ owns the behavior. The deduplication key is independent of
+     * `jobId`, so both can be set together or apart. Both collapse duplicate
+     * **producers** and do not change the at-least-once guarantee on the
+     * **consumer** side.
+     *
+     * Deduplication modes (`deduplication: { id, ttl?, extend?, replace?, keepLastIfActive? }`):
+     *  - Simple `{ id }` — collapse duplicates until the in-flight job completes or fails.
+     *  - Throttle `{ id, ttl }` — ignore duplicates for `ttl` milliseconds.
+     *  - Debounce `{ id, ttl, extend: true, replace: true }` — keep only the latest
+     *    data; each duplicate resets the TTL.
+     *  - keep-last-if-active `{ id, keepLastIfActive: true }` — while a job is active,
+     *    store the latest data and run a single follow-up when it finishes.
+     *
+     * @param queueName - Target queue (created lazily if absent).
+     * @param jobName - Job identifier used by `@Process` to dispatch.
+     * @param data - Typed job payload.
+     * @param options - Per-job BullMQ options (priority, delay, `jobId`, `deduplication`, ...).
+     * @returns The created job.
+     * @example Throttle: at most one reindex per term every 5 seconds.
+     *   await queueService.enqueue('search', 'reindex', { term }, {
+     *     deduplication: { id: `reindex:${term}`, ttl: 5_000 },
+     *   })
+     */
+    enqueue<TData = unknown, TResult = unknown>(queueName: string, jobName: string, data: TData, options?: JobsOptions): Promise<TypedJob<TData, TResult>>;
+    /**
+     * Enqueue multiple jobs in a single Redis roundtrip. The batch is bounded by
+     * {@link MAX_BULK_SIZE} to guard against a self-inflicted memory spike; any
+     * failure is wrapped in a `QueueException`. Delivery is at-least-once, so every
+     * job's handler must be idempotent (see {@link QueueService.enqueue}).
+     *
+     * @param queueName - Target queue.
+     * @param jobs - Job descriptors (length must not exceed the bulk size cap).
+     */
+    enqueueBulk<TData = unknown, TResult = unknown>(queueName: string, jobs: readonly BulkJob<TData>[]): Promise<TypedJob<TData, TResult>[]>;
+    /**
+     * Fetch a job by id. Returns `null` when the job does not exist.
+     *
+     * @param queueName - Target queue.
+     * @param jobId - The job identifier.
+     */
+    getJob<TData = unknown, TResult = unknown>(queueName: string, jobId: string): Promise<TypedJob<TData, TResult> | null>;
+    /**
+     * Fetch jobs in a given status with pagination.
+     *
+     * @param queueName - Target queue.
+     * @param status - Status filter.
+     * @param start - Starting index (inclusive). Default: 0.
+     * @param end - Ending index (inclusive). Default: 50.
+     */
+    getJobs<TData = unknown, TResult = unknown>(queueName: string, status: JobStatus, start?: number, end?: number): Promise<TypedJob<TData, TResult>[]>;
+    /**
+     * Return an uncached snapshot of job counts grouped by status.
+     *
+     * @param queueName - Target queue.
+     */
+    getMetrics(queueName: string): Promise<QueueMetrics>;
+    /**
+     * Create or update a Job Scheduler — the current BullMQ recurring-jobs API.
+     * Idempotent by `schedulerId`: BullMQ performs an atomic `override: true`
+     * upsert, so re-registering on every boot updates the schedule in place and
+     * never duplicates it. This supersedes the repeatable-jobs surface removed in
+     * BullMQ v6.
+     *
+     * The schedule is structurally validated first; the cron string itself is
+     * parsed by BullMQ at registration time, and a parse failure is rethrown as
+     * `INVALID_REPEAT_OPTIONS` (400).
+     *
+     * @param queueName - Target queue.
+     * @param schedulerId - Stable, unique scheduler identifier (the upsert key).
+     * @param repeat - Cron `pattern` OR `every` (ms), plus optional tz/limit/start/end.
+     * @param template - Optional job template; `name` defaults to `schedulerId`, `data` to `{}`.
+     * @returns The first scheduled (delayed) job, or `undefined`.
+     * @throws {QueueException} `INVALID_REPEAT_OPTIONS` (400) for an invalid schedule.
+     */
+    upsertJobScheduler<TData = unknown, TResult = unknown>(queueName: string, schedulerId: string, repeat: JobSchedulerRepeatOptions, template?: {
+        name?: string;
+        data?: TData;
+        opts?: JobsOptions;
+    }): Promise<Job<TData, TResult> | undefined>;
+    /**
+     * Remove a Job Scheduler by id.
+     *
+     * @param queueName - Target queue.
+     * @param schedulerId - The scheduler identifier to remove.
+     * @returns `true` when a scheduler was removed, `false` otherwise.
+     */
+    removeJobScheduler(queueName: string, schedulerId: string): Promise<boolean>;
+    /**
+     * List the Job Schedulers registered on a queue, for inspection or health checks.
+     *
+     * @param queueName - Target queue.
+     * @param start - Page start index (inclusive). Default: 0.
+     * @param end - Page end index (inclusive). Default: 50.
+     * @param asc - Sort ascending by next run time. Default: true.
+     * @returns The registered schedulers in the requested page.
+     */
+    getJobSchedulers(queueName: string, start?: number, end?: number, asc?: boolean): Promise<Awaited<ReturnType<Queue['getJobSchedulers']>>>;
+    /** Pause a queue, halting the processing of new jobs. */
+    pauseQueue(queueName: string): Promise<void>;
+    /** Resume a previously paused queue. */
+    resumeQueue(queueName: string): Promise<void>;
+    /**
+     * Remove up to `limit` jobs older than `gracePeriodMs` in a given status. The
+     * argument order mirrors BullMQ's `Queue.clean(grace, limit, type?)` exactly;
+     * `limit` is required and `0` means no limit. Returns the removed job ids.
+     *
+     * @param queueName - Target queue.
+     * @param gracePeriodMs - Keep jobs younger than this many milliseconds.
+     * @param limit - Maximum number of jobs to remove (`0` = no limit).
+     * @param status - Status of jobs to clean.
+     */
+    cleanQueue(queueName: string, gracePeriodMs: number, limit: number, status?: CleanableStatus): Promise<string[]>;
+    /** Return a read-only view of the cached queues. */
+    getCachedQueues(): ReadonlyMap<string, Queue>;
+    /**
+     * Close every cached queue (swallowing per-queue errors) and clear the cache.
+     *
+     * Deliberately NOT named `onModuleDestroy`: NestJS invokes lifecycle hooks by
+     * method name, so a hook here would run on Nest's own schedule, concurrently
+     * with — and possibly before — the bounded drain in `QueueLifecycle`. Closing a
+     * queue while its worker is still draining is exactly what the ordered sequence
+     * exists to prevent. `QueueLifecycle` is the only caller.
+     */
+    closeAll(): Promise<void>;
+}
+
+/**
+ * @fileoverview FlowService — a guarded wrapper over the BullMQ `FlowProducer`
+ * for hierarchical (parent/child) job graphs. Opt-in: the provider is always
+ * registered so injecting it never fails, but every method throws
+ * `FLOW_DISABLED` (503) unless `flows.enabled` was set.
+ * @layer server/services
+ */
+
+/**
+ * Wrapper over the BullMQ `FlowProducer` for hierarchical (parent/child) job
+ * graphs. The producer runs on the main connection (Mode A received client or
+ * Mode B library-owned client) and is created only when flows are enabled.
+ *
+ * Opt-in: this provider is registered unconditionally so that injecting it never
+ * raises `UnknownDependenciesException`; instead, every operation throws
+ * `QueueException(FLOW_DISABLED, 503)` when `flows.enabled !== true`.
+ *
+ * @example
+ * await flowService.add({
+ *   name: 'generate-pdf',
+ *   queueName: 'pdf',
+ *   data: { reportId: '123' },
+ *   children: [{ name: 'fetch-data', queueName: 'data', data: { reportId: '123' } }],
+ * })
+ */
+declare class FlowService {
+    private readonly logger;
+    private readonly producer?;
+    constructor(connection: ConnectionResolver, enabled: boolean, prefix: string, telemetry?: Telemetry);
+    /**
+     * Add a flow tree (a parent with its descendant children). The root job
+     * becomes processable only after every descendant has completed.
+     *
+     * By BullMQ default a failed (retry-exhausted) child does NOT fail its parent:
+     * the parent stays in the `waiting-children` state until the child eventually
+     * completes. To make a child's failure propagate upward and fail its parent,
+     * set `failParentOnFailure: true` on that child (it cascades when ancestors
+     * also set it). To let a parent proceed despite a failed child, set
+     * `ignoreDependencyOnFailure: true` on that child. Bound each child's
+     * `attempts` so an unrecoverable child cannot leave the parent waiting forever.
+     *
+     * @param flow - Flow tree definition.
+     * @returns The root `JobNode` containing the created job and its children.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     */
+    add(flow: FlowJob): Promise<JobNode>;
+    /**
+     * Add multiple flow trees in a single Redis roundtrip.
+     *
+     * @param flows - Flow tree definitions.
+     * @returns The root `JobNode` for each flow, in input order.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     */
+    addBulk(flows: readonly FlowJob[]): Promise<JobNode[]>;
+    /**
+     * Escape hatch returning the underlying `FlowProducer` for advanced use cases.
+     * Prefer {@link FlowService.add} / {@link FlowService.addBulk} when possible.
+     *
+     * @returns The underlying BullMQ `FlowProducer`.
+     * @throws {QueueException} `FLOW_DISABLED` (503) when flows are not enabled.
+     */
+    getProducer(): FlowProducer;
+    /**
+     * Close the producer when active; a no-op when inactive. A failed `close()` is
+     * swallowed so it never aborts the shutdown sequence.
+     *
+     * Deliberately NOT named `onModuleDestroy`: NestJS invokes lifecycle hooks by
+     * method name, so a hook here would run in addition to the call the ordered
+     * sequence already makes, closing the producer twice. `QueueLifecycle` is the
+     * only caller.
+     */
+    close(): Promise<void>;
+    /**
+     * Return the active producer or throw when flows are disabled. The producer is
+     * present if and only if flows were enabled at construction time.
+     *
+     * @throws {QueueException} `FLOW_DISABLED` (503) when no producer exists.
+     */
+    private requireProducer;
+}
+
+/**
+ * @fileoverview MetricsService — an opt-in, in-memory TTL cache over
+ * `QueueService.getMetrics`. Delegates one direction (Metrics → Queue) so there
+ * is no circular dependency. Guarded: throws `METRICS_DISABLED` (503) unless
+ * `metrics.enabled` was set.
+ * @layer server/services
+ */
+
+/**
+ * Opt-in in-memory TTL cache over `QueueService.getMetrics`. A per-second
+ * `/health` poll reads from the cache instead of hammering Redis. The cache
+ * delegates to `QueueService` in a single direction, so there is no circular
+ * dependency. Every method throws `METRICS_DISABLED` (503) when metrics are not
+ * enabled.
+ *
+ * @example Health check pattern (consumer side — `@nestjs/terminus`, not a dependency here)
+ *   @Injectable()
+ *   class QueueHealthIndicator extends HealthIndicator {
+ *     constructor(private readonly metrics: MetricsService) { super() }
+ *     async isHealthy(key: string): Promise<HealthIndicatorResult> {
+ *       const all = await this.metrics.getAll()
+ *       const stuck = all.filter((m) => m.counts.active > 100 || m.counts.failed > 1000)
+ *       return this.getStatus(key, stuck.length === 0, { stuck: stuck.map((m) => m.queue) })
+ *     }
+ *   }
+ */
+declare class MetricsService {
+    private readonly queueService;
+    private readonly enabled;
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(queueService: QueueService, enabled: boolean, ttlMs: number);
+    /**
+     * Return cached metrics for `queueName`, or fetch fresh (and cache them) on a
+     * miss or after expiry.
+     *
+     * @param queueName - Target queue.
+     * @returns The current metrics snapshot.
+     * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
+     */
+    get(queueName: string): Promise<QueueMetrics>;
+    /**
+     * Return a metrics snapshot for every queue currently cached in `QueueService`.
+     *
+     * @returns Metrics for all known queues.
+     * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
+     */
+    getAll(): Promise<readonly QueueMetrics[]>;
+    /**
+     * Invalidate the cache for `queueName`, or the whole cache when omitted.
+     *
+     * @param queueName - The queue entry to drop; omit to clear everything.
+     * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
+     */
+    invalidate(queueName?: string): void;
+    /**
+     * Guard every operation behind the opt-in flag.
+     *
+     * @throws {QueueException} `METRICS_DISABLED` (503) when metrics are disabled.
+     */
+    private ensureEnabled;
+}
+
+/**
+ * @fileoverview Worker tuning options surfaced when registering a processor.
+ * @layer server/interfaces
+ */
+/**
+ * Tunables applied when registering a Worker (via decorator or programmatically).
+ * Maps to the subset of BullMQ's worker options the library exposes through its
+ * defaults.
+ *
+ * There is intentionally NO `sandboxed` boolean. BullMQ sandboxed processors are
+ * created by passing a FILE PATH (not a class) to the Worker constructor, so they
+ * run out-of-process and cannot use NestJS dependency injection. A toggle on a
+ * DI-managed processor is therefore impossible — sandboxed work uses a separate
+ * registration path (`WorkerRegistry.registerSandboxed`).
+ *
+ * @example
+ * const options: WorkerOptions = { concurrency: 5, limiter: { max: 10, duration: 1000 } }
+ */
+interface WorkerOptions {
+    /** Maximum number of jobs processed concurrently. Default: 2. */
+    concurrency?: number;
+    /** Rate limiter — at most `max` jobs per `duration` milliseconds. */
+    limiter?: {
+        max: number;
+        duration: number;
+    };
+    /** Start the worker automatically on registration. Default: true. */
+    autorun?: boolean;
+    /** Lock duration for active jobs, in milliseconds. Default: 30_000. */
+    lockDuration?: number;
+    /** Interval between stalled-job checks, in milliseconds. Default: 30_000. */
+    stalledInterval?: number;
+}
+
+/**
+ * @fileoverview `WorkerRegistry` — creates, tracks, and destroys BullMQ
+ * `Worker` instances. Provides both an in-process path (handler function, NestJS
+ * DI available) and a file-based sandboxed path (no NestJS DI). Every worker
+ * connection is a duplicate of the Queue-role client with
+ * `maxRetriesPerRequest: null`, as required by BullMQ blocking commands. The
+ * duplicated connection is tracked alongside the worker so the shutdown
+ * orchestrator can close exactly the connections the library opened.
+ * @layer server/services
+ */
+
+/**
+ * Configuration for registering an in-process (NestJS-DI-backed) worker.
+ *
+ * @template TData - Shape of the job data payload.
+ * @template TResult - Shape of the job result.
+ */
+interface ProgrammaticWorkerConfig<TData = unknown, TResult = unknown> {
+    /** BullMQ queue the worker should consume. */
+    queueName: string;
+    /** Async function that processes a single job. Must be idempotent. */
+    handler: (job: Job<TData, TResult>) => Promise<TResult>;
+    /** Optional worker tuning overrides. */
+    options?: WorkerOptions;
+}
+/**
+ * Configuration for registering a sandboxed (file-based, out-of-process) worker.
+ * The processor runs in a separate Node.js process and cannot access NestJS DI.
+ * `processorFile` must be an absolute path or a `file:` URL with a `.js`, `.cjs`,
+ * or `.mjs` extension.
+ *
+ * @see https://docs.bullmq.io/guide/workers/sandboxed-processors
+ */
+interface SandboxedWorkerConfig {
+    /** BullMQ queue the worker should consume. */
+    queueName: string;
+    /**
+     * Absolute path or `file:` URL to the compiled `.js`/`.cjs`/`.mjs` processor
+     * artifact. Relative paths and non-JS extensions are rejected at registration
+     * time. The file must export a default async function
+     * `(job: Job) => Promise<unknown>`.
+     */
+    processorFile: string | URL;
+    /** Optional worker tuning overrides, including `useWorkerThreads`. */
+    options?: WorkerOptions & {
+        useWorkerThreads?: boolean;
+    };
+}
+/**
+ * Creates and lifecycle-manages BullMQ `Worker` instances on behalf of the
+ * module. Supports two registration paths:
+ *
+ * - **Programmatic** (`register`) — in-process handler; NestJS DI is available
+ *   inside the handler function.
+ * - **Sandboxed** (`registerSandboxed`) — file-based, out-of-process; the
+ *   processor file is loaded in a separate Node.js child process and has **no**
+ *   access to NestJS DI.
+ *
+ * All workers use a duplicated Redis connection (`maxRetriesPerRequest: null`)
+ * for the blocking `BRPOPLPUSH`/`BZPOPMIN`/`BLMOVE` commands. The duplicated
+ * connection is closed immediately when the Worker constructor fails, preventing
+ * a connection leak.
+ *
+ * @example
+ * const worker = registry.register({
+ *   queueName: 'email',
+ *   handler: async (job) => sendEmail(job.data),
+ *   options: { concurrency: 5 },
+ * })
+ */
+declare class WorkerRegistry {
+    private readonly connection;
+    private readonly options;
+    private readonly logger;
+    private readonly entries;
+    constructor(connection: ConnectionResolver, options: ResolvedQueueOptions);
+    /**
+     * Register an in-process worker with a handler function. The BullMQ `Worker`
+     * constructor is synchronous — no Redis handshake is performed at registration
+     * time. The duplicated connection is disconnected immediately if construction
+     * fails, preventing a Redis connection leak.
+     *
+     * @param config - Queue name, handler, and optional worker options.
+     * @returns The created BullMQ `Worker` instance.
+     * @throws {QueueException} `DUPLICATE_PROCESSOR` when a worker for
+     *   `queueName` already exists.
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when options are
+     *   invalid or the BullMQ `Worker` constructor throws.
+     */
+    register<TData = unknown, TResult = unknown>(config: ProgrammaticWorkerConfig<TData, TResult>): Worker<TData, TResult>;
+    /**
+     * Register a sandboxed (file-based, out-of-process) worker. The processor
+     * file must be an absolute path or a `file:` URL pointing to a compiled
+     * `.js`/`.cjs`/`.mjs` artifact. NestJS DI is **not** available inside the
+     * processor. The BullMQ `Worker` constructor is synchronous.
+     *
+     * @param config - Queue name, processor file path/URL, and optional options.
+     * @returns The created BullMQ `Worker` instance.
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when `processorFile`
+     *   is a relative path, has a disallowed extension, or uses a non-`file:` URL protocol.
+     * @throws {QueueException} `DUPLICATE_PROCESSOR` when a worker for
+     *   `queueName` already exists.
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when options are
+     *   invalid or the BullMQ `Worker` constructor throws.
+     */
+    registerSandboxed(config: SandboxedWorkerConfig): Worker;
+    /**
+     * Stop and remove the worker for the given queue, releasing the duplicated
+     * connection the library opened for it. If no worker exists for `queueName`
+     * this is a no-op.
+     *
+     * @param queueName - The queue whose worker should be removed.
+     */
+    unregister(queueName: string): Promise<void>;
+    /**
+     * Returns the queue names of all currently registered workers.
+     *
+     * @returns An immutable array of queue names.
+     */
+    list(): readonly string[];
+    /**
+     * Returns a read-only view of the registered workers keyed by queue name.
+     * Intended for the shutdown orchestrator only.
+     *
+     * @returns A read-only map of queue name to worker.
+     */
+    getAll(): ReadonlyMap<string, Worker>;
+    /**
+     * Returns a read-only view of the duplicated connections the library opened
+     * for its workers, keyed by queue name. Intended for the shutdown orchestrator
+     * so it can close exactly the connections the library created (Mode A never
+     * exposes the consumer's shared client here).
+     *
+     * @returns A read-only map of queue name to duplicated connection.
+     */
+    getConnections(): ReadonlyMap<string, Redis>;
+    /**
+     * Gracefully quit a duplicated connection, falling back to a hard disconnect
+     * if the quit handshake fails so a socket is never leaked.
+     *
+     * @param connection - The duplicated connection to release.
+     */
+    private closeConnection;
+    /**
+     * Guard against registering two workers for the same queue.
+     *
+     * @param queueName - Queue name to check.
+     * @throws {QueueException} `DUPLICATE_PROCESSOR` if the queue is already registered.
+     */
+    private guardDuplicate;
+    /**
+     * Validate tunable options before constructing a Worker.
+     * Enforces `concurrency` in `[1, MAX_WORKER_CONCURRENCY]` and
+     * `limiter.max`/`limiter.duration` `>= 1`.
+     *
+     * @param opts - The caller-supplied options (may be undefined).
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when values are out of range.
+     */
+    private validateOptions;
+    /**
+     * Validate that `processorFile` is a safe, reachable artifact path. Accepts
+     * absolute paths with `.js`/`.cjs`/`.mjs` extensions and `file:` URLs. Rejects
+     * relative paths, non-JS extensions, and non-`file:` URL protocols to prevent
+     * path-traversal and arbitrary-file-execution attacks.
+     *
+     * @param processorFile - The path or URL supplied by the caller.
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` when validation fails.
+     */
+    private validateProcessorFile;
+    /**
+     * Reject a processor path whose extension is not an executable JS module,
+     * the last line of defense against loading an arbitrary file as a worker.
+     *
+     * @param filePath - The filesystem path (or file: URL pathname) to check.
+     * @throws {QueueException} `WORKER_REGISTRATION_FAILED` for a disallowed extension.
+     */
+    private assertProcessorExtension;
+    /**
+     * Build a BullMQ `WorkerOptions` object from the library's `WorkerOptions`
+     * shape. Only forwards optional fields that are explicitly set to preserve
+     * `exactOptionalPropertyTypes` correctness. Accepts the pre-created duplicated
+     * connection so callers can close it on construction failure.
+     *
+     * @param opts - Library-level worker options.
+     * @param conn - Pre-created duplicated Redis connection.
+     * @returns A BullMQ-compatible options object.
+     */
+    private buildBullOptions;
+}
+
+/**
+ * @fileoverview `QueueEventsRegistry` — lazily creates and caches one BullMQ
+ * `QueueEvents` instance per queue. A `QueueEvents` connection is opened only
+ * when at least one `@OnQueueEvent` listener is registered for that queue,
+ * avoiding unnecessary Redis connections. Each duplicated connection is tracked
+ * so the shutdown orchestrator can close exactly what the library opened.
+ * @layer server/services
+ */
+
+/**
+ * Lazily creates and caches one BullMQ `QueueEvents` instance per queue.
+ * The backing Redis connection uses `maxRetriesPerRequest: null` (via
+ * `duplicateConnection`) because `QueueEvents` subscribes via blocking
+ * `SUBSCRIBE` commands.
+ *
+ * A single `QueueEvents` is shared across all `@OnQueueEvent` listeners for
+ * the same queue. Connections are opened on demand — only when
+ * `getOrCreate(queueName)` is first called for a given queue. Shutdown is
+ * orchestrated centrally by the queue lifecycle service, which closes each
+ * `QueueEvents` and then releases the duplicated connection exposed here.
+ *
+ * @example
+ * const qe = registry.getOrCreate('email')
+ * qe.on('completed', ({ jobId }) => console.log(jobId))
+ */
+declare class QueueEventsRegistry {
+    private readonly connection;
+    private readonly options;
+    private readonly logger;
+    private readonly events;
+    private readonly connections;
+    constructor(connection: ConnectionResolver, options: ResolvedQueueOptions);
+    /**
+     * Returns the cached `QueueEvents` for `queueName`, creating one on first
+     * call. Subsequent calls for the same name return the same instance without
+     * opening a second Redis connection.
+     *
+     * @param queueName - The BullMQ queue to observe.
+     * @returns The `QueueEvents` instance for the queue.
+     */
+    getOrCreate(queueName: string): QueueEvents;
+    /**
+     * Returns the queue names for which a `QueueEvents` connection is open.
+     *
+     * @returns An immutable array of queue names.
+     */
+    list(): readonly string[];
+    /**
+     * Returns the live `QueueEvents` map. Intended for the shutdown orchestrator.
+     *
+     * @returns A read-only view of the internal map.
+     */
+    getAll(): ReadonlyMap<string, QueueEvents>;
+    /**
+     * Returns a read-only view of the duplicated connections the library opened
+     * for its `QueueEvents`, keyed by queue name. Intended for the shutdown
+     * orchestrator so it can close exactly the connections the library created
+     * (Mode A never exposes the consumer's shared client here).
+     *
+     * Returns a copy. `ReadonlyMap` is a compile-time claim only — handing back the
+     * live registry lets any consumer cast it away and delete a connection the
+     * shutdown sequence is about to close. The allocation costs nothing on a path
+     * that runs once per shutdown.
+     *
+     * @returns A read-only snapshot of queue name to duplicated connection.
+     */
+    getConnections(): ReadonlyMap<string, Redis>;
+}
+
+/**
+ * @fileoverview `QueueLifecycle` — the single, ordered graceful-shutdown
+ * orchestrator. On `onModuleDestroy` it drains every worker within a bounded
+ * budget, then tears down queue-events, the connections the library opened,
+ * the flow producer, the cached queues, and finally the Queue-role connection.
+ *
+ * Delivery is at-least-once: when a worker exceeds the drain budget it is
+ * force-closed and its in-flight job becomes `stalled` and is retried by another
+ * worker. Handlers must therefore be idempotent, and `lockDuration` should
+ * comfortably exceed the worst-case handler runtime so healthy long jobs are
+ * never treated as stalled.
+ * @layer server/lifecycle
+ */
+
+/**
+ * Ordered graceful-shutdown service. Implementing the protocol in one place
+ * guarantees the teardown order — workers drain first, then queue-events, then
+ * the duplicated connections, then the flow producer, the queues, and finally
+ * the Queue-role connection. Every step swallows its own errors so a single
+ * failure never aborts the rest of the sequence.
+ *
+ * Connection ownership: in **Mode B** the library-owned Queue-role client is
+ * quit by the connection resolver; in **Mode A** that step is a no-op and only
+ * the duplicated worker/queue-events connections the library created are closed
+ * — the consumer's shared client is never touched.
+ */
+declare class QueueLifecycle implements OnModuleDestroy {
+    private readonly workers;
+    private readonly events;
+    private readonly queues;
+    private readonly flow;
+    private readonly connection;
+    private readonly resolved;
+    private readonly logger;
+    constructor(workers: WorkerRegistry, events: QueueEventsRegistry, queues: QueueService, flow: FlowService, connection: ConnectionResolver, resolved: ResolvedQueueOptions);
+    /**
+     * Run the ordered shutdown sequence. Called by NestJS when the application
+     * context closes (e.g. on `SIGTERM` with shutdown hooks enabled).
+     */
+    onModuleDestroy(): Promise<void>;
+    /**
+     * Close every worker with a bounded drain, force-closing any that exceed the
+     * budget. Returns the number of workers that had to be force-closed.
+     *
+     * @returns The count of force-closed workers.
+     */
+    private closeWorkers;
+    /**
+     * Race a graceful `worker.close()` against a timer. `worker.close()` already
+     * drains active jobs and takes no timeout argument, so the timer is the only
+     * way to bound the wait. Rejects with a timeout error when the budget elapses.
+     *
+     * @param worker - The worker to close.
+     * @param timeoutMs - The drain budget in milliseconds.
+     */
+    private closeWorkerWithTimeout;
+    /** Close every cached `QueueEvents`, swallowing individual failures. */
+    private closeQueueEvents;
+    /**
+     * Close the duplicated worker/queue-events connections the library opened.
+     * BullMQ treats a passed-in client as shared and never closes it, so the
+     * library must release these explicitly. In Mode A the consumer's shared
+     * client is never among them.
+     */
+    private closeDuplicatedConnections;
+    /**
+     * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
+     * Removes waiting and delayed jobs; off by default to stay production-safe.
+     */
+    private drainQueuesIfRequested;
+    /** Close the flow producer (idempotent), swallowing any failure. */
+    private closeFlowProducer;
+    /** Close every cached queue and clear the cache, swallowing individual failures. */
+    private closeQueues;
+    /**
+     * Tear down the Queue-role connection. Mode B quits the library-owned client;
+     * Mode A is a no-op for the consumer's shared client.
+     */
+    private teardownConnection;
+}
+
+/**
+ * @fileoverview `@Processor` class decorator — marks a provider as the handler
+ * for a named BullMQ queue. Writes {@link ProcessorMetadata} to class-level
+ * reflection metadata under {@link PROCESSOR_METADATA_KEY}.
+ * @layer server/decorators
+ */
+
+/**
+ * Marks a class as the processor for the given queue. The class must be
+ * registered as a NestJS provider so that `ProcessorDiscoveryService` can
+ * discover and wire it during module initialization.
+ *
+ * When `options.concurrency` is omitted the library falls back to
+ * {@link DEFAULT_WORKER_CONCURRENCY} and emits a `Logger.warn` at discovery
+ * time (not here — the decorator itself is side-effect-free).
+ *
+ * Delivery is at-least-once: every `@Process` handler on the class MUST be
+ * idempotent (idempotency key on writes, upserts over inserts, or an
+ * "already-processed" marker keyed by `job.id`). Set `lockDuration` comfortably
+ * above the worst-case handler runtime so healthy long jobs are never treated as
+ * stalled.
+ *
+ * @param queueName - The BullMQ queue this class processes.
+ * @param options - Optional worker tuning overrides.
+ *
+ * @example
+ * `@Processor`('email', { concurrency: 5 })
+ * class EmailProcessor {
+ *   `@Process`()
+ *   async handle(job: Job<EmailPayload>) { ... }
+ * }
+ */
+declare function Processor(queueName: string, options?: WorkerOptions): ClassDecorator;
+
+/**
+ * @fileoverview `@Process` method decorator — registers a method as the handler
+ * for a specific job name (or as the catch-all when no name is given). Metadata
+ * is accumulated in an array so multiple `@Process` annotations on the same
+ * class coexist without overwriting each other.
+ * @layer server/decorators
+ */
+
+/**
+ * Marks a method as a job processor. If `jobName` is supplied the method is
+ * only invoked for jobs whose `name` matches; if omitted the method acts as a
+ * catch-all for all other job names on the same queue.
+ *
+ * Multiple `@Process` decorators on the same class are supported — each adds
+ * an entry to the accumulated metadata array.
+ *
+ * Delivery is at-least-once: a handler may run more than once for the same job
+ * (worker crash, lock expiry, or a shutdown force-close). Handlers MUST be
+ * idempotent — use an idempotency key on writes, prefer upserts over inserts, or
+ * keep an "already-processed" marker keyed by `job.id`.
+ *
+ * @param jobName - Optional job-name filter. Omit for a catch-all handler.
+ *
+ * @example
+ * `@Process`('send-email')
+ * async handleSend(job: Job<EmailPayload>) { ... }
+ *
+ * `@Process`()
+ * async handleOthers(job: Job<EmailPayload>) { ... }
+ */
+declare function Process(jobName?: string): MethodDecorator;
+
+/**
+ * @fileoverview `@OnWorkerEvent` method decorator — binds a method as a
+ * worker-local event listener. The handler is attached directly to the BullMQ
+ * `Worker` instance (no extra Redis connection) and receives the **full**
+ * `Job` object, including `job.data`, `job.returnvalue`, `job.attemptsMade`,
+ * and timing fields. Use `'progress'` to observe `job.updateProgress()`.
+ * @layer server/decorators
+ */
+
+/**
+ * Union of BullMQ `Worker` event names surfaced by this library. Handlers
+ * registered with `@OnWorkerEvent` receive the **full** `Job` instance for
+ * job-scoped events (completed, failed, active, progress) and scalars for
+ * infrastructure events (stalled, closing, closed, error).
+ *
+ * @see https://docs.bullmq.io/guide/workers/worker-events
+ */
+type WorkerEventName = 'completed' | 'failed' | 'progress' | 'active' | 'stalled' | 'closing' | 'closed' | 'error';
+/**
+ * Marks a method as a worker-local event listener for the given event. The
+ * method is bound to the BullMQ `Worker` via `worker.on(event, fn)` at
+ * discovery time. Because worker-local events are emitted directly on the
+ * `Worker` instance, **no extra Redis connection is opened**.
+ *
+ * Handler receives:
+ * - `completed` — `(job: Job, returnValue: unknown, prev: string) => void`
+ * - `failed`    — `(job: Job | undefined, error: Error, prev: string) => void`
+ * - `progress`  — `(job: Job, progress: number | object) => void`
+ * - `active`    — `(job: Job, prev: string) => void`
+ * - `stalled`   — `(jobId: string, prev: string) => void`
+ * - `error`     — `(error: Error) => void`
+ * - `closing`   — `(msg: string) => void`
+ * - `closed`    — `() => void`
+ *
+ * Multiple `@OnWorkerEvent` decorators on the same class accumulate without
+ * overwriting each other.
+ *
+ * Delivery is at-least-once. A `'stalled'` job — for example after a shutdown
+ * force-close or a lock expiry — is re-run by another worker: this is the
+ * visible at-least-once path, so handlers must be idempotent. Set `lockDuration`
+ * comfortably above the worst-case handler runtime to avoid false stalls.
+ *
+ * Dead-letter-queue pattern (`'failed'`): the library ships no DLQ service, but
+ * the endorsed pattern is a `'failed'` listener that, once retries are exhausted
+ * (`job.attemptsMade >= (job.opts.attempts ?? 1)`), re-enqueues the payload plus
+ * failure metadata onto a `<queue>-dlq` queue via `QueueService.enqueue`. Use a
+ * stable DLQ `jobId` (e.g. `dlq-${job.id}`) so a redelivered `'failed'` event is
+ * idempotent and never double-inserts (a custom BullMQ job id must not contain `:`).
+ *
+ * @param eventName - The worker event to listen for.
+ *
+ * @example
+ * `@OnWorkerEvent`('completed')
+ * onCompleted(job: Job, returnValue: unknown) {
+ *   this.logger.log(`Job ${job.id} done`, returnValue)
+ * }
+ */
+declare function OnWorkerEvent(eventName: WorkerEventName): MethodDecorator;
+
+/**
+ * @fileoverview `@OnQueueEvent` method decorator — binds a method as a global
+ * queue-event listener. The handler is attached to a per-queue `QueueEvents`
+ * instance (one extra Redis connection per queue, opened lazily) and receives
+ * a **serialized** payload — only `jobId` and stringified fields such as
+ * `returnvalue` (a string, not the actual return value) or `failedReason`.
+ * To inspect the full `Job`, call `QueueService.getJob(jobId)`.
+ * @layer server/decorators
+ */
+
+/**
+ * Union of BullMQ `QueueEvents` event names surfaced by this library. Listeners
+ * registered with `@OnQueueEvent` receive a serialized event payload, NOT the
+ * full `Job` instance.
+ *
+ * @see https://docs.bullmq.io/guide/workers/queueevents
+ */
+type QueueEventName = 'completed' | 'failed' | 'active' | 'progress' | 'stalled' | 'waiting' | 'delayed' | 'paused' | 'resumed' | 'cleaned' | 'error';
+/**
+ * Marks a method as a global queue-event listener. The method is bound to a
+ * lazily-created `QueueEvents` instance via `queueEvents.on(event, fn)` at
+ * discovery time. A single `QueueEvents` connection is shared across all
+ * `@OnQueueEvent` listeners for the same queue.
+ *
+ * The handler receives a **serialized** payload, e.g.:
+ * - `completed` — `{ jobId: string, returnvalue: string, prev?: string }`
+ * - `failed`    — `{ jobId: string, failedReason: string, prev?: string }`
+ * - `active`    — `{ jobId: string, prev?: string }`
+ * - `progress`  — `{ jobId: string, data: number | object }`
+ * - `waiting`   — `{ jobId: string }`
+ *
+ * `error` is the exception to that rule: it carries a real `Error` instance, not
+ * a serialized payload, because it reports a fault on the connection rather than
+ * a transition of any single job — so there is no `jobId` to look up. The library
+ * registers its own listener for it, which logs and keeps an unlistened emission
+ * from throwing; a handler declared here runs in addition to that one.
+ *
+ * To retrieve the full job, call `QueueService.getJob(payload.jobId)`, which
+ * may return `null` if the job was already evicted by `removeOnComplete`.
+ *
+ * Multiple `@OnQueueEvent` decorators on the same class accumulate without
+ * overwriting each other.
+ *
+ * @param eventName - The queue event to listen for.
+ *
+ * @example
+ * `@OnQueueEvent`('completed')
+ * async onCompleted({ jobId, returnvalue }: { jobId: string; returnvalue: string }) {
+ *   this.logger.log(`Job ${jobId} finished with result ${returnvalue}`)
+ * }
+ */
+declare function OnQueueEvent(eventName: QueueEventName): MethodDecorator;
+
+/**
+ * @fileoverview Reflection metadata shapes attached by the processor decorators.
+ * @layer server/interfaces
+ */
+
+/** Metadata attached by the processor decorator and read on worker discovery. */
+interface ProcessorMetadata {
+    /** Queue the annotated class processes. */
+    queueName: string;
+    /** Worker tuning options for the queue. */
+    workerOptions: WorkerOptions;
+    /**
+     * Internal flag set when the caller omitted `concurrency` on the decorator.
+     * The discovery service logs a warning (naming the queue and the fallback value)
+     * at bootstrap time; the decorator itself must never log.
+     *
+     * @internal
+     */
+    _warnedNoConcurrency?: boolean;
+}
+/** Metadata attached by the process-handler decorator on a handler method. */
+interface ProcessHandlerMetadata {
+    /** Specific job-name filter; `undefined` means catch-all. */
+    jobName?: string;
+    /** Method key on the host class used by the registry to resolve dispatch. */
+    methodKey: string | symbol;
+}
+/** Metadata attached by the queue-event listener decorator on a listener method. */
+interface QueueEventListenerMetadata {
+    /** Queue event the method listens for. */
+    eventName: string;
+    /** Method key on the host class. */
+    methodKey: string | symbol;
+}
+
+/**
+ * @fileoverview Standardized, HTTP-shaped exception for queue operations.
+ * @layer server/errors
+ */
+
+/**
+ * Standardized exception for queue operations. The response body always follows
+ * the shape `{ error: { code, message, details } }`. The `code` is a stable,
+ * transport-independent identifier; consumers catching this exception outside an
+ * HTTP request should branch on `code`, not the HTTP status or the message text.
+ * The code lives in the response envelope — read it via `getResponse()`.
+ *
+ * `details` must never carry secrets (connection strings, passwords, `job.data`)
+ * — only scalar configuration values such as `{ actualValue, expectedValue }`.
+ *
+ * @example Throwing
+ * throw new QueueException('queue.connection_timeout', 500, { timeoutMs: 10_000 })
+ * @example Branching on the code in a consumer
+ * catch (err) {
+ *   if (err instanceof QueueException) {
+ *     const { code } = (err.getResponse() as { error: { code: string } }).error
+ *     if (code === QUEUE_ERROR_CODES.FLOW_DISABLED) enableFlows()
+ *   }
+ * }
+ */
+declare class QueueException extends HttpException {
+    constructor(code: string, statusCode?: HttpStatus, details?: Record<string, unknown>);
+}
+
+/**
+ * @fileoverview Stable error-code catalog emitted by the library, plus the
+ * derived code union. Single source of truth, re-exported by the server barrel.
+ * @layer shared/constants
+ */
+/**
+ * Stable, transport-independent error codes emitted through `QueueException`.
+ * Declared `as const` so each value keeps its literal type in the emitted
+ * declaration files.
+ *
+ * @example
+ * if (error.code === QUEUE_ERROR_CODES.JOB_NOT_FOUND) { return null }
+ */
+declare const QUEUE_ERROR_CODES: {
+    readonly CONNECTION_INVALID: "queue.connection_invalid";
+    readonly CONNECTION_REQUIRES_NULL_RETRIES: "queue.connection_requires_null_retries";
+    readonly CONNECTION_TIMEOUT: "queue.connection_timeout";
+    readonly QUEUE_NOT_FOUND: "queue.queue_not_found";
+    readonly JOB_NOT_FOUND: "queue.job_not_found";
+    readonly INVALID_JOB_DATA: "queue.invalid_job_data";
+    readonly INVALID_REPEAT_OPTIONS: "queue.invalid_repeat_options";
+    readonly DUPLICATE_PROCESSOR: "queue.duplicate_processor";
+    readonly FLOW_DISABLED: "queue.flow_disabled";
+    readonly METRICS_DISABLED: "queue.metrics_disabled";
+    readonly SHUTDOWN_TIMEOUT_EXCEEDED: "queue.shutdown_timeout_exceeded";
+    readonly BULK_ENQUEUE_FAILED: "queue.bulk_enqueue_failed";
+    readonly WORKER_REGISTRATION_FAILED: "queue.worker_registration_failed";
+    readonly INVALID_OPTIONS: "queue.invalid_options";
+};
+/** Union of every value in {@link QUEUE_ERROR_CODES}. */
+type QueueErrorCode = (typeof QUEUE_ERROR_CODES)[keyof typeof QUEUE_ERROR_CODES];
+
+/**
+ * @fileoverview Server-side error-code re-exports plus the human-readable
+ * message catalog keyed by code.
+ * @layer server/constants
+ */
+
+/**
+ * Human-readable messages keyed by error code — mirrors the specification's
+ * error catalog. Every value of {@link QUEUE_ERROR_CODES} has an entry.
+ */
+declare const QUEUE_ERROR_MESSAGES: Record<string, string>;
+
+/**
+ * @fileoverview Consolidated default values applied to module options.
+ * @layer server/constants
+ */
+/** Default worker concurrency — a non-serial starting point, tuned per workload. */
+declare const DEFAULT_WORKER_CONCURRENCY: 2;
+/**
+ * Maximum allowed concurrency per Worker. Values above this ceiling exhaust the
+ * event loop, heap, and lock-renewal timers before providing meaningful throughput
+ * gains. Single-digit hundreds are typical for I/O-bound workloads (BullMQ docs).
+ */
+declare const MAX_WORKER_CONCURRENCY: 1000;
+/**
+ * Default options applied to every job enqueued through the service. The
+ * `removeOnFail.count` cap bounds Redis memory growth under failure storms.
+ */
+declare const DEFAULT_JOB_OPTIONS: {
+    readonly attempts: 3;
+    readonly backoff: {
+        readonly type: "exponential";
+        readonly delay: 2000;
+    };
+    readonly removeOnComplete: {
+        readonly age: number;
+        readonly count: 1000;
+    };
+    readonly removeOnFail: {
+        readonly age: number;
+        readonly count: 5000;
+    };
+};
+/** Default TTL (ms) for the metrics cache. */
+declare const DEFAULT_METRICS_CACHE_TTL_MS: 5000;
+/** Default window (ms) for in-flight jobs to drain before force-close on shutdown. */
+declare const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS: 30000;
+
+/**
+ * @fileoverview Canonical job-status constant object.
+ * @layer shared/constants
+ */
+/**
+ * Canonical job status constants — use these in business logic instead of
+ * hardcoded string literals. Declared `as const` so the literal types survive
+ * into the emitted declaration files.
+ *
+ * @example
+ * if (status === JOB_STATUS.FAILED) { retry() }
+ */
+declare const JOB_STATUS: {
+    readonly WAITING: "waiting";
+    readonly ACTIVE: "active";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly DELAYED: "delayed";
+    readonly PAUSED: "paused";
+};
+
+export { BYMAX_QUEUE_CONNECTION_MODE, BYMAX_QUEUE_OPTIONS, BYMAX_QUEUE_REDIS_CLIENT, BYMAX_QUEUE_RESOLVED_OPTIONS, type BulkJob, BymaxQueueModule, type BymaxQueueModuleAsyncOptions, type BymaxQueueModuleOptions, type BymaxQueueOptionsFactory, ConnectionResolver, DEFAULT_JOB_OPTIONS, DEFAULT_METRICS_CACHE_TTL_MS, DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS, DEFAULT_WORKER_CONCURRENCY, FlowService, JOB_STATUS, type JobSchedulerRepeatOptions, type JobStatus, MAX_WORKER_CONCURRENCY, MetricsService, OnQueueEvent, OnWorkerEvent, Process, type ProcessHandlerMetadata, Processor, type ProcessorMetadata, type ProgrammaticWorkerConfig, QUEUE_ERROR_CODES, QUEUE_ERROR_MESSAGES, type QueueConnectionConfig, type QueueConnectionMode, type QueueErrorCode, type QueueEventListenerMetadata, type QueueEventName, QueueEventsRegistry, QueueException, QueueLifecycle, type QueueMetrics, QueueService, type SandboxedWorkerConfig, type WorkerEventName, type WorkerOptions, WorkerRegistry };