🚑 🚴 🚌 🚕 🚗 🚚 🚛

A very fast JavaScript priority queue, implemented using a binary heap, which in turn is implemented using two underlying parallel typed arrays. No dependencies whatsoever; just plain, vanilla JS.

import {MinQueue} from "heapify";
// const {MinQueue} = require("heapify");  // alternatively, require() also works

const queue = new MinQueue();
queue.push(1, 10);
queue.push(2, 5);
queue.pop();  // 2
queue.peek();  // 1
queue.clear();
queue.pop();  // undefined

It's the fastest publicly available JavaScript library implementation of a priority queue. Here's a benchmark comparing Heapify to other popular libraries:

Generated from commit 97ff2c2 on 2026-03-04T11:46:43.158Z.

See the benchmark section for more details.

Heapify's design strives for reliability, with strong test coverage and a focus on code readability. It should be easy to understand what the library is doing. The library is also very lean, with no dependencies and a small, concise codebase.

Table of contents

• Features
• How to install
• How to import
• API
  • constructor
  • capacity
  • clear()
  • peek()
  • peekPriority()
  • pop()
  • push(key, priority)
  • size
• Benchmark
• Contributing

Features

Supported queue operations:

• push: O(log n)
• pop: O(log n) in the general case, O(1) if not preceded by a pop
• peek: O(1) in the general case, O(log n) if preceded by a pop
• peekPriority: O(1) in the general case, O(log n) if preceded by a pop
• creation with pre-existing list of priorities: O(n)

Other features:

• runs on the browser and Node.js with ES5 and ES6 support
• tiny code base (under 200 LoC)
• no runtime dependencies
• supports several types of priorities and keys

How to install

npm i heapify

Or if you're a yarn person:

yarn add heapify

How to import

Node.js

You can import it in your Node.js project using TypeScript:

import {MinQueue} from "heapify";

Or directly via native ES6 module support, using the mjs ES6 module bundle:

import {MinQueue} from "heapify/heapify.mjs";

Or just require() it in your good old CommonJS project:

const {MinQueue} = require("heapify");

Browser

If you're using npm/pnpm/yarn/etc with a traditional bundler (e.g.: vite), you can just import it as usual from your JS/TS file:

const {MinQueue} = require("heapify");

<script src="https://unpkg.com/heapify"></script>
<script>
  const {MinQueue} = Heapify;
</script>

<script type="importmap">
{
  "imports": {
    "heapify": "https://unpkg.com/heapify/heapify.mjs"
  }
}
</script>

<script type="module">
    import { MinQueue } from "heapify";

API

constructor(capacity = 64, keys = [], priorities = [], KeysBackingArrayType = Uint32Array, PrioritiesBackingArrayType = Uint32Array)

Creates a new priority queue. Parameters are:

• capacity: the size of the underlying typed arrays backing the heap;
• keys: an optional array of pre-existing keys. Provide [] to skip this field;
• priorities: an optional array of pre-existing priorities. Must match the number of keys above. Provide [] to skip this field;
• KeysBackingArrayType: the array type to be used for keys;
• PrioritiesBackingArrayType: the array type to be used for priorities.

Example:

const queue1 = new MinQueue(32);
const queue2 = new MinQueue(16, [], [], Uint16Array, Uint32Array);

capacity

A read-only property that returns the maximum capacity of the queue. Example:

const queue = new MinQueue(32);
queue.capacity;  // 32

clear()

Effectively empties the queue. The heap capacity is not changed, nor are its elements erased in any way; it's just the variable that tracks the length that gets cleared to zero, so it's a very cheap operation.

Example:

const queue = new MinQueue();
queue.push(1, 10);
console.info(queue.size);  // 1
queue.clear();
console.info(queue.size);  // 0

peek()

Gets the key with the smallest priority, but does not remove it from the queue.

Example:

const queue = new MinQueue();
queue.push(1, 10);
queue.peek();  // 1

peekPriority()

Gets the priority of the key with the smallest priority, but does not remove the item from the queue.

Example:

const queue = new MinQueue();
queue.push(1, 10);
queue.peekPriority();  // 10

pop()

Removes the smallest priority item from the queue, returning its key. Returns undefined if the queue is empty.

Note that Heapify's heap implementation is not stable. If multiple keys have the same priority, there are no guarantees about the order in which they will be popped.

Example:

const queue = new MinQueue();
queue.push(1, 10);
queue.pop();  // 1

push(key, priority)

Adds a new item to the queue with a given key and priority. Throws an error if the queue is already at its capacity.

Example:

const queue = new MinQueue();
queue.push(1, 10);
queue.size;  // 1
queue.peek();  // 1
queue.peekPriority();  // 10

size

A read-only property that returns the current size of the queue.

Example:

const queue = new MinQueue();
queue.size;  // 0
queue.push(1, 10);
queue.size;  // 1
queue.pop();
queue.size;  // 0

Benchmark

Times are measured in milliseconds.

Operations:

• build - build a queue from scratch by providing a collection of keys and priorities, all at once;
• push - insert a single element into the queue;
• pop - remove a single element from the queue;
• push/pop batch - performs batches of 1k pushes followed by 1k pops;
• push/pop interleaved - starting with a partially filled queue, this test inserts a random element and then immediately removes the lowest priority value from the queue;
• push/pop random - starting with a partially filled queue, this test runs either a push or a pop at random.

Each test performs 1 million operations and is repeated 5 times. The median value is used as the result.

Tested libraries:

• Google Closure library - a hugely popular library, but it is the worst implementation with respect to performance;
• Fast Priority Queue - runs comparably fast, but doesn't support inserting keys either, so its implementation significantly limits what the user is able to achieve with it;
• FlatQueue and TinyQueue - two very nice queue implementations by Vladimir Agafonkin. They don't support the build method and that's why they're missing this benchmark. FlatQueue performs quite well for an implementation that is not based on typed arrays.

Contributing

You are welcome to contribute, but please take the time to read and follow these guidelines.