{"id":10902,"library":"flatqueue","title":"FlatQueue","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/mourner/flatqueue","tags":["javascript","algorithms","data structures","priority queue","binary heap","typescript"],"install":[{"cmd":"npm install flatqueue","lang":"bash","label":"npm"},{"cmd":"yarn add flatqueue","lang":"bash","label":"yarn"},{"cmd":"pnpm add flatqueue","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"FlatQueue is ESM-only since v2.0.0. UMD bundles were dropped in v3.0.0.","wrong":"const FlatQueue = require('flatqueue');","symbol":"FlatQueue","correct":"import FlatQueue from 'flatqueue';"},{"note":"For direct browser usage as an ES module via CDN.","symbol":"FlatQueue (CDN)","correct":"import FlatQueue from 'https://cdn.jsdelivr.net/npm/flatqueue/+esm';"},{"note":"The package ships with first-class TypeScript types, automatically picked up by TypeScript compilers without explicit type imports.","symbol":"TypeScript Types","correct":"import FlatQueue from 'flatqueue'; // Types are inferred via JSDoc"}],"quickstart":{"code":"import FlatQueue from 'flatqueue';\n\ninterface Item {\n  id: number;\n  priority: number;\n  data: string;\n}\n\nconst q = new FlatQueue();\n\nconst items: Item[] = [\n  { id: 0, priority: 5, data: 'task A' },\n  { id: 1, priority: 1, data: 'task B' },\n  { id: 2, priority: 8, data: 'task C' },\n  { id: 3, priority: 2, data: 'task D' }\n];\n\nconsole.log('Pushing items...');\nfor (let i = 0; i < items.length; i++) {\n  // Push the item's original ID (or the item itself) and its priority value.\n  // Storing only integers (like IDs/indices) is generally faster for JavaScript engine optimizations.\n  q.push(items[i].id, items[i].priority);\n}\n\nconsole.log(`\\nQueue length: ${q.length}`);\nconsole.log(`Top item (ID): ${q.peek()}`); // Expected: 1 (ID of task B)\nconsole.log(`Top item priority: ${q.peekValue()}`); // Expected: 1\n\nconst poppedId = q.pop(); // Removes ID 1\nconsole.log(`Popped item ID: ${poppedId}`); // Expected: 1\n\nconsole.log(`\\nNew top item (ID): ${q.peek()}`); // Expected: 3 (ID of task D)\nconsole.log(`New top item priority: ${q.peekValue()}`); // Expected: 2\n\nq.clear();\nconsole.log(`\\nQueue length after clear: ${q.length}`); // Expected: 0\n","lang":"typescript","description":"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."},"warnings":[{"fix":"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).","message":"FlatQueue transitioned to ESM-only in v2.0.0, dropping the CommonJS entry point. In v3.0.0, the legacy UMD bundle was also removed. Direct CommonJS `require()` statements will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"To explicitly release unused memory after extensive `pop()` or `clear()` operations, call `queue.shrink()`.","message":"The `pop()` and `clear()` methods do not automatically shrink the internal arrays (`ids` and `values`) to free memory. This behavior is intentional to improve performance by avoiding unnecessary reallocations during intensive reuse, but can lead to higher memory consumption if the queue size frequently fluctuates downwards and isn't explicitly managed.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"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.","message":"FlatQueue is not 'stable' for items with identical priority values. If multiple items share the same lowest priority, there is no guarantee which of them will be returned first by `pop()` or `peek()`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Before pushing items, initialize `q.ids = new Uint16Array(maxSize);` and `q.values = new Uint32Array(maxSize);`.","message":"For maximum performance and memory efficiency, especially when the maximum queue size is known, you can override the internal `ids` and `values` arrays with typed arrays (e.g., `Uint16Array`, `Uint32Array`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"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.","cause":"Attempting to use CommonJS `require()` to import `flatqueue` after it became an ESM-only package.","error":"ReferenceError: require is not defined"},{"fix":"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.","cause":"The internal `ids` and `values` arrays do not automatically resize down after `pop()` or `clear()` operations to improve performance by avoiding frequent reallocations.","error":"Perceived 'memory leak' or unexpectedly high memory usage over time."},{"fix":"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); }`","cause":"Attempting to access properties of the return value from `peek()` or `pop()` when the queue is empty. Both methods return `undefined` when the queue contains no items.","error":"TypeError: Cannot read properties of undefined (reading 'id') (or similar for other properties)"}],"ecosystem":"npm"}