workmatic

library1.1.0jsnpmunverified

A persistent job queue for Node.js using SQLite. Version 1.1.0 combines the simplicity of fastq with durable SQLite storage, offering concurrency, priority, delayed jobs, retries with exponential backoff, lease-based locking, and state persistence. Zero external dependencies beyond SQLite and built-in TypeScript support. Features include a built-in web dashboard, multi-queue orchestration with job transfer, and CLI tools. Released under active development with frequent updates.

storage

npm install workmatic

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WORKMATIC

workmatic

storagejavascriptv1.1.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.

createDatabase

✓ import { createDatabase } from 'workmatic'

✗ const createDatabase = require('workmatic').createDatabase

ESM-only since v1.0; no CommonJS support. TypeScript types are included.

createClient

✓ import { createClient } from 'workmatic'

✗ import createClient from 'workmatic'

Named export, not default export.

createWorker

✓ import { createWorker } from 'workmatic'

✗ import { Worker } from 'workmatic'

The factory function is named createWorker, not Worker.

createOrchestrator

✓ import { createOrchestrator } from 'workmatic'

✗ import { Orchestrator } from 'workmatic'

Factory function, not a class.

Shows creating a database, client, and worker to persist and process jobs with concurrency.

import { createDatabase, createClient, createWorker } from 'workmatic'; const db = createDatabase({ filename: './jobs.db' }); const client = createClient({ db, queue: 'emails' }); const { id } = await client.add({ to: 'user@example.com', subject: 'Hello!' }); console.log(`Job created: ${id}`); const worker = createWorker({ db, queue: 'emails', concurrency: 4 }); worker.process(async (job) => { console.log(`Sending email to ${job.payload.to}`); await sendEmail(job.payload); }); worker.start();

Debug

Known issues

breakingcreateDatabase now returns an object, not the raw better-sqlite3 instance. Use getUnderlyingDb() to access the driver.

fix

Replace db.prepare() with getUnderlyingDb(db).prepare()

affects: >=1.1.0

gotchaUsing ':memory:' for filename creates a transient database that is lost on restart; not suitable for production persistence.

fix

Use a file path like './jobs.db' for persistent storage

affects: >=1.0.0

gotchaConcurrent workers on same SQLite file can cause SQLITE_BUSY errors; lease locking prevents double processing but concurrent writes may conflict.

fix

Run a single Node process or use WAL mode (enable via db.pragma('journal_mode=WAL'))

affects: >=1.0.0

gotchaThe built-in dashboard is for local development only; not hardened for production use.

fix

Do not expose the dashboard port in production

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: exports is not defined in ES module scope

Using CommonJS require in a project configured for ES modules

fix

Use import syntax: import { createDatabase } from 'workmatic'

TypeError: db.prepare is not a function

createDatabase no longer returns the raw better-sqlite3 instance directly

fix

Use getUnderlyingDb(db) to access the raw driver: const sqlite = getUnderlyingDb(db)

TypeError: workmatic.createDatabase is not a function

Using default import instead of named import

fix

Use import { createDatabase } from 'workmatic'

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

better-sqlite3requiredRequired for SQLite database operations, used internally for persistent storage

kyselyoptionalType-safe SQL query builder used for type definitions and optional integration

fastqrequiredCore async queue implementation used for in-memory concurrency management

Agent activity

49 hits · last 30 days

node

Resources

githubhttps://github.com/litepacks/workmatic ↗

packageworkmatic ↗

homepagehttps://github.com/litepacks/workmatic#readme ↗