mysql-queue

library0.1.5jsnpmunverified

A lightweight, type-safe MySQL-based job queue for Node.js (v0.1.5). Provides a simple API to enqueue and process jobs with retries, concurrency control, polling, and timeouts. Uses Zod for runtime schema validation and ships TypeScript definitions. Contrasts with Redis-backed queues like Bull by relying on MySQL, making it suitable for projects already using MySQL and wanting minimal dependencies. Release cadence is low, as it is a young package.

database

npm install mysql-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-QUEUE

mysql-queue

databasejavascriptv0.1.5

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.

connect

✓ import { connect } from 'mysql-queue'

✗ import connect from 'mysql-queue'

Connect is a named export, not a default export. CommonJS users must use const { connect } = require('mysql-queue').

LiteQueue

✓ import { LiteQueue } from 'mysql-queue'

✗ import LiteQueue from 'mysql-queue'

Named export, not default. Also provides generic typing LiteQueue<T>.

Runner

✓ import { Runner } from 'mysql-queue'

✗ const Runner = require('mysql-queue').Runner;

Runner is a named export. Also accepts a generic type for the job data.

Connects to MySQL, creates a queue, enqueues a job, and starts a runner with Zod validation and log handlers.

import { connect, Runner, LiteQueue } from 'mysql-queue'; import { z } from 'zod'; async function main() { const db = await connect(process.env.MYSQL_URL ?? 'mysql://root:root@localhost:3306/queue'); const requestSchema = z.object({ message: z.string() }); type Request = z.infer<typeof requestSchema>; const queue = new LiteQueue<Request>('requests', db, { defaultJobArgs: { numRetries: 2 }, keepFailedJobs: false, }); await queue.enqueue({ message: 'Hello world' }); const worker = new Runner<Request>(queue, { run: async (job) => { console.log(`[${job.id}] ${job.data.message}`); }, onComplete: async (job) => { console.log(`Done ${job.id}`); }, onError: async (job) => { console.error(`Failed ${job.id}: ${job.error}`); }, }, { concurrency: 1, pollIntervalMs: 1000, timeoutSecs: 60, validator: requestSchema, }); } main().catch(console.error);

Debug

Known issues

gotchaLiteQueue constructor requires a database connection object obtained from connect(), not a connection pool or raw mysql2 connection.

fix

Use the async connect() function provided by mysql-queue to obtain the db object.

affects: >=0.1.0

gotchaThe Runner will exit immediately if no jobs are present; pollIntervalMs only affects how often it checks for new jobs after completing existing ones.

fix

Ensure the Runner is set up with the correct pollIntervalMs for your desired polling schedule.

affects: >=0.1.0

deprecatedThe keepFailedJobs option in LiteQueue constructor is not yet implemented; setting it to false may result in failed jobs still being retained.

fix

Check the library's issue tracker for updates; consider implementing cleanup manually.

affects: >=0.1.0

breakingIn versions prior to 0.1.0, the connect function returned a promise resolving to a raw mysql2 connection; now it returns a custom object.

fix

Update code to use the new connect() API and the returned db object.

affects: <0.1.0

gotchaThe Runner's timeoutSecs option sets the timeout for job execution in seconds; if a job runs longer, it will be marked as failed even if it eventually succeeds.

fix

Set timeoutSecs appropriately for your expected job durations.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'mysql-queue'

Package not installed or incorrect import path.

fix

Run 'npm install mysql-queue' and ensure your project's package.json includes it.

TypeError: db.query is not a function

The db object passed to LiteQueue is not the one returned by connect().

fix

Use the db object returned from await connect(uri).

ZodError: [ { "validation": "invalid_type", ... } ]

Job data failed Zod validation in the Runner's validator option.

fix

Ensure the enqueued data matches the Zod schema defined for the queue.

Upgrade

Version history

0.1.5latest on npm

Audit

Dependencies

zodoptionalUsed for job schema validation in the Runner's validator option

mysql2requiredPeer dependency for database connection via connect()

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/rabrain/mysql-queue ↗

packagemysql-queue ↗

homepagehttps://github.com/rabrain/mysql-queue#readme ↗