Skip to main content

Quik Framework :: Queue Worker

Runs the scheduler's database-backed task queue inside a Node worker_threads worker, isolated from the main application thread. Polls for due tasks on an interval and executes registered handlers in batches.

Installation​

pnpm add @quik/queue-worker

Usage​

Worker entry point​

onBoot only runs inside a worker_threads worker — booting the app with this module on the main thread is a no-op.

// worker-entry.ts
import { boot, setup } from '@quik/bootstrap';
import { Module as DatabaseModule } from '@quik/database';
import { Module as QueueWorkerModule } from '@quik/queue-worker';

await setup({ modules: [DatabaseModule, QueueWorkerModule] });
await boot();

Spawn the worker​

import { Worker } from 'node:worker_threads';

new Worker(new URL('./worker-entry.js', import.meta.url), {
  workerData: {
    intervalMs: 2000,
    batchSize: 10,
    workerName: 'queue-worker:1'
  }
});

Register the task executor​

import { WorkerHooks } from '@quik/queue-worker';

WorkerHooks.register('execute', async (batchSize) => {
  // claim and run up to `batchSize` due tasks
});

WorkerHooks.register('reloadConfig', async () => {
  // re-read config that affects task execution
});

WorkerHooks.register('restart', async () => {
  // re-initialize resources
});

Control a running worker​

worker.postMessage({ type: 'reload-config' });
worker.postMessage({ type: 'restart' });
worker.postMessage({ type: 'shutdown' }); // waits for the in-flight tick, then exits

Configuration​

  • scheduler.queue.intervalMs (SCHEDULER_QUEUE_INTERVAL_MS) — polling interval between queue checks. Defaults to 2000.
  • scheduler.queue.batchSize (SCHEDULER_QUEUE_BATCH_SIZE) — number of due tasks claimed per poll. Defaults to 10.

workerData.intervalMs/batchSize passed to the Worker constructor override these per-worker.

API Highlights​

  • WorkerHooks.register(type, handler) — register an execute, reloadConfig, or restart handler.
  • WorkerHooks.get(type) — read registered handlers for a hook type.
  • Module — lifecycle hooks (setup, onBoot, onAfterBoot) wired into @quik/bootstrap.

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the queue-worker API section.