queue-jobs-worker 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -6,18 +6,45 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
-## [1.0.1] — 2026-08-31
+## [1.0.2] — 2026-09-05
 
 ### Core
 
 ### Fixed
 
-- **`Worker.stop()` — clarified `releaseLock()` behavior in shutdown comment** ([#1](https://github.com/rafidahmed870/queue-jobs-worker/issues/1))
-
-  The inline comment in `worker.ts` now correctly explains that `releaseLock()`
-  sets `lockExpiresAt` to an already-expired timestamp (not null/empty), so
-  `recoverStalledJobs()` on any worker will immediately reclaim the job on the
-  next stall-check cycle.
+- **`Worker` — croner added as a required dependency; invalid expressions no longer fall back to a 1-minute interval** ([#5](https://github.com/rafidahmed870/queue-jobs-worker/issues/5))
+
+  `enqueueCronNext()` previously attempted a dynamic `import("croner")` inside
+  a try/catch. If the import failed — or if the resolved `Cron` class was not a
+  function — the code silently fell back to `Date.now() + 60_000`, scheduling
+  the next run 60 seconds later regardless of the configured cron expression.
+  The same silent fallback was also triggered for invalid cron expressions that
+  caused the `Cron` constructor to throw.
+
+  After the fix:
+
+  - `croner` is now declared as a proper `dependency` in `package.json`
+    (`^10.0.1`) and imported statically, so it is always available without any
+    dynamic-import dance.
+  - If the `Cron` constructor throws (invalid expression), a descriptive
+    `worker:error` event is emitted and re-enqueue is skipped. The worker
+    remains running.
+  - If `cronInstance.nextRun()` returns `null` (the schedule has no future
+    occurrences), a `worker:error` is emitted and re-enqueue is skipped. Again,
+    the worker keeps running.
+  - The 1-minute fallback path has been removed entirely — there is no silent
+    fallback under any failure condition.
+
+- **`Worker` — rate-limit quota no longer consumed on empty-queue polls** ([#4](https://github.com/rafidahmed870/queue-jobs-worker/issues/4))
+
+  `claimNext()` previously called `checkAndIncrementRateLimit()` before
+  attempting to claim a job. This meant every poll cycle against an empty queue
+  burned a quota slot, potentially exhausting the configured window budget
+  before any real work was done. After the fix, the storage `claim()` call
+  happens first; the rate-limit counter is only incremented when a job is
+  actually claimed for processing. If the rate limit is reached at that point
+  the lock is immediately released via `releaseLock()` so the job remains
+  reclaimable on the next window.
 
 ---
 
@@ -38,85 +65,64 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Fixed
 
-- **`releaseLock()` leaves jobs permanently stuck in `active` status** ([#1](https://github.com/rafidahmed870/queue-jobs-worker/issues/1))
-
-  All four adapters were clearing `lockExpiresAt` to `null` / empty string
-  while keeping `status` as `"active"`. Because `recoverStalledJobs()` requires
-  a non-null, already-expired `lockExpiresAt` to match a stalled job, those
-  jobs were silently skipped and could never be reclaimed or retried.
-
-  - `InMemoryStorageAdapter.releaseLock()` — `lockExpiresAt` now set to `new Date().toISOString()` instead of `null`.
-  - `RedisStorageAdapter.releaseLock()` — `lockExpiresAt` hash field now set to the current ISO timestamp instead of `""`.
-  - `PostgreSQLStorageAdapter.releaseLock()` — `lock_expires_at` column now set to `NOW()` instead of `NULL`.
-  - `MySQLStorageAdapter.releaseLock()` — `lock_expires_at` column now set to `NOW(3)` instead of `NULL`.
-
----
-
-## [1.0.0] — 2026-08-29
-
-### Added
-
-**Core**
-
-- `QueueClient` — primary entry point; configures storage, exposes queues, and coordinates lifecycle.
-- `Queue` — independent job stream with per-queue configuration overrides.
-- `Job` — rich wrapper around the raw job data record; passed to user processors.
-- `Worker` — claims and executes jobs with configurable concurrency and graceful shutdown.
-- `QueueEventEmitter` — strongly-typed lifecycle event bus shared across all components.
-
-**Job processing**
-
-- At-least-once delivery guarantee.
-- Stable job identity preserved across all retries (no duplicate job IDs).
-- Full attempt history stored per job.
-- Per-job processor timeout enforcement.
-- Priority-ordered job claiming (higher priority = claimed first).
-- Delayed and scheduled job support via `schedule.delay` and `schedule.runAt`.
-- Recurring job support via `schedule.cron` field (cron expression stored; recurrence integration point provided).
+- **`recoverStalledJobs()` race condition — stale recovery overwrites a live job** ([#6](https://github.com/rafidahmed870/queue-jobs-worker/issues/6))
 
-**Reliability**
+  The previous implementation used a two-phase read-then-write pattern:
 
-- Configurable retry with `attempts`, `retryDelay`, and `backoff` strategy.
-- Three backoff strategies: `fixed`, `linear`, `exponential` (capped at 10 minutes).
-- Dead Letter Queue (DLQ): jobs moved to `dead` status after exhausting all attempts.
-- Stalled-job recovery: expired locks on `active` jobs are detected and re-queued automatically.
-- Configurable lock duration (`lockDuration`) per queue.
+  1. A fetch pipeline read `lockExpiresAt` and `priority` for all active jobs.
+  2. A separate write pipeline recovered every job whose lock appeared expired.
 
-**Concurrency**
+  Between those two phases a worker could complete the job, fail it, or renew
+  its lock.  The write pipeline had no knowledge of that change and would
+  unconditionally overwrite the job back to `"waiting"`, causing duplicate
+  processing or data loss.
 
-- Per-worker concurrency limit (`concurrency`).
-- Atomic job claiming inside `InMemoryStorageAdapter` (single event-loop tick).
+  **`RedisStorageAdapter`** — the write pipeline has been replaced with a
+  per-job Lua script (`RECOVER_STALLED_LUA`) that implements a
+  **compare-and-swap (CAS)** guard.  The script atomically re-reads
+  `lockExpiresAt`, `lockId`, and `status` from the hash and aborts if any of
+  the three values differ from what the caller observed in the read phase.
+  Because Redis executes Lua scripts as a single indivisible command, no
+  concurrent write can slip between the re-read and the state update.  The
+  pre-filter (skip jobs whose lock has not yet expired) is preserved as an
+  optimisation to avoid unnecessary Lua round-trips.
 
-**Rate limiting**
+  **`InMemoryStorageAdapter`** — all operations run within a single event-loop
+  tick so the race is theoretical, but an equivalent CAS guard has been added
+  for consistency: `lockId` and `lockExpiresAt` are snapshotted at decision
+  time and re-validated immediately before the write.  Any interleaving that
+  mutated those fields will cause the recovery to be skipped.
 
-- Sliding-window rate limiter configurable per queue (`rateLimit.max` / `rateLimit.duration`).
-
-**Storage**
+---
 
-- `StorageAdapter` interface — clean abstraction; all core logic talks through this interface.
-- `InMemoryStorageAdapter` — full-featured in-process adapter for development and testing.
+## [1.0.1] — 2026-08-31
 
-**Configuration**
+### Core
 
-- Layered configuration: Client defaults → Queue options → Worker options → Job options.
-- `QueueClient.withAdapter()` static factory for supplying a custom storage adapter.
+### Fixed
 
-**TypeScript**
+- **`Worker.stop()` — clarified `releaseLock()` behavior in shutdown comment** ([#1](https://github.com/rafidahmed870/queue-jobs-worker/issues/1))
 
-- Full strict TypeScript types with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`.
-- All public types exported from the top-level `index.ts`.
+  The inline comment in `worker.ts` now correctly explains that `releaseLock()`
+  sets `lockExpiresAt` to an already-expired timestamp (not null/empty), so
+  `recoverStalledJobs()` on any worker will immediately reclaim the job on the
+  next stall-check cycle.
 
-**Build**
+---
 
-- Dual ESM + CJS output via `tsup`.
-- Declaration files (`.d.ts` + `.d.ts.map`) generated via `tsc`.
+### Events
 
-**Tests**
+### Added
 
-- 31 tests across backoff strategies, storage adapter, queue client, and worker behaviour.
-- Coverage: job lifecycle, retry, DLQ, concurrency, stalled recovery, rate limiting, graceful shutdown.
+- `QueueEventEmitter` — strongly-typed lifecycle event bus shared across all components.
+- Emits events for the full job lifecycle: enqueued, started, completed, failed, retrying, dead, stalled.
+- All event payloads fully typed via `events.types.ts`.
 
 ---
 
+<!-- Links -->
+
+[1.0.2]: https://github.com/rafidahmed870/queue-jobs-worker/compare/v1.0.0...v1.0.2
+[1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0
 [1.0.1]: https://github.com/rafidahmed870/queue-jobs-worker/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0

package/README.md

@@ -12,6 +12,8 @@ A production-ready background job queue for Node.js — persistent, reliable, an
 
 `queue-jobs-worker` lets you push work into a persistent queue and process it in the background — outside the main request lifecycle. You define the processor; the library handles everything else: queueing, persistence, retries, scheduling, concurrency, and failure recovery.
 
+For a full breakdown of every feature, see [FEATURES.md](./FEATURES.md).
+
 **Supports:**
 - In-memory (dev / testing)
 - Redis (node-redis v4+)
@@ -374,29 +376,7 @@ queue.process("send-push", async (job) => {
 });
 ```
 
-The `job` object exposes:
-
-```js
-job.id                // unique stable ID
-job.type              // job type string
-job.data              // your payload (never logged)
-job.attemptsMade      // attempts already executed
-job.maxAttempts       // maximum allowed
-job.attemptsRemaining
-job.attemptHistory    // array of past attempt records
-job.status            // current status
-job.priority
-job.runAt
-job.createdAt
-job.updatedAt
-
-// helpers
-job.isActive()
-job.isCompleted()
-job.isWaiting()
-job.isDelayed()
-job.isDead()
-```
+For the full list of `job` fields and helper methods, see [FEATURES.md → Job Identity & Metadata](./FEATURES.md#job-identity--metadata).
 
 ---
 
@@ -429,35 +409,17 @@ const w2 = queue.createWorker({ concurrency: 5 });
 All lifecycle events are emitted on the client. Subscribe before creating queues/workers:
 
 ```js
-// Job events
-client.on("job:enqueued",  (job) => console.log("Enqueued:", job.id));
-client.on("job:started",   (job) => console.log("Started:", job.id));
 client.on("job:completed", (job) => console.log("Done:", job.id));
 client.on("job:failed",    (job, err) => console.error("Failed:", job.id, err.message));
-client.on("job:retrying",  (job, err, nextRunAt) => {
-  console.log(`Retrying ${job.id} at ${nextRunAt}`);
-});
 client.on("job:dead",      (job, err) => console.error("DLQ:", job.id, err.message));
-client.on("job:stalled",   (jobId) => console.warn("Stalled:", jobId));
-client.on("job:recovered", (jobId) => console.log("Recovered:", jobId));
+client.on("worker:error",  (workerId, err) => console.error("Worker error:", err));
 
-// Worker events
-client.on("worker:started", (workerId) => console.log("Worker started:", workerId));
-client.on("worker:stopped", (workerId) => console.log("Worker stopped:", workerId));
-client.on("worker:status",  (workerId, status) => console.log(workerId, "→", status));
-client.on("worker:error",   (workerId, err) => console.error("Worker error:", err));
-
-// Queue / system errors
-client.on("queue:error", (queueName, err) => console.error("Queue error:", queueName, err));
-client.on("error",       (err) => console.error("Error:", err));
-
-// Remove a listener
-client.off("job:completed", myListener);
-
-// One-time listener
-client.once("job:dead", (job, err) => alertTeam(job, err));
+client.off("job:completed", myListener);  // remove a listener
+client.once("job:dead", (job, err) => alertTeam(job, err));  // one-time listener
 ```
 
+For the full event reference (all job, worker, and system events), see [FEATURES.md → Event System](./FEATURES.md#event-system).
+
 ---
 
 ## Querying Jobs
@@ -507,44 +469,24 @@ await queue.enqueue("task", payload, {
 });
 ```
 
-**Backoff strategies:**
-
-| Strategy | Formula | Example (base = 1 s) |
-|---|---|---|
-| `fixed` | `baseDelay` | 1 s, 1 s, 1 s |
-| `linear` | `baseDelay × attempt` | 1 s, 2 s, 3 s |
-| `exponential` | `baseDelay × 2^(attempt-1)` (max 10 min) | 1 s, 2 s, 4 s, 8 s |
-
-Each failed attempt is recorded in `job.attemptHistory`:
-
-```js
-job.attemptHistory.forEach((attempt) => {
-  console.log(`Attempt ${attempt.attempt}: ${attempt.error}`);
-});
-```
+Three strategies are available: `fixed`, `linear`, and `exponential`. Each failed attempt is recorded in `job.attemptHistory`. See [FEATURES.md → Retry & Backoff](./FEATURES.md#retry--backoff) for strategy formulas and details.
 
 ---
 
 ## Scheduling
 
 ```js
-// Run 30 seconds from now
-await queue.enqueue("reminder", payload, {
-  schedule: { delay: 30_000 },
-});
+// Relative delay
+await queue.enqueue("reminder", payload, { schedule: { delay: 30_000 } });
 
-// Run at a specific time
-await queue.enqueue("report", payload, {
-  schedule: { runAt: "2026-09-01T09:00:00Z" },
-});
+// Absolute timestamp
+await queue.enqueue("report", payload, { schedule: { runAt: "2026-09-01T09:00:00Z" } });
 
-// Store a cron expression (integration point for recurring jobs)
-await queue.enqueue("cleanup", payload, {
-  schedule: { cron: "0 3 * * *" },
-});
+// Cron expression (stored for recurring jobs)
+await queue.enqueue("cleanup", payload, { schedule: { cron: "0 3 * * *" } });
 ```
 
-Delayed jobs are not eligible until their `runAt` time. The Redis adapter promotes them automatically inside the Lua claim script; SQL adapters check `run_at` in the `WHERE` clause.
+Delayed jobs are not eligible until their `runAt` time. See [FEATURES.md → Scheduling](./FEATURES.md#scheduling) for details on how each adapter handles promotion.
 
 ---
 
@@ -556,34 +498,22 @@ Higher values are processed first. Default is `0`.
 await queue.enqueue("urgent-task", payload, { priority: 100 });
 await queue.enqueue("normal-task", payload, { priority: 0 });
 await queue.enqueue("low-task",    payload, { priority: -10 });
-
 // Processing order: urgent → normal → low
 ```
 
+See [FEATURES.md → Priority](./FEATURES.md#priority).
+
 ---
 
 ## Rate Limiting
 
-Limit how many jobs are processed per time window:
-
 ```js
-// Queue-level rate limit
 const queue = client.createQueue("webhooks", {
-  rateLimit: {
-    max: 50,          // max 50 jobs
-    duration: 60_000, // per 60 seconds
-  },
-});
-
-// Or as a client default
-const client = new QueueClient({
-  defaults: {
-    rateLimit: { max: 100, duration: 60_000 },
-  },
+  rateLimit: { max: 50, duration: 60_000 }, // 50 jobs per minute
 });
 ```
 
-When the limit is reached, workers skip claiming until the window resets. Jobs stay in the queue and are not lost.
+When the limit is reached, workers skip claiming until the window resets — jobs are never discarded. See [FEATURES.md → Rate Limiting](./FEATURES.md#rate-limiting).
 
 ---
 
@@ -593,26 +523,14 @@ When a job exhausts all retry attempts it is moved to the DLQ (status: `"dead"`)
 
 ```js
 client.on("job:dead", async (job, error) => {
-  await alertOncall({
-    jobId: job.id,
-    type: job.type,
-    error: error.message,
-    attempts: job.attemptsMade,
-  });
+  await alertOncall({ jobId: job.id, type: job.type, error: error.message });
 });
 
-// Query dead jobs
 const deadJobs = await queue.getJobs("dead");
-
-// Inspect a dead job's full attempt history
-const job = await queue.getJob(jobId);
-if (job) {
-  job.attemptHistory.forEach((a) => {
-    console.log(`Attempt ${a.attempt} failed: ${a.error}`);
-  });
-}
 ```
 
+Full attempt history is preserved on the job. See [FEATURES.md → Dead Letter Queue](./FEATURES.md#dead-letter-queue).
+
 ---
 
 ## Graceful Shutdown
@@ -620,21 +538,17 @@ if (job) {
 Always call `client.close()` before your process exits:
 
 ```js
-async function shutdown() {
-  await client.close(); // stops workers, releases locks, closes DB connections
+process.on("SIGTERM", async () => {
+  await client.close(); // stops workers, releases locks, closes connections
   process.exit(0);
-}
-
-process.on("SIGTERM", shutdown);
-process.on("SIGINT",  shutdown);
+});
+process.on("SIGINT", async () => {
+  await client.close();
+  process.exit(0);
+});
 ```
 
-During shutdown each worker:
-1. Stops polling for new jobs
-2. Waits up to `shutdownTimeout` (default 30 s) for active jobs to finish
-3. Releases DB/Redis connections
-
-Interrupted jobs remain recoverable — the stalled-job recovery mechanism will reclaim them on the next startup.
+Interrupted jobs remain recoverable via the stalled-job recovery mechanism. See [FEATURES.md → Graceful Shutdown](./FEATURES.md#graceful-shutdown).
 
 ---
 
@@ -820,8 +734,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 MIT — [LICENSE](./LICENSE)
 
-# Donations
+## Donation
 
-## Buy me a coffee!
+If you find this project useful, you can support me with a coffee.
 
-BTC — ``12dxgVQ3sRFhc4g7M6oydsN2tTMMthJJqS``
+**BTC:** `12dxgVQ3sRFhc4g7M6oydsN2tTMMthJJqS`

package/dist/core/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/core/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,KAAK,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AAyBjD,qBAAa,MAAM;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,WAAW,CAAK;IAExB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,YAAY,CAA+B;IAEnD,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAA6B;gBAG/C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,EAC3C,aAAa,EAAE,aAAa,EAC5B,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,gBAAgB;IAc5B,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAab;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqD3B,OAAO,CAAC,YAAY;YAQN,IAAI;YAsBJ,SAAS;YAiCT,UAAU;YAwDV,eAAe;YAwDf,aAAa;IA0C3B,OAAO,CAAC,kBAAkB;YAQZ,kBAAkB;CAkBjC"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/core/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,KAAK,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AAyBjD,qBAAa,MAAM;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,WAAW,CAAK;IAExB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,YAAY,CAA+B;IAEnD,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAA6B;gBAG/C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,EAC3C,aAAa,EAAE,aAAa,EAC5B,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,gBAAgB;IAc5B,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAab;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqD3B,OAAO,CAAC,YAAY;YAQN,IAAI;YAsBJ,SAAS;YAyCT,UAAU;YAwDV,eAAe;YA4Df,aAAa;IA0C3B,OAAO,CAAC,kBAAkB;YAQZ,kBAAkB;CAkBjC"}