@bernierllc/task-queue

Background task queue with priority and retry

Installation

npm install @bernierllc/task-queue

Features

• Priority-based ordering - Tasks processed by priority (LOW, NORMAL, HIGH, URGENT)
• Concurrency control - Limit concurrent task execution
• Retry logic - Automatic retry with configurable delays
• Event-driven - Subscribe to task lifecycle events
• In-memory queue - Fast, lightweight task processing
• TypeScript support - Full type safety

Usage

Basic Usage

import { createTaskQueue, TaskPriority } from '@bernierllc/task-queue';

const queue = createTaskQueue({ concurrency: 3 });

// Add a task
await queue.add({
  id: 'task-1',
  handler: async () => {
    // Do work
    return { success: true };
  },
  maxRetries: 3
}, TaskPriority.HIGH);

// Subscribe to events
queue.on('task.completed', (result) => {
  console.log('Task completed:', result.id);
});

// Process tasks
await queue.process();

Priority Levels

import { TaskPriority } from '@bernierllc/task-queue';

// Priority levels (higher number = higher priority)
TaskPriority.LOW = 1
TaskPriority.NORMAL = 5
TaskPriority.HIGH = 10
TaskPriority.URGENT = 20

Concurrency Control

const queue = createTaskQueue({ concurrency: 5 });

// Process up to 5 tasks simultaneously
await queue.process();

Retry Configuration

await queue.add({
  id: 'task-1',
  handler: async () => { /* work */ },
  maxRetries: 3,
  retryDelay: 1000 // 1 second between retries
});

Pause and Resume

queue.pause();  // Stop processing new tasks
queue.resume(); // Resume processing

Statistics

const stats = queue.getStats();
console.log(stats.total);      // Total tasks enqueued
console.log(stats.completed);  // Tasks completed
console.log(stats.failed);     // Tasks failed
console.log(stats.processing); // Currently processing

API

createTaskQueue(config?: TaskQueueConfig): TaskQueue

Creates a new task queue instance.

queue.add(task: Task, priority?: TaskPriority): Promise<TaskResult>

Adds a task to the queue and returns a promise that resolves when the task completes.

queue.process(concurrency?: number): Promise<void>

Processes tasks from the queue up to the concurrency limit.

queue.pause(): void

Pauses task processing.

queue.resume(): void

Resumes task processing.

queue.clear(): void

Clears all tasks from the queue.

queue.getStats(): TaskQueueStats

Returns queue statistics.

queue.on(event, handler): void

Subscribe to task events: task.completed, task.failed, task.retry.

Integration Status

Logger Integration

Status: ✅ Integrated

Uses @bernierllc/logger for comprehensive task lifecycle logging including task enqueueing, processing, completion, failures, and retries.

NeverHub Integration

Status: ⚠️ Optional

Can emit task events to NeverHub event bus for distributed monitoring and observability. Task queue can publish events like task.enqueued, task.completed, task.failed, and task.retry to NeverHub when available.

Pattern: Optional service discovery integration - package can emit task lifecycle events to NeverHub for distributed monitoring.

Example Integration:

// If NeverHub is available, emit events
if (typeof detectNeverHub === 'function') {
  queue.on('task.completed', (result) => {
    neverhub.emit('task-queue.task.completed', result);
  });
}

Docs-Suite Integration

Status: ✅ Ready

TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.