{"id":16817,"library":"fastpriorityqueue","title":"Fast Heap-based Priority Queue","description":"FastPriorityQueue.js is a high-performance, heap-based priority queue implementation for JavaScript and TypeScript. It provides efficient O(log n) operations for adding and polling elements, and O(1) for peeking the smallest element. The package is currently at version 0.8.0 and maintains an active development status, with recent minor releases addressing bug fixes and performance optimizations. Its primary differentiator is its focus on raw performance, often outperforming other JavaScript priority queue libraries by a significant margin, making it ideal for applications where the speed of data structure operations is critical. It ships with TypeScript types, ensuring a robust developer experience in typed environments.","status":"active","version":"0.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/lemire/FastPriorityQueue.js","tags":["javascript","heap","binary heap","data structure","priority queue","performance","typescript"],"install":[{"cmd":"npm install fastpriorityqueue","lang":"bash","label":"npm"},{"cmd":"yarn add fastpriorityqueue","lang":"bash","label":"yarn"},{"cmd":"pnpm add fastpriorityqueue","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `FastPriorityQueue` class is a default export for ESM/TypeScript. Named imports using destructuring will result in an `undefined` value for `FastPriorityQueue`.","wrong":"import { FastPriorityQueue } from 'fastpriorityqueue';","symbol":"FastPriorityQueue","correct":"import FastPriorityQueue from 'fastpriorityqueue';"},{"note":"For CommonJS environments, the `FastPriorityQueue` class is the module's default export. Attempting to destructure it as a named export will fail.","wrong":"const { FastPriorityQueue } = require('fastpriorityqueue');","symbol":"FastPriorityQueue","correct":"const FastPriorityQueue = require('fastpriorityqueue');"},{"note":"For TypeScript, it is good practice to explicitly import the type using `import type` if you only need the type definition, which can aid bundler optimizations.","symbol":"FastPriorityQueue (Type)","correct":"import type FastPriorityQueue from 'fastpriorityqueue';"}],"quickstart":{"code":"import FastPriorityQueue from 'fastpriorityqueue';\n\n// Create a default min-priority queue\nconst pqMin = new FastPriorityQueue();\npqMin.add(1);\npqMin.add(0);\npqMin.add(5);\npqMin.add(4);\npqMin.add(3);\n\nconsole.log('Min-Priority Queue - Peek:', pqMin.peek()); // Should return 0\nconsole.log('Min-Priority Queue - Size:', pqMin.size); // Should return 5\n\n// Create a max-priority queue using a custom comparator\nconst pqMax = new FastPriorityQueue(function(a, b) {\n  return a > b; // Returns true if a has higher priority (is 'larger') than b\n});\npqMax.add(1);\npqMax.add(0);\npqMax.add(5);\npqMax.add(4);\npqMax.add(3);\n\nconsole.log('\\nElements from Min-Priority Queue (poll):');\nwhile (!pqMin.isEmpty()) {\n  console.log(pqMin.poll()); // Will print 0 1 3 4 5\n}\n\nconsole.log('\\nElements from Max-Priority Queue (poll):');\nwhile (!pqMax.isEmpty()) {\n  console.log(pqMax.poll()); // Will print 5 4 3 1 0\n}\n\npqMin.trim(); // Optional: optimizes memory usage after churn","lang":"typescript","description":"This quickstart demonstrates the core functionality of FastPriorityQueue, including adding elements, peeking at the top element, checking the queue size, and polling elements. It also illustrates how to create a max-priority queue using a custom comparator function."},"warnings":[{"fix":"Thoroughly test custom comparator functions with diverse data sets and edge cases to ensure the expected ordering. Remember that the comparator should return `true` if `a` has higher priority (comes before) `b`.","message":"When providing a custom comparator function to the `FastPriorityQueue` constructor, ensure its logic correctly defines the desired priority. A common mistake is to reverse the comparison, leading to an improperly sorted queue. For a min-priority queue (smallest elements first), the default `(a, b) => a < b` or no comparator is used. For a max-priority queue, use `(a, b) => a > b`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If an element's priority changes, it must be explicitly removed from the queue (`remove()` or `removeOne()`), its value updated, and then re-added (`add()`) to ensure the queue maintains its heap property. The `replaceTop()` method can be used if the mutated element was the top element.","message":"Mutating objects that are already stored in the priority queue can lead to an inconsistent or incorrectly sorted queue state. The queue does not automatically detect external changes to element priorities and re-heapify. Operations like `peek()` and `poll()` will then return incorrect results.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Users relying on `kSmallest` functionality should upgrade to version `0.7.4` or newer to resolve this correctness issue and ensure accurate results.","message":"Versions of `fastpriorityqueue` prior to `0.7.4` contained a bug related to the `kSmallest` exponent calculation. This bug could lead to incorrect results when utilizing features that depend on finding the k-smallest elements within the queue.","severity":"breaking","affected_versions":"<0.7.4"},{"fix":"If precise removal of a specific object instance is required, use `removeOne(callback)` and provide a callback function that performs a strict identity check (e.g., `(item) => item === mySpecificObject`).","message":"The `remove(value)` method uses the queue's internal comparator function to locate elements. This means it may not perform a strict identity comparison (`===`) but rather a comparison based on the defined priority. If multiple elements in the queue are considered 'equal' by the comparator, `remove(value)` might remove an arbitrary one of them, not necessarily a specific object instance.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consider calling `pq.trim()` after periods of significant queue modification to reclaim unused memory and optimize the heap's underlying storage.","message":"After extensive `add()` and `poll()` operations (high churn), the underlying array used by the heap can accumulate unused memory slots. While not a functional error, failing to call `pq.trim()` periodically can lead to increased memory consumption, which might be critical in performance-sensitive or long-running applications.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Always instantiate the queue using `new FastPriorityQueue()`. For ESM/TypeScript, use `import FastPriorityQueue from 'fastpriorityqueue';`. For CommonJS, use `const FastPriorityQueue = require('fastpriorityqueue');`.","cause":"This error typically occurs when attempting to instantiate `FastPriorityQueue` without the `new` keyword, or when importing it incorrectly as a named export in an ESM/TypeScript environment.","error":"TypeError: FastPriorityQueue is not a constructor"},{"fix":"First, ensure the package is installed: `npm install fastpriorityqueue`. Then, verify your import/require statement matches your module system (e.g., `import FastPriorityQueue from 'fastpriorityqueue';` for ESM/TypeScript or `const FastPriorityQueue = require('fastpriorityqueue');` for CommonJS).","cause":"The `fastpriorityqueue` module was either not installed, not imported/required correctly, or the variable name `FastPriorityQueue` was misspelled after import.","error":"ReferenceError: FastPriorityQueue is not defined"},{"fix":"Review your comparator function to ensure it correctly defines the priority (e.g., `(a, b) => a > b` for a max-heap, `(a, b) => a < b` or default for a min-heap). If using objects, ensure they are not mutated after being added to the queue; if their priority changes, remove and re-add them.","cause":"This usually indicates an issue with the custom comparator function (if provided) or that elements within the queue have been mutated externally, altering their priority without the queue being updated.","error":"Elements are not sorted as expected / `peek()` returns an incorrect value."}],"ecosystem":"npm","meta_description":null}