Release v1.0.5

What's Changed

Core

Fixed

• Storage Initialization Enforcement prior to Queue Creation & Execution (#14)
  • Prevented queues from being created before await client.init() when using external storage dialects or custom adapters.
  • Added initialization checks to enqueue, getJob, getJobs, getJobCounts, and createWorker.
  • Added explicit errors when queue creation or operations are attempted before storage initialization.
  • Preserved synchronous auto-initialization for the in-memory dialect.

Events

Added

• Added QueueEventEmitter, a strongly-typed lifecycle event bus shared across all components.
• Added lifecycle events for:
  • enqueued
  • started
  • completed
  • failed
  • retrying
  • dead
  • stalled
• Added fully typed event payloads through events.types.ts.

Lib

Added

• Extracted Redis Lua scripts into standalone .lua files under lib/scripts/:
  • 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.
• Added lib/scripts/index.ts to re-export scripts as named string constants:
  • CLAIM_LUA
  • RECOVER_STALLED_LUA
  • RENEW_LOCK_LUA
  • RATE_LIMIT_LUA
• Configured tsup to embed Lua scripts as strings in both CJS and ESM distribution bundles.

Storage

Added

• Consistent timestamps across Lua scripts
  • Updated RedisStorageAdapter to use now_iso from ARGV[3] for updatedAt in CLAIM_LUA and RECOVER_STALLED_LUA.
  • Ensures updatedAt reflects the actual operation time.

Fixed

• Atomic rate limiting across Redis, PostgreSQL, and MySQL adapters
  • RedisStorageAdapter
    • Added rate-limit.lua for atomic window checking, expiry reset, counter evaluation, increment, and TTL renewal.
  • PostgreSQLStorageAdapter
    • Wrapped checkAndIncrementRateLimit in a database transaction using BEGIN ... COMMIT.
    • Added INSERT ... ON CONFLICT DO NOTHING and SELECT ... FOR UPDATE row locking.
  • MySQLStorageAdapter
    • Wrapped checkAndIncrementRateLimit in a connection transaction.
    • Added INSERT ... ON DUPLICATE KEY UPDATE and SELECT ... FOR UPDATE row locking.

Types

Added

• Added lua.d.ts ambient module declaration for .lua imports.
• TypeScript now recognises Lua files as string-exporting modules.

Tests

Added

• Added lua-scripts.test.ts with 22 tests covering all four Redis Lua scripts.
• Added tests to verify:
  • Lua scripts load as non-empty strings.
  • Required Redis commands are present.
  • CAS and rate-limit guard conditions are present.
• Added rawLuaPlugin to vitest.config.ts to load .lua files as raw text during tests, matching the production tsup configuration.

Summary

This release improves storage initialization safety, introduces a strongly-typed job lifecycle event system, extracts Redis Lua scripts into maintainable standalone files, makes rate limiting atomic across all supported storage adapters, and adds comprehensive Lua script test coverage.

Related Issue

Fixes #14
Fixes #15
Fixes #16
Fixes #17

Release v1.0.4

What's Changed

Fixed

• Preserve custom storage adapters in QueueClient.withAdapter()
  • Fixed an issue where the custom adapter supplied through QueueClient.withAdapter() was replaced during client.init().
  • The supplied adapter instance is now preserved throughout the client lifecycle.
  • adapter.initialize() is called correctly during initialization.
  • init() remains idempotent and does not initialize the adapter more than once.

Tests

• Added regression coverage for custom adapter preservation and initialization.
• Existing tests continue to pass.

Related Issue: #13

Release v1.0.3

What's Changed

Job Timeout Cooperative Cancellation

• Added AbortSignal support to job processors.
• Updated the Processor type to receive an AbortSignal as the second argument.
• Each job attempt now gets its own AbortController.
• When the configured timeout is reached, the worker aborts the processor's signal before marking the attempt as failed.
• Processors can now cooperatively cancel ongoing operations using signal.aborted, signal.throwIfAborted(), or abortable APIs such as fetch.
• Prevents timed-out processor executions from unnecessarily continuing in the background and overlapping with retries.
• Updated documentation and examples to explain cooperative cancellation and its limitations.

NPM Package Assets

• Added the assets directory to the npm package files configuration.
• Ensures required package assets, including assets/queue-jobs-worker-github.png, are included in published npm releases.

Version & Documentation

• Bumped package version from 1.0.2 to 1.0.3.
• Updated release notes and changelogs.
• Updated README.md, FEATURES.md, and docs/ARCHITECTURE.md with AbortSignal usage guidelines.

Verification

• All 43 unit tests passed.
• Type checking passed with 0 errors.
• ESLint passed with 0 errors.
• Production build completed successfully.
• ESM and CommonJS bundles generated successfully.

Example

queue.process("slow-job", async (job, signal) => {
  if (signal.aborted) return;

  await fetch("https://api.example.com/long-task", {
    signal,
  });

  console.log("processor finished");
});

Note: Cancellation is cooperative. AbortSignal cannot forcibly terminate arbitrary Node.js asynchronous operations. Processors must explicitly support and respond to the provided signal.

Release v1.0.2

What's Changed

Bug Fixes and Improvements

• Atomic Stalled Job Recovery: Fixed a potential race condition in recoverStalledJobs() where stale lock information could cause active or completed jobs to be erroneously requeued. Lock validation and status updates are now handled safely to prevent duplicate job executions under high concurrency.
• Dependency Updates: Upgraded package dependencies to their latest versions for improved stability and security.

Testing and Reliability

• Added concurrency regression test scenarios covering lock renewal and job completion during stalled job recovery flows.
• All unit and integration test suites passed successfully.

---

Full Changelog: v1.0.1...v1.0.2

Release v1.0.1

What's Changed - v1.0.1

Fixed

• Fixed jobs getting permanently stuck in active status after releaseLock().
• Fixed stalled job recovery across InMemory, Redis, PostgreSQL, and MySQL adapters.
• Clarified Worker.stop() / releaseLock() shutdown behavior.

Added

• Added strongly typed QueueEventEmitter.
• Added lifecycle events: enqueued, started, completed, failed, retrying, dead, and stalled.

Full Changelog

See the changes in this release for more details.

Release v1.0.0

queue-jobs-worker v1.0.0

Initial stable release of queue-jobs-worker — a TypeScript-first background job queue and worker library for Node.js.

Highlights

• Reliable at-least-once job delivery
• Configurable retries with fixed, linear, and exponential backoff
• Dead Letter Queue (DLQ) support
• Automatic stalled-job detection and recovery
• Priority-based job processing
• Delayed, scheduled, and recurring jobs
• Configurable worker concurrency
• Sliding-window rate limiting
• Graceful worker shutdown
• TypeScript-first API with full type declarations
• Pluggable StorageAdapter architecture
• Built-in InMemoryStorageAdapter
• Dual ESM + CommonJS builds

Testing

• 31 tests covering core queue and worker behaviour
• Coverage includes retries, DLQ, concurrency, stalled-job recovery, rate limiting, and graceful shutdown

Installation

npm install queue-jobs-worker

See the README for installation, configuration, and usage details.

Full changelog: 1.0.0