{"id":13465124,"url":"https://github.com/luciopaiva/heapify","last_synced_at":"2025-05-16T05:02:33.945Z","repository":{"id":39793591,"uuid":"239196544","full_name":"luciopaiva/heapify","owner":"luciopaiva","description":"The fastest JavaScript priority queue out there. Zero dependencies.","archived":false,"fork":false,"pushed_at":"2023-03-14T18:50:09.000Z","size":996,"stargazers_count":721,"open_issues_count":13,"forks_count":21,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-11T21:43:48.748Z","etag":null,"topics":["binary-heap","data-structures","heap","heapify","javascript","javascript-library","priority-queue","queue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luciopaiva.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"patreon":"luciopaiva"}},"created_at":"2020-02-08T20:01:16.000Z","updated_at":"2025-02-20T09:16:57.000Z","dependencies_parsed_at":"2024-02-04T13:05:07.829Z","dependency_job_id":"e4a92e98-bf56-410d-ac21-bc50b33aad63","html_url":"https://github.com/luciopaiva/heapify","commit_stats":{"total_commits":172,"total_committers":6,"mean_commits":"28.666666666666668","dds":"0.13953488372093026","last_synced_commit":"db2a07a2354a46992751865887d6bc8272b3f8dc"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciopaiva%2Fheapify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciopaiva%2Fheapify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciopaiva%2Fheapify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luciopaiva%2Fheapify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luciopaiva","download_url":"https://codeload.github.com/luciopaiva/heapify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471028,"owners_count":22076582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-heap","data-structures","heap","heapify","javascript","javascript-library","priority-queue","queue"],"created_at":"2024-07-31T14:01:00.266Z","updated_at":"2025-05-16T05:02:33.921Z","avatar_url":"https://github.com/luciopaiva.png","language":"TypeScript","funding_links":["https://patreon.com/luciopaiva"],"categories":["TypeScript","JavaScript","Packages"],"sub_categories":["Others"],"readme":"\n![Heapify](https://raw.githubusercontent.com/luciopaiva/heapify/master/logo.png)\n\n[![codecov](https://img.shields.io/codecov/c/github/luciopaiva/heapify)](https://codecov.io/gh/luciopaiva/heapify)\n[![travis](https://api.travis-ci.com/luciopaiva/heapify.svg?branch=master)](https://travis-ci.com/luciopaiva/heapify) \n[![version](https://img.shields.io/npm/v/heapify?color=brightgreen\u0026label=version)](https://www.npmjs.com/package/heapify)\n\n🚑 🚴 🚌 🚕 🚗 🚚 🚛\n\nA very fast JavaScript priority queue, implemented using a binary heap, which in turn is implemented using two underlying parallel [typed arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray). No dependencies whatsoever; just plain, vanilla JS.\n\n```js\nimport {MinQueue} from \"heapify\";\n// const {MinQueue} = require(\"heapify\");  // alternatively, require() also works\n\nconst queue = new MinQueue();\nqueue.push(1, 10);\nqueue.push(2, 5);\nqueue.pop();  // 2\nqueue.peek();  // 1\nqueue.clear();\nqueue.pop();  // undefined\n```\n\nIt's the fastest publicly available JavaScript library implementation of a priority queue. Here's a benchmark comparing Heapify to other popular libraries:\n\n| Operation            | Closure | FlatQueue | TinyQueue | Heapify |\n|----------------------|---------|-----------|-----------|---------|\n| build                | 201     | n/a       | n/a       | 18      |\n| push                 | 222     | 66        | 75        | 24      |\n| pop                  | 496     | 137       | 917       | 110     |\n| push/pop batch       | 279     | 83        | 280       | 89      |\n| push/pop interleaved | 315     | 50        | 265       | 34      |\n| push/pop random      | 186     | 50        | 257       | 48      |\n\nSee the [benchmark](#benchmark) section for more details.\n\nHeapify's design strives for reliability, with strong test coverage and 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 and concise source code. \n\n# Table of contents\n\n- [Features](#features)\n- [How to install](#how-to-install)\n- [How to import](#how-to-import)\n- [API](#api)\n  - [constructor](#constructorcapacity--64-keys---priorities---keysbackingarraytype--uint32array-prioritiesbackingarraytype--uint32array)\n  - [capacity](#capacity)\n  - [clear()](#clear)\n  - [peek()](#peek)\n  - [peekPriority()](#peekpriority)\n  - [pop()](#pop)\n  - [push(key, priority)](#pushkey-priority)\n  - [size](#size)\n- [Benchmark](#benchmark)\n- [Contributing](#contributing)\n\n## Features\n\nSupported queue operations:\n\n- push: O(log n)\n- pop: O(log n) in the general case, O(1) if not preceded by a pop\n- peek: O(1) in the general case, O(log n) if preceded by a pop\n- peekPriority: O(1) in the general case, O(log n) if preceded by a pop\n- creation with pre-existing list of priorities: O(n)\n\nOther features:\n\n- runs on browser and Node.js with ES5 and ES6 support\n- tiny code base (under 200 LoC)\n- no runtime dependencies\n- supports several types of priorities and keys\n\n## How to install\n\n```sh\nnpm i heapify\n```\n\nOr if you're a yarn person:\n\n```sh\nyarn add heapify\n```\n\n## How to import\n\n### Node.js\n\nYou can `import` it in your Node.js project using TypeScript:\n\n```js\nimport {MinQueue} from \"heapify\";\n```\n\nOr directly via [native ES6 module support](https://nodejs.org/api/esm.html), using the `mjs` ES6 module bundle:\n\n```js\nimport {MinQueue} from \"heapify/heapify.mjs\";\n```\n\nOr just `require()` it in your good old CommonJS project:\n\n```js\nconst {MinQueue} = require(\"heapify\");\n```\n\n### Browser\n\nHeapify can be included via regular script tags, where `Heapify` will be exposed globally:\n\n```html\n\u003cscript src=\"https://unpkg.com/heapify\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const {MinQueue} = Heapify;\n\u003c/script\u003e\n```\n\nThe example above uses [unpkg](https://unpkg.com), but you can of course reference a local copy installed either manually or via npm/yarn.\n\nFor projects using native ES6 modules, make sure to import the `mjs` ES6 module bundle instead:\n\n```js\nimport {MinQueue} from \"https://unpkg.com/heapify/heapify.mjs\"\n```\n\n## API\n\n### constructor(capacity = 64, keys = [], priorities = [], KeysBackingArrayType = Uint32Array, PrioritiesBackingArrayType = Uint32Array)\n\nCreates a new priority queue. Parameters are:\n\n- `capacity`: the size of the underlying typed arrays backing the heap;\n- `keys`: an optional array of pre-existing keys. Provide `[]` to skip this field;\n- `priorities`: an optional array of pre-existing priorities. Must match number of keys above. Provide `[]` to skip this field;\n- `KeysBackingArrayType`: the array type to be used for keys;\n- `PrioritiesBackingArrayType`: the array type to be used for priorities.\n\nExample:\n\n```js\nconst queue1 = new MinQueue(32);\nconst queue2 = new MinQueue(16, [], [], Uint16Array, Uint32Array);\n```\n\n### capacity\n\nA read-only property that returns the maximum capacity of the queue. Example:\n\n```js\nconst queue = new MinQueue(32);\nqueue.capacity;  // 32\n```\n\n### clear()\n\nEffectively empties the queue. The heap capacity is not changed, nor its elements get 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.\n\nExample:\n\n```js\nconst queue = new MinQueue();\nqueue.push(1, 10);\nconsole.info(queue.size);  // 1\nqueue.clear();\nconsole.info(queue.size);  // 0\n```\n\n### peek()\n\nGets the key with the smallest priority, but does not remove it from the queue.\n\nExample:\n\n```js\nconst queue = new MinQueue();\nqueue.push(1, 10);\nqueue.peek();  // 1\n```\n\n### peekPriority()\n\nGets the _priority_ of the key with the smallest priority, but does not remove the item from the queue.\n\nExample:\n\n```js\nconst queue = new MinQueue();\nqueue.push(1, 10);\nqueue.peekPriority();  // 10\n```\n\n### pop()\n\nRemoves the smallest priority item from the queue, returning its key. Returns `undefined` if the queue is empty.\n\nNote that Heapify's heap implementation is not [stable](https://ece.uwaterloo.ca/~dwharder/aads/Projects/4/Stable_binary_heap/#:~:text=A%20heap%20is%20said%20to,were%20placed%20into%20the%20heap.). If multiple keys have the same priority, there are no guarantees about the order in which they will be popped.\n\nExample:\n\n```js\nconst queue = new MinQueue();\nqueue.push(1, 10);\nqueue.pop();  // 1\n```\n\n### push(key, priority)\n\nAdds a new item to the queue with a given `key` and `priority`. Will throw an error if the queue is already at its capacity.\n\nExample:\n\n```js\nconst queue = new MinQueue();\nqueue.push(1, 10);\nqueue.size;  // 1\nqueue.peek();  // 1\nqueue.peekPriority();  // 10\n```\n\n### size\n\nA read-only property that returns the current size of the queue.\n\nExample:\n\n```js\nconst queue = new MinQueue();\nqueue.size;  // 0\nqueue.push(1, 10);\nqueue.size;  // 1\nqueue.pop();\nqueue.size;  // 0\n```\n\n## Benchmark\n\nHere's a table comparing Heapify with other implementations (times are in milliseconds):\n\n```\n                             Closure     FastPQ  FlatQueue  TinyQueue    Heapify\nbuild                            201         15          -          -         18\npush                             222         47         66         75         24\npop                              496        143        137        917        110\npush/pop batch                   279        128         83        280         89\npush/pop interleaved             315         65         50        265         34\npush/pop random                  186         45         50        257         48\n```\n\nHost machine: Node.js 13.8.0, 2.6 GHz 6-Core Intel Core i7, 32 GB 2400 MHz DDR4 RAM.\n\nOperations:\n- build - build queue from scratch by providing a collection of keys and priorities, all at once;\n- push - insert a single element into the queue;\n- pop - remove a single element from the queue;\n- push/pop batch - performs batches of 1k pushes followed by 1k pops;\n- 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;\n- push/pop random - starting with a partially filled queue, this test runs either a push or a pop at random.\n\nEach test performs 1 million operations and is repeated 5 times. The median value is used as the result.\n\nTested libraries:\n\n- [Google Closure library](https://github.com/google/closure-library/blob/master/closure/goog/structs/heap.js) - a hugely popular library, but is the worst implementation with respect to performance;\n- [Fast Priority Queue](https://github.com/lemire/FastPriorityQueue.js) - runs comparably fast, but doesn't support inserting keys as well, so its implementation significantly limits what the user is able to achieve with it;\n- [FlatQueue](https://github.com/mourner/flatqueue) and [TinyQueue](https://github.com/mourner/flatqueue) - 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 considerably well for an implementation that is not based on typed arrays.\n\n## Contributing\n\nYou are welcome to contribute, but please take the time to read and follow [these guidelines](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluciopaiva%2Fheapify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluciopaiva%2Fheapify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluciopaiva%2Fheapify/lists"}