queue-jobs-worker 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -5,134 +5,108 @@ 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.5] — 2026-09-15
 
 ### Core
 
 ### Fixed
 
-- **`Worker` — Job timeout cooperative cancellation via `AbortSignal`** ([#12](https://github.com/rafidahmed870/queue-jobs-worker/issues/12))
+- **Storage Initialization Enforcement prior to Queue Creation & Execution** ([#14](https://github.com/rafidahmed870/queue-jobs-worker/issues/14))
 
-  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.
+  Previously, `QueueClient.createQueue()` allowed queues to be created before `await client.init()` was called when using external storage dialects (e.g. Redis, PostgreSQL, MySQL). This caused the created queue to bind to the temporary `InMemoryStorageAdapter` instance. When `client.init()` was subsequently called, the real external storage adapter replaced the internal storage field on `QueueClient`, rendering previously enqueued jobs lost or inaccessible.
 
   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.
+  - `QueueClient.createQueue()` checks `isInitialised` before creating a queue. For external dialects and custom adapters, attempting to create a queue before `await client.init()` throws an explicit error.
+  - Queue operations (`enqueue`, `getJob`, `getJobs`, `getJobCounts`, and `createWorker`) enforce initialization status checks before executing, preventing operations on uninitialized storage.
+  - In-memory dialect continues to auto-initialize synchronously, preserving convenient single-line setup for tests and local development.
 
-### Package
+---
 
-### Fixed
+### Events
 
-- **`package.json` — Added `assets` to npm package `files` distribution**
+### Added
 
-  Added `"assets"` to the `"files"` list in `package.json` so header banner graphics in `README.md` display properly on npmjs.com.
+- `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`.
 
 ---
 
-## [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))
+<!-- Links -->
+[1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0
 
-  `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.
+### Lib
 
-  After the fix:
+### Added
 
-  - `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.
+- **`lib/scripts/` — Redis Lua scripts extracted to standalone `.lua` files**
+  - `claim.lua` — atomic job claim with delayed-job promotion.
+  - `recover-stalled.lua` — compare-and-swap stalled job recovery.
+  - `renew-lock.lua` — atomic lock renewal with ownership guard.
+  - `rate-limit.lua` — atomic rate limit decision, reset, and counter increment.
+  - `lib/scripts/index.ts` re-exports scripts as named string constants (`CLAIM_LUA`, `RECOVER_STALLED_LUA`, `RENEW_LOCK_LUA`, `RATE_LIMIT_LUA`).
+  - Scripts are embedded into the CJS/ESM distribution bundles at build time via `tsup`'s `loader: { ".lua": "text" }`.
 
 ---
 
-### Events
+### Storage
 
 ### Added
 
-- `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`.
+- **Consistent timestamps across Lua scripts**
+  - Changed `RedisStorageAdapter` to use `now_iso` from `ARGV[3]` for `updatedAt` in `CLAIM_LUA` and `RECOVER_STALLED_LUA`.
+  - Previously, `updatedAt` was sometimes derived from `lockExpiresAt`, which could differ from the actual time of the operation.
 
----
+### Fixed
 
-<!-- Links -->
-[1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0
+- **Atomic rate limiting across Redis, PostgreSQL, and MySQL adapters**
+  - `RedisStorageAdapter`: Implemented `rate-limit.lua` (`RATE_LIMIT_LUA`) script to perform window check, expiry reset, counter evaluation, increment, and TTL renewal atomically inside Redis.
+  - `PostgreSQLStorageAdapter`: Wrapped `checkAndIncrementRateLimit` in a pool client transaction (`BEGIN ... COMMIT`) utilizing `INSERT ... ON CONFLICT DO NOTHING` and `SELECT ... FOR UPDATE` row locking.
+  - `MySQLStorageAdapter`: Wrapped `checkAndIncrementRateLimit` in a connection transaction (`beginTransaction ... commit`) utilizing `INSERT ... ON DUPLICATE KEY UPDATE` and `SELECT ... FOR UPDATE` row locking.
 
-### Storage
 
-### Fixed
+---
 
-- **`recoverStalledJobs()` race condition — stale recovery overwrites a live job** ([#6](https://github.com/rafidahmed870/queue-jobs-worker/issues/6))
+### Types
 
-  The previous implementation used a two-phase read-then-write pattern:
+### Added
+
+- **`lua.d.ts` — ambient module declaration for `.lua` imports**
+  - Declares `declare module "*.lua"` so TypeScript recognises `.lua` files as `string`-exporting modules.
+  - Required by `src/lib/scripts/index.ts` to import Lua scripts directly without type errors.
 
-  1. A fetch pipeline read `lockExpiresAt` and `priority` for all active jobs.
-  2. A separate write pipeline recovered every job whose lock appeared expired.
+---
 
-  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.
+### Tests
 
-  **`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.
+### Added
 
-  **`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.
+- **`lua-scripts.test.ts` — unit tests for Redis Lua scripts**
+  - 22 tests covering all four Lua scripts (`CLAIM_LUA`, `RECOVER_STALLED_LUA`, `RENEW_LOCK_LUA`, `RATE_LIMIT_LUA`).
+  - Verifies each script loads as a non-empty string from `src/lib/scripts/index.ts`.
+  - Asserts presence of critical Redis commands (`ZPOPMIN`, `ZRANGEBYSCORE`, `SADD`, `HSET`, `SREM`, `ZADD`, `INCR`, `EXPIRE`) and CAS/RateLimit guard conditions.
+- **`vitest.config.ts` — `rawLuaPlugin` added**
+  - Custom Vite transform plugin that loads `.lua` files as raw text strings during tests, mirroring `tsup`'s `loader: { ".lua": "text" }` used at build time.
 
 ---
 
-## [1.0.1] — 2026-08-31
+## [1.0.4] — 2026-09-13
 
 ### 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))
+
+  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:
 
-  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.
+  - `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.
 
 ---
 
@@ -148,6 +122,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 <!-- Links -->
 
+[1.0.5]: https://github.com/rafidahmed870/queue-jobs-worker/compare/v1.0.0...v1.0.5
+[1.0.0]: https://github.com/rafidahmed870/queue-jobs-worker/releases/tag/v1.0.0
+[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,17 +2,20 @@
 
 # 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">
-    <img src="https://img.shields.io/npm/v/queue-jobs-worker.svg" alt="npm version">
+    <img src="https://img.shields.io/npm/dm/queue-jobs-worker.svg?label=npm%20downloads" alt="npm downloads">
+  </a>&nbsp;
+  <a href="https://www.npmjs.com/package/queue-jobs-worker">
+    <img src="https://img.shields.io/npm/v/queue-jobs-worker.svg?label=npm%20version" alt="npm version">
   </a>&nbsp;
   <a href="./LICENSE">
     <img src="https://img.shields.io/npm/l/queue-jobs-worker.svg" alt="license">
   </a>&nbsp;
   <a href="https://nodejs.org">
-    <img src="https://img.shields.io/node/v/queue-jobs-worker.svg" alt="node">
+    <img src="https://img.shields.io/node/v/queue-jobs-worker.svg" alt="node version">
   </a>
 </p>
 
@@ -31,7 +34,7 @@ It supports all major local and production-friendly backends:
 
 For a detailed feature breakdown, see [FEATURES.md](./FEATURES.md).
 
----
+<img src="./assets/queue-jobs-worker-demo.gif" alt="demo" />
 
 ## Installation
 
@@ -86,99 +89,54 @@ 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
-const client = new QueueClient({
-  dialect: "redis",
-  connectionString: "redis://:yourpassword@redis-host:6379/0",
-});
-
-await client.init();
-```
 
-With TLS:
-
-```js
+// 2. Redis (Supports standard redis://, TLS rediss://, and authentication)
 const client = new QueueClient({
   dialect: "redis",
-  connectionString: "rediss://user:password@host:6380",
+  connectionString: process.env.REDIS_URL || "redis://localhost:6379",
 });
 
-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 |
 
 ---
 
 ## Core Concepts
 
-| Concept | Description |
-|---|---|
-| `QueueClient` | Entry point that owns configuration, storage, and queues |
-| `Queue` | A separate job stream with its own settings |
-| `Job` | A unit of work passed to your processor |
-| `Worker` | Claims and executes jobs |
-| `Processor` | Your async function, e.g. `async (job) => { ... }` |
-| `StorageAdapter` | A backend abstraction for durable storage |
-| `DLQ` | Dead Letter Queue for permanently failed jobs |
+| Concept          | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `QueueClient`    | Entry point that owns configuration, storage, and queues |
+| `Queue`          | A separate job stream with its own settings              |
+| `Job`            | A unit of work passed to your processor                  |
+| `Worker`         | Claims and executes jobs                                 |
+| `Processor`      | Your async function, e.g. `async (job) => { ... }`       |
+| `StorageAdapter` | A backend abstraction for durable storage                |
+| `DLQ`            | Dead Letter Queue for permanently failed jobs            |
 
 ---
 
@@ -225,13 +183,17 @@ const queue = client.createQueue("notifications");
 
 await queue.enqueue("send-push", { userId: "u_123" });
 
-await queue.enqueue("send-push", { userId: "u_123" }, {
-  attempts: 5,
-  retryDelay: 2000,
-  backoff: "linear",
-  timeout: 10_000,
-  priority: 10,
-});
+await queue.enqueue(
+  "send-push",
+  { userId: "u_123" },
+  {
+    attempts: 5,
+    retryDelay: 2000,
+    backoff: "linear",
+    timeout: 10_000,
+    priority: 10,
+  },
+);
 ```
 
 If you want TypeScript type safety for `job.data`, pass a generic when creating the queue, such as `client.createQueue<{ userId: string }>("notifications")`.
@@ -431,19 +393,45 @@ You can provide a custom backend by implementing the `StorageAdapter` interface.
 const { QueueClient } = require("queue-jobs-worker");
 
 class MongoStorageAdapter {
-  async initialize() { /* connect, create indexes */ }
-  async close() { /* disconnect */ }
-  async enqueue(input) { /* ... */ }
-  async claim(input) { /* atomic claim */ }
-  async complete(jobId) { /* ... */ }
-  async requeue(input) { /* ... */ }
-  async moveToDlq(input) { /* ... */ }
-  async releaseLock(jobId) { /* ... */ }
-  async recoverStalledJobs(queue, now) { /* ... */ }
-  async getJob(jobId) { /* ... */ }
-  async getJobs(filter) { /* ... */ }
-  async getJobCounts(queue) { /* ... */ }
-  async checkAndIncrementRateLimit(queue, max, windowMs, now) { /* ... */ }
+  async initialize() {
+    /* connect, create indexes */
+  }
+  async close() {
+    /* disconnect */
+  }
+  async enqueue(input) {
+    /* ... */
+  }
+  async claim(input) {
+    /* atomic claim */
+  }
+  async complete(jobId) {
+    /* ... */
+  }
+  async requeue(input) {
+    /* ... */
+  }
+  async moveToDlq(input) {
+    /* ... */
+  }
+  async releaseLock(jobId) {
+    /* ... */
+  }
+  async recoverStalledJobs(queue, now) {
+    /* ... */
+  }
+  async getJob(jobId) {
+    /* ... */
+  }
+  async getJobs(filter) {
+    /* ... */
+  }
+  async getJobCounts(queue) {
+    /* ... */
+  }
+  async checkAndIncrementRateLimit(queue, max, windowMs, now) {
+    /* ... */
+  }
 }
 
 const client = QueueClient.withAdapter(new MongoStorageAdapter(), {
@@ -459,19 +447,19 @@ await client.init();
 
 ### `new QueueClient(options?)`
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `dialect` | `"memory" \| "redis" \| "postgres" \| "mysql"` | `"memory"` | Storage backend |
-| `connectionString` | `string` | — | Required for Redis/PostgreSQL/MySQL |
-| `defaults.attempts` | `number` | `3` | Max retries per job |
-| `defaults.retryDelay` | `number` | `1000` | Base retry delay in ms |
-| `defaults.backoff` | `"fixed" \| "linear" \| "exponential"` | `"exponential"` | Retry strategy |
-| `defaults.timeout` | `number` | `30000` | Per-attempt timeout in ms |
-| `defaults.concurrency` | `number` | `10` | Default worker concurrency |
-| `defaults.pollInterval` | `number` | `1000` | Poll interval in ms |
-| `defaults.stalledInterval` | `number` | `30000` | Stalled-job check interval in ms |
-| `defaults.lockDuration` | `number` | `60000` | Lock TTL in ms |
-| `defaults.rateLimit` | `{ max, duration }` | — | Optional rate limiting |
+| Option                     | Type                                           | Default         | Description                         |
+| -------------------------- | ---------------------------------------------- | --------------- | ----------------------------------- |
+| `dialect`                  | `"memory" \| "redis" \| "postgres" \| "mysql"` | `"memory"`      | Storage backend                     |
+| `connectionString`         | `string`                                       | —               | Required for Redis/PostgreSQL/MySQL |
+| `defaults.attempts`        | `number`                                       | `3`             | Max retries per job                 |
+| `defaults.retryDelay`      | `number`                                       | `1000`          | Base retry delay in ms              |
+| `defaults.backoff`         | `"fixed" \| "linear" \| "exponential"`         | `"exponential"` | Retry strategy                      |
+| `defaults.timeout`         | `number`                                       | `30000`         | Per-attempt timeout in ms           |
+| `defaults.concurrency`     | `number`                                       | `10`            | Default worker concurrency          |
+| `defaults.pollInterval`    | `number`                                       | `1000`          | Poll interval in ms                 |
+| `defaults.stalledInterval` | `number`                                       | `30000`         | Stalled-job check interval in ms    |
+| `defaults.lockDuration`    | `number`                                       | `60000`         | Lock TTL in ms                      |
+| `defaults.rateLimit`       | `{ max, duration }`                            | —               | Optional rate limiting              |
 
 ### `client.init()`
 
@@ -499,16 +487,16 @@ Creates a client using a custom storage backend.
 
 ### `queue.enqueue(type, payload, options?)`
 
-| Option | Type | Description |
-|---|---|---|
-| `attempts` | `number` | Maximum attempts for this job |
-| `retryDelay` | `number` | Base retry delay in ms |
-| `backoff` | `string` | Retry backoff strategy |
-| `timeout` | `number` | Per-attempt timeout in ms |
-| `priority` | `number` | Higher values are processed first |
-| `schedule.delay` | `number` | Delay before the job becomes eligible |
-| `schedule.runAt` | `string \| number` | Absolute run time |
-| `schedule.cron` | `string` | Cron expression for recurring jobs |
+| Option           | Type               | Description                           |
+| ---------------- | ------------------ | ------------------------------------- |
+| `attempts`       | `number`           | Maximum attempts for this job         |
+| `retryDelay`     | `number`           | Base retry delay in ms                |
+| `backoff`        | `string`           | Retry backoff strategy                |
+| `timeout`        | `number`           | Per-attempt timeout in ms             |
+| `priority`       | `number`           | Higher values are processed first     |
+| `schedule.delay` | `number`           | Delay before the job becomes eligible |
+| `schedule.runAt` | `string \| number` | Absolute run time                     |
+| `schedule.cron`  | `string`           | Cron expression for recurring jobs    |
 
 ### `queue.process(type, processor)`
 
@@ -516,30 +504,31 @@ Registers an async processor for a job type. The processor signature is `async (
 
 ### `queue.createWorker(options?)`
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `concurrency` | `number` | queue config | Maximum simultaneous job executions |
-| `shutdownTimeout` | `number` | `30000` | Graceful shutdown wait time in ms |
+| Option            | Type     | Default      | Description                         |
+| ----------------- | -------- | ------------ | ----------------------------------- |
+| `concurrency`     | `number` | queue config | Maximum simultaneous job executions |
+| `shutdownTimeout` | `number` | `30000`      | Graceful shutdown wait time in ms   |
 
 ### `queue.getJob(id)` / `queue.getJobs(status?, limit?, offset?)`
+
 ### `queue.getJobCounts()`
 
 ---
 
 ## Storage Support Matrix
 
-| Feature | Memory | Redis | PostgreSQL | MySQL |
-|---|:---:|:---:|:---:|:---:|
-| Persistence | — | ✓ | ✓ | ✓ |
-| Atomic claim | ✓ | ✓ (Lua) | ✓ (SKIP LOCKED) | ✓ (SKIP LOCKED) |
-| Priority ordering | ✓ | ✓ | ✓ | ✓ |
-| Delayed jobs | ✓ | ✓ | ✓ | ✓ |
-| Retry + backoff | ✓ | ✓ | ✓ | ✓ |
-| DLQ | ✓ | ✓ | ✓ | ✓ |
-| Stalled recovery | ✓ | ✓ | ✓ | ✓ |
-| Rate limiting | ✓ | ✓ | ✓ | ✓ |
-| Connection check on init | — | ✓ PING | ✓ SELECT 1 | ✓ SELECT 1 |
-| Auto-create schema | — | — | ✓ | ✓ |
+| Feature                  | Memory |  Redis  |   PostgreSQL    |      MySQL      |
+| ------------------------ | :----: | :-----: | :-------------: | :-------------: |
+| Persistence              |   —    |    ✓    |        ✓        |        ✓        |
+| Atomic claim             |   ✓    | ✓ (Lua) | ✓ (SKIP LOCKED) | ✓ (SKIP LOCKED) |
+| Priority ordering        |   ✓    |    ✓    |        ✓        |        ✓        |
+| Delayed jobs             |   ✓    |    ✓    |        ✓        |        ✓        |
+| Retry + backoff          |   ✓    |    ✓    |        ✓        |        ✓        |
+| DLQ                      |   ✓    |    ✓    |        ✓        |        ✓        |
+| Stalled recovery         |   ✓    |    ✓    |        ✓        |        ✓        |
+| Rate limiting            |   ✓    |    ✓    |        ✓        |        ✓        |
+| Connection check on init |   —    | ✓ PING  |   ✓ SELECT 1    |   ✓ SELECT 1    |
+| Auto-create 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;IAkB5C,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;IAwBtF,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;CAOf"}

package/dist/core/queue.d.ts

@@ -26,11 +26,13 @@ export declare class Queue<TPayload = unknown> {
     private readonly emitter;
     private readonly resolvedConfig;
     private readonly clientDefaults;
+    private readonly isInitialisedCheck?;
     /** Registered processors keyed by job type. */
     private readonly processors;
     /** Active worker instances created by this queue. */
     private readonly workers;
-    constructor(name: string, storage: StorageAdapter, emitter: QueueEventEmitter, options: QueueOptions | undefined, defaults: ResolvedDefaults);
+    constructor(name: string, storage: StorageAdapter, emitter: QueueEventEmitter, options: QueueOptions | undefined, defaults: ResolvedDefaults, isInitialisedCheck?: (() => boolean) | undefined);
+    private assertInitialised;
     /**
      * Add a new job to the queue.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/core/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,KAAK,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AA2BjD,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmB;IAElD,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IAEpE,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAGtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,QAAQ,EAAE,gBAAgB;IAa5B;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAqC5F;;;;;OAKG;IACH,OAAO,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAQlE;;;;OAIG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM;IAoB7C,8EAA8E;IACxE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAM1D,iEAAiE;IAC3D,OAAO,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,SAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;IAUpF,+CAA+C;IACzC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAQxD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,wDAAwD;IACxD,UAAU,IAAI,SAAS,MAAM,EAAE;CAGhC"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/core/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,KAAK,gBAAgB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AA2BjD,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmB;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAA8B;IAElE,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IAEpE,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAGtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,GAAG,SAAS;IAUlD,OAAO,CAAC,iBAAiB;IAYzB;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAsC5F;;;;;OAKG;IACH,OAAO,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAQlE;;;;OAIG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM;IAqB7C,8EAA8E;IACxE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAO1D,iEAAiE;IAC3D,OAAO,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,SAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;IAWpF,+CAA+C;IACzC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IASxD;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,wDAAwD;IACxD,UAAU,IAAI,SAAS,MAAM,EAAE;CAGhC"}