@llblab/uniqueue 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# Uniqueue
+
+A high-performance **priority queue with unique key constraint**.
+
+Combines a binary heap with a key-to-index `Map`, enabling O(log n) inserts/updates and O(1) lookups. Designed for leaderboard deduplication, task scheduling with updates, and LRU-like eviction scenarios.
+
+## Features
+
+- **Unique Constraint**: Ensures only one item per key exists in the queue.
+- **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.
+
+## Installation
+
+```bash
+npm install @llblab/uniqueue
+```
+
+## Usage
+
+### Basic Example (Max Heap)
+
+```javascript
+import { UniQueue } from "uniqueue";
+
+// Create a max-heap for leaderboard scores
+const leaderboard = new UniQueue({
+  compare: (a, b) => b.score - a.score, // Sort by score descending
+  extractKey: (item) => item.playerId, // Unique by playerId
+  maxSize: 3, // Keep only top 3 scores
+});
+
+// Add items
+leaderboard.push({ playerId: "alice", score: 100 });
+leaderboard.push({ playerId: "bob", score: 80 });
+leaderboard.push({ playerId: "charlie", score: 120 });
+
+console.log(leaderboard.peek());
+// Output: { playerId: "charlie", score: 120 }
+
+// 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
+
+console.log(leaderboard.data);
+// Contains dave (200), alice (150), charlie (120)
+```
+
+## API
+
+### `new UniQueue(options)`
+
+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.                       |
+
+### Instance Methods
+
+#### `push(item: T): void`
+
+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).
+
+#### `pop(): T | undefined`
+
+Removes and returns the highest priority item (the root of the heap).
+
+#### `peek(): T | undefined`
+
+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.
+
+#### `has(key: string): boolean`
+
+Checks if an item with the given key exists in the queue.
+
+#### `get(key: string): T | undefined`
+
+Returns the item with the given key without removing it.
+
+#### `clear(): void`
+
+Removes all items from the queue.
+
+#### `size: number`
+
+Getter property that returns the number of items in the queue.
+
+## Complexity
+
+| Operation       | Time Complexity |
+| :-------------- | :-------------- |
+| `push` (insert) | O(log n)        |
+| `push` (update) | O(log n)        |
+| `pop`           | O(log n)        |
+| `remove`        | O(log n)        |
+| `peek` / `get`  | O(1)            |
+| `has`           | O(1)            |
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,245 @@
+/**
+ * @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;
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@llblab/uniqueue",
+  "version": "1.0.0",
+  "description": "High-performance priority queue with unique key constraint (O(1) lookup, O(log n) update)",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "repository": "github:llblab/uniqueue",
+  "scripts": {
+    "test": "node --test test.js"
+  },
+  "keywords": [
+    "priority-queue",
+    "heap",
+    "unique",
+    "deduplication",
+    "leaderboard",
+    "cache",
+    "lru",
+    "performance"
+  ],
+  "author": "LLB <shlavik@gmail.com>",
+  "license": "MIT",
+  "sideEffects": false
+}