v1.2.2

@walq/core

Patch Changes

• fd98379: Report malformed job JSON as onError operation parse instead of handler, with the same job ID, attempt, and attemptsExhausted fields. Handlers still receive only valid payloads, and retry/backoff behavior is unchanged in both process and processMany. Consumers switching on context.operation should handle the new parse operation.
• e8af85e: Report unexpected worker polling failures and reject malformed grouped claim results instead of treating missing results as empty claims.
• 946b1b6: Preserve the original error and context when onError fails, retain cron validation causes, and handle unexpected background rejections without letting logging failures disrupt polling. Public APIs and retry policies are unchanged.
• e66742d: Document error logging, direct-call rejections, worker diagnostics, and aggregate cleanup errors.
• 2fdd44c: Include error cause chains in persisted job.error diagnostic text. Formatting is depth-bounded, handles circular references, and does not invoke custom inspection hooks. Errors without causes keep their existing text; onError still receives the original error and retry behavior is unchanged.

@walq/sqlite-common

Patch Changes

• 685303a: Use serialize-error for storage worker error transport so causes, SQLite diagnostic fields, and custom enumerable properties are preserved. Error properties are serialized with bounded depth and without invoking custom toJSON hooks. Public APIs and SQL execution policies are unchanged.
• Updated dependencies [fd98379]
• Updated dependencies [e8af85e]
• Updated dependencies [946b1b6]
• Updated dependencies [e66742d]
• Updated dependencies [2fdd44c]
  • @walq/core@1.2.2

@walq/better-sqlite3

Patch Changes

• b4fb895: Preserve both the original and cleanup errors when node:sqlite rollback fails or a managed adapter cannot close after initialization failure. These failures reject with a standard AggregateError containing both errors and the original as cause. Successful cleanup still rethrows the original error unchanged.
• 685303a: Use serialize-error for storage worker error transport so causes, SQLite diagnostic fields, and custom enumerable properties are preserved. Error properties are serialized with bounded depth and without invoking custom toJSON hooks. Public APIs and SQL execution policies are unchanged.
• e66742d: Document error logging, direct-call rejections, worker diagnostics, and aggregate cleanup errors.
• Updated dependencies [fd98379]
• Updated dependencies [e8af85e]
• Updated dependencies [685303a]
• Updated dependencies [946b1b6]
• Updated dependencies [e66742d]
• Updated dependencies [2fdd44c]
  • @walq/core@1.2.2
  • @walq/sqlite-common@1.2.2

@walq/sqlite

Patch Changes

• b4fb895: Preserve both the original and cleanup errors when node:sqlite rollback fails or a managed adapter cannot close after initialization failure. These failures reject with a standard AggregateError containing both errors and the original as cause. Successful cleanup still rethrows the original error unchanged.
• 685303a: Use serialize-error for storage worker error transport so causes, SQLite diagnostic fields, and custom enumerable properties are preserved. Error properties are serialized with bounded depth and without invoking custom toJSON hooks. Public APIs and SQL execution policies are unchanged.
• e66742d: Document error logging, direct-call rejections, worker diagnostics, and aggregate cleanup errors.
• Updated dependencies [fd98379]
• Updated dependencies [e8af85e]
• Updated dependencies [685303a]
• Updated dependencies [946b1b6]
• Updated dependencies [e66742d]
• Updated dependencies [2fdd44c]
  • @walq/core@1.2.2
  • @walq/sqlite-common@1.2.2

v1.2.1

@walq/core

Patch Changes

• eab33ed: Improve README quick starts, adapter selection, caller-owned connection examples, and code examples for queue features.

@walq/sqlite-common

Patch Changes

• Updated dependencies [eab33ed]
  • @walq/core@1.2.1

@walq/better-sqlite3

Patch Changes

• eab33ed: Improve README quick starts, adapter selection, caller-owned connection examples, and code examples for queue features.
• Updated dependencies [eab33ed]
  • @walq/core@1.2.1
  • @walq/sqlite-common@1.2.1

@walq/sqlite

Patch Changes

• eab33ed: Improve README quick starts, adapter selection, caller-owned connection examples, and code examples for queue features.
• Updated dependencies [eab33ed]
  • @walq/core@1.2.1
  • @walq/sqlite-common@1.2.1

v1.2.0

walq 1.2.0

walq 1.2 adds managed SQLite connections with opt-in storage worker threads. Synchronous SQLite calls can now run outside the main event loop without changing queue handlers.

Packages

All public packages are released at 1.2.0:

• @walq/core — version alignment; no core API changes
• @walq/sqlite-common — shared connection lifecycle and worker RPC
• @walq/better-sqlite3 — managed factory and optional worker execution
• @walq/sqlite — managed factory and optional worker execution

Highlights

• Both adapters export an always-async createStorage({ filename, worker? }) factory that opens and owns the connection.
• worker: true runs synchronous SQLite operations in one dedicated thread per storage instance. Worker execution is currently verified on Node.js only.
• Worker mode prevents SQLite execution and lock waits from directly blocking the main thread; it does not promise higher throughput or remove SQLite write locks. Queue handlers still run in the main thread.
• worker defaults to false; direct mode still executes synchronous SQLite work in the calling thread.
• Both modes expose an idempotent close() that rejects new calls, drains accepted operations, and closes the connection.
• Worker mode bounds outstanding calls with maxPending (default 1024); calls beyond the limit reject.
• Worker failures reject outstanding calls. Mutations are never automatically replayed because their commit outcome may be unknown.
• Default connection settings are WAL, synchronous = FULL, and a 5000-millisecond busy timeout. Override them with the initialization SQL option.

Install

Using the built-in SQLite adapter:

pnpm add @walq/core@1.2.0 @walq/sqlite@1.2.0

Using better-sqlite3:

pnpm add @walq/core@1.2.0 @walq/better-sqlite3@1.2.0 better-sqlite3

@walq/sqlite-common is installed automatically by the adapters.

Managed storage

import { Queue } from '@walq/core'
import { createStorage } from '@walq/sqlite'

const storage = await createStorage({
  filename: './queue.sqlite',
  worker: true,
})

const queue = new Queue<{ to: string }>('email', { storage })
const processor = queue.process(async ({ to }) => console.log(`Email ${to}`))
await queue.add({ to: 'user@example.com' })

// On shutdown, stop processors before closing storage.
await processor.close()
await storage.close()

For better-sqlite3, import createStorage from @walq/better-sqlite3 instead.

Compatibility

Existing externally owned betterSqlite3(db) and sqlite(db) APIs remain unchanged. Their callers still configure and close the connections themselves.

This release does not change the database format: both adapters continue using schema v12. Existing databases can be reopened without a format conversion. Stop processors and back up file-backed databases before upgrading.

See the @walq/sqlite README and @walq/better-sqlite3 README for connection settings and shutdown guidance.

v1.1.0

walq 1.1.0

walq 1.1 adds a second SQLite adapter based on the built-in node:sqlite API.

Highlights

• New @walq/sqlite adapter with no external SQLite driver or native npm addon
• Works with Node.js 22.16+, Bun 1.4.2+, and Deno 2.9.7+
• Existing @walq/better-sqlite3 adapter remains supported with the same public API
• Both adapters use the same database schema and migrations
• Existing databases can be opened with either adapter without conversion
• Shared SQLite implementation moved into @walq/sqlite-common
• Added cross-adapter conformance, concurrency, and runtime tests

Install

Using the built-in SQLite adapter:

pnpm add @walq/core@1.1.0 @walq/sqlite@1.1.0

Using better-sqlite3:

pnpm add @walq/core@1.1.0 @walq/better-sqlite3@1.1.0

@walq/sqlite-common is installed automatically by the adapters.

Switching adapters

Both adapters use schema v12 and the same migrations, so an existing walq database can be reopened with either adapter without format conversion.

Stop workers and back up file-backed databases before upgrading or switching adapters.

See the @walq/sqlite README and @walq/better-sqlite3 README for setup details.

v1.0.0

walq 1.0.0

Both @walq/core and @walq/better-sqlite3 are released at 1.0.0.

Breaking changes

• Move handler-failure retry backoff from the retry wrapper to the top-level backoff queue option. Update callers that configure retry backoff.
• Custom storage adapters must implement the new storage operations required by job counts, durable pause/resume, and other queue features. Consult the storage contract before upgrading an adapter.
• Upgrade both packages together: @walq/better-sqlite3 now requires @walq/core 1.x.

Highlights

• Process leased jobs in batches with queue.processMany().
• Prioritize jobs, deduplicate by queue-scoped keys, and enforce persistent concurrency limits for job groups. Eligible groups and ungrouped jobs share round-robin claims.
• Pause and resume queues durably; inspect persisted job counts with queue.stats().
• Register durable repeating schedules with intervals or UTC cron expressions.

v0.3.0

walq 0.3.0

• Inspect and list jobs with queue.get() and queue.list().
• Manage jobs with queue.retry(), queue.cancel(), queue.reschedule(), and queue.remove().
• The SQLite adapter migrates existing databases from schema v2 to v3 on open.

v0.2.1

Changed

• Changed retry backoff jitter semantics.
• jitter: 1 now provides full jitter from 0 up to the calculated base delay.

Full Changelog: v0.2.0...v0.2.1

v0.2.0

Added

• Added atomic queue.addMany() for batch enqueueing.
• Added fixed and exponential retry backoff.
• Added configurable retry jitter.
• Added delayed and scheduled jobs through queue.add() options.

Storage adapters

• Added the required enqueueMany() storage method for atomic batch inserts.

Full Changelog: v0.1.0...v0.2.0

v0.1.0

Initial release of walq — a small, lease-based job queue for SQLite.

Features

• At-least-once job processing.
• Atomic claims with expiring leases.
• Retries, attempt limits, and heartbeats.
• Stale-worker protection with unique lease tokens.
• Multiple logical queues in one SQLite database.
• Grouped claims and shared polling across queues.
• Configurable retention for completed and failed jobs.
• better-sqlite3 storage adapter.

Full Changelog: https://github.com/unsady/walq/commits/v0.1.0