priority-queue

library0.2.1jsnpmunverified

A functional, data-oriented priority queue (max-heap) for Node.js, version 0.2.1. Designed to be tiny (~150 lines), pure ES module, and — critically — does not allocate memory at runtime after initial creation. It is a preallocated array-based heap offering queue, dequeue, isEmpty, clear, delete, and list operations. Unlike typical priority queue libraries that allocate dynamically, this one is suited for performance-critical or real-time applications where GC pauses must be avoided. The package is actively maintained and has tests via GitHub Actions.

storage

npm install priority-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PRIORITY-QUEUE

priority-queue

storagejavascriptv0.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.

default

✓ import PQ from 'priority-queue'

✗ const PQ = require('priority-queue')

ESM-only since v0.1.0; CommonJS require() will throw.

create

✓ import PQ from 'priority-queue'; const obj = PQ.create()

✗ import { create } from 'priority-queue'; const obj = create()

create is not a named export; it is a method on the default export.

queue

✓ PQ.queue(obj, 'item', priority)

✗ obj.queue('item', priority)

API is functional, not object-oriented. Methods are on the PQ module, not the queue object.

Create a priority queue, insert items with priorities, and dequeue them in order of descending priority. Shows that dequeue returns undefined when empty.

import PQ from 'priority-queue' const obj = PQ.create(20000) PQ.queue(obj, 'low', 1) PQ.queue(obj, 'high', 10) PQ.queue(obj, 'medium', 5) console.log(PQ.dequeue(obj)) // 'high' console.log(PQ.dequeue(obj)) // 'medium' console.log(PQ.dequeue(obj)) // 'low' console.log(PQ.dequeue(obj)) // undefined

Debug

Known issues

gotchaThe queue has a fixed maximum size set at creation (default 1000). Inserting more items will exceed capacity and cause undefined behavior or errors.

fix

Always use PQ.create(maxSize) with a size adequate for your workload.

affects: >=0.1.0

gotchaThe queue is a max-heap. Items with higher priority are dequeued first. If you need a min-heap (lowest priority first), invert the priority values (e.g., use negative values).

fix

Pass priority as -value if you need min-heap behavior.

affects: >=0.1.0

gotchadelete method expects exact reference equality to remove an item. If you pass a different object with same data, it won't be found.

fix

Keep a reference to the item when you queue it, and use that same reference for delete.

affects: >=0.1.0

breakingVersion 0.2.0 changed internal structure; PQ.queue now takes (obj, item, priority) instead of (obj, item, priority, ...) previously? Check release notes for exact changes.

fix

Verify arguments: PQ.queue(queueObject, item, priority).

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: PQ.create is not a function

Attempting named import { create } instead of default import.

fix

Use: import PQ from 'priority-queue'

Error: Cannot find module 'priority-queue'

CommonJS require used on an ESM-only package.

fix

Use import syntax or run in an ESM context (e.g., type: 'module' in package.json).

TypeError: obj.queue is not a function

Calling queue method on the queue object instead of the PQ module.

fix

Call PQ.queue(obj, item, priority) instead of obj.queue(item, priority).

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/mreinstein/priority-queue ↗

packagepriority-queue ↗

homepagehttps://github.com/mreinstein/priority-queue#readme ↗