liteque

library0.8.0jsnpmunverified

Liteque is a simple, typesafe SQLite-based job queue for Node.js, built on better-sqlite3. Version 0.8.0 is the latest stable release; the project follows a regular release cadence. It differentiates from other queues (e.g., Bull, Bee-Queue) by using SQLite as the backing store, eliminating the need for Redis or additional infrastructure. Designed for single-process or embedded use cases, it offers TypeScript-first APIs with Zod schema validation for job data, configurable retries, concurrency control, and lifecycle hooks (onComplete, onError).

database

npm install liteque

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LITEQUE

liteque

databasejavascriptv0.8.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.

buildDBClient

✓ import { buildDBClient } from 'liteque'

✗ import buildDBClient from 'liteque'

Named export; no default import.

Runner

✓ import { Runner } from 'liteque'

✗ const { Runner } = require('liteque')

ESM-only package; use import syntax or dynamic import with CommonJS.

SqliteQueue

✓ import { SqliteQueue } from 'liteque'

Generic type parameter: new SqliteQueue<YourDataType>(...).

Demonstrates setting up a SQLite queue, enqueuing a job, and running a worker with lifecycle hooks.

import { buildDBClient, Runner, SqliteQueue } from 'liteque'; import { z } from 'zod'; const db = buildDBClient(':memory:', { runMigrations: true }); const requestSchema = z.object({ message: z.string() }); type ZRequest = z.infer<typeof requestSchema>; const queue = new SqliteQueue<ZRequest>('requests', db, { defaultJobArgs: { numRetries: 2 }, keepFailedJobs: false, }); await queue.enqueue({ message: 'Hello world' }); const worker = new Runner<ZRequest>(queue, { run: async (job) => { console.log(job.data.message); }, onComplete: async (job) => { console.log('Done'); }, onError: async (job) => { console.error(job.error); }, }, { concurrency: 1, pollIntervalMs: 1000, timeoutSecs: 60, validator: requestSchema, }); await worker.start();

Debug

Known issues

gotchaThe 'validator' option in Runner is required for type safety; omitting it may cause runtime errors with malformed jobs.

fix

Always provide a Zod schema or similar validator in the third argument to Runner.

affects: >=0.4.0

breakingMigration from earlier versions (pre-0.7.0) required manual schema changes; 'runMigrations: true' is now the default.

fix

Set 'runMigrations: true' in buildDBClient options, or update database schema manually.

affects: <0.7.0

gotchaUsing an in-memory database (':memory:') means all jobs are lost when the process exits. Not suitable for production.

fix

Use a persistent file path for long-lived queues.

affects: all

gotchaConcurrency greater than 1 may lead to SQLITE_BUSY errors if multiple workers access the same in-memory database concurrently.

fix

Use WAL mode on the database file and tune SQLite's busy timeout.

affects: >0.5.0

deprecatedThe 'timeoutSecs' option in Runner is deprecated as of v0.8.0; use 'jobTimeoutSecs' instead.

fix

Replace 'timeoutSecs' with 'jobTimeoutSecs' in the Runner options object.

affects: 0.8.0

Errors

Common errors & fixes

Cannot find module 'better-sqlite3'

Missing peer dependency better-sqlite3.

fix

Install better-sqlite3: npm install better-sqlite3

TypeError: buildDBClient is not a function

Incorrect import: default import used but it's a named export.

fix

Use named import: import { buildDBClient } from 'liteque'

SchemaValidationError: Invalid job data

No validator passed to Runner; job data didn't match expected type.

fix

Provide a validator (Zod schema) in Runner's third argument.

SQLITE_BUSY: database is locked

High concurrency with in-memory database or missing WAL mode.

fix

Use a file-based database and enable WAL mode: PRAGMA journal_mode=WAL; or reduce concurrency.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

better-sqlite3requiredRequired as a peer dependency to provide synchronous SQLite database access for job storage and queue operations.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/karakeep-app/liteque ↗

packageliteque ↗

homepagehttps://github.com/karakeep-app/liteque#readme ↗