TinyQueue: Smallest JavaScript Priority Queue

Common errors

• TypeError: require is not a function

  cause Attempting to import `tinyqueue` using CommonJS `require()` syntax (e.g., `const TinyQueue = require('tinyqueue');`) in an ES module context or Node.js environment configured for ES modules (e.g., `"type": "module"` in package.json) since v3.0.0.
  fix Change the import statement to `import TinyQueue from 'tinyqueue';`. Ensure your project's `package.json` correctly specifies `"type": "module"` if you are using Node.js ES modules, or adjust your build system accordingly.

• Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './tinyqueue.min.js' is not defined by 'exports' in .../node_modules/tinyqueue/package.json

  cause Attempting to directly reference UMD or CJS browser bundles, which were removed in v3.0.0. This error typically occurs when trying to load the library directly in a browser via a script tag referencing a local file or an outdated CDN path.
  fix For browser usage without a build system, use a modern CDN that provides ES module builds (e.g., `https://cdn.jsdelivr.net/npm/tinyqueue@3/tinyqueue.mjs`). If using a build system, import `tinyqueue` as an ES module and let your bundler handle it.

Warnings

• breaking Version 3.0.0 removed CommonJS and UMD distribution support. The package is now exclusively published as an ES module.
  Fix: Migrate your project to use ES module imports (e.g., `import TinyQueue from 'tinyqueue';`). Ensure your Node.js environment or build tool supports ES modules. For browser usage without a build step, load via a CDN that provides ESM compatibility or bundle it with a tool like Rollup/Webpack.
• gotcha For use cases strictly involving numerical priority queues where extreme performance is critical, the `flatqueue` library (from the same author) offers a potentially faster, specialized alternative.
  Fix: Evaluate `flatqueue` if `tinyqueue`'s general-purpose binary heap performance does not meet specific, high-frequency numerical processing requirements.
• gotcha When initializing a `TinyQueue` from an existing array, the input array is mutated (rearranged internally) by the queue's constructor to create the heap. This means the original array reference will point to a modified array.
  Fix: If you need to preserve the original array, pass a shallow copy to the constructor: `new TinyQueue([...myArray], comparator)`.

Install

• npm install tinyqueue npm
• yarn add tinyqueue yarn
• pnpm add tinyqueue pnpm

Imports

• TinyQueue
  wrong:

  const TinyQueue = require('tinyqueue');

  correct:

  import TinyQueue from 'tinyqueue';

  Since v3.0.0, tinyqueue is published exclusively as an ES module. CommonJS `require()` is no longer supported and will result in an error in modern Node.js environments. TypeScript types are bundled and automatically available for this default export.

Quickstart

Demonstrates how to initialize a TinyQueue, add elements, retrieve the highest priority item, inspect the queue's length, and use custom comparators for complex objects, including how to turn a queue into a sorted array.

import TinyQueue from 'tinyqueue';

// Create an empty priority queue
const queue = new TinyQueue();

// Add some items
queue.push(7);
queue.push(5);
queue.push(10);

console.log('Initial top item:', queue.peek()); // Expected: 5

// Remove the top item
const top = queue.pop(); // Returns 5
console.log('Popped item:', top);
console.log('Current top item:', queue.peek()); // Expected: 7
console.log('Queue length:', queue.length); // Expected: 2

// Create a priority queue from an existing array
const initialArrayQueue = new TinyQueue([7, 5, 10]);
console.log('Queue from array, top:', initialArrayQueue.peek()); // Expected: 5

// Pass a custom item comparator for objects
const customQueue = new TinyQueue([{value: 5}, {value: 7}, {value: 3}], function (a, b) {
    return a.value - b.value;
});
console.log('Custom queue top item value:', customQueue.peek().value); // Expected: 3

// Turn a queue into a sorted array by repeatedly popping
const sortedArray = [];
while (customQueue.length) {
    sortedArray.push(customQueue.pop().value);
}
console.log('Sorted array from queue:', sortedArray); // Expected: [3, 5, 7]