{"id":28265054,"url":"https://github.com/andrewvo89/use-priority-queue","last_synced_at":"2026-02-16T06:34:43.308Z","repository":{"id":284475089,"uuid":"955079860","full_name":"andrewvo89/use-priority-queue","owner":"andrewvo89","description":"Use Priority Queue is a React hook that provides a simple and efficient way to manage a priority queue in your React applications. It uses a binary heap under the hood with values stored inside a JavaScript array.","archived":false,"fork":false,"pushed_at":"2026-01-29T23:03:58.000Z","size":89,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-30T02:40:54.448Z","etag":null,"topics":["data-structures","hook","priority-queue","react","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/use-priority-queue","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/andrewvo89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-26T04:32:56.000Z","updated_at":"2026-01-29T23:04:01.000Z","dependencies_parsed_at":"2025-03-26T04:36:32.775Z","dependency_job_id":"8c1b9bde-4fed-4708-9623-9a10886ba21a","html_url":"https://github.com/andrewvo89/use-priority-queue","commit_stats":null,"previous_names":["andrewvo89/use-priority-queue"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/andrewvo89/use-priority-queue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fuse-priority-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fuse-priority-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fuse-priority-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fuse-priority-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewvo89","download_url":"https://codeload.github.com/andrewvo89/use-priority-queue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fuse-priority-queue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29501918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T05:57:17.024Z","status":"ssl_error","status_checked_at":"2026-02-16T05:56:49.929Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["data-structures","hook","priority-queue","react","typescript"],"created_at":"2025-05-20T10:13:08.015Z","updated_at":"2026-02-16T06:34:43.303Z","avatar_url":"https://github.com/andrewvo89.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n[![Status](https://img.shields.io/badge/status-active-blue)](https://github.com/andrewvo89/use-priority-queue)\n[![GitHub Issues](https://img.shields.io/github/issues/andrewvo89/use-priority-queue?color=blue)](https://github.com/andrewvo89/use-priority-queue/issues)\n[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/andrewvo89/use-priority-queue?color=blue)](https://github.com/andrewvo89/use-priority-queue/pulls)\n[![License](https://img.shields.io/github/license/andrewvo89/use-priority-queue?color=blue)](/LICENSE)\n\n\u003c/div\u003e\n\n# Use Priority Queue\n\n## Table of contents\n\n- [About](#about)\n- [Complexity](#complexity)\n- [Installation](#installation)\n- [Basic usage](#basic-usage)\n- [Comparators](#comparators)\n- [PriorityQueue class](#priorityqueue-class)\n- [License](#license)\n\n## About\n\nUse Priority Queue is a React hook that provides a simple and efficient way to manage a priority queue in your React applications. It uses a binary heap under the hood, with values stored inside a JavaScript array.\n\n## Complexity\n\n| Operation   | Time Complexity | Space Complexity |\n| ----------- | --------------- | ---------------- |\n| Enqueue     | O(log n)        | O(1)             |\n| Deqeue      | O(log n)        | O(1)             |\n| Next (Peek) | O(1)            | O(1)             |\n| Size        | O(1)            | O(1)             |\n\n## Installation\n\nInstall the package as a dependency on your project by running:\n\n```bash\nnpm install use-priority-queue\n```\n\n```bash\nyarn add use-priority-queue\n```\n\n```bash\npnpm add use-priority-queue\n```\n\n## Live demo\n\nAn interactive example can be found on [CodeSandbox](https://codesandbox.io/p/sandbox/7m8gjk).\n\n## Basic usage\n\n```tsx\nimport { useState } from 'react';\nimport { usePriorityQueue } from 'use-priority-queue';\n\ntype WeatherCondition = 'windy 🍃' | 'thunderstorm ⛈️' | 'tornado 🌪️' | 'hurricane 🌀' | 'tsunami 🌊';\n\ntype Priority = number;\n\nconst initWeatherConditions: [WeatherCondition, Priority][] = [\n  ['hurricane 🌀', 2],\n  ['tsunami 🌊', 1],\n  ['tornado 🌪️', 3],\n  ['windy 🍃', 5],\n  ['thunderstorm ⛈️', 4],\n];\n\nexport default function App() {\n  const { next, size, enqueue, dequeue } = usePriorityQueue\u003cWeatherCondition\u003e();\n  const [weatherConditions, setWeatherConditions] = useState(initWeatherConditions);\n  const [added, setAdded] = useState\u003cWeatherCondition[]\u003e([]);\n  const [removed, setRemoved] = useState\u003cWeatherCondition[]\u003e([]);\n  const nextWeatherCondition = weatherConditions.at(-1);\n\n  const onAddWeatherCondition = () =\u003e {\n    if (!nextWeatherCondition) {\n      return;\n    }\n    const [weatherCondition, priority] = nextWeatherCondition;\n    enqueue(weatherCondition, priority);\n    setWeatherConditions(weatherConditions.slice(0, -1));\n    setAdded((prev) =\u003e [...prev, weatherCondition]);\n  };\n\n  const onRemoveWeatherCondition = () =\u003e {\n    const removedWeather = dequeue();\n    if (removedWeather) {\n      setRemoved((prev) =\u003e [...prev, removedWeather]);\n      setAdded((prev) =\u003e prev.filter((weather) =\u003e weather !== removedWeather));\n    }\n  };\n\n  const emptyQueue = () =\u003e {\n    while (dequeue() !== undefined) {\n      // dequeue until empty\n    }\n  };\n\n  const onResetApp = () =\u003e {\n    emptyQueue();\n    setRemoved([]);\n    setAdded([]);\n    setWeatherConditions(initWeatherConditions);\n  };\n\n  return (\n    \u003cdiv className='container'\u003e\n      \u003ch1\u003eWeather Queue\u003c/h1\u003e\n      \u003cp\u003e{`Queue size: ${size}`}\u003c/p\u003e\n      \u003cbutton disabled={!nextWeatherCondition} onClick={onAddWeatherCondition}\u003e\n        Add weather condition to queue\n      \u003c/button\u003e\n      \u003cp\u003eAdded to queue: {added.join(' › ')}\u003c/p\u003e\n      \u003cp\u003eNext most severe in queue: {next}\u003c/p\u003e\n      \u003cbutton disabled={weatherConditions.length \u003e 0 || !next} onClick={onRemoveWeatherCondition}\u003e\n        Remove most severe from queue\n      \u003c/button\u003e\n      \u003cp\u003eRemoved from queue: {removed.join(' › ')}\u003c/p\u003e\n      \u003cbutton onClick={onResetApp}\u003eReset\u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## Comparators\n\nBy default `usePriorityQueue()` uses a min binary heap (lower priority numbers are prioritized first) to determine the priority of its nodes. The `usePriorityQueue()` hook can accept a custom comparator of the following signature:\n\n```ts\ntype Comparator\u003cT\u003e = (a: Node\u003cT\u003e, b: Node\u003cT\u003e) =\u003e number;\n```\n\n| Comparator(a, b) return value | Sort order                                       |\n| ----------------------------- | ------------------------------------------------ |\n| \u003e 0                           | `b` as a higher priority than `a`, e.g. `[b, a]` |\n| \u003c 0                           | `a` as a higher priority than `b`, e.g. `[a, b]` |\n| === 0                         | `a` and `b` are equal priority                   |\n\nBy default, the comparator is set to `minHeapComparator()`:\n\n```ts\nimport { minHeapComparator, usePriorityQueue } from 'use-priority-queue';\n\n// minHeapComparator by default\nconst { next, enqueue, dequeue } = usePriorityQueue();\n\n// minHeapComparator explicitely\nconst { next, enqueue, dequeue } = usePriorityQueue(minHeapComparator);\n```\n\n`maxHeapComparator()` is a utility provided for max binary heaps (higher priority numbers are prioritized first):\n\n```ts\nimport { maxHeapComparator, usePriorityQueue } from 'use-priority-queue';\n// maxHeapComparator\nconst { next, enqueue, dequeue } = usePriorityQueue(maxHeapComparator);\n```\n\nYou are welcome to supply your custom comparator to the `usePriorityQueue()` hook. A custom comparator can completely ignore `a.priority` and `b.priority` and use `a.value` and `b.value` instead. For example, if you want to sort blog posts by timestamp, you can do the following:\n\n```ts\nimport { usePriorityQueue } from 'use-priority-queue';\n\ntype BlogPost = {\n  title: string;\n  timestamp: Date;\n};\n\nconst { next, enqueue, dequeue } = usePriorityQueue\u003cBlogPost\u003e((a, b) =\u003e {\n  if (a.value.timestamp \u003e b.value.timestamp) {\n    return 1;\n  }\n  if (a.value.timestamp \u003c b.value.timestamp) {\n    return -1;\n  }\n  return 0;\n});\n```\n\n## PriorityQueue class\n\nThe `usePriorityQueue()` hook is a wrapper around the `PriorityQueue` class. You can use the `PriorityQueue` class directly to manage the queue outside a React component. The `PriorityQueue` class has the same API as the `usePriorityQueue()` hook, but it does not have the React-specific features like reactivity every time a node is added or removed.\n\n```ts\nimport { PriorityQueue } from 'use-priority-queue';\n\ntype WeatherCondition = 'windy 🍃' | 'thunderstorm ⛈️' | 'tornado 🌪️' | 'hurricane 🌀' | 'tsunami 🌊';\n\nconst queue = new PriorityQueue\u003cWeatherCondition\u003e();\nqueue.enqueue('windy 🍃', 5);\nqueue.enqueue('thunderstorm ⛈️', 4);\nqueue.enqueue('tornado 🌪️', 3);\nqueue.enqueue('hurricane 🌀', 2);\nqueue.enqueue('tsunami 🌊', 1);\nconst nextWeather = queue.next;\nconsole.log(`Next weather condition: ${nextWeather}`);\n// Next weather condition: tsunami 🌊\nconst removedWeather = queue.dequeue();\nconsole.log(`Removed weather condition: ${removedWeather}`);\n// Removed weather condition: tsunami 🌊\nconst queueSize = queue.size;\nconsole.log(`Queue size: ${queueSize}`);\n// Queue size: 4\n```\n\n## License\n\nUse Priority Queue is distributed under MIT license, Copyright (c) 2025 Andrew Vo-Nguyen. See [LICENSE](LICENSE) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewvo89%2Fuse-priority-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewvo89%2Fuse-priority-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewvo89%2Fuse-priority-queue/lists"}