@hardlydifficult/queue 1.1.2 → 1.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/queue
 
-A high-performance priority queue implementation with O(1) enqueue and dequeue operations, supporting FIFO ordering within priority levels.
+A high-performance priority queue with O(1) enqueue/dequeue operations and FIFO ordering within priority levels.
 
 ## Installation
 
@@ -15,195 +15,228 @@ import { createPriorityQueue } from "@hardlydifficult/queue";
 
 const queue = createPriorityQueue<string>();
 
-queue.enqueue("low-priority", "low");
-queue.enqueue("urgent", "high");
-queue.enqueue("standard"); // defaults to 'medium'
+queue.enqueue("low-priority task", "low");
+queue.enqueue("urgent fix", "high");
 
-// Dequeues in priority order, then by insertion time
-console.log(queue.dequeue()?.data); // "urgent"
-console.log(queue.dequeue()?.data); // "standard"
-console.log(queue.dequeue()?.data); // "low-priority"
+// High priority item dequeued first
+console.log(queue.dequeue()?.data); // "urgent fix"
+console.log(queue.dequeue()?.data); // "low-priority task"
 ```
 
-## Core API
+## Priority-Based Ordering
 
-### createPriorityQueue
-
-Creates a new priority queue instance.
+Items are dequeued in priority order: high → medium → low. Within each priority level, items follow FIFO (first-in, first-out) order.
 
 ```typescript
-import { createPriorityQueue } from "@hardlydifficult/queue";
+const queue = createPriorityQueue<string>();
 
-const queue = createPriorityQueue<number>();
+queue.enqueue("a", "low");
+queue.enqueue("b", "high");
+queue.enqueue("c", "medium");
+queue.enqueue("d", "high");
+
+// Dequeue order: b, d, c, a
+console.log(queue.toArray().map(i => i.data)); // ["b", "d", "c", "a"]
 ```
 
-### PriorityQueue Interface
+### Priority Levels
 
-All queue operations are provided via the `PriorityQueue<T>` interface returned by `createPriorityQueue()`.
+| Priority | Dequeue Order |
+|----------|---------------|
+| `high`   | First         |
+| `medium` | Second (default) |
+| `low`    | Third         |
 
-#### enqueue(data, priority?)
+## Queue Operations
 
-Adds an item to the queue.
+### `enqueue(data, priority?)`
 
-| Parameter | Type      | Default   | Description                  |
-|-----------|-----------|-----------|------------------------------|
-| data      | `T`       | —         | The item data to enqueue     |
-| priority  | `Priority`| `"medium"`| Priority level: `"high"`, `"medium"`, or `"low"` |
+Adds an item to the queue.
 
-Returns a `QueueItem<T>` with metadata including unique ID and enqueue timestamp.
+- **Parameters**:
+  - `data`: The item to queue
+  - `priority`: `"high"`, `"medium"`, or `"low"` (default: `"medium"`)
+- **Returns**: `QueueItem<T>` with metadata (`data`, `priority`, `enqueuedAt`, `id`)
+- **Time complexity**: O(1)
 
 ```typescript
-const item = queue.enqueue("task", "high");
-console.log(item.id); // "q_1"
-console.log(item.priority); // "high"
-```
-
-#### dequeue()
-
-Removes and returns the highest-priority item (FIFO within same priority).
+const queue = createPriorityQueue<number>();
+const item = queue.enqueue(42, "high");
 
-```typescript
-const item = queue.dequeue();
-if (item) {
-  console.log(item.data); // "urgent"
-}
+console.log(item); // { data: 42, priority: "high", enqueuedAt: 1712345678901, id: "q_1" }
 ```
 
-Returns `undefined` if the queue is empty.
-
-#### peek()
+### `dequeue()`
 
-Returns the next item to be dequeued without removing it.
+Removes and returns the highest-priority item.
 
-```typescript
-const next = queue.peek();
-if (next) {
-  console.log(next.data); // First item to be dequeued
-}
-```
+- **Returns**: `QueueItem<T> | undefined`
+- **Time complexity**: O(1)
 
-#### remove(id)
+### `peek()`
 
-Removes an item by its unique ID.
+Returns the next item without removing it.
 
-```typescript
-const item = queue.enqueue("remove-me");
-const removed = queue.remove(item.id); // true
-const absent = queue.remove("unknown"); // false
-```
+- **Returns**: `QueueItem<T> | undefined`
+- **Time complexity**: O(1)
 
-#### size
+### `size` & `isEmpty`
 
-Readonly property returning the total number of items in the queue.
+Accessors for queue state.
 
 ```typescript
-console.log(queue.size); // 5
-```
+const queue = createPriorityQueue<string>();
 
-#### isEmpty
+console.log(queue.size);      // 0
+console.log(queue.isEmpty);   // true
 
-Readonly property indicating whether the queue is empty.
+queue.enqueue("item");
 
-```typescript
-console.log(queue.isEmpty); // false
+console.log(queue.size);      // 1
+console.log(queue.isEmpty);   // false
 ```
 
-#### onEnqueue(callback)
+### `toArray()`
 
-Registers a callback invoked whenever an item is enqueued.
+Returns all items in dequeue order (snapshot).
 
-Returns an unsubscribe function.
+- **Returns**: `readonly QueueItem<T>[]`
+- Does not modify the queue
 
 ```typescript
-const unsubscribe = queue.onEnqueue((item) => {
-  console.log("Enqueued:", item.data);
-});
+const queue = createPriorityQueue<string>();
+queue.enqueue("c", "low");
+queue.enqueue("a", "high");
+queue.enqueue("b", "medium");
 
-queue.enqueue("test");
-unsubscribe();
-queue.enqueue("ignored"); // callback no longer invoked
+console.log(queue.toArray().map(i => i.data)); // ["a", "b", "c"]
 ```
 
-#### toArray()
+### `clear()`
 
-Returns a snapshot of all items in dequeue order (by priority, then FIFO). Does not modify the queue.
+Removes all items from the queue.
 
 ```typescript
-const items = queue.toArray();
-// Items sorted by priority: high → medium → low, then by insertion order
+const queue = createPriorityQueue<string>();
+queue.enqueue("item");
+queue.clear();
+console.log(queue.size); // 0
 ```
 
-#### clear()
+## Item Management
 
-Removes all items from the queue.
+### `remove(id)`
+
+Removes a specific item by ID.
+
+- **Returns**: `boolean` (`true` if found and removed)
+- **Time complexity**: O(n) (due to linear search)
 
 ```typescript
-queue.enqueue("a");
-queue.enqueue("b");
-queue.clear();
-console.log(queue.size); // 0
+const queue = createPriorityQueue<string>();
+const item = queue.enqueue("remove-me");
+queue.enqueue("keep-me");
+
+console.log(queue.remove(item.id)); // true
+console.log(queue.size);            // 1
+console.log(queue.dequeue()?.data); // "keep-me"
 ```
 
-### Priority Updates
+### `updatePriority(id, newPriority)`
 
-#### updatePriority(id, newPriority)
+Changes an item's priority.
 
-Changes the priority of an existing item.
+- **Returns**: `boolean` (`true` if item found)
+- Preserves `data` and `enqueuedAt`; appends to new priority bucket
 
 ```typescript
+const queue = createPriorityQueue<string>();
 const item = queue.enqueue("task", "low");
-queue.updatePriority(item.id, "high"); // true
+queue.enqueue("other", "high");
+
+console.log(queue.toArray().map(i => i.priority)); // ["high", "low"]
+
+queue.updatePriority(item.id, "high");
+console.log(queue.toArray().map(i => i.priority)); // ["high", "high"]
 ```
 
-Returns `true` if the item was found and updated, `false` otherwise.
+### `moveBefore(itemId, beforeItemId)`
 
-#### moveBefore(itemId, beforeItemId)
+Reorders items within the same priority bucket.
 
-Moves an item before another item within the same priority bucket.
+- **Returns**: `boolean` (`true` if move succeeded)
+- Both items must exist and share the same priority
 
 ```typescript
-const a = queue.enqueue("a", "medium");
-const b = queue.enqueue("b", "medium");
-const c = queue.enqueue("c", "medium");
+const queue = createPriorityQueue<string>();
+const a = queue.enqueue("first");
+const b = queue.enqueue("second");
+const c = queue.enqueue("third");
 
-queue.moveBefore(c.id, a.id); // true
-console.log(queue.toArray().map(i => i.data)); // ["c", "a", "b"]
+queue.moveBefore(c.id, a.id);
+console.log(queue.toArray().map(i => i.data)); // ["third", "first", "second"]
 ```
 
-Both items must exist and share the same priority. Returns `true` on success.
-
-#### moveToEnd(itemId)
+### `moveToEnd(itemId)`
 
 Moves an item to the end of its priority bucket.
 
+- **Returns**: `boolean` (`true` if item found)
+- No-op if already at end
+
 ```typescript
-const a = queue.enqueue("a", "medium");
-const b = queue.enqueue("b", "medium");
-queue.moveToEnd(a.id); // true
-console.log(queue.toArray().map(i => i.data)); // ["b", "a"]
+const queue = createPriorityQueue<string>();
+queue.enqueue("first");
+queue.enqueue("second");
+const last = queue.enqueue("third");
+
+queue.moveToEnd(last.id); // No change (already at end)
+console.log(queue.toArray().map(i => i.data)); // ["first", "second", "third"]
 ```
 
-Returns `true` if the item was found (even if already at end), `false` otherwise.
+## Observer Pattern
+
+### `onEnqueue(callback)`
 
-## QueueItem Type
+Registers a listener for new items.
 
-Represents an item in the queue with metadata:
+- **Returns**: Unsubscribe function
 
 ```typescript
-interface QueueItem<T> {
-  data: T;
-  priority: Priority;
-  enqueuedAt: number; // epoch milliseconds
-  id: string;         // unique identifier
-}
+const queue = createPriorityQueue<string>();
+const handler = (item) => {
+  console.log("Enqueued:", item.data, "at", item.enqueuedAt);
+};
+
+const unsubscribe = queue.onEnqueue(handler);
+
+queue.enqueue("test"); // Logs the enqueue event
+unsubscribe();
+queue.enqueue("ignored"); // Not logged
 ```
 
-## Priority Order
+## API Reference
+
+### Types
+
+| Name         | Description                              |
+|--------------|------------------------------------------|
+| `Priority`   | `"high" | "medium" | "low"`             |
+| `QueueItem<T>` | Item with `data`, `priority`, `enqueuedAt`, `id` |
+| `PriorityQueue<T>` | Core queue interface                |
+
+### Exports
 
-Priority levels are ordered from highest to lowest:
+| Export               | Description                      |
+|----------------------|----------------------------------|
+| `createPriorityQueue<T>()` | Factory function for new queues |
+| `PriorityQueue<T>`   | Queue interface type             |
+| `QueueItem<T>`       | Item interface type              |
+| `Priority`           | Priority type alias              |
 
-1. `"high"`
-2. `"medium"` (default)
-3. `"low"`
+### Time Complexity
 
-Items with higher priority are dequeued before items with lower priority. Within the same priority, items are dequeued in FIFO order (first-in, first-out).
+| Operation              | Complexity |
+|------------------------|------------|
+| `enqueue`, `dequeue`, `peek`, `toArray`, `size`, `isEmpty`, `clear` | O(1) |
+| `remove`, `updatePriority`, `moveBefore`, `moveToEnd` | O(n) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/queue",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [