CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-queue

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/queue@7.0.x
Publish Source
CLI
Badge
tessl/npm-queue badge