@llblab/uniqueue 1.0.0 → 1.1.0

package/README.md

@@ -10,7 +10,8 @@ Combines a binary heap with a key-to-index `Map`, enabling O(log n) inserts/upda
 - **In-Place Updates**: If an item with the same key is pushed, it updates the existing entry in-place (bubbling up or down as needed).
 - **O(1) Lookup**: Tracks item positions internally, avoiding O(n) scans for updates.
 - **Max Size Eviction**: Automatically removes the lowest-priority item when the limit is reached.
-- **Zero Dependencies**: Pure ES6 class, ~1KB minified.
+- **Iterable**: Supports `for...of` iteration over items.
+- **Zero Dependencies**: ~1KB minified.
 
 ## Installation
 
@@ -23,7 +24,7 @@ npm install @llblab/uniqueue
 ### Basic Example (Max Heap)
 
 ```javascript
-import { UniQueue } from "uniqueue";
+import { UniQueue } from "@llblab/uniqueue";
 
 // Create a max-heap for leaderboard scores
 const leaderboard = new UniQueue({
@@ -50,6 +51,11 @@ leaderboard.push({ playerId: "dave", score: 200 });
 
 console.log(leaderboard.data);
 // Contains dave (200), alice (150), charlie (120)
+
+// Iterate over all items
+for (const player of leaderboard) {
+  console.log(player.playerId, player.score);
+}
 ```
 
 ## API
@@ -60,21 +66,21 @@ Creates a new priority queue instance.
 
 #### Options
 
-| Option       | Type               | Default           | Description                                                            |
-| :----------- | :----------------- | :---------------- | :--------------------------------------------------------------------- |
-| `data`       | `Array<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` | Comparison function. Returns < 0 if a < b, > 0 if a > b.               |
-| `extractKey` | `(item) => string` | `(item) => item`  | Function to extract unique key string from item.                       |
+| Option       | Type               | Default                                  | Description                                                            |
+| :----------- | :----------------- | :--------------------------------------- | :--------------------------------------------------------------------- |
+| `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.                       |
 
 ### Instance Methods
 
-#### `push(item: T): void`
+#### `push(item: T): T | undefined`
 
 Adds an item to the queue or updates an existing item with the same key.
 
-- If the key is new: Adds item. If size > maxSize, removes and returns the lowest priority item.
-- If the key exists: Updates the existing item with the new value and rebalances (bubbles up or down).
+- If the key is new: Adds item. If size > maxSize, removes and returns the evicted item.
+- If the key exists: Updates the existing item and rebalances. Returns `undefined`.
 
 #### `pop(): T | undefined`
 
@@ -86,11 +92,11 @@ Returns the highest priority item without removing it.
 
 #### `remove(key: string): boolean`
 
-Removes the item with the given key from the queue. Returns `true` if an item was removed, `false` otherwise.
+Removes the item with the given key. Returns `true` if removed, `false` otherwise.
 
 #### `has(key: string): boolean`
 
-Checks if an item with the given key exists in the queue.
+Checks if an item with the given key exists.
 
 #### `get(key: string): T | undefined`
 
@@ -102,7 +108,11 @@ Removes all items from the queue.
 
 #### `size: number`
 
-Getter property that returns the number of items in the queue.
+Getter property that returns the number of items.
+
+#### `[Symbol.iterator](): IterableIterator<T>`
+
+Iterates over items in heap order (not sorted).
 
 ## Complexity
 

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export interface UniQueueOptions<T> {
+    data?: T[];
+    maxSize?: number;
+    compare?: (a: T, b: T) => number;
+    extractKey?: (item: T) => string;
+}
+export declare class UniQueue<T> {
+    #private;
+    data: T[];
+    indexes: Map<string, number>;
+    constructor({ data, maxSize, compare, extractKey, }?: UniQueueOptions<T>);
+    push(item: T): T | undefined;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    remove(key: string): boolean;
+    has(key: string): boolean;
+    get(key: string): T | undefined;
+    clear(): void;
+    get size(): number;
+    [Symbol.iterator](): IterableIterator<T>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,147 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _UniQueue_instances, _UniQueue_maxSize, _UniQueue_compare, _UniQueue_extractKey, _UniQueue_siftUp, _UniQueue_siftDown;
+export class UniQueue {
+    constructor({ data = [], maxSize = Infinity, compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0), extractKey = (item) => item, } = {}) {
+        _UniQueue_instances.add(this);
+        _UniQueue_maxSize.set(this, void 0);
+        _UniQueue_compare.set(this, void 0);
+        _UniQueue_extractKey.set(this, void 0);
+        this.data = data;
+        this.indexes = new Map(data.map((item, index) => [extractKey(item), index]));
+        __classPrivateFieldSet(this, _UniQueue_maxSize, maxSize, "f");
+        __classPrivateFieldSet(this, _UniQueue_compare, compare, "f");
+        __classPrivateFieldSet(this, _UniQueue_extractKey, extractKey, "f");
+        if (data.length > 0) {
+            for (let i = (data.length >>> 1) - 1; i >= 0; i--) {
+                __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftDown).call(this, i);
+            }
+        }
+    }
+    push(item) {
+        const key = __classPrivateFieldGet(this, _UniQueue_extractKey, "f").call(this, item);
+        const index = this.indexes.get(key);
+        if (index === undefined) {
+            this.data.push(item);
+            __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftUp).call(this, this.data.length - 1);
+            if (this.data.length <= __classPrivateFieldGet(this, _UniQueue_maxSize, "f"))
+                return;
+            return this.pop();
+        }
+        const oldItem = this.data[index];
+        this.data[index] = item;
+        const cmp = __classPrivateFieldGet(this, _UniQueue_compare, "f").call(this, oldItem, item);
+        if (cmp < 0) {
+            __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftDown).call(this, index);
+        }
+        else if (cmp > 0) {
+            __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftUp).call(this, index);
+        }
+    }
+    pop() {
+        if (this.data.length === 0)
+            return;
+        const top = this.data[0];
+        this.indexes.delete(__classPrivateFieldGet(this, _UniQueue_extractKey, "f").call(this, top));
+        const bottom = this.data.pop();
+        if (this.data.length > 0 && bottom !== undefined) {
+            this.indexes.set(__classPrivateFieldGet(this, _UniQueue_extractKey, "f").call(this, bottom), 0);
+            this.data[0] = bottom;
+            __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftDown).call(this, 0);
+        }
+        return top;
+    }
+    peek() {
+        return this.data[0];
+    }
+    remove(key) {
+        const index = this.indexes.get(key);
+        if (index === undefined)
+            return false;
+        const lastIndex = this.data.length - 1;
+        if (index === lastIndex) {
+            this.indexes.delete(key);
+            this.data.pop();
+            return true;
+        }
+        const item = this.data.pop();
+        this.indexes.delete(key);
+        this.indexes.set(__classPrivateFieldGet(this, _UniQueue_extractKey, "f").call(this, item), index);
+        this.data[index] = item;
+        const parentIndex = (index - 1) >>> 1;
+        if (index > 0 && __classPrivateFieldGet(this, _UniQueue_compare, "f").call(this, item, this.data[parentIndex]) < 0) {
+            __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftUp).call(this, index);
+        }
+        else {
+            __classPrivateFieldGet(this, _UniQueue_instances, "m", _UniQueue_siftDown).call(this, index);
+        }
+        return true;
+    }
+    has(key) {
+        return this.indexes.has(key);
+    }
+    get(key) {
+        const index = this.indexes.get(key);
+        return index !== undefined ? this.data[index] : undefined;
+    }
+    clear() {
+        this.data = [];
+        this.indexes.clear();
+    }
+    get size() {
+        return this.data.length;
+    }
+    *[(_UniQueue_maxSize = new WeakMap(), _UniQueue_compare = new WeakMap(), _UniQueue_extractKey = new WeakMap(), _UniQueue_instances = new WeakSet(), _UniQueue_siftUp = function _UniQueue_siftUp(pos) {
+        const { data, indexes } = this;
+        const compare = __classPrivateFieldGet(this, _UniQueue_compare, "f");
+        const extractKey = __classPrivateFieldGet(this, _UniQueue_extractKey, "f");
+        const item = data[pos];
+        while (pos > 0) {
+            const parentIndex = (pos - 1) >>> 1;
+            const parent = data[parentIndex];
+            if (compare(item, parent) >= 0)
+                break;
+            indexes.set(extractKey(parent), pos);
+            data[pos] = parent;
+            pos = parentIndex;
+        }
+        indexes.set(extractKey(item), pos);
+        data[pos] = item;
+    }, _UniQueue_siftDown = function _UniQueue_siftDown(pos) {
+        const { data, indexes } = this;
+        const compare = __classPrivateFieldGet(this, _UniQueue_compare, "f");
+        const extractKey = __classPrivateFieldGet(this, _UniQueue_extractKey, "f");
+        const item = data[pos];
+        const halfLength = data.length >>> 1;
+        while (pos < halfLength) {
+            let leftIndex = (pos << 1) + 1;
+            let best = data[leftIndex];
+            const rightIndex = leftIndex + 1;
+            if (rightIndex < data.length) {
+                const right = data[rightIndex];
+                if (compare(right, best) < 0) {
+                    leftIndex = rightIndex;
+                    best = right;
+                }
+            }
+            if (compare(best, item) >= 0)
+                break;
+            indexes.set(extractKey(best), pos);
+            data[pos] = best;
+            pos = leftIndex;
+        }
+        indexes.set(extractKey(item), pos);
+        data[pos] = item;
+    }, Symbol.iterator)]() {
+        yield* this.data;
+    }
+}

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@llblab/uniqueue",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "High-performance priority queue with unique key constraint (O(1) lookup, O(log n) update)",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
-    "index.js",
+    "dist",
     "README.md"
   ],
   "repository": "github:llblab/uniqueue",
   "scripts": {
-    "test": "node --test test.js"
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test.js"
   },
   "keywords": [
     "priority-queue",
@@ -27,5 +33,8 @@
   ],
   "author": "LLB <shlavik@gmail.com>",
   "license": "MIT",
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }

package/index.js

@@ -1,245 +0,0 @@
-/**
- * @template T
- * @typedef {Object} UniQueueOptions
- * @property {T[]} [data] - Initial data array
- * @property {number} [maxSize] - Maximum queue size (default: Infinity)
- * @property {(a: T, b: T) => number} [compare] - Comparison function for heap ordering
- * @property {(item: T) => string} [extractKey] - Function to extract unique key from item
- */
-
-/**
- * Priority queue with unique key constraint.
- * Combines a min-heap with a key-to-index map for O(log n) push/pop with deduplication.
- *
- * @template T
- */
-export class UniQueue {
-  /** @type {T[]} */
-  data;
-
-  /** @type {Map<string, number>} */
-  indexes;
-
-  /** @type {number} */
-  #maxSize;
-
-  /** @type {(a: T, b: T) => number} */
-  #compare;
-
-  /** @type {(item: T) => string} */
-  #extractKey;
-
-  /**
-   * @param {UniQueueOptions<T>} [options]
-   */
-  constructor({
-    data = [],
-    maxSize = Infinity,
-    compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0),
-    extractKey = (item) =>
-      /** @type {string} */ (/** @type {unknown} */ (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.#siftDown(i);
-      }
-    }
-  }
-
-  /**
-   * Move item up the heap to maintain heap property.
-   * @param {number} pos
-   */
-  #siftUp(pos) {
-    const { data, indexes } = this;
-    const compare = this.#compare;
-    const extractKey = this.#extractKey;
-    const item = data[pos];
-
-    while (pos > 0) {
-      const parentIndex = (pos - 1) >>> 1;
-      const parent = data[parentIndex];
-      if (compare(item, parent) >= 0) break;
-      indexes.set(extractKey(parent), pos);
-      data[pos] = parent;
-      pos = parentIndex;
-    }
-
-    indexes.set(extractKey(item), pos);
-    data[pos] = item;
-  }
-
-  /**
-   * Move item down the heap to maintain heap property.
-   * @param {number} pos
-   */
-  #siftDown(pos) {
-    const { data, indexes } = this;
-    const compare = this.#compare;
-    const extractKey = this.#extractKey;
-    const item = data[pos];
-    const halfLength = data.length >>> 1;
-
-    while (pos < halfLength) {
-      let leftIndex = (pos << 1) + 1;
-      let best = data[leftIndex];
-      const rightIndex = leftIndex + 1;
-
-      if (rightIndex < data.length) {
-        const right = data[rightIndex];
-        if (compare(right, best) < 0) {
-          leftIndex = rightIndex;
-          best = right;
-        }
-      }
-
-      if (compare(best, item) >= 0) break;
-
-      indexes.set(extractKey(best), pos);
-      data[pos] = best;
-      pos = leftIndex;
-    }
-
-    indexes.set(extractKey(item), pos);
-    data[pos] = item;
-  }
-
-  /**
-   * Add or update an item in the queue.
-   * - If key exists: Updates item and rebalances (unconditional update).
-   * - If key new: Adds item. If size > maxSize, evicts and returns min item.
-   * @param {T} item
-   * @returns {T | undefined} Evicted item if queue was full
-   */
-  push(item) {
-    const key = this.#extractKey(item);
-    const index = this.indexes.get(key);
-
-    if (index === undefined) {
-      this.data.push(item);
-      this.#siftUp(this.data.length - 1);
-      if (this.data.length <= this.#maxSize) return;
-      return this.pop();
-    }
-
-    const oldItem = this.data[index];
-    this.data[index] = item;
-    const cmp = this.#compare(oldItem, item);
-
-    if (cmp < 0) {
-      this.#siftDown(index);
-    } else if (cmp > 0) {
-      this.#siftUp(index);
-    }
-  }
-
-  /**
-   * Remove and return the top (minimum) item.
-   * @returns {T | undefined}
-   */
-  pop() {
-    if (this.data.length === 0) return;
-
-    const top = this.data[0];
-    this.indexes.delete(this.#extractKey(top));
-
-    const bottom = this.data.pop();
-    if (this.data.length > 0 && bottom !== undefined) {
-      this.indexes.set(this.#extractKey(bottom), 0);
-      this.data[0] = bottom;
-      this.#siftDown(0);
-    }
-
-    return top;
-  }
-
-  /**
-   * Return the top (minimum) item without removing it.
-   * @returns {T | undefined}
-   */
-  peek() {
-    return this.data[0];
-  }
-
-  /**
-   * Remove an item by key.
-   * @param {string} key
-   * @returns {boolean} true if item was removed
-   */
-  remove(key) {
-    const index = this.indexes.get(key);
-    if (index === undefined) return false;
-
-    const lastIndex = this.data.length - 1;
-    if (index === lastIndex) {
-      this.indexes.delete(key);
-      this.data.pop();
-      return true;
-    }
-
-    const item = /** @type {T} */ (this.data.pop());
-    this.indexes.delete(key);
-    this.indexes.set(this.#extractKey(item), index);
-    this.data[index] = item;
-
-    const parentIndex = (index - 1) >>> 1;
-    if (index > 0 && this.#compare(item, this.data[parentIndex]) < 0) {
-      this.#siftUp(index);
-    } else {
-      this.#siftDown(index);
-    }
-
-    return true;
-  }
-
-  /**
-   * Check if an item exists.
-   * @param {string} key
-   * @returns {boolean}
-   */
-  has(key) {
-    return this.indexes.has(key);
-  }
-
-  /**
-   * Get an item by key.
-   * @param {string} key
-   * @returns {T | undefined}
-   */
-  get(key) {
-    const index = this.indexes.get(key);
-    return index !== undefined ? this.data[index] : undefined;
-  }
-
-  /**
-   * Remove all items.
-   */
-  clear() {
-    this.data = [];
-    this.indexes.clear();
-  }
-
-  /**
-   * Get item count.
-   * @returns {number}
-   */
-  get size() {
-    return this.data.length;
-  }
-
-  /**
-   * Iterate over items (arbitrary heap order).
-   * @returns {IterableIterator<T>}
-   */
-  *[Symbol.iterator]() {
-    yield* this.data;
-  }
-}