adapter-queue

library0.3.0jsnpmunverified

adapter-queue v0.3.0 is a TypeScript queue system inspired by Yii2-Queue architecture, providing a clean abstraction for job processing with multiple storage backends (database, SQS, file) and event-based job handling. It offers type-safe APIs with full TypeScript support, driver-based architecture for swapping backends seamlessly, and supports features like TTR, delay, priority (per driver). The library is actively developed, requires Node.js >=18, and has peer dependencies for SQS (@aws-sdk/client-sqs), SQLite (better-sqlite3), MongoDB (mongoose), and Redis. Unlike similar systems (e.g., Bull, Bee-Queue), adapter-queue focuses on minimal boilerplate, driver flexibility, and Yii2-inspired simplicity with an event-driven handler registration.

devops

npm install adapter-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ADAPTER-QUEUE

adapter-queue

devopsjavascriptv0.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FileQueue

✓ import { FileQueue } from 'adapter-queue'

✗ const { FileQueue } = require('adapter-queue')

ESM-only package; CommonJS require() not supported.

DbQueue

✓ import { DbQueue } from 'adapter-queue'

✗ import DbQueue from 'adapter-queue'

Named export, not default. DbQueue is used for database-backed queues.

SqsQueue

✓ import { SqsQueue } from 'adapter-queue'

✗ import { SQSQueue } from 'adapter-queue'

Export is 'SqsQueue' (lowercase 'qs'), not 'SQSQueue'. Ensure correct casing.

DatabaseAdapter

✓ import { DatabaseAdapter } from 'adapter-queue'

Type import for implementing custom database adapters.

Creates a file-based queue, registers typed handlers, adds a job with TTR, and starts continuous polling every 3 seconds.

import { FileQueue } from 'adapter-queue'; interface MyJobs { 'send-email': { to: string; subject: string; body: string }; 'resize-image': { url: string; width: number; height: number }; } const queue = new FileQueue<MyJobs>({ path: './queue-data' }); queue.setHandlers({ 'send-email': async ({ payload }) => { console.log(`Sending email to ${payload.to}: ${payload.subject}`); }, 'resize-image': async ({ payload }) => { console.log(`Resizing image ${payload.url} to ${payload.width}x${payload.height}`); } }); await queue.addJob('send-email', { payload: { to: 'user@example.com', subject: 'Welcome!', body: 'Signed up.' }, ttr: 300 }); await queue.run(true, 3); async function sendEmail(to: string, subject: string, body: string) { // implement } async function resizeImage(url: string, width: number, height: number) { // implement }

Debug

Known issues

breakingIn v0.3.0, the constructor signature for FileQueue changed. Previously it accepted a string path, now it requires an options object with 'path' property.

fix

Update constructor: new FileQueue({ path: './queue-data' }) instead of new FileQueue('./queue-data')

affects: >=0.3.0

gotchaThe 'adapter-queue' package is ESM-only. Using require() or importing in a CommonJS project will fail with ERR_REQUIRE_ESM.

fix

Convert project to ESM (type: 'module' in package.json) or use dynamic import().

affects: >=0.1.0

gotchaFileQueue does not support priority. The 'priority' option is silently ignored. Database drivers may support priority depending on adapter implementation.

fix

Use DbQueue with an adapter that implements priority if needed.

affects: >=0.1.0

deprecatedThe queue.stop() method has been deprecated in v0.3.0. Use await queue.run(false) for one-off processing instead.

fix

Replace queue.stop() with queue.run(false).

affects: >=0.3.0

gotchaJob handlers must be registered before calling run(). If no handlers are set, run() will throw an error.

fix

Call queue.setHandlers() before queue.run().

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: adapter_queue_1.FileQueue is not a constructor

Named import used incorrectly with default import expectation or CommonJS require.

fix

Use ESM import: import { FileQueue } from 'adapter-queue'

ERR_REQUIRE_ESM

Trying to require() an ESM-only package in a CommonJS context.

fix

Switch to ESM or use dynamic import: const { FileQueue } = await import('adapter-queue')

Error: Handlers must be set before processing jobs

Calling run() without first registering handlers with setHandlers().

fix

Add queue.setHandlers({ ... }) before queue.run().

TypeError: queue.addJob is not a function

Using an old version where method was named 'add' instead of 'addJob'.

fix

Upgrade to v0.2.0+ and use queue.addJob().

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

@aws-sdk/client-sqsoptionalRequired for SQS driver

better-sqlite3optionalOptional peer dep for database driver (SQLite adapter)

mongooseoptionalOptional peer dep for database driver (MongoDB adapter)

redisoptionalOptional peer dep for database driver (Redis adapter)

Agent activity

42 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/muniter/adapter-queue ↗

packageadapter-queue ↗

homepagehttps://github.com/muniter/adapter-queue#readme ↗