queuebit

queuebit

Queuebit is a Redis-backed background job queue for Node.js and vext projects.

The basic flow is small:

• Install queuebit.
• Pass Redis configuration.
• Register a processor.
• Call jobs.add() from your Web/API code.
• Run one or more Workers.

Use BatchRun only when you need to page many database records, create jobs from each page, record batch/final results, and recover progress after failures.

Release status: the current package is pre-v0.1. The docs/v01 site is the confirmed user contract for the planned v0.1 runtime. Some full examples are still target contracts until release evidence closes.

Install

npm install queuebit

First Job

import { createQueuebitClient } from 'queuebit';
import config from './queuebit.config.js';

const queuebit = await createQueuebitClient({ config });

const job = await queuebit.jobs.add(
  'notification',
  'send-receipt',
  { orderId, tenantId, recipient }
);

return { jobId: job.id, state: job.state };

Run the Worker separately:

npx queuebit worker start --config queuebit.config.ts --runtime queuebit.runtime.ts --queue notification

Documentation

The bilingual user manual lives in docs/v01:

• Quick start
• Run one background job
• Process many database records
• Configure Redis and Workers
• Production deployment
• Failure runbooks
• 中文用户手册

Choose a Path

Goal	Start here
Run the first background task	Quick start
Add retry, timeout, delay, or duplicate protection	Run one background job
Page many database records into jobs	Process many database records
Integrate with vext	vext integration
Prepare production Redis and Workers	Configure Redis and Workers
Recover an incident	Failure runbooks

Compatibility

Queuebit core requires Node.js >=20. The queuebit/vext adapter and canonical vext example require Node.js >=20.19 with vextjs@0.3.26.

Redis requires >=7.2. Supported Redis topologies are standalone Redis or managed single-primary Redis, optionally discovered by Sentinel. Redis Cluster and non-Redis backends are not part of v0.1.

Queuebit provides at-least-once processing. External side effects such as email, payment, webhook, and business database writes still need stable business idempotency keys.

What Is Included

• Direct jobs with jobs.add, addBulk, inspect, cancel, retry-failed replacement, delay, retry, timeout, and backpressure.
• Worker kernel and runner with Redis-backed claim, renew, drain, stalled recovery, and cooperative time advancement.
• Durable BatchRun identity with source/mapper/processor/completion registration, sequential/paced dispatch, progress checkpoints, run controls, failure listing, and recovery runs.
• Completion event delivery with retry.
• Redis direct URL/direct options/Sentinel connection support through @redis/client.
• Health, metrics, capacity, retention, alert evaluation, CLI, and queuebit/vext client lifecycle adapter.

What Is Not Included in v0.1

• Cron/repeatable jobs.
• DAG or workflow orchestration.
• Priority queues.
• Global rate limiting.
• Dashboard/Admin UI.
• CDC or unbounded streams.
• Redis Cluster or non-Redis backends.

Development Checks

npm run typecheck
npm run typecheck:examples
npm test
npm run docs:validate
npm run docs:build

Redis-backed suites are environment-gated:

npm run test:redis
npm run test:redis:faults
npm run test:redis:sentinel

Without the required Redis or Sentinel environment variables, those suites skip with exit code 0.

Package

npm pack --dry-run

The published package contains dist, README.md, LICENSE, and package.json.

License

Apache-2.0