mourner / flatqueue

A very fast and simple JavaScript priority queue

flatqueue

A very fast and tiny binary heap priority queue in JavaScript.

Similar to tinyqueue, but stores the queue as two flat arrays of items and their numeric priority values respectively (without a way to specify a comparator function). This makes the queue more limited, but several times faster.

Usage

const q = new FlatQueue();

for (let i = 0; i < items.length; i++) {
    // Push an item index and its priority value. You can push other values as well,
    // but storing only integers is much faster due to JavaScript engine optimizations.
    q.push(i, items[i].priority);
}

q.peekValue(); // Read the top item's priority value
q.peek(); // Read the top item
q.pop(); // Remove and return the top item

Install

Install with npm install flatqueue, then use as a module:

import FlatQueue from 'flatqueue';

Alternatively, use as a module in a browser directly:

<script type="module">
    import FlatQueue from 'https://cdn.jsdelivr.net/npm/flatqueue/+esm';

There's also a UMD bundle that exposes a global FlatQueue global variable:

<script src="https://cdn.jsdelivr.net/npm/flatqueue"></script>

API

new FlatQueue()

Creates an empty queue object with the following methods and properties:

push(item, priority)

Adds item to the queue with the specified priority.

priority must be a number. Items are sorted and returned from low to high priority. Multiple items with the same priority value can be added to the queue, but the queue is not stable (items with the same priority are not guaranteed to be popped in iteration order).

pop()

Removes and returns the item from the head of this queue, which is one of the items with the lowest priority. If this queue is empty, returns undefined.

peek()

Returns the item from the head of this queue without removing it. If this queue is empty, returns undefined.

peekValue()

Returns the priority value of the item at the head of this queue without removing it. If this queue is empty, returns undefined.

clear()

Removes all items from the queue.

shrink()

Shrinks the internal arrays to this.length.

pop() and clear() calls don't free memory automatically to avoid unnecessary resize operations. This also means that items that have been added to the queue can't be garbage collected until a new item is pushed in their place, or this method is called.

length

Number of items in the queue. Read-only.

ids

An underlying array of items. Note that it can be bigger than the length as it's not eagerly cleared.

values

An underlying array of priority values. Note that it can be bigger than the length as it's not eagerly cleared.

Using typed arrays

If you know the maximum queue size beforehand, you can override the queue to use typed arrays for better performance and memory footprint. This makes it match the performance of the popular heapify library.

const q = new FlatQueue();
q.ids = new Uint16Array(32);
q.values = new Uint32Array(32);

flatqueue's Issues

Improve documentation and naming of arguments

I tried using FlatQueue but accidentally mixed up id and value parameters.

I was under the impression that id would be some order-index, whereas value would be the actual data associated with that element. However, in reality it's the other way around.
The naming of the id parameter is what led to this confusion.

Before I understood the issue, I even wrote a wrapper because I wanted to pop the data associated with the element (instead of the order-index), because I thought FlatQueue only allowed popping the order-index.
The naming of the peek() / peekValue() functions made my confusion worse.

Even when I understood this, it also wasn't clear to me wether the order-index (value parameter) had to be an integer, or wether it could also be a rational number. It was also unclear wether the order-index could be negative.
And lastly, it also wasn't clear what happens if the same order-index is used multiple times.

It's also not clear how people should check for items in the queue: while(flatqueue.length > 0) or while(flatqueue.peekValue() !== undefined); for API stability, this should probably be documented.

Add support for updating priority of entry

Since I'm trying to implement Dijkstra's algorithm, I want to be able to update the priority of an already existing entry in the queue.

Add support for Node.js require

Add support for being able to use require instead of import.

This is useful when working with Node.js and you for some reason can't use ES modules

Shrink internal arrays

Currently, once a FlatQueue was filled, it will use a considerable amount of memory, even when the queue is less full (even after a clear).

That happens because the FlatQueue itself will only use this.length to track the size of the queue, but the ids and values arrays will never be shrunk again (to match the current this.length).

There should be a way to trigger a cleanup of the queue, or it should clean up after itself using some heuristic.

Typescript not happy with the advice from README

Trying to take this advice in the README: https://github.com/mourner/flatqueue#using-typed-arrays

But Typescript is not happy:

I am using flatqueue v2.0.3.

What am I doing wrong here?

Publish version with typescript types to npm

It's great that there are TypeScript types, but they currently don't exist in the npm version. Could a new version including them be pushed?

Popped items can't be garbage collected

Hi!
I noticed that you only reduce this.length in pop() and clear(), but don't actually update ids. That means if I store large objects (e.g. DOM nodes) in the queue, they might not get garbage collected even if my code has no other references to them.
I don't know what the performance impact would be to always shrink ids. In any case, it should be safe to assign undefined to the unused indexes.