@warlock.js/queue 5.33.0 → 5.34.1

package/CHANGELOG.md

@@ -1,14 +1,17 @@
-# Changelog — @warlock.js/queue
+# Changelog — @warlock.js/queue
 
 All notable changes to `@warlock.js/queue` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
-## 5.33.0 - 2026-10-19
+## 5.34.0 - 2026-10-19
 
-### Changed
+### Added
 
-- Lockstep release; package APIs are unchanged.
+- Select `driver: "local"` for durable single-host SQLite queues using Node's built-in `node:sqlite` without Redis, or `driver: "memory"` for tests executing real handlers. Existing configuration defaults to BullMQ.
+- A shared `QueueDriver` contract and `getQueueDriver()` for dispatch, snapshots, failed-job recovery, and worker lifecycle across all backends.
+- Local/memory delays, priorities, retries with fixed/exponential backoff, retention, per-queue concurrency, context propagation, progress, and results through the existing `defineJob()` API.
+- Transactional claims, renewable fenced leases, recovery after worker crashes, and bounded graceful shutdown releasing unfinished local jobs. Local/memory handlers receive an optional cancellation `signal`.
 
 ## 5.32.0 - 2026-10-18
 
@@ -27,29 +30,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Local Redis integration tests skip with a clear service message when Redis is unavailable; CI and explicitly requested integration runs fail instead. Unit cases remain runnable without Redis.
 
-## 5.30.0 - 2026-10-16
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
 ## 5.29.0 - 2026-10-01
 
 ### Changed
 
-- Lockstep release; package APIs are unchanged. Skills refer to other topics by name instead of file paths, so cross-references keep working after `agent-kit` copies them into an app.
+- Skills refer to other topics by name instead of file paths, so cross-references keep working after `agent-kit` copies them into an app.
 
 ## 5.28.0 - 2026-10-01
 
 ### Changed
 
-- Lockstep release; package APIs are unchanged. `llms.txt` now lists every skill topic with its description (frontmatter in CRLF files was skipped).
-
-## 5.27.0 - 2026-10-01
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
+- `llms.txt` now lists every skill topic with its description (frontmatter in CRLF files was skipped).
 
 ## 5.26.0 - 2026-09-30
 
@@ -63,24 +54,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - `startWorkers()` (and the `queueConnector`'s `start()`, which calls it) no longer starts in-process workers on a process that doesn't serve the `worker` role (`WARLOCK_ROLES`), logging `queue: workers not started (role: ...)` instead. Producers (`dispatch`) and the dashboard mount are unaffected. With no `--role` passed, every role is on and nothing changes.
 
-## 5.24.0 - 2026-09-27
-
-### Changed
-
-- Lockstep release; package APIs are unchanged.
-
-## 5.23.2 - 2026-09-26
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
-
-## 5.23.1 - 2026-09-26
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
-
 ## 5.23.0 - 2026-09-25
 
 ### Added
@@ -88,24 +61,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - `defineQueueContext()` / `setQueueContext()`: capture ambient state (tenant, request id) at `dispatch` and restore it around the job handler. The captured value travels in a versioned envelope; jobs without one still run. Exposed as `ctx.context`. Opt a job out with `context: false`.
 - `UnrecoverableJobError`: throw it from a handler or `restore` to fail the job permanently (mapped to BullMQ's `UnrecoverableError`).
 
-## 5.22.1 - 2026-09-25
-
-### Changed
-
-- Lockstep patch release; package APIs are unchanged.
-
-## 5.22.0 - 2026-09-25
-
-### Changed
-
-- Lockstep release maintenance and dependency refresh.
-
-## 5.21.0 - 2026-09-25
-
-### Changed
-
-- Lockstep release maintenance and dependency refresh.
-
 ## 5.20.0 - 2026-09-24
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # @warlock.js/queue
 
-Durable background jobs for Warlock.js, built on [BullMQ](https://docs.bullmq.io).
+Background jobs for Warlock.js with [BullMQ](https://docs.bullmq.io), durable local SQLite, or memory for tests.
 
 - `defineJob({ name, handle, attempts, backoff })` → a typed job with `.dispatch(payload, { delay, priority, jobId })`
 - Retries with fixed or exponential backoff, delays, priorities, progress
@@ -11,13 +11,15 @@ Durable background jobs for Warlock.js, built on [BullMQ](https://docs.bullmq.io
 
 ## Requirements
 
-**Redis is required.** BullMQ stores every job in Redis (5.0 or newer; any Redis-compatible server BullMQ supports, such as Valkey or Dragonfly, also works). This package does not start or bundle Redis.
+**BullMQ (the default)** stores jobs in Redis (5.0 or newer; any Redis-compatible server BullMQ supports, such as Valkey or Dragonfly, also works). This package does not start or bundle Redis.
+
+Select `driver: "local"` for SQLite on Node >= 22.15 (built-in `node:sqlite`, no flags; experimental in 22.15), or `driver: "memory"` for tests. Both use the same `defineJob` API. See the [local queues guide](https://warlock.js.org/v/latest/queue/guides/local-queues/) for leases, crash recovery, shutdown, and cancellation.
 
 ## Not the same as core's `Queue`
 
 `@warlock.js/core` exports a `Queue` class (`core/src/utils/queue.ts`). That one is an **in-memory batcher inside one process**: it collects items and flushes them when a size or time limit is reached. Nothing is stored; items are lost when the process exits; there are no retries.
 
-`@warlock.js/queue` is for **durable jobs**: they are stored in Redis, survive restarts, retry on failure, and can be processed by another process.
+`@warlock.js/queue` provides retries and worker execution; Redis and local SQLite storage survive restarts and support multiple worker processes. The memory driver is process-local and loses jobs on close/exit.
 
 ## Install
 
@@ -53,6 +55,19 @@ The connector starts after your app code is loaded, so every `defineJob` is regi
 
 Set `workers.enabled: false` in a process that should only dispatch jobs.
 
+### Without Redis
+
+```ts
+setQueueConfig({
+  driver: "local",
+  local: { path: "/var/lib/my-app/jobs.sqlite", leaseDuration: 30_000, pollInterval: 100 },
+  workers: { concurrency: 4, shutdownTimeout: 5000 },
+});
+// Tests: setQueueConfig({ driver: "memory" });
+```
+
+Import `setQueueConfig` from `@warlock.js/queue`, or put these options in the config file. Share the same absolute path and `prefix` across processes on one host. Local storage uses transactions and renewable leases; crashed jobs re-deliver after lease expiry. Shutdown releases unfinished jobs after its timeout and aborts their `ctx.signal`. Handlers must be idempotent and observe cancellation. Keep SQLite on local disk. The memory driver clears jobs on close/exit; bull-board and `getQueue()` require BullMQ.
+
 ## Define and dispatch
 
 ```ts