@llblab/uniqueue 1.1.1 → 1.2.1

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
-const leaderboard = new UniQueue({
-  compare: (a, b) => b.score - a.score, // Sort by score descending
+import { Uniqueue } from "@llblab/uniqueue";
+
+// 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) => 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) {
@@ -60,7 +64,7 @@ for (const player of leaderboard) {
 
 ## API
 
-### `new UniQueue(options)`
+### `new Uniqueue(options)`
 
 Creates a new priority queue instance.
 

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-export interface UniQueueOptions<T> {
+export interface UniqueueOptions<T> {
     data?: T[];
     maxSize?: number;
     compare?: (a: T, b: T) => number;
     extractKey?: (item: T) => string;
 }
-export declare class UniQueue<T> {
+export declare class Uniqueue<T> {
     #private;
     data: T[];
     indexes: Map<string, number>;
-    constructor({ data, maxSize, compare, extractKey, }?: UniQueueOptions<T>);
+    constructor({ data, maxSize, compare, extractKey, }?: UniqueueOptions<T>);
     push(item: T): T | undefined;
     pop(): T | undefined;
     peek(): T | undefined;

package/dist/index.js

@@ -1,4 +1,4 @@
-export class UniQueue {
+export class Uniqueue {
     data;
     indexes;
     #maxSize;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/uniqueue",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "High-performance priority queue with unique key constraint (O(1) lookup, O(log n) update)",
   "type": "module",
   "main": "dist/index.js",