@llblab/uniqueue 1.2.0 → 1.3.0

package/README.md

@@ -21,14 +21,19 @@ npm install @llblab/uniqueue
 
 ## Usage
 
-### Basic Example (Max Heap)
+### Basic Example (Top-N Leaderboard)
 
 ```javascript
 import { Uniqueue } from "@llblab/uniqueue";
 
-// Create a max-heap for leaderboard scores
+// The `compare` function determines which item sits at the root:
+// - (a, b) => a - b → Min-heap (smallest at root, evicted first)
+// - (a, b) => b - a → Max-heap (largest at root, evicted first)
+//
+// For "Top-N" scenario, use min-heap: when maxSize is exceeded,
+// the root (smallest/worst) is evicted, keeping the best scores.
 const leaderboard = new Uniqueue({
-  compare: (a, b) => b.score - a.score, // Sort by score descending
+  compare: (a, b) => a.score - b.score,
   extractKey: (item) => item.playerId, // Unique by playerId
   maxSize: 3, // Keep only top 3 scores
 });
@@ -39,18 +44,17 @@ leaderboard.push({ playerId: "bob", score: 80 });
 leaderboard.push({ playerId: "charlie", score: 120 });
 
 console.log(leaderboard.peek());
-// Output: { playerId: "charlie", score: 120 }
+// Output: { playerId: "bob", score: 80 } (min-heap root)
 
 // Update existing item (alice improves score)
 leaderboard.push({ playerId: "alice", score: 150 });
-// Now alice is top, bob is pushed down
 
 // Add item that exceeds maxSize
 leaderboard.push({ playerId: "dave", score: 200 });
-// Dave enters, Bob (lowest score) is evicted
+// Bob (lowest score at root) is evicted
 
 console.log(leaderboard.data);
-// Contains dave (200), alice (150), charlie (120)
+// Contains charlie (120), alice (150), dave (200)
 
 // Iterate over all items
 for (const player of leaderboard) {
@@ -71,7 +75,7 @@ Creates a new priority queue instance.
 | `data`       | `T[]`              | `[]`                                     | Initial data array.                                                    |
 | `maxSize`    | `number`           | `Infinity`                               | Maximum number of items. If exceeded, lowest priority item is evicted. |
 | `compare`    | `(a, b) => number` | `(a, b) => (a < b ? -1 : a > b ? 1 : 0)` | Comparison function for heap ordering.                                 |
-| `extractKey` | `(item) => string` | `(item) => item`                         | Function to extract unique key string from item.                       |
+| `extractKey` | `(item) => K`      | `(item) => item`                         | Function to extract unique key any type from item.                     |
 
 ### Instance Methods
 
@@ -90,15 +94,15 @@ Removes and returns the highest priority item (the root of the heap).
 
 Returns the highest priority item without removing it.
 
-#### `remove(key: string): boolean`
+#### `remove(key: K): boolean`
 
 Removes the item with the given key. Returns `true` if removed, `false` otherwise.
 
-#### `has(key: string): boolean`
+#### `has(key: K): boolean`
 
 Checks if an item with the given key exists.
 
-#### `get(key: string): T | undefined`
+#### `get(key: K): T | undefined`
 
 Returns the item with the given key without removing it.
 

package/dist/index.d.ts

@@ -1,20 +1,20 @@
-export interface UniqueueOptions<T> {
+export interface UniqueueOptions<T, K = string> {
     data?: T[];
     maxSize?: number;
     compare?: (a: T, b: T) => number;
-    extractKey?: (item: T) => string;
+    extractKey?: (item: T) => K;
 }
-export declare class Uniqueue<T> {
+export declare class Uniqueue<T, K = string> {
     #private;
     data: T[];
-    indexes: Map<string, number>;
-    constructor({ data, maxSize, compare, extractKey, }?: UniqueueOptions<T>);
+    indexes: Map<K, number>;
+    constructor({ data, maxSize, compare, extractKey, }?: UniqueueOptions<T, K>);
     push(item: T): T | undefined;
     pop(): T | undefined;
     peek(): T | undefined;
-    remove(key: string): boolean;
-    has(key: string): boolean;
-    get(key: string): T | undefined;
+    remove(key: K): boolean;
+    has(key: K): boolean;
+    get(key: K): T | undefined;
     clear(): void;
     get size(): number;
     [Symbol.iterator](): IterableIterator<T>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CAClC;AAED,qBAAa,QAAQ,CAAC,CAAC;;IACrB,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAMjB,EACV,IAAS,EACT,OAAkB,EAClB,OAAgD,EAChD,UAAgD,GACjD,GAAE,eAAe,CAAC,CAAC,CAAM;IAkE1B,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAsB5B,GAAG,IAAI,CAAC,GAAG,SAAS;IAgBpB,IAAI,IAAI,CAAC,GAAG,SAAS;IAIrB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IA0B5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAK/B,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEA,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC;CAG1C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM;IAC5C,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;CAC7B;AAED,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM;;IACjC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;gBAMZ,EACV,IAAS,EACT,OAAkB,EAClB,OAAgD,EAChD,UAA2C,GAC5C,GAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAM;IAyE7B,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAsB5B,GAAG,IAAI,CAAC,GAAG,SAAS;IAgBpB,IAAI,IAAI,CAAC,GAAG,SAAS;IAIrB,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IA0BvB,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAK1B,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEA,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC;CAG1C"}

package/dist/index.js

@@ -5,13 +5,20 @@ export class Uniqueue {
     #compare;
     #extractKey;
     constructor({ data = [], maxSize = Infinity, compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0), extractKey = (item) => item, } = {}) {
-        this.data = data;
-        this.indexes = new Map(data.map((item, index) => [extractKey(item), index]));
         this.#maxSize = maxSize;
         this.#compare = compare;
         this.#extractKey = extractKey;
-        if (data.length > 0) {
-            for (let i = (data.length >>> 1) - 1; i >= 0; i--) {
+        this.data = [];
+        this.indexes = new Map();
+        for (const item of data) {
+            const key = extractKey(item);
+            if (!this.indexes.has(key)) {
+                this.indexes.set(key, this.data.length);
+                this.data.push(item);
+            }
+        }
+        if (this.data.length > 0) {
+            for (let i = (this.data.length >>> 1) - 1; i >= 0; i--) {
                 this.#siftDown(i);
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/uniqueue",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "High-performance priority queue with unique key constraint (O(1) lookup, O(log n) update)",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,6 @@
     "deduplication",
     "leaderboard",
     "cache",
-    "lru",
     "performance"
   ],
   "author": "LLB <shlavik@gmail.com>",