or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

array-operations.mdevent-system.mdindex.mdqueue-management.md
tile.json

tessl/npm-queue

Asynchronous function queue with adjustable concurrency control and Promise/callback support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/queue@7.0.x

To install, run

npx @tessl/cli install tessl/npm-queue@7.0.0

index.mddocs/

Queue

Queue is a powerful asynchronous function queue implementation with adjustable concurrency control. It provides an Array-like API for managing jobs, supports both callback-based and Promise-based async functions, and includes comprehensive event handling with timeout support.

Package Information

  • Package Name: queue
  • Package Type: npm
  • Language: JavaScript (ES Module with TypeScript definitions)
  • Installation: npm install queue

Core Imports

import Queue from "queue";

For named imports (ES modules):

import Queue, { QueueEvent } from "queue";

For CommonJS (requires Node.js module compatibility):

const Queue = require("queue").default;
const { QueueEvent } = require("queue");

Basic Usage

import Queue from "queue";

// Create queue with concurrency control
const q = new Queue({ 
  concurrency: 2,
  timeout: 5000,
  results: []
});

// Add jobs using Array-like methods
q.push((callback) => {
  setTimeout(() => {
    callback(null, "job 1 complete");
  }, 1000);
});

q.push(() => {
  return new Promise((resolve) => {
    setTimeout(() => resolve("job 2 complete"), 500);
  });
});

// Listen for events
q.addEventListener('success', (event) => {
  console.log('Job completed:', event.detail.result);
});

// Start processing
q.start((err, results) => {
  if (err) throw err;
  console.log('All jobs complete:', results);
});

Architecture

Queue is built around several key components:

  • Queue Class: Main queue implementation extending EventTarget for event handling
  • Array-like API: Familiar methods (push, pop, shift, etc.) for job manipulation
  • Concurrency Control: Configurable maximum concurrent job execution
  • Event System: Comprehensive event emission for monitoring job lifecycle
  • Timeout Management: Global and per-job timeout handling with cleanup
  • Result Collection: Optional array for collecting job return values

Capabilities

Queue Management

Core queue functionality for creating, configuring, and controlling job execution. Handles both callback-based and Promise-based async functions.

class Queue extends EventTarget {
  constructor(options?: Options);
  start(): Promise<any[] | null>;
  start(callback: (error?: Error, results?: any[] | null) => void): void;
  stop(): void;
  end(error?: Error): void;
  clearTimers(): void;
  readonly length: number;
  readonly pending: number;
  readonly session: number;
  readonly running: boolean;
  readonly jobs: QueueWorker[];
  readonly timers: number[];
}

interface Options {
  concurrency?: number;    // Default: Infinity
  timeout?: number;        // Default: 0 (no timeout)
  autostart?: boolean;     // Default: false
  results?: any[];         // Default: null
}

Queue Management

Array-like Operations

Familiar Array methods for adding, removing, and manipulating jobs in the queue. All methods support the same signatures as native Array methods.

// Job addition methods
push(...workers: QueueWorker[]): number;
unshift(...workers: QueueWorker[]): number;
splice(start: number, deleteCount?: number, ...workers: QueueWorker[]): Queue;

// Job removal methods  
pop(): QueueWorker | undefined;
shift(): QueueWorker | undefined;

// Job manipulation methods
slice(start?: number, end?: number): Queue;
reverse(): Queue;
indexOf(searchElement: QueueWorker, fromIndex?: number): number;
lastIndexOf(searchElement: QueueWorker, fromIndex?: number): number;

Array Operations

Event System

Comprehensive event system for monitoring job lifecycle, handling errors, and responding to timeouts. Uses custom QueueEvent class with detailed event data.

class QueueEvent extends Event {
  constructor(name: string, detail: any);
  readonly detail: any;
}

// Event types and their detail structures
interface EventsMap {
  start: { job?: QueueWorker };
  success: { result: any[] };
  error: { error: Error, job: QueueWorker };
  timeout: { next: (err?: Error, ...result: any[]) => void, job: QueueWorker };
  end: { error?: Error };
}

Event System

Types

interface QueueWorker {
  (callback?: QueueWorkerCallback): void | Promise<any>;
  timeout?: number;     // Override queue timeout for this job
  promise?: Promise<any>; // Promise reference if job returns one
}

interface QueueWorkerCallback {
  (error?: Error, data?: Object): void;
}