flatqueue is a highly optimized JavaScript priority queue implementation that leverages a binary heap structure, distinguished by storing items and their numeric priorities in two separate, flat arrays. This design choice, while limiting custom comparator functions, enables significant performance gains, often several times faster than alternatives like tinyqueue. The package is currently at version 3.0.0, primarily focused on modern JavaScript environments, being ESM-only since version 2.0.0, with further streamlining in v3.0.0 by dropping the legacy UMD bundle. It ships with first-class TypeScript types via JSDoc. Its core differentiators include its minimalistic API, small footprint, and exceptional speed, particularly effective in scenarios requiring frequent push and pop operations, making it suitable for algorithms like A* pathfinding or event schedulers where performance is critical. Its release cadence indicates active maintenance, with recent versions focusing on performance optimizations and module system compatibility, ensuring it remains a performant choice for priority queue needs in web and Node.js applications.
npm install flatqueueVerified import paths — ran on the pinned version, not inferred.
This example demonstrates how to create a FlatQueue, push items with associated priorities, peek at the top item, pop the lowest-priority item, and clear the queue. It highlights basic API usage and the queue's length property.
Migrate your project to use ES module imports (`import FlatQueue from 'flatqueue';`) and ensure your environment (Node.js, bundler) is configured for ESM (e.g., `"type": "module"` in package.json).
To explicitly release unused memory after extensive `pop()` or `clear()` operations, call `queue.shrink()`.
If deterministic ordering for same-priority items is required, you must incorporate a secondary sorting criterion into your priority value (e.g., by combining priority with a stable index) or use a different priority queue implementation.
Before pushing items, initialize `q.ids = new Uint16Array(maxSize);` and `q.values = new Uint32Array(maxSize);`.
Update your import statement to `import FlatQueue from 'flatqueue';` and ensure your project's `package.json` specifies `"type": "module"` if running in Node.js, or use a bundler configured for ESM.
Call `queue.shrink()` manually to trim the internal arrays to the current `length` of the queue, freeing unused memory. This should be done when memory usage is a concern or after significant reduction in queue size.
Always check if the return value of `peek()` or `pop()` is `undefined` before attempting to access its properties. For example: `const item = q.pop(); if (item !== undefined) { console.log(item.id); }`No dependency data recorded yet.