@hardlydifficult/queue 1.1.1 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/queue
 
-A high-performance priority queue with O(1) enqueue and dequeue operations, supporting FIFO ordering within priority levels.
+A high-performance priority queue implementation with O(1) enqueue and dequeue operations, supporting FIFO ordering within priority levels.
 
 ## Installation
 
@@ -15,180 +15,195 @@ import { createPriorityQueue } from "@hardlydifficult/queue";
 
 const queue = createPriorityQueue<string>();
 
-// Enqueue items with priorities
-queue.enqueue("urgent task", "high");
-queue.enqueue("normal task", "medium");
-queue.enqueue("background task", "low");
+queue.enqueue("low-priority", "low");
+queue.enqueue("urgent", "high");
+queue.enqueue("standard"); // defaults to 'medium'
 
-// Dequeue in priority order (high → medium → low)
-console.log(queue.dequeue()?.data); // "urgent task"
-console.log(queue.dequeue()?.data); // "normal task"
-console.log(queue.dequeue()?.data); // "background task"
+// 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"
 ```
 
-## Core Operations
+## Core API
 
-### Enqueue and Dequeue
+### createPriorityQueue
 
-Add items to the queue with a priority level (defaults to `"medium"`). Items are dequeued in priority order, with FIFO ordering within the same priority level.
+Creates a new priority queue instance.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-
-// Enqueue with explicit priority
-const item1 = queue.enqueue("task A", "high");
-const item2 = queue.enqueue("task B", "high");
-const item3 = queue.enqueue("task C", "medium");
+import { createPriorityQueue } from "@hardlydifficult/queue";
 
-// Dequeue returns highest priority first, FIFO within same priority
-queue.dequeue()?.data; // "task A" (high, enqueued first)
-queue.dequeue()?.data; // "task B" (high, enqueued second)
-queue.dequeue()?.data; // "task C" (medium)
+const queue = createPriorityQueue<number>();
 ```
 
-### Peek
+### PriorityQueue Interface
 
-Inspect the next item without removing it from the queue.
+All queue operations are provided via the `PriorityQueue<T>` interface returned by `createPriorityQueue()`.
 
-```typescript
-const queue = createPriorityQueue<string>();
-queue.enqueue("first", "high");
-queue.enqueue("second", "low");
+#### enqueue(data, priority?)
 
-queue.peek()?.data; // "first" (highest priority)
-queue.size; // Still 2
-```
+Adds an item to the queue.
 
-### Queue Status
+| Parameter | Type      | Default   | Description                  |
+|-----------|-----------|-----------|------------------------------|
+| data      | `T`       | —         | The item data to enqueue     |
+| priority  | `Priority`| `"medium"`| Priority level: `"high"`, `"medium"`, or `"low"` |
 
-Check the number of items and whether the queue is empty.
+Returns a `QueueItem<T>` with metadata including unique ID and enqueue timestamp.
 
 ```typescript
-const queue = createPriorityQueue<string>();
+const item = queue.enqueue("task", "high");
+console.log(item.id); // "q_1"
+console.log(item.priority); // "high"
+```
 
-queue.isEmpty; // true
-queue.size; // 0
+#### dequeue()
 
-queue.enqueue("item");
-queue.isEmpty; // false
-queue.size; // 1
+Removes and returns the highest-priority item (FIFO within same priority).
+
+```typescript
+const item = queue.dequeue();
+if (item) {
+  console.log(item.data); // "urgent"
+}
 ```
 
-## Item Management
+Returns `undefined` if the queue is empty.
 
-### Remove Items
+#### peek()
 
-Remove a specific item by its ID. Returns `true` if the item was found and removed.
+Returns the next item to be dequeued without removing it.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-const item = queue.enqueue("task", "high");
-
-queue.remove(item.id); // true
-queue.size; // 0
+const next = queue.peek();
+if (next) {
+  console.log(next.data); // First item to be dequeued
+}
 ```
 
-### Update Priority
+#### remove(id)
 
-Change an item's priority level while keeping its data and enqueue timestamp intact.
+Removes an item by its unique ID.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-const item = queue.enqueue("task", "low");
-
-queue.updatePriority(item.id, "high"); // true
-queue.peek()?.data; // "task" (now highest priority)
+const item = queue.enqueue("remove-me");
+const removed = queue.remove(item.id); // true
+const absent = queue.remove("unknown"); // false
 ```
 
-### Reorder Within Priority
+#### size
 
-Move an item before another item in the same priority bucket, or move it to the end of its bucket.
+Readonly property returning the total number of items in the queue.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-const a = queue.enqueue("A", "high");
-const b = queue.enqueue("B", "high");
-const c = queue.enqueue("C", "high");
+console.log(queue.size); // 5
+```
+
+#### isEmpty
 
-// Move A before C
-queue.moveBefore(a.id, c.id); // true
-queue.toArray().map(i => i.data); // ["B", "A", "C"]
+Readonly property indicating whether the queue is empty.
 
-// Move B to the end
-queue.moveToEnd(b.id); // true
-queue.toArray().map(i => i.data); // ["A", "C", "B"]
+```typescript
+console.log(queue.isEmpty); // false
 ```
 
-## Snapshots and Listeners
+#### onEnqueue(callback)
 
-### Get All Items
+Registers a callback invoked whenever an item is enqueued.
 
-Retrieve all items in dequeue order without modifying the queue.
+Returns an unsubscribe function.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-queue.enqueue("low", "low");
-queue.enqueue("high", "high");
-queue.enqueue("medium", "medium");
+const unsubscribe = queue.onEnqueue((item) => {
+  console.log("Enqueued:", item.data);
+});
+
+queue.enqueue("test");
+unsubscribe();
+queue.enqueue("ignored"); // callback no longer invoked
+```
 
+#### toArray()
+
+Returns a snapshot of all items in dequeue order (by priority, then FIFO). Does not modify the queue.
+
+```typescript
 const items = queue.toArray();
-items.map(i => i.data); // ["high", "medium", "low"]
-queue.size; // Still 3
+// Items sorted by priority: high → medium → low, then by insertion order
 ```
 
-### Listen for Enqueues
+#### clear()
 
-Register a callback that fires whenever an item is enqueued. Returns an unsubscribe function.
+Removes all items from the queue.
 
 ```typescript
-const queue = createPriorityQueue<string>();
+queue.enqueue("a");
+queue.enqueue("b");
+queue.clear();
+console.log(queue.size); // 0
+```
 
-const unsubscribe = queue.onEnqueue((item) => {
-  console.log(`Enqueued: ${item.data} (priority: ${item.priority})`);
-});
+### Priority Updates
 
-queue.enqueue("task", "high");
-// Logs: "Enqueued: task (priority: high)"
+#### updatePriority(id, newPriority)
 
-unsubscribe();
-queue.enqueue("another"); // No log
+Changes the priority of an existing item.
+
+```typescript
+const item = queue.enqueue("task", "low");
+queue.updatePriority(item.id, "high"); // true
 ```
 
-### Clear the Queue
+Returns `true` if the item was found and updated, `false` otherwise.
+
+#### moveBefore(itemId, beforeItemId)
 
-Remove all items from the queue.
+Moves an item before another item within the same priority bucket.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-queue.enqueue("a");
-queue.enqueue("b");
+const a = queue.enqueue("a", "medium");
+const b = queue.enqueue("b", "medium");
+const c = queue.enqueue("c", "medium");
 
-queue.clear();
-queue.isEmpty; // true
+queue.moveBefore(c.id, a.id); // true
+console.log(queue.toArray().map(i => i.data)); // ["c", "a", "b"]
 ```
 
-## Item Metadata
+Both items must exist and share the same priority. Returns `true` on success.
+
+#### moveToEnd(itemId)
 
-Each enqueued item includes metadata accessible via the returned `QueueItem` object:
+Moves an item to the end of its priority bucket.
 
 ```typescript
-const queue = createPriorityQueue<string>();
-const item = queue.enqueue("my task", "high");
+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"]
+```
+
+Returns `true` if the item was found (even if already at end), `false` otherwise.
 
-item.data; // "my task"
-item.priority; // "high"
-item.id; // "q_1" (unique identifier)
-item.enqueuedAt; // 1699564800000 (epoch milliseconds)
+## QueueItem Type
+
+Represents an item in the queue with metadata:
+
+```typescript
+interface QueueItem<T> {
+  data: T;
+  priority: Priority;
+  enqueuedAt: number; // epoch milliseconds
+  id: string;         // unique identifier
+}
 ```
 
-## Priority Levels
+## Priority Order
 
-The queue supports three priority levels, dequeued in this order:
+Priority levels are ordered from highest to lowest:
 
-| Priority | Dequeue Order |
-|----------|---------------|
-| `"high"` | 1st           |
-| `"medium"` | 2nd         |
-| `"low"`  | 3rd           |
+1. `"high"`
+2. `"medium"` (default)
+3. `"low"`
 
-When no priority is specified, `"medium"` is used as the default.
+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).

package/package.json

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