ticket-queue

library0.2.1jsnpmunverified

A ticket-based FIFO queue for Node.js (v24+), Bun, and Deno. Unlike traditional mutexes or single-blocking acquire, it allows non-blocking ticket acquisition, then later blocking until the ticket is first in line. Uses Explicit Resource Management (Disposable) for automatic cleanup. v0.2.1, ESM-only, TypeScript-types included. Differentiator: tickets can be acquired early, allowing parallel work before serializing order.

testing

npm install ticket-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TICKET-QUEUE

ticket-queue

testingjavascriptv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TicketQueue

✓ import { TicketQueue } from 'ticket-queue'

✗ const { TicketQueue } = require('ticket-queue')

ESM-only package; CommonJS require will fail. Use dynamic import if needed.

Ticket (type)

✓ import type { Ticket } from 'ticket-queue'

✗ import { Ticket } from 'ticket-queue'

Ticket is a type/interface, not a runtime value. Use 'import type' to avoid bundler warnings.

default import

✓ import { TicketQueue } from 'ticket-queue'

✗ import TicketQueue from 'ticket-queue'

No default export; named export only.

Creates a TicketQueue and demonstrates non-blocking ticket acquisition with FIFO ordering and automatic disposal via Explicit Resource Management (`using`).

import { TicketQueue } from 'ticket-queue'; const tq = new TicketQueue(); async function processInOrder(name: string) { // acquire a ticket (non-blocking) using ticket = tq.acquireTicket(); // simulate variable work await new Promise(r => setTimeout(r, Math.random() * 1000)); // wait until this ticket is first await tq.waitForFirst(ticket); console.log(name); // ticket auto-disposed: removed from queue } processInOrder('A'); processInOrder('B'); processInOrder('C'); // logs A, B, C in order regardless of work duration

Debug

Known issues

breakingNode.js < v24 lacks Explicit Resource Management (`using`). Without `using`, tickets must be manually removed or queue stalls.

fix

Upgrade to Node.js >= v24 or manually call `ticket[Symbol.dispose]()` in a finally block after every acquireTicket().

affects: <0.1.0

gotchaForgetting to remove a ticket (via using or manual dispose) will stall the queue indefinitely.

fix

Always use `using` (preferred) or wrap acquireTicket() in try/finally with ticket[Symbol.dispose]() or waitForFirstAndRemove().

affects: >=0.0.0

deprecatedThe `waitForFirstAndRemove(ticket)` method is deprecated in favor of manual dispose via `using`.

fix

Use `using ticket = tq.acquireTicket(); await tq.waitForFirst(ticket);` and let disposal happen automatically.

affects: >=0.2.0

breakingESM-only; CommonJS require() throws an error. Node.js < 16 does not support ESM.

fix

Use `import` syntax or dynamic `import('ticket-queue').then(...)`. For Node <16, upgrade or use bundler.

affects: >=0.0.0

gotchaTickets are not thread-safe; do not share tickets across worker threads or processes.

fix

Each runtime context (e.g., worker thread) must create its own TicketQueue instance.

affects: >=0.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using CommonJS require() on an ESM-only package.

fix

Change to `import { TicketQueue } from 'ticket-queue'` or use dynamic import.

TypeError: ticket[Symbol.dispose] is not a function

Using `using` syntax with a ticket in a runtime that doesn't support Explicit Resource Management (Node <24).

fix

Upgrade to Node >=24 or use try/finally with `ticket[Symbol.dispose]?.()` or manual queue removal.

Queue stalled: waiting for ticket but no one advances

A ticket was acquired but never removed (disposed), blocking the queue forever.

fix

Ensure every acquireTicket() is paired with disposal: preferably `using` or explicit `ticket[Symbol.dispose]()` in a finally block.

'Ticket' only refers to a type, but is being used as a value here.

Importing `Ticket` as a value instead of a type.

fix

Use `import type { Ticket } from 'ticket-queue'`.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/AtoraSuunva/ticket-queue ↗

packageticket-queue ↗

homepagehttps://github.com/AtoraSuunva/ticket-queue#readme ↗