{"_id":"d-ary-heap","_rev":"7-d63c26576976ae8bad8a9d30108bf18b","name":"d-ary-heap","dist-tags":{"latest":"2.7.0"},"versions":{"2.1.1":{"name":"d-ary-heap","version":"2.1.1","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","_id":"d-ary-heap@2.1.1","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"dist":{"shasum":"38d4f45cbd05463bb477f685409c2f949fac3f02","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.1.1.tgz","fileCount":11,"integrity":"sha512-q+f8AqOxdjz8DM8rlKwzGfEl0Hfm9FbXPN8/q6X5w9i5wkeL6KnIaLEr0xiWpZYtmhTdbD94prvy7/f7fCQwGw==","signatures":[{"sig":"MEQCICXjevuBrWBfEQ8vZxf6vBKIQYENsPZcDO+3HNfVYs0IAiAyfn5HsZyrqzAlD5dGrWqJUMmshPcocEHbsPV/jK+/Dw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":149557},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"dcc96e5eaec49fbb470eae24b8e9430c038d010d","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"pcfvw","email":"ejacopin@ymail.com"},"repository":{"url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git","type":"git"},"_npmVersion":"11.6.2","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.2","vitest":"^1.0.0","@eslint/js":"^9.39.2","typescript":"^5.3.0","@types/node":"^20.10.0","@typescript-eslint/parser":"^8.50.0","@typescript-eslint/eslint-plugin":"^8.50.0"},"_npmOperationalInternal":{"tmp":"tmp/d-ary-heap_2.1.1_1766489642658_0.2987445766427623","host":"s3://npm-registry-packages-npm-production"}},"2.1.2":{"name":"d-ary-heap","version":"2.1.2","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","_id":"d-ary-heap@2.1.2","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"dist":{"shasum":"b0c341e971791823f936d35912424b0858487a89","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.1.2.tgz","fileCount":11,"integrity":"sha512-F6khByEoLas1GJ3eHejRFDJ8g6yCNE70fG4tUxhcVMzupYMtTwzpGGe/YY7BnmBtU+If67g1Mpquw3b/zhpN8Q==","signatures":[{"sig":"MEQCIAnqrzcnWTUy89aAHFpkoOPUsmiBQNnKCfGDGF5geYKuAiAyp5ycgSWzFZ33Pg2NBHrM6MOLCxtUWNfj9d92z1PApg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":150601},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"dcc96e5eaec49fbb470eae24b8e9430c038d010d","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"pcfvw","email":"ejacopin@ymail.com"},"repository":{"url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git","type":"git"},"_npmVersion":"11.6.2","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.2","vitest":"^1.0.0","@eslint/js":"^9.39.2","typescript":"^5.3.0","@types/node":"^20.10.0","@typescript-eslint/parser":"^8.50.0","@typescript-eslint/eslint-plugin":"^8.50.0"},"_npmOperationalInternal":{"tmp":"tmp/d-ary-heap_2.1.2_1766687490481_0.6163777828481702","host":"s3://npm-registry-packages-npm-production"}},"2.2.0":{"name":"d-ary-heap","version":"2.2.0","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","_id":"d-ary-heap@2.2.0","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"dist":{"shasum":"98bcb1e6fbd2b278aa62296b00a6e9f6840c570f","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.2.0.tgz","fileCount":11,"integrity":"sha512-4JtL+Orm29RquGIY/xNJFVVYOD8MiKO2Xx9ZSLXqeAcRW7SADPWSs6TMgy6085dCMO9vy1vaWCJeXkXjuhJB3Q==","signatures":[{"sig":"MEUCIAoLJDxKOULT5rl22GrKfL35b0Y35qnbi+bHCIF/vQZ6AiEAuwoXizCUPm1VHsqE18D0g6sIthlTdnSCyDdep6j2jG8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":150601},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"da04d705bf266788fca194b1eb4968de6f99702e","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"pcfvw","email":"ejacopin@ymail.com"},"repository":{"url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git","type":"git"},"_npmVersion":"11.6.2","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.2","vitest":"^1.0.0","@eslint/js":"^9.39.2","typescript":"^5.3.0","@types/node":"^20.10.0","@typescript-eslint/parser":"^8.50.0","@typescript-eslint/eslint-plugin":"^8.50.0"},"_npmOperationalInternal":{"tmp":"tmp/d-ary-heap_2.2.0_1766766870366_0.12322730803368742","host":"s3://npm-registry-packages-npm-production"}},"2.4.0":{"name":"d-ary-heap","version":"2.4.0","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","_id":"d-ary-heap@2.4.0","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"dist":{"shasum":"9d44f52748ede6bafa1515fb4ffcf35ec1a93da6","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.4.0.tgz","fileCount":12,"integrity":"sha512-5cWLXBLyyCBIfIMYl902ua77RByj68SSJRAsQUqyX4OR1ZibaB+MQphboJIYoUgt3QuLZydJXCfpNr0iUO7nRA==","signatures":[{"sig":"MEYCIQDqvzCaZhWfPiSQEM58EmXPMEOJsKi77oZsRn0PCMa93AIhAM47JMeNmlhmKid7kC54hPp5UwLV7GFclPMcsUdsi1Vo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":227164},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"d138c9efddd6785af09689940fde523833a7a64e","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"pcfvw","email":"ejacopin@ymail.com"},"repository":{"url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git","type":"git"},"_npmVersion":"11.6.2","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.2","vitest":"^1.0.0","@eslint/js":"^9.39.2","typescript":"^5.3.0","@types/node":"^20.10.0","@typescript-eslint/parser":"^8.50.0","@typescript-eslint/eslint-plugin":"^8.50.0"},"_npmOperationalInternal":{"tmp":"tmp/d-ary-heap_2.4.0_1767799973750_0.5590234819651874","host":"s3://npm-registry-packages-npm-production"}},"2.5.0":{"name":"d-ary-heap","version":"2.5.0","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","_id":"d-ary-heap@2.5.0","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"dist":{"shasum":"71b67f28588c46848c0db620e927c0cdc618ca4e","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.5.0.tgz","fileCount":12,"integrity":"sha512-lywb/4XUvuxPkktw2eSBgjCAiVOPtHuzOiwPShQ/beU9bnumboKtBxu1NHuDZUyQ3U3GiOY05WeULZu+1DvxTA==","signatures":[{"sig":"MEUCIGQToqjsqSRqYNVjEgmF5xsIMSK9zC3Ky2/I1KNVm70nAiEA/RmV96XXYMa0OWJZe7W8q7S2+HE6P04gQvfeGVzqGOc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":252424},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"411c9614aa1690acc23933bf43ed8078619e3d42","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"pcfvw","email":"ejacopin@ymail.com"},"repository":{"url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git","type":"git"},"_npmVersion":"11.6.2","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.2","vitest":"^1.0.0","@eslint/js":"^9.39.2","typescript":"^5.3.0","@types/node":"^20.10.0","typescript-eslint":"^8.53.0","@typescript-eslint/parser":"^8.50.0","@typescript-eslint/eslint-plugin":"^8.50.0"},"_npmOperationalInternal":{"tmp":"tmp/d-ary-heap_2.5.0_1769423026443_0.658371334210015","host":"s3://npm-registry-packages-npm-production"}},"2.6.0":{"name":"d-ary-heap","version":"2.6.0","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","_id":"d-ary-heap@2.6.0","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"dist":{"shasum":"0853f3854bb16b695be9bdd6ae035b894fc66bc2","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.6.0.tgz","fileCount":12,"integrity":"sha512-iFevSAt4W2XOCh4YjKn8/7FQ//eNn3oGJr6QM5Ar8V2nu1wBxEXyfuWPb2XyNpyVkkgQl+gxNq8DOuRH4qe1Lg==","signatures":[{"sig":"MEUCIQC+YBHqUDjDmlRJuVuVdNdSPrQLtKhsgrp+GSpbZ53dvAIgWMRh/iUrpR8279vBCh+CpdbmhHh9Z+hm7vkU3UlV7gg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":253940},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"314e0159905ea545511bd4b47ad9a272146b34aa","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"pcfvw","email":"ejacopin@ymail.com"},"repository":{"url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git","type":"git"},"_npmVersion":"11.12.1","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^9.39.2","vitest":"^1.0.0","@eslint/js":"^9.39.2","typescript":"^5.3.0","@types/node":"^20.10.0","typescript-eslint":"^8.53.0","@typescript-eslint/parser":"^8.50.0","@typescript-eslint/eslint-plugin":"^8.50.0"},"_npmOperationalInternal":{"tmp":"tmp/d-ary-heap_2.6.0_1778517906832_0.25753383343020886","host":"s3://npm-registry-packages-npm-production"}},"2.7.0":{"type":"module","name":"d-ary-heap","version":"2.7.0","description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src --ext .ts","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git"},"devDependencies":{"@eslint/js":"^9.39.2","@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^8.50.0","@typescript-eslint/parser":"^8.50.0","eslint":"^9.39.2","tsup":"^8.0.0","typescript":"^5.3.0","typescript-eslint":"^8.53.0","vitest":"^1.0.0"},"engines":{"node":">=18.0.0"},"gitHead":"c4f88ce3a96190f5e1c48af4ef3bda11eb9e3f9b","_id":"d-ary-heap@2.7.0","bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","_nodeVersion":"24.19.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-z1PFErwSIag0arwqwDHq47t2l61Fquhd3mJSg2dtdNVssHCBEUCmVVYvddYN/L1qk03GDTCSSeiU2equr4k4oQ==","shasum":"96c628cc851d3785bc8a213ab8357f08687c651d","tarball":"https://registry.npmjs.org/d-ary-heap/-/d-ary-heap-2.7.0.tgz","fileCount":12,"unpackedSize":250136,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/d-ary-heap@2.7.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFJfJ3p5mUNTZdE5lbqFZuCJJraBdkiBFGlGoZA14HvjAiEAtNwqka5LvvM+iR133d7EGYVNI853KXmllfV3EmjmR5s="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b0156b42-e355-433c-ba26-783e3fd33797"}},"directories":{},"maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/d-ary-heap_2.7.0_1788180301617_0.03728459816034135"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-23T11:34:02.657Z","modified":"2026-08-31T12:45:02.093Z","2.1.1":"2025-12-23T11:34:02.804Z","2.1.2":"2025-12-25T18:31:30.631Z","2.2.0":"2025-12-26T16:34:30.522Z","2.4.0":"2026-01-07T15:32:53.900Z","2.5.0":"2026-01-26T10:23:46.601Z","2.6.0":"2026-05-11T16:45:06.990Z","2.7.0":"2026-08-31T12:45:01.760Z"},"bugs":{"url":"https://github.com/PCfVW/d-Heap-priority-queue/issues"},"author":{"name":"Eric Jacopin"},"license":"Apache-2.0","homepage":"https://github.com/PCfVW/d-Heap-priority-queue#readme","keywords":["priority-queue","heap","d-ary-heap","d-heap","min-heap","max-heap","data-structure","algorithm","dijkstra","typescript"],"repository":{"type":"git","url":"git+https://github.com/PCfVW/d-Heap-priority-queue.git"},"description":"High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support","maintainers":[{"name":"pcfvw","email":"ejacopin@ymail.com"}],"readme":"![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)\n![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)\n\n# d-Heap Priority Queue (TypeScript) v2.7.0\n\n**Wikipedia-standard d-ary heap** with configurable arity, O(1) item lookup, and zero-cost comparison-count instrumentation. Cross-language API parity with C++, Go, Rust, and Zig.\n\n## 🎬 See it in action\n\n**[Interactive demo →](https://pcfvw.github.io/d-Heap-priority-queue/)**\n\nWatch the heap tree update as items are inserted, popped, and re-prioritized. Toggle arity (d=2 / d=4 / d=8) to see how tree depth changes. Step through Dijkstra's algorithm on a weighted graph, or run **race mode** to compare all three arities side-by-side. Built with React Flow; runs in the browser, no install.\n\n## Why this crate?\n\nIf you already know you want a priority queue, here's what `d-ary-heap` gives you over `js-priority-queue`, `priority-queue`, and other npm alternatives:\n\n- **Configurable arity `d`** (not just d=2). Pick `d=4` for cache-friendlier inserts, `d=8` for very insert-heavy workloads.\n- **O(1) item lookup + priority updates.** `increasePriority(item)`, `decreasePriority(item)`, `updatePriority(item)` — the operations Dijkstra and A\\* actually need. Most npm priority-queue packages don't expose these.\n- **Zero-cost comparison-count instrumentation** (in the library since v2.4.0; cross-language identical since v2.6.0). Opt-in `instrumentComparator(...)` + `onBeforeOperation` / `onAfterOperation` heap hooks; JIT-elided when not in use. See [Instrumentation](#instrumentation-v240) below.\n- **Cross-language API parity** with Rust, Go, C++, and Zig — same method names, same complexity guarantees, **byte-for-byte identical comparison counts** on shared benchmarks (verified across 24 cells × 5 languages).\n- **Zero runtime dependencies. Full TypeScript types.**\n- **Published numbers**: see [`benchmarks/`](https://github.com/PCfVW/d-Heap-priority-queue/tree/master/benchmarks) for cross-language Dijkstra benchmarks (24 cells × 5 languages) and the [methodology](https://github.com/PCfVW/d-Heap-priority-queue/blob/master/benchmarks/methodology.md).\n\n## Installation\n\n```bash\nnpm install d-ary-heap\n```\n\n## Quick Start\n\n```typescript\nimport { PriorityQueue, minBy, maxBy } from 'd-ary-heap';\n\n// Define your item type\ninterface Task {\n  id: number;\n  priority: number;\n  name: string;\n}\n\n// Create a min-heap (lower priority value = higher importance)\nconst pq = new PriorityQueue<Task, number>({\n  d: 4,                                    // 4-ary heap\n  comparator: minBy(task => task.priority), // Min-heap by priority\n  keyExtractor: task => task.id,           // Identity by id\n});\n\n// Insert items\npq.insert({ id: 1, priority: 10, name: 'Low priority task' });\npq.insert({ id: 2, priority: 1, name: 'High priority task' });\npq.insert({ id: 3, priority: 5, name: 'Medium priority task' });\n\n// Get highest priority item (lowest priority value in min-heap)\nconsole.log(pq.front()); // { id: 2, priority: 1, name: 'High priority task' }\n\n// Update priority of existing item\npq.increasePriority({ id: 1, priority: 0, name: 'Now urgent!' });\nconsole.log(pq.front()); // { id: 1, priority: 0, name: 'Now urgent!' }\n\n// Remove items in priority order\nwhile (!pq.isEmpty()) {\n  console.log(pq.pop());\n}\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew PriorityQueue<T, K>(options: PriorityQueueOptions<T, K>)\n```\n\nOptions:\n- `d`: Number of children per node (arity). Default: 2. Must be >= 1.\n- `comparator`: Function `(a: T, b: T) => boolean` returning true if `a` has higher priority.\n- `keyExtractor`: Function `(item: T) => K` extracting the identity key from an item.\n- `initialCapacity`: Optional hint for pre-allocation.\n\n### Static Factory Methods\n\n| Method | Description |\n|--------|-------------|\n| `PriorityQueue.withFirst(options, item)` | Create queue with initial item |\n\n### Query Methods\n\n| Method | Description | Time |\n|--------|-------------|------|\n| `len()` | Number of items | O(1) |\n| `size` | Property alias for `len()` | O(1) |\n| `isEmpty()` | Check if empty (primary method) | O(1) |\n| `is_empty()` | Alias for `isEmpty()` (cross-language compatibility) | O(1) |\n| `d()` | Get arity | O(1) |\n| `contains(item)` | Check if item exists (by key) | O(1) |\n| `containsKey(key)` | Check if key exists | O(1) |\n| `getPosition(item)` | Get item's index in heap | O(1) |\n| `getPositionByKey(key)` | Get index by key | O(1) |\n| `front()` | Get highest-priority item (throws if empty) | O(1) |\n| `peek()` | Get highest-priority item (returns undefined if empty) | O(1) |\n\n### Modification Methods\n\n| Method | Description | Time |\n|--------|-------------|------|\n| `insert(item)` | Add new item | O(log_d n) |\n| `pop()` | Remove and return highest-priority item | O(d · log_d n) |\n| `increasePriority(item)` | Update item to higher priority (primary method) | O(log_d n) |\n| `increase_priority(item)` | Alias for `increasePriority()` (cross-language compatibility) | O(log_d n) |\n| `increasePriorityByIndex(i)` | Update by index (primary method) | O(log_d n) |\n| `increase_priority_by_index(i)` | Alias for `increasePriorityByIndex()` (cross-language compatibility) | O(log_d n) |\n| `decreasePriorityByIndex(i)` | Update by index (primary method) | O(d · log_d n) |\n| `decrease_priority_by_index(i)` | Alias for `decreasePriorityByIndex()` (cross-language compatibility) | O(d · log_d n) |\n| `decreasePriority(item)` | Update item to lower priority (primary method) | O(d · log_d n) |\n| `decrease_priority(item)` | Alias for `decreasePriority()` (cross-language compatibility) | O(d · log_d n) |\n| `updatePriority(item)` | Update item when direction unknown (primary method) | O((d+1) · log_d n) |\n| `update_priority(item)` | Alias for `updatePriority()` (cross-language compatibility) | O((d+1) · log_d n) |\n| `clear(newD?)` | Remove all items, optionally change arity | O(1) |\n\n### Utility Methods\n\n| Method | Description |\n|--------|-------------|\n| `toString()` | String representation (primary method) |\n| `to_string()` | Alias for `toString()` (cross-language compatibility) |\n| `toArray()` | Copy of internal array |\n| `[Symbol.iterator]()` | Iterate over items in heap order |\n\n### Method Naming Convention\n\nThis TypeScript implementation follows **camelCase** as the primary naming convention (TypeScript/JavaScript standard), with **snake_case aliases** provided for cross-language compatibility:\n\n- **Primary methods**: `isEmpty()`, `increasePriority()`, `increasePriorityByIndex()`, `decreasePriority()`, `decreasePriorityByIndex()`, `updatePriority()`, `toString()`\n- **Compatibility aliases**: `is_empty()`, `increase_priority()`, `increase_priority_by_index()`, `decrease_priority()`, `decrease_priority_by_index()`, `update_priority()`, `to_string()`\n\nUse the primary camelCase methods for TypeScript/JavaScript projects, and the snake_case aliases when porting code from C++/Rust implementations.\n\n## Comparator Helpers\n\n```typescript\nimport { minBy, maxBy, minNumber, maxNumber, reverse, chain } from 'd-ary-heap';\n\n// Min-heap by extracted key\nconst minByCost = minBy<Item, number>(item => item.cost);\n\n// Max-heap by extracted key\nconst maxByCost = maxBy<Item, number>(item => item.cost);\n\n// For primitive numbers\nconst minHeap = minNumber;  // (a, b) => a < b\nconst maxHeap = maxNumber;  // (a, b) => a > b\n\n// Reverse any comparator\nconst reversed = reverse(minByCost);\n\n// Chain comparators (tiebreaker)\nconst byPriorityThenTime = chain(\n  minBy<Task, number>(t => t.priority),\n  minBy<Task, number>(t => t.timestamp)\n);\n```\n\n## Instrumentation (v2.4.0+)\n\nThe library provides opt-in instrumentation for counting comparisons during heap operations. This is useful for:\n\n- **Educational purposes**: Understanding theoretical vs actual comparison costs\n- **Benchmarking**: Measuring real comparison counts across different arities\n- **Visualization**: Powering interactive demos that show heap behavior\n\n### Zero-Cost When Disabled\n\nInstrumentation follows a zero-overhead design:\n- No performance impact when not using instrumentation\n- Existing code works unchanged\n- Per-operation tracking distinguishes insert/pop/increasePriority/decreasePriority/updatePriority comparisons\n\n### Usage\n\n```typescript\nimport {\n  PriorityQueue,\n  minBy,\n  instrumentComparator,\n  theoreticalInsertComparisons,\n  theoreticalPopComparisons\n} from 'd-ary-heap';\n\n// 1. Wrap your comparator with instrumentation\nconst comparator = instrumentComparator(minBy((v: Vertex) => v.distance));\n\n// 2. Create priority queue with operation hooks\nconst pq = new PriorityQueue({\n  d: 4,\n  comparator,\n  keyExtractor: (v) => v.id,\n  onBeforeOperation: (op) => comparator.startOperation(op),\n  onAfterOperation: () => comparator.endOperation(),\n});\n\n// 3. Use normally - comparisons are tracked automatically\npq.insert({ id: 'A', distance: 0 });\npq.insert({ id: 'B', distance: 5 });\npq.insert({ id: 'C', distance: 3 });\npq.pop();\n\n// 4. Access statistics\nconsole.log(comparator.stats);\n// { insert: 3, pop: 2, decreasePriority: 0, increasePriority: 0, updatePriority: 0, total: 5 }\n\n// 5. Compare with theoretical bounds\nconst n = 3;\nconst d = 4;\nconsole.log('Theoretical insert (worst):', theoreticalInsertComparisons(n, d));\nconsole.log('Theoretical pop (worst):', theoreticalPopComparisons(n, d));\n\n// 6. Reset for next measurement\ncomparator.stats.reset();\n```\n\n### Theoretical Complexity\n\nFor a d-ary heap with n elements:\n\n| Operation        | Comparisons (worst case)       |\n|------------------|--------------------------------|\n| insert           | floor(log_d(n))                |\n| pop              | d × floor(log_d(n))            |\n| increasePriority | floor(log_d(n)) (moveUp only)  |\n| decreasePriority | d × floor(log_d(n)) (moveDown only) |\n| updatePriority   | (d+1) × floor(log_d(n)) (both) |\n\n### Cross-Language Consistency\n\nInstrumentation is implemented in **all five languages** with **byte-for-byte identical comparison counts** (verified across 24 (graph, arity) cells; see [benchmarks/README.md](https://github.com/PCfVW/d-Heap-priority-queue/blob/master/benchmarks/README.md)). Each language uses its idiomatic zero-cost mechanism:\n\n| Language   | Mechanism                                       | Overhead When Disabled |\n|------------|-------------------------------------------------|------------------------|\n| TypeScript | Optional hooks + instrumented comparator        | Zero (JIT optimization) |\n| Go         | Nil stats pointer                               | ~1 cycle (nil check)   |\n| Rust       | Generic over `StatsCollector` trait             | Zero (monomorphization + ZST layout) |\n| C++        | Template policy class + `[[no_unique_address]]` | Zero (inlining + ZST collapse) |\n| Zig        | Comptime bool parameter on `DHeapWithStats`     | Zero (branch elimination + `void` field type) |\n\n## Priority Update Semantics\n\nThis library uses **importance-based** semantics:\n\n- **`increasePriority()`**: Make an item **more important** (moves toward heap root). Only moves up for O(log_d n) performance.\n- **`decreasePriority()`**: Make an item **less important** (moves toward leaves). Only moves down for O(d · log_d n) performance.\n- **`updatePriority()`**: Update when direction is **unknown**. Checks both directions for O((d+1) · log_d n) performance.\n\n**When to use each:**\n- Use `increasePriority()` when you know the item became more important\n- Use `decreasePriority()` when you know the item became less important\n- Use `updatePriority()` when you don't know which direction the priority changed\n\n**Heap Context:**\n- **Min-heap**: Lower priority values = higher importance\n- **Max-heap**: Higher priority values = higher importance\n\n## Performance\n\n### Benchmarks\n\nSee [`benchmarks/`](https://github.com/PCfVW/d-Heap-priority-queue/tree/master/benchmarks) for the Phase 3 cross-language Dijkstra sweep (24 cells × 5 languages, K=2 warmup + 10 timed reps each, median + IQR reporting). On AMD Ryzen 9 5950X with Node v24.11.1, the TypeScript example runs `huge_dense × d=8` (75 936 heap comparisons) at a median of **13.4 ms (~177 ns/cmp)** — within 25% of Go's 11.0 ms / 145 ns/cmp on the same workload. The full methodology is in [`benchmarks/methodology.md`](https://github.com/PCfVW/d-Heap-priority-queue/blob/master/benchmarks/methodology.md).\n\n### Performance Tips\n\n1. **Choose arity wisely**: d=4 is often optimal, balancing tree height vs comparison work per level.\n\n2. **Use inline comparators**: `(a, b) => a.cost < b.cost` is faster than `minBy(x => x.cost)` in hot paths.\n\n3. **Pre-allocate**: Use `initialCapacity` if you know the approximate size.\n\n4. **Simple key extractors**: Keep `keyExtractor` simple—`(item) => item.id` is ideal.\n\n5. **Avoid unnecessary updates**: Check if priority actually changed before calling update methods.\n\n### Running Benchmarks\n\n```bash\n# Full benchmark suite\nnpx tsx benchmarks/run-benchmarks.ts\n\n# Compare with naive implementation\nnpx tsx benchmarks/compare-implementations.ts\n```\n\n## What is a d-Heap?\n\nA [d-ary heap](https://en.wikipedia.org/wiki/D-ary_heap) is a tree where:\n- Each node has up to d children\n- The root holds the highest priority\n- Children are unordered\n- Priorities decrease along any root-to-leaf path\n\nTime complexities over n items:\n- O(1): access top\n- O(d · log_d n): delete-top\n- O(log_d n): insert and upward update\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n```\n\n## Reference\n\nSection A.3, [d-Heaps](https://en.wikipedia.org/wiki/D-ary_heap), pp. 773–778 of Ravindra Ahuja, Thomas Magnanti & James Orlin, **Network Flows** (Prentice Hall, 1993).\n\n## License\n\nApache License 2.0 — See [LICENSE](https://github.com/PCfVW/d-Heap-priority-queue/blob/master/LICENSE) for details.\n","readmeFilename":"README.md"}