@bymax-one/nest-queue 1.2.12 → 1.2.14

package/CHANGELOG.md

@@ -11,6 +11,124 @@ versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.2.14] — 2026-11-14
+
+Several defaults change in this release, so read the Apply note below. A boot that succeeds, an
+enqueue that Redis answers and a job that completes behave as before.
+
+### Fixed
+
+- **A failed Mode B startup no longer leaves a client reconnecting.** When Redis was not ready in
+  time the library rejected the boot but kept the `ioredis` client it had opened, which kept
+  reconnecting and held the process open. The
+  client is now closed on every startup failure.
+- **`connectionReadyTimeoutMs` is a budget, not a first-error limit.** The first connection error
+  used to reject the boot at once with the raw `ioredis` error, so a
+  Redis restarting during a deploy failed the application. Errors while the client is
+  reconnecting are now waited through until the budget ends; the boot then rejects with
+  `queue.connection_timeout` whose `details` carry `timeoutMs` and `lastErrorCode` (for example
+  `ECONNREFUSED`), never the message, which can name the host. A refused credential
+  (`WRONGPASS`, `NOAUTH`) or a client that stopped reconnecting rejects at once with
+  `queue.connection_invalid`. Code that matched the raw `ioredis` error of a failed boot should
+  match the `QueueException` code instead.
+
+### Changed
+
+- **A producer call can no longer hang on a Redis that does not answer.** On the connection the
+  library opens, every command now carries a 5 s deadline (`commandTimeoutMs`, or the ioredis
+  `commandTimeout` you set), and `enqueue` and `enqueueBulk` reject with `CONNECTION_TIMEOUT` after
+  `enqueueTimeoutMs` (10 s) in either connection mode. A command that hits the connection's deadline
+  is reported the same way, as `CONNECTION_TIMEOUT` with `details.operation` and `timeoutMs` and the
+  original error as `cause`.
+- **The owned connection no longer buffers commands during an outage.** Its offline queue is off, so
+  a call made while Redis is down fails at once instead of waiting in memory. Set `options.enableOfflineQueue: true` to keep the old
+  behaviour. Worker and QueueEvents connections keep their offline queue and have no command deadline.
+- **A shared client with `maxRetriesPerRequest: null` is reported at boot.** Calls other than `enqueue` and
+  `enqueueBulk` then wait for as long as an outage lasts; the library warns and does not refuse.
+- **Shutdown is bounded by one budget, not one per worker.** Workers are closed in parallel and the
+  queue-events and connection steps share what is left of `drainTimeoutMs`; a connection that has not
+  quit by then is disconnected. With several stuck workers the previous sequence took the budget once
+  for each.
+- **`unregister` releases the connection even when the worker's `close()` throws.** It then rethrows
+  that error; the registry entry is dropped and the socket closed either way.
+- **`jobTimeoutMs` bounds a handler that never settles.** It is a new worker option with no default,
+  a whole number of milliseconds from 1 to 2 147 483 647, as are `commandTimeoutMs` and `enqueueTimeoutMs`.
+  When it passes, the job fails with a `queue.job_timeout` error, retries under its `attempts` and
+  `backoff`, and its concurrency slot is free again. Handlers receive an `AbortSignal` as a second
+  argument, which aborts at that moment or when BullMQ cancels the job (`worker.cancelJob()`,
+  `worker.cancelAllJobs()`); closing the worker does not abort it. Before, a hung handler held its
+  slot for good and the rest of the queue waited.
+- **Retries are spread by default.** The default backoff now carries 50% jitter: a retry waits between
+  half of its exponential delay and the whole of it, so jobs that failed together no longer retry in
+  the same instant after an outage. A `backoff` you set yourself is used as given.
+- **`getJobs` reads a bounded window.** At most 1 000 jobs per call, with integer bounds and
+  `0 <= start <= end`; an `end` of `-1`, which BullMQ reads as the whole list, is refused with
+  `INVALID_OPTIONS`.
+
+### Documentation
+
+- **Queue names are documented as keys, not user input**, because each distinct name keeps a queue and
+  its Redis resources for the life of the process.
+- **The `prefix` option's JSDoc says it is a namespace, not an access control**.
+- **A timed-out `enqueue` may still have been added**, and the README says to pass a deterministic
+  `jobId` for anything that must not run twice.
+- **The README no longer says a Redis outage fails fast regardless of configuration.** It now states
+  what bounds a producer call and when the bound does not apply.
+
+#### Apply to a derived backend
+
+- If you matched ioredis's `Command timed out` error on a producer or inspection call, match
+  `CONNECTION_TIMEOUT` instead; the original error is its `cause`.
+- If you rely on an `enqueue` waiting out a Redis outage, it now rejects with `CONNECTION_TIMEOUT`
+  after `enqueueTimeoutMs` (the add may still complete in Redis afterwards, so retry with a stable
+  `jobId` or `deduplication`); raise the option to keep waiting longer.
+- If you assert exact retry delays, expect them between 50% and 100% of the computed value; set
+  `defaultJobOptions.backoff` without `jitter` to keep exact delays.
+- If you call `getJobs` with an `end` of `-1` or a window over 1 000 jobs, those calls now throw
+  `INVALID_OPTIONS`. Page through the list with several calls of at most 1 000 jobs, for example
+  `getJobs(queue, status, start, start + 499)` in a loop until a page comes back short; the README
+  has the loop.
+- Nothing changes until you set `jobTimeoutMs`. If you do, a handler that runs longer than it is
+  failed and retried while its own promise keeps running unless it honours the `AbortSignal`, so keep
+  handlers idempotent. If you wrap `ProgrammaticWorkerConfig.handler`, accept the new optional second
+  parameter.
+- If you relied on shutdown taking up to one `drainTimeoutMs` per stuck worker, it now takes at most
+  one in total; raise `drainTimeoutMs` if jobs need longer.
+- If your Mode B code calls a `QueueService` method during a Redis outage and expected it to wait for
+  the reconnect, it now rejects at once, since the owned connection has no offline queue; set
+  `connection.options.enableOfflineQueue: true` to restore that.
+- A command that takes longer than 5 s on the owned connection (a very large `getJobs` range, for
+  example) now rejects; raise `commandTimeoutMs`.
+
+---
+
+## [1.2.13] — 2026-11-12
+
+No action required. Measured with `diff -r` of the unpacked 1.2.12 tarball against a fresh
+`npm pack`, the files that differ are `README.md`, `CHANGELOG.md` and the `version` field of
+`package.json`; `dist/` is byte-identical, so the public API, the declaration files and the peer
+ranges are those of 1.2.12.
+
+### Documentation
+
+- **The bundle budgets are no longer misquoted.** The Testing section gave "server ≤ 18 KiB brotli,
+  shared ≤ 2 500 B"; the gate sets 9 200 B and 440 B. The README now points at `pnpm size` instead of
+  restating the numbers.
+- **The tech stack names the real end-to-end dependency.** It listed `@testcontainers/redis`, which
+  is not a dependency; the suite uses `testcontainers`.
+- **The Quick Start no longer implies `isGlobal: true` is needed.** It is the default, so the option is
+  gone from the snippet and the step says `QueueService` is injectable without it.
+- **The connection-release claim covers only what the library opens.** In Mode A the shared client is
+  yours and the library never closes it.
+- **Mode A, Mode B and the connection budget are one Connections section**, the deduplication examples
+  are one block, and the msgpackr entry is a short paragraph. API Reference and the error catalog now
+  follow Testing, the tech stack is a badge row, and the Quick Start is numbered.
+- **Removed what a reader of the package does not need:** a note about an internal test fixture, a
+  history line about a BullMQ state, the pnpm 10 versus 11 narration, and the pointers to the technical
+  specification.
+
+---
+
 ## [1.2.12] — 2026-11-09
 
 No action required. The public API, the declaration files and the peer ranges are unchanged
@@ -895,7 +1013,9 @@ v6 peer range.
 
 ---
 
-[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.12...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-queue/compare/v1.2.14...HEAD
+[1.2.14]: https://github.com/bymaxone/nest-queue/compare/v1.2.13...v1.2.14
+[1.2.13]: https://github.com/bymaxone/nest-queue/compare/v1.2.12...v1.2.13
 [1.2.12]: https://github.com/bymaxone/nest-queue/compare/v1.2.11...v1.2.12
 [1.2.11]: https://github.com/bymaxone/nest-queue/compare/v1.2.10...v1.2.11
 [1.2.10]: https://github.com/bymaxone/nest-queue/compare/v1.2.9...v1.2.10