queue-jobs-worker 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -4,8 +4,7 @@ All notable changes to **queue-jobs-worker** will be documented in this file.
 
 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.3] — 2026-09-09
+## [1.0.4] — 2026-09-13
 
 ### Core
 
@@ -22,56 +21,6 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   - When job execution times out, the worker aborts the `AbortSignal` with a timeout error before rejecting the wrapper promise.
   - User processors can monitor `signal.aborted` or pass `signal` to async operations (e.g. `fetch`, database queries, timers) for cooperative cancellation.
 
-### Package
-
-### Fixed
-
-- **`package.json` — Added `assets` to npm package `files` distribution**
-
-  Added `"assets"` to the `"files"` list in `package.json` so header banner graphics in `README.md` display properly on npmjs.com.
-
----
-
-## [1.0.2] — 2026-09-05
-
-### Core
-
-### Fixed
-
-- **`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.
-
 ---
 
 ### Events
@@ -121,18 +70,72 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
-## [1.0.1] — 2026-08-31
+## [1.0.3] — 2026-09-09
 
 ### Core
 
 ### Fixed
 
-- **`Worker.stop()` — clarified `releaseLock()` behavior in shutdown comment** ([#1](https://github.com/rafidahmed870/queue-jobs-worker/issues/1))
+- **`Worker` — Job timeout cooperative cancellation via `AbortSignal`** ([#12](https://github.com/rafidahmed870/queue-jobs-worker/issues/12))
 
-  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.
+  Previously, when a job attempt reached its configured `timeout`, the worker rejected the internal execution promise and marked the attempt as failed (or scheduled a retry), but the underlying processor `Promise` continued running in the background. This could lead to duplicate side effects when retries overlapped with timed-out attempts.
+
+  After the fix:
+
+  - `Processor` type signature is updated: `type Processor<TPayload = unknown> = (job: Job<TPayload>, signal: AbortSignal) => Promise<void>`.
+  - An `AbortController` is created for each job attempt.
+  - When job execution times out, the worker aborts the `AbortSignal` with a timeout error before rejecting the wrapper promise.
+  - User processors can monitor `signal.aborted` or pass `signal` to async operations (e.g. `fetch`, database queries, timers) for cooperative cancellation.
+
+### Package
+
+### Fixed
+
+- **`package.json` — Added `assets` to npm package `files` distribution**
+
+  Added `"assets"` to the `"files"` list in `package.json` so header banner graphics in `README.md` display properly on npmjs.com.
+
+---
+
+## [1.0.2] — 2026-09-05
+
+### Core
+
+### Fixed
+
+- **`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.
 
 ---
 
@@ -148,6 +151,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 <!-- Links -->
 
+[1.0.4]: https://github.com/rafidahmed870/queue-jobs-worker/compare/v1.0.0...v1.0.4
+[1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0
 [1.0.3]: https://github.com/rafidahmed870/queue-jobs-worker/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/rafidahmed870/queue-jobs-worker/compare/v1.0.1...v1.0.2
 [1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 # queue-jobs-worker
 
-A durable, TypeScript-first job queue for Node.js built for asynchronous work, retries, scheduling, and recovery.
+A durable, TypeScript-first job queue for Node.js built for asynchronous work, retries, scheduling, and recovery. It based on multiple storage adapter with postgresql, mysql, redis also in-memory support for dev/testing.
 
 <p align="center">
   <a href="https://www.npmjs.com/package/queue-jobs-worker">
@@ -86,85 +86,40 @@ If you are using TypeScript, you can optionally make the queue payload type-safe
 
 ## Supported Backends
 
-### Memory
-
-Use the in-memory backend for local development and tests. Data is not persisted across restarts.
+Pass `dialect` and `connectionString` to `QueueClient`. Call `await client.init()` to establish database connections and create required schema tables.
 
 ```js
-const client = new QueueClient();
-// or explicitly:
+// 1. In-Memory (Default for local development & tests, no persistence)
 const client = new QueueClient({ dialect: "memory" });
-```
-
-`init()` is effectively a no-op for this backend.
-
-### Redis
-
-```js
-const { QueueClient } = require("queue-jobs-worker");
-
-const client = new QueueClient({
-  dialect: "redis",
-  connectionString: "redis://localhost:6379",
-});
-
-await client.init();
-const jobs = client.createQueue("jobs");
-```
-
-With authentication:
 
-```js
+// 2. Redis (Supports standard redis://, TLS rediss://, and authentication)
 const client = new QueueClient({
   dialect: "redis",
-  connectionString: "redis://:yourpassword@redis-host:6379/0",
+  connectionString: process.env.REDIS_URL || "redis://localhost:6379",
 });
 
-await client.init();
-```
-
-With TLS:
-
-```js
-const client = new QueueClient({
-  dialect: "redis",
-  connectionString: "rediss://user:password@host:6380",
-});
-
-await client.init();
-```
-
-`init()` creates the Redis client, connects to the server, sends `PING`, and verifies the response is `PONG`.
-
-### PostgreSQL
-
-```js
-const { QueueClient } = require("queue-jobs-worker");
-
+// 3. PostgreSQL (Auto-creates required queue tables on init)
 const client = new QueueClient({
   dialect: "postgres",
-  connectionString: "postgresql://user:password@localhost:5432/mydb",
+  connectionString: process.env.POSTGRES_URL || "postgresql://user:password@localhost:5432/mydb",
 });
 
-await client.init();
-```
-
-`init()` verifies connectivity with `SELECT 1` and creates the queue tables if they do not already exist.
-
-### MySQL
-
-```js
-const { QueueClient } = require("queue-jobs-worker");
-
+// 4. MySQL (Auto-creates required queue tables on init)
 const client = new QueueClient({
   dialect: "mysql",
-  connectionString: "mysql://user:password@localhost:3306/mydb",
+  connectionString: process.env.MYSQL_URL || "mysql://user:password@localhost:3306/mydb",
 });
 
+// Initialize backend connection (Required for Redis, PostgreSQL, MySQL)
 await client.init();
 ```
 
-`init()` validates the connection and creates the required tables in the database.
+| Dialect | Connection Format | `client.init()` Behavior |
+|---|---|---|
+| `memory` | N/A | No-op (transient memory store) |
+| `redis` | `redis://...`, `rediss://...` (TLS), Auth URL | Connects & verifies with `PING` |
+| `postgres` | `postgresql://user:pass@host:5432/dbname` | `SELECT 1` check & creates schema |
+| `mysql` | `mysql://user:pass@host:3306/dbname` | Connection check & creates schema |
 
 ---
 

package/dist/core/client.d.ts

@@ -36,6 +36,8 @@ export declare class QueueClient {
     private readonly queues;
     private initialised;
     private closed;
+    /** True when the adapter was supplied via {@link withAdapter}; init() skips resolveAdapter() in that case. */
+    private _customAdapter;
     constructor(options?: QueueClientOptions);
     private buildMemoryOrEagerAdapter;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAwBnC,qBAAa,WAAW;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,kBAAuB;IAe5C,OAAO,CAAC,yBAAyB;IAajC;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,gCAAgC;IAC1B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAInB,cAAc;IAkC5B;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC;IAgBtF,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,SAAS;IAIvE,wDAAwD;IACxD,YAAY,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC;IAQ/D,qDAAqD;IACrD,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED,wDAAwD;IACxD,IAAI,aAAa,IAAI,OAAO,CAE3B;IAMD,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAK5F,IAAI,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAK9F,GAAG,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAS7F;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,CAChB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,kBAAkB,CAAM,GACrE,WAAW;CAKf"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAwBnC,qBAAa,WAAW;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,cAAc,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,8GAA8G;IAC9G,OAAO,CAAC,cAAc,CAAS;gBAEnB,OAAO,GAAE,kBAAuB;IAe5C,OAAO,CAAC,yBAAyB;IAajC;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,gCAAgC;IAC1B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAInB,cAAc;IAkC5B;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC;IAgBtF,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,SAAS;IAIvE,wDAAwD;IACxD,YAAY,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC;IAQ/D,qDAAqD;IACrD,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED,wDAAwD;IACxD,IAAI,aAAa,IAAI,OAAO,CAE3B;IAMD,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAK5F,IAAI,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAK9F,GAAG,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAS7F;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;;;;;;;OAQG;IACH,MAAM,CAAC,WAAW,CAChB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,kBAAkB,CAAM,GACrE,WAAW;CAMf"}

package/dist/index.cjs

@@ -2350,6 +2350,8 @@ var QueueClient = class _QueueClient {
   queues = /* @__PURE__ */ new Map();
   initialised = false;
   closed = false;
+  /** True when the adapter was supplied via {@link withAdapter}; init() skips resolveAdapter() in that case. */
+  _customAdapter = false;
   constructor(options = {}) {
     this.defaults = { ...HARD_DEFAULTS, ...options.defaults };
     this.dialect = options.dialect ?? "memory";
@@ -2385,7 +2387,9 @@ var QueueClient = class _QueueClient {
    */
   async init() {
     if (this.initialised) return;
-    this._storage = await this.resolveAdapter();
+    if (!this._customAdapter) {
+      this._storage = await this.resolveAdapter();
+    }
     await this._storage.initialize();
     this.initialised = true;
   }
@@ -2502,6 +2506,7 @@ var QueueClient = class _QueueClient {
   static withAdapter(adapter, options = {}) {
     const client = new _QueueClient(options);
     client._storage = adapter;
+    client._customAdapter = true;
     return client;
   }
 };