d-ary-heap 2.4.0 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -14
- package/dist/index.cjs +79 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +76 -20
- package/dist/index.d.ts +76 -20
- package/dist/index.js +78 -14
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/src/PriorityQueue.ts +65 -5
- package/src/index.ts +2 -0
- package/src/instrumentation.ts +55 -18
package/dist/index.d.cts
CHANGED
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
*
|
|
54
54
|
* // 4. Access statistics
|
|
55
55
|
* console.log(comparator.stats);
|
|
56
|
-
* // { insert: 1, pop: 2, decreasePriority: 0, total: 3 }
|
|
56
|
+
* // { insert: 1, pop: 2, decreasePriority: 0, increasePriority: 0, updatePriority: 0, total: 3 }
|
|
57
57
|
*
|
|
58
58
|
* // 5. Reset for next measurement
|
|
59
59
|
* comparator.stats.reset();
|
|
@@ -63,12 +63,13 @@
|
|
|
63
63
|
*
|
|
64
64
|
* For a d-ary heap with n elements:
|
|
65
65
|
*
|
|
66
|
-
* | Operation | Comparisons (worst case)
|
|
67
|
-
*
|
|
68
|
-
* | insert | ⌊log_d(n)⌋
|
|
69
|
-
* | pop | d × ⌊log_d(n)⌋
|
|
70
|
-
* |
|
|
71
|
-
* |
|
|
66
|
+
* | Operation | Comparisons (worst case) |
|
|
67
|
+
* |------------------|-------------------------------|
|
|
68
|
+
* | insert | ⌊log_d(n)⌋ |
|
|
69
|
+
* | pop | d × ⌊log_d(n)⌋ |
|
|
70
|
+
* | increasePriority | ⌊log_d(n)⌋ (moveUp only) |
|
|
71
|
+
* | decreasePriority | d × ⌊log_d(n)⌋ (moveDown only)|
|
|
72
|
+
* | updatePriority | (d+1) × ⌊log_d(n)⌋ (both) |
|
|
72
73
|
*
|
|
73
74
|
* The demo visualization compares actual counts against these theoretical bounds.
|
|
74
75
|
*
|
|
@@ -80,10 +81,10 @@
|
|
|
80
81
|
/**
|
|
81
82
|
* Operation types that can be tracked.
|
|
82
83
|
*
|
|
83
|
-
* Note: `
|
|
84
|
-
*
|
|
84
|
+
* Note: `updatePriority` is tracked separately for when the caller doesn't know
|
|
85
|
+
* whether priority increased or decreased (checks both directions).
|
|
85
86
|
*/
|
|
86
|
-
type OperationType = 'insert' | 'pop' | 'decreasePriority' | 'increasePriority';
|
|
87
|
+
type OperationType = 'insert' | 'pop' | 'decreasePriority' | 'increasePriority' | 'updatePriority';
|
|
87
88
|
/**
|
|
88
89
|
* Statistics tracking comparison counts per operation type.
|
|
89
90
|
*
|
|
@@ -94,10 +95,12 @@ interface ComparisonStats {
|
|
|
94
95
|
insert: number;
|
|
95
96
|
/** Comparisons during pop operations (moveDown + bestChildPosition) */
|
|
96
97
|
pop: number;
|
|
97
|
-
/** Comparisons during decreasePriority operations (
|
|
98
|
+
/** Comparisons during decreasePriority operations (moveDown only) */
|
|
98
99
|
decreasePriority: number;
|
|
99
|
-
/** Comparisons during increasePriority operations (moveUp) */
|
|
100
|
+
/** Comparisons during increasePriority operations (moveUp only) */
|
|
100
101
|
increasePriority: number;
|
|
102
|
+
/** Comparisons during updatePriority operations (moveUp + moveDown) */
|
|
103
|
+
updatePriority: number;
|
|
101
104
|
/** Total comparisons across all operation types */
|
|
102
105
|
readonly total: number;
|
|
103
106
|
/** Reset all counters to zero */
|
|
@@ -212,18 +215,39 @@ declare function theoreticalInsertComparisons(n: number, d: number): number;
|
|
|
212
215
|
* @returns Theoretical worst-case comparison count
|
|
213
216
|
*/
|
|
214
217
|
declare function theoreticalPopComparisons(n: number, d: number): number;
|
|
218
|
+
/**
|
|
219
|
+
* Calculate theoretical comparison count for an increasePriority operation.
|
|
220
|
+
*
|
|
221
|
+
* IncreasePriority performs only moveUp (item became more important).
|
|
222
|
+
* Worst case: ⌊log_d(n)⌋ comparisons (one per level).
|
|
223
|
+
*
|
|
224
|
+
* @param n - Number of elements in heap
|
|
225
|
+
* @param d - Heap arity
|
|
226
|
+
* @returns Theoretical worst-case comparison count
|
|
227
|
+
*/
|
|
228
|
+
declare function theoreticalIncreasePriorityComparisons(n: number, d: number): number;
|
|
215
229
|
/**
|
|
216
230
|
* Calculate theoretical comparison count for a decreasePriority operation.
|
|
217
231
|
*
|
|
218
|
-
* DecreasePriority
|
|
219
|
-
*
|
|
220
|
-
* Worst case: ⌊log_d(n)⌋ comparisons.
|
|
232
|
+
* DecreasePriority performs only moveDown (item became less important).
|
|
233
|
+
* Worst case: d × ⌊log_d(n)⌋ comparisons.
|
|
221
234
|
*
|
|
222
235
|
* @param n - Number of elements in heap
|
|
223
236
|
* @param d - Heap arity
|
|
224
|
-
* @returns Theoretical worst-case comparison count
|
|
237
|
+
* @returns Theoretical worst-case comparison count
|
|
225
238
|
*/
|
|
226
239
|
declare function theoreticalDecreasePriorityComparisons(n: number, d: number): number;
|
|
240
|
+
/**
|
|
241
|
+
* Calculate theoretical comparison count for an updatePriority operation.
|
|
242
|
+
*
|
|
243
|
+
* UpdatePriority performs both moveUp and moveDown (direction unknown).
|
|
244
|
+
* Worst case: (d + 1) × ⌊log_d(n)⌋ comparisons.
|
|
245
|
+
*
|
|
246
|
+
* @param n - Number of elements in heap
|
|
247
|
+
* @param d - Heap arity
|
|
248
|
+
* @returns Theoretical worst-case comparison count
|
|
249
|
+
*/
|
|
250
|
+
declare function theoreticalUpdatePriorityComparisons(n: number, d: number): number;
|
|
227
251
|
|
|
228
252
|
/**
|
|
229
253
|
* d-ary Heap Priority Queue - TypeScript Implementation
|
|
@@ -233,8 +257,9 @@ declare function theoreticalDecreasePriorityComparisons(n: number, d: number): n
|
|
|
233
257
|
* - Min-heap or max-heap behavior via comparator functions
|
|
234
258
|
* - O(1) item lookup using Map for efficient priority updates
|
|
235
259
|
* - O(1) access to highest-priority item
|
|
236
|
-
* - O(log_d n) insert and
|
|
237
|
-
* - O(d · log_d n) pop and
|
|
260
|
+
* - O(log_d n) insert and increasePriority operations
|
|
261
|
+
* - O(d · log_d n) pop and decreasePriority operations
|
|
262
|
+
* - O((d+1) · log_d n) updatePriority (bidirectional)
|
|
238
263
|
* - Optional instrumentation hooks for performance analysis
|
|
239
264
|
*
|
|
240
265
|
* @version 2.4.0
|
|
@@ -314,6 +339,7 @@ interface PriorityQueueOptions<T, K> {
|
|
|
314
339
|
* - pop(): O(d · log_d n)
|
|
315
340
|
* - increasePriority(): O(log_d n)
|
|
316
341
|
* - decreasePriority(): O(d · log_d n)
|
|
342
|
+
* - updatePriority(): O((d+1) · log_d n)
|
|
317
343
|
* - contains(): O(1)
|
|
318
344
|
* - len(), isEmpty(), d(): O(1)
|
|
319
345
|
*
|
|
@@ -484,6 +510,21 @@ declare class PriorityQueue<T, K = string | number> {
|
|
|
484
510
|
increasePriorityByIndex(index: number): void;
|
|
485
511
|
/** Alias for increasePriorityByIndex() - snake_case for cross-language consistency */
|
|
486
512
|
increase_priority_by_index(index: number): void;
|
|
513
|
+
/**
|
|
514
|
+
* Decrease the priority of the item at the given index.
|
|
515
|
+
* Time complexity: O(d · log_d n)
|
|
516
|
+
*
|
|
517
|
+
* @param index - Index of the item in the heap array
|
|
518
|
+
* @throws Error if index is out of bounds
|
|
519
|
+
*
|
|
520
|
+
* @remarks
|
|
521
|
+
* This is a lower-level method. Prefer decreasePriority() with the item itself.
|
|
522
|
+
* The item at the given index should already have its priority value updated
|
|
523
|
+
* in the container before calling this method.
|
|
524
|
+
*/
|
|
525
|
+
decreasePriorityByIndex(index: number): void;
|
|
526
|
+
/** Alias for decreasePriorityByIndex() - snake_case for cross-language consistency */
|
|
527
|
+
decrease_priority_by_index(index: number): void;
|
|
487
528
|
/**
|
|
488
529
|
* Decrease the priority of an existing item (move toward leaves).
|
|
489
530
|
* Time complexity: O(d · log_d n)
|
|
@@ -494,11 +535,26 @@ declare class PriorityQueue<T, K = string | number> {
|
|
|
494
535
|
* @remarks
|
|
495
536
|
* For min-heap: increasing the priority value decreases importance.
|
|
496
537
|
* For max-heap: decreasing the priority value decreases importance.
|
|
497
|
-
* This method
|
|
538
|
+
* This method only moves items downward. Use updatePriority() if direction is unknown.
|
|
498
539
|
*/
|
|
499
540
|
decreasePriority(updatedItem: T): void;
|
|
500
541
|
/** Alias for decreasePriority() - snake_case for cross-language consistency */
|
|
501
542
|
decrease_priority(updatedItem: T): void;
|
|
543
|
+
/**
|
|
544
|
+
* Update the priority of an existing item when direction is unknown.
|
|
545
|
+
* Time complexity: O((d+1) · log_d n) - checks both directions
|
|
546
|
+
*
|
|
547
|
+
* @param updatedItem - Item with same identity but updated priority
|
|
548
|
+
* @throws Error if item not found
|
|
549
|
+
*
|
|
550
|
+
* @remarks
|
|
551
|
+
* Use this method when you don't know whether the priority increased or decreased.
|
|
552
|
+
* If you know the direction, prefer increasePriority() or decreasePriority() for
|
|
553
|
+
* better performance (log_d n vs (d+1) · log_d n comparisons).
|
|
554
|
+
*/
|
|
555
|
+
updatePriority(updatedItem: T): void;
|
|
556
|
+
/** Alias for updatePriority() - snake_case for cross-language consistency */
|
|
557
|
+
update_priority(updatedItem: T): void;
|
|
502
558
|
/**
|
|
503
559
|
* Remove and return the highest-priority item.
|
|
504
560
|
* Time complexity: O(d · log_d n)
|
|
@@ -647,4 +703,4 @@ declare function reverse<T>(cmp: Comparator<T>): Comparator<T>;
|
|
|
647
703
|
*/
|
|
648
704
|
declare function chain<T>(...comparators: Comparator<T>[]): Comparator<T>;
|
|
649
705
|
|
|
650
|
-
export { type Comparator, type ComparisonStats, type InstrumentedComparator, type KeyExtractor, type OperationType, type Position, PriorityQueue, type PriorityQueueOptions, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons };
|
|
706
|
+
export { type Comparator, type ComparisonStats, type InstrumentedComparator, type KeyExtractor, type OperationType, type Position, PriorityQueue, type PriorityQueueOptions, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalIncreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons, theoreticalUpdatePriorityComparisons };
|
package/dist/index.d.ts
CHANGED
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
*
|
|
54
54
|
* // 4. Access statistics
|
|
55
55
|
* console.log(comparator.stats);
|
|
56
|
-
* // { insert: 1, pop: 2, decreasePriority: 0, total: 3 }
|
|
56
|
+
* // { insert: 1, pop: 2, decreasePriority: 0, increasePriority: 0, updatePriority: 0, total: 3 }
|
|
57
57
|
*
|
|
58
58
|
* // 5. Reset for next measurement
|
|
59
59
|
* comparator.stats.reset();
|
|
@@ -63,12 +63,13 @@
|
|
|
63
63
|
*
|
|
64
64
|
* For a d-ary heap with n elements:
|
|
65
65
|
*
|
|
66
|
-
* | Operation | Comparisons (worst case)
|
|
67
|
-
*
|
|
68
|
-
* | insert | ⌊log_d(n)⌋
|
|
69
|
-
* | pop | d × ⌊log_d(n)⌋
|
|
70
|
-
* |
|
|
71
|
-
* |
|
|
66
|
+
* | Operation | Comparisons (worst case) |
|
|
67
|
+
* |------------------|-------------------------------|
|
|
68
|
+
* | insert | ⌊log_d(n)⌋ |
|
|
69
|
+
* | pop | d × ⌊log_d(n)⌋ |
|
|
70
|
+
* | increasePriority | ⌊log_d(n)⌋ (moveUp only) |
|
|
71
|
+
* | decreasePriority | d × ⌊log_d(n)⌋ (moveDown only)|
|
|
72
|
+
* | updatePriority | (d+1) × ⌊log_d(n)⌋ (both) |
|
|
72
73
|
*
|
|
73
74
|
* The demo visualization compares actual counts against these theoretical bounds.
|
|
74
75
|
*
|
|
@@ -80,10 +81,10 @@
|
|
|
80
81
|
/**
|
|
81
82
|
* Operation types that can be tracked.
|
|
82
83
|
*
|
|
83
|
-
* Note: `
|
|
84
|
-
*
|
|
84
|
+
* Note: `updatePriority` is tracked separately for when the caller doesn't know
|
|
85
|
+
* whether priority increased or decreased (checks both directions).
|
|
85
86
|
*/
|
|
86
|
-
type OperationType = 'insert' | 'pop' | 'decreasePriority' | 'increasePriority';
|
|
87
|
+
type OperationType = 'insert' | 'pop' | 'decreasePriority' | 'increasePriority' | 'updatePriority';
|
|
87
88
|
/**
|
|
88
89
|
* Statistics tracking comparison counts per operation type.
|
|
89
90
|
*
|
|
@@ -94,10 +95,12 @@ interface ComparisonStats {
|
|
|
94
95
|
insert: number;
|
|
95
96
|
/** Comparisons during pop operations (moveDown + bestChildPosition) */
|
|
96
97
|
pop: number;
|
|
97
|
-
/** Comparisons during decreasePriority operations (
|
|
98
|
+
/** Comparisons during decreasePriority operations (moveDown only) */
|
|
98
99
|
decreasePriority: number;
|
|
99
|
-
/** Comparisons during increasePriority operations (moveUp) */
|
|
100
|
+
/** Comparisons during increasePriority operations (moveUp only) */
|
|
100
101
|
increasePriority: number;
|
|
102
|
+
/** Comparisons during updatePriority operations (moveUp + moveDown) */
|
|
103
|
+
updatePriority: number;
|
|
101
104
|
/** Total comparisons across all operation types */
|
|
102
105
|
readonly total: number;
|
|
103
106
|
/** Reset all counters to zero */
|
|
@@ -212,18 +215,39 @@ declare function theoreticalInsertComparisons(n: number, d: number): number;
|
|
|
212
215
|
* @returns Theoretical worst-case comparison count
|
|
213
216
|
*/
|
|
214
217
|
declare function theoreticalPopComparisons(n: number, d: number): number;
|
|
218
|
+
/**
|
|
219
|
+
* Calculate theoretical comparison count for an increasePriority operation.
|
|
220
|
+
*
|
|
221
|
+
* IncreasePriority performs only moveUp (item became more important).
|
|
222
|
+
* Worst case: ⌊log_d(n)⌋ comparisons (one per level).
|
|
223
|
+
*
|
|
224
|
+
* @param n - Number of elements in heap
|
|
225
|
+
* @param d - Heap arity
|
|
226
|
+
* @returns Theoretical worst-case comparison count
|
|
227
|
+
*/
|
|
228
|
+
declare function theoreticalIncreasePriorityComparisons(n: number, d: number): number;
|
|
215
229
|
/**
|
|
216
230
|
* Calculate theoretical comparison count for a decreasePriority operation.
|
|
217
231
|
*
|
|
218
|
-
* DecreasePriority
|
|
219
|
-
*
|
|
220
|
-
* Worst case: ⌊log_d(n)⌋ comparisons.
|
|
232
|
+
* DecreasePriority performs only moveDown (item became less important).
|
|
233
|
+
* Worst case: d × ⌊log_d(n)⌋ comparisons.
|
|
221
234
|
*
|
|
222
235
|
* @param n - Number of elements in heap
|
|
223
236
|
* @param d - Heap arity
|
|
224
|
-
* @returns Theoretical worst-case comparison count
|
|
237
|
+
* @returns Theoretical worst-case comparison count
|
|
225
238
|
*/
|
|
226
239
|
declare function theoreticalDecreasePriorityComparisons(n: number, d: number): number;
|
|
240
|
+
/**
|
|
241
|
+
* Calculate theoretical comparison count for an updatePriority operation.
|
|
242
|
+
*
|
|
243
|
+
* UpdatePriority performs both moveUp and moveDown (direction unknown).
|
|
244
|
+
* Worst case: (d + 1) × ⌊log_d(n)⌋ comparisons.
|
|
245
|
+
*
|
|
246
|
+
* @param n - Number of elements in heap
|
|
247
|
+
* @param d - Heap arity
|
|
248
|
+
* @returns Theoretical worst-case comparison count
|
|
249
|
+
*/
|
|
250
|
+
declare function theoreticalUpdatePriorityComparisons(n: number, d: number): number;
|
|
227
251
|
|
|
228
252
|
/**
|
|
229
253
|
* d-ary Heap Priority Queue - TypeScript Implementation
|
|
@@ -233,8 +257,9 @@ declare function theoreticalDecreasePriorityComparisons(n: number, d: number): n
|
|
|
233
257
|
* - Min-heap or max-heap behavior via comparator functions
|
|
234
258
|
* - O(1) item lookup using Map for efficient priority updates
|
|
235
259
|
* - O(1) access to highest-priority item
|
|
236
|
-
* - O(log_d n) insert and
|
|
237
|
-
* - O(d · log_d n) pop and
|
|
260
|
+
* - O(log_d n) insert and increasePriority operations
|
|
261
|
+
* - O(d · log_d n) pop and decreasePriority operations
|
|
262
|
+
* - O((d+1) · log_d n) updatePriority (bidirectional)
|
|
238
263
|
* - Optional instrumentation hooks for performance analysis
|
|
239
264
|
*
|
|
240
265
|
* @version 2.4.0
|
|
@@ -314,6 +339,7 @@ interface PriorityQueueOptions<T, K> {
|
|
|
314
339
|
* - pop(): O(d · log_d n)
|
|
315
340
|
* - increasePriority(): O(log_d n)
|
|
316
341
|
* - decreasePriority(): O(d · log_d n)
|
|
342
|
+
* - updatePriority(): O((d+1) · log_d n)
|
|
317
343
|
* - contains(): O(1)
|
|
318
344
|
* - len(), isEmpty(), d(): O(1)
|
|
319
345
|
*
|
|
@@ -484,6 +510,21 @@ declare class PriorityQueue<T, K = string | number> {
|
|
|
484
510
|
increasePriorityByIndex(index: number): void;
|
|
485
511
|
/** Alias for increasePriorityByIndex() - snake_case for cross-language consistency */
|
|
486
512
|
increase_priority_by_index(index: number): void;
|
|
513
|
+
/**
|
|
514
|
+
* Decrease the priority of the item at the given index.
|
|
515
|
+
* Time complexity: O(d · log_d n)
|
|
516
|
+
*
|
|
517
|
+
* @param index - Index of the item in the heap array
|
|
518
|
+
* @throws Error if index is out of bounds
|
|
519
|
+
*
|
|
520
|
+
* @remarks
|
|
521
|
+
* This is a lower-level method. Prefer decreasePriority() with the item itself.
|
|
522
|
+
* The item at the given index should already have its priority value updated
|
|
523
|
+
* in the container before calling this method.
|
|
524
|
+
*/
|
|
525
|
+
decreasePriorityByIndex(index: number): void;
|
|
526
|
+
/** Alias for decreasePriorityByIndex() - snake_case for cross-language consistency */
|
|
527
|
+
decrease_priority_by_index(index: number): void;
|
|
487
528
|
/**
|
|
488
529
|
* Decrease the priority of an existing item (move toward leaves).
|
|
489
530
|
* Time complexity: O(d · log_d n)
|
|
@@ -494,11 +535,26 @@ declare class PriorityQueue<T, K = string | number> {
|
|
|
494
535
|
* @remarks
|
|
495
536
|
* For min-heap: increasing the priority value decreases importance.
|
|
496
537
|
* For max-heap: decreasing the priority value decreases importance.
|
|
497
|
-
* This method
|
|
538
|
+
* This method only moves items downward. Use updatePriority() if direction is unknown.
|
|
498
539
|
*/
|
|
499
540
|
decreasePriority(updatedItem: T): void;
|
|
500
541
|
/** Alias for decreasePriority() - snake_case for cross-language consistency */
|
|
501
542
|
decrease_priority(updatedItem: T): void;
|
|
543
|
+
/**
|
|
544
|
+
* Update the priority of an existing item when direction is unknown.
|
|
545
|
+
* Time complexity: O((d+1) · log_d n) - checks both directions
|
|
546
|
+
*
|
|
547
|
+
* @param updatedItem - Item with same identity but updated priority
|
|
548
|
+
* @throws Error if item not found
|
|
549
|
+
*
|
|
550
|
+
* @remarks
|
|
551
|
+
* Use this method when you don't know whether the priority increased or decreased.
|
|
552
|
+
* If you know the direction, prefer increasePriority() or decreasePriority() for
|
|
553
|
+
* better performance (log_d n vs (d+1) · log_d n comparisons).
|
|
554
|
+
*/
|
|
555
|
+
updatePriority(updatedItem: T): void;
|
|
556
|
+
/** Alias for updatePriority() - snake_case for cross-language consistency */
|
|
557
|
+
update_priority(updatedItem: T): void;
|
|
502
558
|
/**
|
|
503
559
|
* Remove and return the highest-priority item.
|
|
504
560
|
* Time complexity: O(d · log_d n)
|
|
@@ -647,4 +703,4 @@ declare function reverse<T>(cmp: Comparator<T>): Comparator<T>;
|
|
|
647
703
|
*/
|
|
648
704
|
declare function chain<T>(...comparators: Comparator<T>[]): Comparator<T>;
|
|
649
705
|
|
|
650
|
-
export { type Comparator, type ComparisonStats, type InstrumentedComparator, type KeyExtractor, type OperationType, type Position, PriorityQueue, type PriorityQueueOptions, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons };
|
|
706
|
+
export { type Comparator, type ComparisonStats, type InstrumentedComparator, type KeyExtractor, type OperationType, type Position, PriorityQueue, type PriorityQueueOptions, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalIncreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons, theoreticalUpdatePriorityComparisons };
|
package/dist/index.js
CHANGED
|
@@ -271,6 +271,28 @@ var PriorityQueue = class _PriorityQueue {
|
|
|
271
271
|
increase_priority_by_index(index) {
|
|
272
272
|
this.increasePriorityByIndex(index);
|
|
273
273
|
}
|
|
274
|
+
/**
|
|
275
|
+
* Decrease the priority of the item at the given index.
|
|
276
|
+
* Time complexity: O(d · log_d n)
|
|
277
|
+
*
|
|
278
|
+
* @param index - Index of the item in the heap array
|
|
279
|
+
* @throws Error if index is out of bounds
|
|
280
|
+
*
|
|
281
|
+
* @remarks
|
|
282
|
+
* This is a lower-level method. Prefer decreasePriority() with the item itself.
|
|
283
|
+
* The item at the given index should already have its priority value updated
|
|
284
|
+
* in the container before calling this method.
|
|
285
|
+
*/
|
|
286
|
+
decreasePriorityByIndex(index) {
|
|
287
|
+
if (index < 0 || index >= this.container.length) {
|
|
288
|
+
throw new Error("Index out of bounds");
|
|
289
|
+
}
|
|
290
|
+
this.moveDown(index);
|
|
291
|
+
}
|
|
292
|
+
/** Alias for decreasePriorityByIndex() - snake_case for cross-language consistency */
|
|
293
|
+
decrease_priority_by_index(index) {
|
|
294
|
+
this.decreasePriorityByIndex(index);
|
|
295
|
+
}
|
|
274
296
|
/**
|
|
275
297
|
* Decrease the priority of an existing item (move toward leaves).
|
|
276
298
|
* Time complexity: O(d · log_d n)
|
|
@@ -281,7 +303,7 @@ var PriorityQueue = class _PriorityQueue {
|
|
|
281
303
|
* @remarks
|
|
282
304
|
* For min-heap: increasing the priority value decreases importance.
|
|
283
305
|
* For max-heap: decreasing the priority value decreases importance.
|
|
284
|
-
* This method
|
|
306
|
+
* This method only moves items downward. Use updatePriority() if direction is unknown.
|
|
285
307
|
*/
|
|
286
308
|
decreasePriority(updatedItem) {
|
|
287
309
|
this.onBeforeOperation?.("decreasePriority");
|
|
@@ -292,7 +314,6 @@ var PriorityQueue = class _PriorityQueue {
|
|
|
292
314
|
throw new Error("Item not found in priority queue");
|
|
293
315
|
}
|
|
294
316
|
this.container[index] = updatedItem;
|
|
295
|
-
this.moveUp(index);
|
|
296
317
|
this.moveDown(index);
|
|
297
318
|
this.onAfterOperation?.();
|
|
298
319
|
}
|
|
@@ -300,6 +321,35 @@ var PriorityQueue = class _PriorityQueue {
|
|
|
300
321
|
decrease_priority(updatedItem) {
|
|
301
322
|
this.decreasePriority(updatedItem);
|
|
302
323
|
}
|
|
324
|
+
/**
|
|
325
|
+
* Update the priority of an existing item when direction is unknown.
|
|
326
|
+
* Time complexity: O((d+1) · log_d n) - checks both directions
|
|
327
|
+
*
|
|
328
|
+
* @param updatedItem - Item with same identity but updated priority
|
|
329
|
+
* @throws Error if item not found
|
|
330
|
+
*
|
|
331
|
+
* @remarks
|
|
332
|
+
* Use this method when you don't know whether the priority increased or decreased.
|
|
333
|
+
* If you know the direction, prefer increasePriority() or decreasePriority() for
|
|
334
|
+
* better performance (log_d n vs (d+1) · log_d n comparisons).
|
|
335
|
+
*/
|
|
336
|
+
updatePriority(updatedItem) {
|
|
337
|
+
this.onBeforeOperation?.("updatePriority");
|
|
338
|
+
const key = this.keyExtractor(updatedItem);
|
|
339
|
+
const index = this.positions.get(key);
|
|
340
|
+
if (index === void 0) {
|
|
341
|
+
this.onAfterOperation?.();
|
|
342
|
+
throw new Error("Item not found in priority queue");
|
|
343
|
+
}
|
|
344
|
+
this.container[index] = updatedItem;
|
|
345
|
+
this.moveUp(index);
|
|
346
|
+
this.moveDown(index);
|
|
347
|
+
this.onAfterOperation?.();
|
|
348
|
+
}
|
|
349
|
+
/** Alias for updatePriority() - snake_case for cross-language consistency */
|
|
350
|
+
update_priority(updatedItem) {
|
|
351
|
+
this.updatePriority(updatedItem);
|
|
352
|
+
}
|
|
303
353
|
/**
|
|
304
354
|
* Remove and return the highest-priority item.
|
|
305
355
|
* Time complexity: O(d · log_d n)
|
|
@@ -497,14 +547,16 @@ function createComparisonStats() {
|
|
|
497
547
|
pop: 0,
|
|
498
548
|
decreasePriority: 0,
|
|
499
549
|
increasePriority: 0,
|
|
550
|
+
updatePriority: 0,
|
|
500
551
|
get total() {
|
|
501
|
-
return this.insert + this.pop + this.decreasePriority + this.increasePriority;
|
|
552
|
+
return this.insert + this.pop + this.decreasePriority + this.increasePriority + this.updatePriority;
|
|
502
553
|
},
|
|
503
554
|
reset() {
|
|
504
555
|
this.insert = 0;
|
|
505
556
|
this.pop = 0;
|
|
506
557
|
this.decreasePriority = 0;
|
|
507
558
|
this.increasePriority = 0;
|
|
559
|
+
this.updatePriority = 0;
|
|
508
560
|
}
|
|
509
561
|
};
|
|
510
562
|
return stats;
|
|
@@ -540,10 +592,20 @@ function theoreticalPopComparisons(n, d) {
|
|
|
540
592
|
const height = Math.floor(Math.log(n) / Math.log(d));
|
|
541
593
|
return d * height;
|
|
542
594
|
}
|
|
543
|
-
function
|
|
595
|
+
function theoreticalIncreasePriorityComparisons(n, d) {
|
|
544
596
|
if (n <= 1) return 0;
|
|
545
597
|
return Math.floor(Math.log(n) / Math.log(d));
|
|
546
598
|
}
|
|
599
|
+
function theoreticalDecreasePriorityComparisons(n, d) {
|
|
600
|
+
if (n <= 1) return 0;
|
|
601
|
+
const height = Math.floor(Math.log(n) / Math.log(d));
|
|
602
|
+
return d * height;
|
|
603
|
+
}
|
|
604
|
+
function theoreticalUpdatePriorityComparisons(n, d) {
|
|
605
|
+
if (n <= 1) return 0;
|
|
606
|
+
const height = Math.floor(Math.log(n) / Math.log(d));
|
|
607
|
+
return (d + 1) * height;
|
|
608
|
+
}
|
|
547
609
|
/**
|
|
548
610
|
* d-ary Heap Priority Queue - TypeScript Implementation
|
|
549
611
|
*
|
|
@@ -552,8 +614,9 @@ function theoreticalDecreasePriorityComparisons(n, d) {
|
|
|
552
614
|
* - Min-heap or max-heap behavior via comparator functions
|
|
553
615
|
* - O(1) item lookup using Map for efficient priority updates
|
|
554
616
|
* - O(1) access to highest-priority item
|
|
555
|
-
* - O(log_d n) insert and
|
|
556
|
-
* - O(d · log_d n) pop and
|
|
617
|
+
* - O(log_d n) insert and increasePriority operations
|
|
618
|
+
* - O(d · log_d n) pop and decreasePriority operations
|
|
619
|
+
* - O((d+1) · log_d n) updatePriority (bidirectional)
|
|
557
620
|
* - Optional instrumentation hooks for performance analysis
|
|
558
621
|
*
|
|
559
622
|
* @version 2.4.0
|
|
@@ -622,7 +685,7 @@ function theoreticalDecreasePriorityComparisons(n, d) {
|
|
|
622
685
|
*
|
|
623
686
|
* // 4. Access statistics
|
|
624
687
|
* console.log(comparator.stats);
|
|
625
|
-
* // { insert: 1, pop: 2, decreasePriority: 0, total: 3 }
|
|
688
|
+
* // { insert: 1, pop: 2, decreasePriority: 0, increasePriority: 0, updatePriority: 0, total: 3 }
|
|
626
689
|
*
|
|
627
690
|
* // 5. Reset for next measurement
|
|
628
691
|
* comparator.stats.reset();
|
|
@@ -632,12 +695,13 @@ function theoreticalDecreasePriorityComparisons(n, d) {
|
|
|
632
695
|
*
|
|
633
696
|
* For a d-ary heap with n elements:
|
|
634
697
|
*
|
|
635
|
-
* | Operation | Comparisons (worst case)
|
|
636
|
-
*
|
|
637
|
-
* | insert | ⌊log_d(n)⌋
|
|
638
|
-
* | pop | d × ⌊log_d(n)⌋
|
|
639
|
-
* |
|
|
640
|
-
* |
|
|
698
|
+
* | Operation | Comparisons (worst case) |
|
|
699
|
+
* |------------------|-------------------------------|
|
|
700
|
+
* | insert | ⌊log_d(n)⌋ |
|
|
701
|
+
* | pop | d × ⌊log_d(n)⌋ |
|
|
702
|
+
* | increasePriority | ⌊log_d(n)⌋ (moveUp only) |
|
|
703
|
+
* | decreasePriority | d × ⌊log_d(n)⌋ (moveDown only)|
|
|
704
|
+
* | updatePriority | (d+1) × ⌊log_d(n)⌋ (both) |
|
|
641
705
|
*
|
|
642
706
|
* The demo visualization compares actual counts against these theoretical bounds.
|
|
643
707
|
*
|
|
@@ -657,6 +721,6 @@ function theoreticalDecreasePriorityComparisons(n, d) {
|
|
|
657
721
|
* @copyright 2023-2025 Eric Jacopin
|
|
658
722
|
*/
|
|
659
723
|
|
|
660
|
-
export { PriorityQueue, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons };
|
|
724
|
+
export { PriorityQueue, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalIncreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons, theoreticalUpdatePriorityComparisons };
|
|
661
725
|
//# sourceMappingURL=index.js.map
|
|
662
726
|
//# sourceMappingURL=index.js.map
|