@bymax-one/nest-queue 1.2.4 → 1.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +71 -1
  2. package/README.md +87 -60
  3. package/dist/server/index.cjs +1 -1
  4. package/dist/server/index.d.cts +1 -1
  5. package/dist/server/index.d.ts +1 -1
  6. package/dist/server/index.mjs +1 -1
  7. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -11,6 +11,75 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
11
11
 
12
12
  ---
13
13
 
14
+ ## [1.2.5] — 2026-10-31
15
+
16
+ No action required: behaviour, the public API, the types and the peer ranges are unchanged.
17
+ Measured with `diff -r` of a fresh build against the unpacked 1.2.4 tarball, `dist/` differs in
18
+ one comment line only, the description of the `drainOnShutdown` step, which sits in the bundles
19
+ (`index.mjs`, `index.cjs`) and in the declarations (`index.d.ts`, `index.d.cts`); the package
20
+ otherwise changes in `README.md`, this file and the version in `package.json`.
21
+
22
+ ### Documentation
23
+
24
+ - **Several statements in `README.md` described behaviour the code does not have.** The prose and the
25
+ tables were checked against the source, which the snippet gate does not do:
26
+ - `shutdown.drainOnShutdown` was described as waiting for the queue to drain. It calls `drain()`
27
+ on every cached queue after the workers close, which removes the waiting jobs, so it is for
28
+ development and tests only.
29
+ - `@OnQueueEvent` was said to need `queueEvents: { enabled: true }`. No such option exists; the
30
+ library opens the `QueueEvents` connection when it discovers the first listener.
31
+ - Graceful Shutdown named `onApplicationShutdown`; `QueueLifecycle` runs from `onModuleDestroy`.
32
+ - The Troubleshooting entry for `CONNECTION_REQUIRES_NULL_RETRIES` told Mode A users to pass a
33
+ client built with `maxRetriesPerRequest: null`. Worker connections are `duplicate()` calls that
34
+ force it, so a stock ioredis client never triggers the error; the entry now says so.
35
+ - The stuck-jobs entry pointed `lockDuration` at `workerOptions` (the `options` of `@Processor`
36
+ and `register` are what a consumer sets) and at a `maxStalledCount` setting the library does not
37
+ expose.
38
+ - The Testing section and the badge quoted a mutation score of 99.68% against `break 95`; the
39
+ suite is held at 100.00% against `break 100`. The shared bundle budget is 2 500 B, not 2.5 KiB, and the gate
40
+ chain now includes `pnpm check:published`.
41
+ - `QueueException.details` was described by four keys; it carries more, always scalar. The
42
+ `cleanQueue` row named its second parameter `graceMs`, which is `gracePeriodMs`.
43
+
44
+ - A warning callout under the Configuration table now says plainly that `shutdown.drainOnShutdown`
45
+ deletes the waiting jobs of every queue the process created and must not be enabled
46
+ in production; the table cell alone was easy to miss.
47
+
48
+ - **Two README examples did not compile against the published types.** The OpenTelemetry example
49
+ built `new BullMQOtel('my-service', tracer)`, the `bullmq-otel` 1.x signature; the `^2` peer takes
50
+ an options object, so it is now `new BullMQOtel({ tracerName: 'my-service' })`. The
51
+ `WorkerRegistry.register` example passed `processor:`; the property is `handler`. Two fragments
52
+ also used `path` and `Module` without importing them.
53
+
54
+ - **Further README statements were wrong, and the exports nothing described are now listed.** The
55
+ Configuration table said that injecting `FlowService` or `MetricsService` while disabled throws;
56
+ both are always provided and every method throws `FLOW_DISABLED` or `METRICS_DISABLED`, except
57
+ `FlowService.close()`, which is a no-op while flows are disabled. The
58
+ `@OnQueueEvent` example declared `(jobId, returnValue)`, but the handler receives one serialized
59
+ payload object (`completed` carries `{ jobId, returnvalue, prev? }`), so the example and the prose
60
+ above it now say so. An "Other exports" table now covers the exports the README never named.
61
+
62
+ ### Tests
63
+
64
+ - `pnpm check:published` now fails on a wrong method, option or field anywhere in the README.
65
+ It reads syntactic and semantic diagnostics together, compiles every snippet, not only those
66
+ that import the package, types the names the prose introduces in
67
+ `scripts/readme-prelude.d.ts`, resolves a relative import to the snippet that exports it and
68
+ fails one that no snippet satisfies. The prelude is compiled as a `.ts` file, so a type in it that
69
+ stops resolving is an error instead of `any`, and no syntax error is tolerated: a snippet that
70
+ shortens an example with a bare `...` fails and is written out in full.
71
+ - The Mode A null-retries probe is exercised with real ioredis clients: a stock client with finite
72
+ retries is accepted, a client whose `duplicate()` ignores the override is refused with
73
+ `CONNECTION_REQUIRES_NULL_RETRIES`, the probe is closed in both cases, and BullMQ itself refuses
74
+ a Worker on the connection the probe rejected.
75
+ - A spec fails when a name exported from `src/server/index.ts` or `src/shared/index.ts` is not
76
+ named in the README, so an export nobody documented cannot ship unnoticed again.
77
+ - The README's option-defaults table and error-code catalog are now parsed and compared with
78
+ `applyDefaults`, `DEFAULT_JOB_OPTIONS` and `QUEUE_ERROR_CODES`, so a default or a code that drifts
79
+ fails the suite instead of reaching the npm page.
80
+
81
+ ---
82
+
14
83
  ## [1.2.4] — 2026-10-30
15
84
 
16
85
  No action required: behaviour, the public API, the types and the peer ranges are unchanged.
@@ -609,7 +678,8 @@ v6 peer range.
609
678
 
610
679
  ---
611
680
 
612
- [Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.4...HEAD
681
+ [Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.5...HEAD
682
+ [1.2.5]: https://github.com/bymaxone/nest-queue/compare/v1.2.4...v1.2.5
613
683
  [1.2.4]: https://github.com/bymaxone/nest-queue/compare/v1.2.3...v1.2.4
614
684
  [1.2.3]: https://github.com/bymaxone/nest-queue/compare/v1.2.2...v1.2.3
615
685
  [1.2.2]: https://github.com/bymaxone/nest-queue/compare/v1.2.1...v1.2.2
package/README.md CHANGED
@@ -14,7 +14,7 @@
14
14
  <a href="https://www.npmjs.com/package/@bymax-one/nest-queue"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-queue?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
15
15
  <a href="https://github.com/bymaxone/nest-queue/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-queue/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
16
16
  <a href="https://github.com/bymaxone/nest-queue/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
17
- <a href="https://github.com/bymaxone/nest-queue/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.68%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
17
+ <a href="https://github.com/bymaxone/nest-queue/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
18
18
  <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-queue"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-queue/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
19
19
  <a href="https://github.com/bymaxone/nest-queue/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-queue?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
20
20
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -216,6 +216,9 @@ export class EmailProcessor {
216
216
  Register the processor in your module alongside `BymaxQueueModule`:
217
217
 
218
218
  ```typescript
219
+ import { Module } from '@nestjs/common'
220
+ import { EmailProcessor } from './email.processor'
221
+
219
222
  @Module({
220
223
  providers: [EmailProcessor],
221
224
  })
@@ -228,20 +231,26 @@ export class EmailModule {}
228
231
 
229
232
  Every option passed to `forRoot` / `forRootAsync`. Only `connection` is required.
230
233
 
231
- | Option | Type | Default | Description |
232
- | -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
233
- | `connection` | `{ client } \| { url, options? } \| { options }` | — | **Required.** Mode A supplies an existing `ioredis` client; Mode B lets the library open its own. The three arms are mutually exclusive. |
234
- | `prefix` | `string` | `'bull'` | Redis key namespace. Applied to the `Queue`, `Worker`, `QueueEvents` **and** `FlowProducer` — see [Architecture](#-architecture). |
235
- | `defaultJobOptions` | `JobsOptions` | `attempts: 3` · exponential backoff `2000` ms · `removeOnComplete: { age: 24 h, count: 1000 }` · `removeOnFail: { age: 7 d, count: 5000 }` | Merged into every job enqueued through the service; per-job options win. The bounded `removeOn*` caps are what keep Redis from growing without limit under a failure storm. |
236
- | `queueOptions` | `Partial<QueueOptions>` | `{}` | Extra BullMQ `Queue` options. `connection`, `defaultJobOptions` and `prefix` are owned by the library and cannot be set here. |
237
- | `flows.enabled` | `boolean` | `false` | Registers `FlowService`. Injecting it while disabled throws `FLOW_DISABLED`. |
238
- | `metrics.enabled` | `boolean` | `false` | Registers `MetricsService`. Injecting it while disabled throws `METRICS_DISABLED`. |
239
- | `metrics.cacheTtlMs` | `number` | `5_000` | TTL of the metrics snapshot cache. `0` disables caching. Must be `>= 0`. |
240
- | `telemetry` | `Telemetry` | — | A BullMQ `Telemetry` instance (typically `new BullMQOtel(...)` from the optional `bullmq-otel` peer), attached to every `Queue` and `Worker`. |
241
- | `shutdown.drainTimeoutMs` | `number` | `30_000` | Upper bound on the graceful drain before workers are force-closed. Must be `> 0`. |
242
- | `shutdown.drainOnShutdown` | `boolean` | `false` | Wait for the queue to drain, not just for in-flight jobs to finish. |
243
- | `connectionReadyTimeoutMs` | `number` | `10_000` | Mode B only: how long to wait for Redis `ready` before failing with `CONNECTION_TIMEOUT`. |
244
- | `isGlobal` | `boolean` | `true` | Register the module globally, so `QueueService` is injectable without re-importing. |
234
+ | Option | Type | Default | Description |
235
+ | -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
236
+ | `connection` | `{ client } \| { url, options? } \| { options }` | — | **Required.** Mode A supplies an existing `ioredis` client; Mode B lets the library open its own. The arms are mutually exclusive. |
237
+ | `prefix` | `string` | `'bull'` | Redis key namespace. Applied to the `Queue`, `Worker`, `QueueEvents` **and** `FlowProducer` — see [Architecture](#-architecture). |
238
+ | `defaultJobOptions` | `JobsOptions` | `attempts: 3` · exponential backoff `2000` ms · `removeOnComplete: { age: 24 h, count: 1000 }` · `removeOnFail: { age: 7 d, count: 5000 }` | Merged into every job enqueued through the service; per-job options win. The bounded `removeOn*` caps are what keep Redis from growing without limit under a failure storm. |
239
+ | `queueOptions` | `Partial<QueueOptions>` | `{}` | Extra BullMQ `Queue` options. `connection`, `defaultJobOptions` and `prefix` are owned by the library and cannot be set here. |
240
+ | `flows.enabled` | `boolean` | `false` | `FlowService` is always provided; while disabled, every method except `close()` throws `FLOW_DISABLED`. |
241
+ | `metrics.enabled` | `boolean` | `false` | `MetricsService` is always provided; while disabled, every method throws `METRICS_DISABLED`. |
242
+ | `metrics.cacheTtlMs` | `number` | `5_000` | TTL of the metrics snapshot cache. `0` disables caching. Must be `>= 0`. |
243
+ | `telemetry` | `Telemetry` | — | A BullMQ `Telemetry` instance (typically `new BullMQOtel(...)` from the optional `bullmq-otel` peer), attached to every `Queue` and `Worker`. |
244
+ | `shutdown.drainTimeoutMs` | `number` | `30_000` | Upper bound on the graceful drain before workers are force-closed. Must be `> 0`. |
245
+ | `shutdown.drainOnShutdown` | `boolean` | `false` | Development and test only: after the workers close, call `drain()` on every cached queue, which **removes** its waiting jobs (delayed and active jobs are left alone). Leave it `false` in production. |
246
+ | `connectionReadyTimeoutMs` | `number` | `10_000` | Mode B only: how long to wait for Redis `ready` before failing with `CONNECTION_TIMEOUT`. |
247
+ | `isGlobal` | `boolean` | `true` | Register the module globally, so `QueueService` is injectable without re-importing. |
248
+
249
+ > [!WARNING]
250
+ > **`shutdown.drainOnShutdown` deletes jobs.** When it is `true`, shutdown calls `drain()` on every
251
+ > queue this process created, which removes all of that queue's waiting jobs from
252
+ > Redis, including the ones other instances were about to process. It exists for development and
253
+ > tests that need an empty queue. Never enable it in production.
245
254
 
246
255
  Invalid options are rejected at bootstrap with `QueueException(INVALID_OPTIONS)` — never
247
256
  silently corrected. A misconfigured queue fails when the application starts, not when the
@@ -300,8 +309,8 @@ BymaxQueueModule.forRoot({
300
309
  })
301
310
  ```
302
311
 
303
- The library opens one connection for queues and one per worker/QueueEvents listener, each
304
- with `maxRetriesPerRequest: null` where BullMQ requires it.
312
+ The library opens one connection for queues, one per worker and one per queue that has an
313
+ `@OnQueueEvent` listener. The worker and `QueueEvents` connections carry `maxRetriesPerRequest: null`.
305
314
 
306
315
  ---
307
316
 
@@ -321,34 +330,35 @@ import type {
321
330
  } from '@bymax-one/nest-queue'
322
331
  ```
323
332
 
324
- | Method | Signature | Description |
325
- | -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
326
- | `enqueue` | `<TData, TResult>(queue, name, data, opts?) → Promise<Job<TData, TResult>>` | Add a single job |
327
- | `enqueueBulk` | `<TData, TResult>(queue, jobs) → Promise<Job<TData, TResult>[]>` | Add up to 1 000 jobs in one Redis roundtrip |
328
- | `getJob` | `<TData, TResult>(queue, jobId) → Promise<Job<TData, TResult> \| null>` | Get job by ID; `null` when it does not exist |
329
- | `getJobs` | `<TData, TResult>(queue, status, start?, end?) → Promise<Job<TData, TResult>[]>` | Page jobs in one status (default `0`–`50`) |
330
- | `getMetrics` | `(queue) → Promise<QueueMetrics>` | Uncached snapshot of job counts per status, with a collection timestamp |
331
- | `pauseQueue` | `(queue) → Promise<void>` | Pause a queue |
332
- | `resumeQueue` | `(queue) → Promise<void>` | Resume a paused queue |
333
- | `cleanQueue` | `(queue, graceMs, limit, status?) → Promise<string[]>` | Remove up to `limit` jobs older than `graceMs` (`0` = no limit); returns removed ids |
334
- | `upsertJobScheduler` | `<TData, TResult>(queue, id, repeat, template?) → Promise<Job<TData, TResult> \| undefined>` | Create or update a recurring Job Scheduler; returns the first scheduled job |
335
- | `removeJobScheduler` | `(queue, id) → Promise<boolean>` | Remove a Job Scheduler by ID |
336
- | `getJobSchedulers` | `(queue, start?, end?, asc?) → Promise<JobSchedulerJson[]>` | Page the schedulers registered on a queue |
337
- | `getOrCreateQueue` | `<TData, TResult>(queue, overrides?) → Queue<TData, TResult>` | Return the cached raw `Queue` instance |
338
- | `getCachedQueues` | `() → ReadonlyMap<string, Queue>` | Read-only view of every queue created so far |
333
+ | Method | Signature | Description |
334
+ | -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
335
+ | `enqueue` | `<TData, TResult>(queue, name, data, opts?) → Promise<Job<TData, TResult>>` | Add a single job |
336
+ | `enqueueBulk` | `<TData, TResult>(queue, jobs) → Promise<Job<TData, TResult>[]>` | Add up to 1 000 jobs in one Redis roundtrip |
337
+ | `getJob` | `<TData, TResult>(queue, jobId) → Promise<Job<TData, TResult> \| null>` | Get job by ID; `null` when it does not exist |
338
+ | `getJobs` | `<TData, TResult>(queue, status, start?, end?) → Promise<Job<TData, TResult>[]>` | Page jobs in one status (default `0`–`50`) |
339
+ | `getMetrics` | `(queue) → Promise<QueueMetrics>` | Uncached snapshot of job counts per status, with a collection timestamp |
340
+ | `pauseQueue` | `(queue) → Promise<void>` | Pause a queue |
341
+ | `resumeQueue` | `(queue) → Promise<void>` | Resume a paused queue |
342
+ | `cleanQueue` | `(queue, gracePeriodMs, limit, status?) → Promise<string[]>` | Remove up to `limit` jobs older than `gracePeriodMs` (`0` = no limit); returns removed ids |
343
+ | `upsertJobScheduler` | `<TData, TResult>(queue, id, repeat, template?) → Promise<Job<TData, TResult> \| undefined>` | Create or update a recurring Job Scheduler; returns the first scheduled job |
344
+ | `removeJobScheduler` | `(queue, id) → Promise<boolean>` | Remove a Job Scheduler by ID |
345
+ | `getJobSchedulers` | `(queue, start?, end?, asc?) → Promise<JobSchedulerJson[]>` | Page the schedulers registered on a queue |
346
+ | `getOrCreateQueue` | `<TData, TResult>(queue, overrides?) → Queue<TData, TResult>` | Return the cached raw `Queue` instance |
347
+ | `getCachedQueues` | `() → ReadonlyMap<string, Queue>` | Read-only view of every queue created so far |
339
348
 
340
349
  ### `WorkerRegistry`
341
350
 
342
351
  Programmatic API to create and manage BullMQ workers at runtime.
343
352
 
344
353
  ```typescript
354
+ import path from 'node:path'
345
355
  import { WorkerRegistry } from '@bymax-one/nest-queue'
346
356
  import type { ProgrammaticWorkerConfig, SandboxedWorkerConfig } from '@bymax-one/nest-queue'
347
357
 
348
358
  // Register an in-process worker
349
359
  registry.register({
350
360
  queueName: 'email',
351
- processor: async (job) => {
361
+ handler: async (job) => {
352
362
  /* … */
353
363
  },
354
364
  options: { concurrency: 4 },
@@ -404,6 +414,23 @@ const metrics: QueueMetrics = await this.metricsService.get('email')
404
414
  const all: readonly QueueMetrics[] = await this.metricsService.getAll()
405
415
  ```
406
416
 
417
+ ### Other exports
418
+
419
+ | Export | What it is |
420
+ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
421
+ | `WorkerRegistry.unregister(queue)`, `list()` | Stop and remove a worker and its connection; list the queue names that have a worker |
422
+ | `FlowService.addBulk(flows)`, `getProducer()`, `close()` | Add several flows at once; the underlying BullMQ `FlowProducer`; close it (a no-op while flows are disabled) |
423
+ | `MetricsService.invalidate(queue?)` | Drop the cached snapshot of one queue, or of all of them |
424
+ | `QueueEventsRegistry` | The shared `QueueEvents` per queue (`getOrCreate`, `list`), used by `@OnQueueEvent` |
425
+ | `BYMAX_QUEUE_OPTIONS`, `BYMAX_QUEUE_RESOLVED_OPTIONS` | Injection tokens for the options as given and with the defaults applied |
426
+ | `BYMAX_QUEUE_REDIS_CLIENT`, `BYMAX_QUEUE_CONNECTION_MODE` | Injection tokens for the Queue-role ioredis client and for `'mode-a-byo'` or `'mode-b-owned'` |
427
+ | `DEFAULT_WORKER_CONCURRENCY`, `MAX_WORKER_CONCURRENCY` | The worker concurrency used when none is given, and its ceiling |
428
+ | `DEFAULT_JOB_OPTIONS`, `DEFAULT_METRICS_CACHE_TTL_MS`, `DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS` | The defaults of the Configuration table |
429
+ | `QUEUE_ERROR_MESSAGES` | The default message of each error code |
430
+ | `BymaxQueueModuleOptions`, `BymaxQueueModuleAsyncOptions`, `BymaxQueueOptionsFactory`, `QueueConnectionConfig`, `QueueConnectionMode` | The option and connection types behind `forRoot` and `forRootAsync` |
431
+ | `ProcessorMetadata`, `ProcessHandlerMetadata`, `QueueEventListenerMetadata` | The reflection metadata the decorators write |
432
+ | `JobStatus`, `JOB_STATUS`, `BulkJob`, `SandboxedJob`, `WorkerEventName`, `QueueEventName`, `WorkerOptions` | Constants and types for the APIs above |
433
+
407
434
  ---
408
435
 
409
436
  ## 🚨 Error Code Catalog
@@ -495,12 +522,14 @@ onFailed(job: Job | undefined, err: Error): void {
495
522
 
496
523
  ### `@OnQueueEvent(eventName)`
497
524
 
498
- Listens to BullMQ `QueueEvents` (global, cross-process events). Requires `queueEvents: { enabled: true }` in module options.
525
+ Listens to BullMQ `QueueEvents` (global, cross-process events). The library opens one shared `QueueEvents` connection per queue when it discovers the first listener for it; there is no option to enable.
526
+
527
+ The handler receives one serialized payload object, not a `Job`: `completed` carries `{ jobId, returnvalue, prev? }`, `failed` carries `{ jobId, failedReason, prev? }`, and `error` carries a real `Error`. Fetch the job with `QueueService.getJob` when you need it.
499
528
 
500
529
  ```typescript
501
530
  @OnQueueEvent('completed')
502
- onCompleted(jobId: string, returnValue: string): void {
503
- console.log(`Job ${jobId} completed`)
531
+ onCompleted({ jobId, returnvalue }: { jobId: string; returnvalue: string }): void {
532
+ console.log(`Job ${jobId} completed with ${returnvalue}`)
504
533
  }
505
534
  ```
506
535
 
@@ -586,7 +615,7 @@ import { BullMQOtel } from 'bullmq-otel'
586
615
 
587
616
  BymaxQueueModule.forRoot({
588
617
  connection: { url: process.env.REDIS_URL ?? 'redis://localhost:6379' },
589
- telemetry: new BullMQOtel('my-service', tracer),
618
+ telemetry: new BullMQOtel({ tracerName: 'my-service' }),
590
619
  })
591
620
  ```
592
621
 
@@ -594,7 +623,7 @@ BymaxQueueModule.forRoot({
594
623
 
595
624
  ## 🛑 Graceful Shutdown
596
625
 
597
- `QueueLifecycle` is registered and invoked automatically via NestJS `onApplicationShutdown`.
626
+ `QueueLifecycle` runs automatically when NestJS closes the application context, through its `onModuleDestroy` hook (call `app.enableShutdownHooks()` so that a termination signal closes the context).
598
627
  It implements a **bounded drain protocol** with at-least-once semantics:
599
628
 
600
629
  1. All workers are closed with a grace period (`drainTimeoutMs`, default 30 s).
@@ -708,7 +737,7 @@ Connection details arrive through injected options — the library never reads
708
737
  `process.env` itself, so credentials live wherever your configuration layer keeps them.
709
738
  No connection string, password, or TLS material is written to a log line, an exception
710
739
  message, or an exception payload. `QueueException.details` carries only scalar
711
- configuration values (`{ actualValue, expectedValue, limit, received }`), never a
740
+ values — a reason, a limit, a queue or scheduler name, a status — never a
712
741
  connection object and never `job.data`.
713
742
 
714
743
  They are also not reachable by serializing the objects that hold them. The connection is
@@ -766,7 +795,7 @@ key will do it twice at some point.
766
795
  | Layer | Implementation |
767
796
  | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
768
797
  | Credentials | Injected options only; never read from `process.env`, never logged, never placed in an exception; held in a non-enumerable accessor and private fields, so serializing a service omits them |
769
- | Error payloads | `QueueException.details` restricted to scalar configuration values — no `job.data`, no connection object |
798
+ | Error payloads | `QueueException.details` restricted to scalar values — no `job.data`, no connection object |
770
799
  | Job payloads | Treated as opaque; never deep-merged (prototype-pollution guard), never logged |
771
800
  | Namespacing | `prefix` applied uniformly to `Queue`, `Worker`, `QueueEvents` and `FlowProducer` |
772
801
  | Connection policy | `maxRetriesPerRequest: null` confined to duplicated consumer connections; producers keep fail-fast retries |
@@ -796,7 +825,7 @@ key will do it twice at some point.
796
825
  ## 🧪 Testing & Quality
797
826
 
798
827
  - **100% line/branch coverage** on every implemented file (hard CI gate).
799
- - **Mutation score 99.68%** (Stryker `break 95`) — see [`docs/mutation_testing_results.md`](docs/mutation_testing_results.md).
828
+ - **Mutation score 100.00%** (Stryker `break 100`) — see [`docs/mutation_testing_results.md`](docs/mutation_testing_results.md).
800
829
  - **Real-Redis E2E** via Testcontainers (workers, flows, schedulers, deduplication, retries,
801
830
  DLQ, graceful shutdown).
802
831
  - **Type-level API tests** (`pnpm test:types`) pin the published signatures, so a refactor
@@ -804,13 +833,13 @@ key will do it twice at some point.
804
833
  - **Published-shape gates**: `pnpm check:exports` resolves every entrypoint the way each
805
834
  module-resolution mode would (all four `attw` quadrants green, `node10` included), and
806
835
  `pnpm smoke` resolves the packed tarball from a real consumer in ESM _and_ CommonJS.
807
- - **Bundle budgets** enforced (`pnpm size`): server ≤ 18 KiB brotli, shared ≤ 2.5 KiB.
836
+ - **Bundle budgets** enforced (`pnpm size`): server ≤ 18 KiB brotli, shared ≤ 2 500 B.
808
837
  - **Supply chain:** SHA-pinned third-party GitHub Actions, OSV-Scanner, TruffleHog, OpenSSF Scorecard,
809
838
  npm publish with provenance (OIDC).
810
839
 
811
840
  ```bash
812
841
  pnpm typecheck && pnpm test:types && pnpm lint && pnpm test:cov:all && \
813
- pnpm build && pnpm size && pnpm check:exports && pnpm smoke
842
+ pnpm build && pnpm size && pnpm check:exports && pnpm check:published && pnpm smoke
814
843
  ```
815
844
 
816
845
  ---
@@ -852,20 +881,17 @@ implementation, so BullMQ still works, just without the native accelerator.
852
881
 
853
882
  ### `CONNECTION_REQUIRES_NULL_RETRIES`
854
883
 
855
- This error fires in Mode A when the injected client was not configured with
856
- `maxRetriesPerRequest: null`. BullMQ workers require this setting to block on
857
- Redis operations rather than giving up after a few retries.
858
-
859
- If you use `@bymax-one/nest-cache`, pass a queue-dedicated client with `maxRetriesPerRequest: null`:
860
-
861
- ```typescript
862
- // In your cache module, create a second ioredis client for the queue
863
- const queueRedis = new Redis({ ..., maxRetriesPerRequest: null })
864
- ```
884
+ BullMQ workers need `maxRetriesPerRequest: null` to block on Redis operations rather
885
+ than giving up after a few retries. The library does not ask you to configure it: every
886
+ Worker and `QueueEvents` connection is a `duplicate()` of the client you pass, made with
887
+ `maxRetriesPerRequest: null`, and in Mode A it checks that a duplicate really comes back
888
+ that way. This error means one did not — measured with ioredis, a client created with
889
+ `maxRetriesPerRequest: 3` duplicates to `null`, so a stock client never triggers it.
865
890
 
866
- The library duplicates the client you pass and applies the correct setting; ensure
867
- the **original** client passed to Mode A is usable as a duplication source (ioredis
868
- allows duplicate on any state).
891
+ If you see it, the client you passed is not a plain ioredis client (a wrapper or a test
892
+ double whose `duplicate()` ignores its options). Pass the ioredis client itself, or let the
893
+ library open its own connection with Mode B. The producer keeps the client's own retry
894
+ policy, which is what lets it fail fast during an outage.
869
895
 
870
896
  ### Jobs get stuck (not processed after restart)
871
897
 
@@ -873,10 +899,11 @@ Stalled jobs are re-queued automatically by BullMQ's stalled-job check. If worke
873
899
  do not pick them up:
874
900
 
875
901
  1. Verify `drainTimeoutMs` is larger than the worst-case job runtime.
876
- 2. Verify `lockDuration` (in `workerOptions`) covers the handler execution time —
877
- a worker that runs longer than `lockDuration` will have its lock stolen, marking
878
- the job as stalled.
879
- 3. Check `worker.maxStalledCount` is `> 0` (default `1`) so stalled jobs re-queue.
902
+ 2. Verify `lockDuration` (in the `options` you pass to `@Processor` or `register`) covers
903
+ the handler execution time — a worker that runs longer than `lockDuration` will have its
904
+ lock stolen, marking the job as stalled.
905
+ 3. BullMQ re-queues a stalled job up to its `maxStalledCount` times (default `1`) and then
906
+ fails it; this library does not expose that setting.
880
907
 
881
908
  ---
882
909
 
package/dist/server/index.cjs CHANGED
@@ -1396,7 +1396,7 @@ var QueueLifecycle = class {
1396
1396
  }
1397
1397
  /**
1398
1398
  * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
1399
- * Removes waiting and delayed jobs; off by default to stay production-safe.
1399
+ * Removes waiting jobs and leaves delayed and active ones; off by default to stay production-safe.
1400
1400
  */
1401
1401
  async drainQueuesIfRequested() {
1402
1402
  if (!this.resolved.shutdown.drainOnShutdown) return;
package/dist/server/index.d.cts CHANGED
@@ -1067,7 +1067,7 @@ declare class QueueLifecycle implements OnModuleDestroy {
1067
1067
  private closeDuplicatedConnections;
1068
1068
  /**
1069
1069
  * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
1070
- * Removes waiting and delayed jobs; off by default to stay production-safe.
1070
+ * Removes waiting jobs and leaves delayed and active ones; off by default to stay production-safe.
1071
1071
  */
1072
1072
  private drainQueuesIfRequested;
1073
1073
  /** Close the flow producer (idempotent), swallowing any failure. */
package/dist/server/index.d.ts CHANGED
@@ -1067,7 +1067,7 @@ declare class QueueLifecycle implements OnModuleDestroy {
1067
1067
  private closeDuplicatedConnections;
1068
1068
  /**
1069
1069
  * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
1070
- * Removes waiting and delayed jobs; off by default to stay production-safe.
1070
+ * Removes waiting jobs and leaves delayed and active ones; off by default to stay production-safe.
1071
1071
  */
1072
1072
  private drainQueuesIfRequested;
1073
1073
  /** Close the flow producer (idempotent), swallowing any failure. */
package/dist/server/index.mjs CHANGED
@@ -1394,7 +1394,7 @@ var QueueLifecycle = class {
1394
1394
  }
1395
1395
  /**
1396
1396
  * Drain every cached queue when `drainOnShutdown` is enabled (dev/test only).
1397
- * Removes waiting and delayed jobs; off by default to stay production-safe.
1397
+ * Removes waiting jobs and leaves delayed and active ones; off by default to stay production-safe.
1398
1398
  */
1399
1399
  async drainQueuesIfRequested() {
1400
1400
  if (!this.resolved.shutdown.drainOnShutdown) return;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-queue",
3
- "version": "1.2.4",
3
+ "version": "1.2.5",
4
4
  "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",