@hardlydifficult/queue 1.1.1 → 1.1.3

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 with O(1) enqueue/dequeue and FIFO ordering within priority levels.
 
 ## Installation
 
@@ -15,180 +15,108 @@ 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-task", "low");
+queue.enqueue("critical-task", "high");
+queue.enqueue("default-task"); // defaults to 'medium' priority
 
-// 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"
+console.log(queue.dequeue()?.data); // "critical-task"
+console.log(queue.dequeue()?.data); // "default-task"
+console.log(queue.dequeue()?.data); // "low-priority-task"
 ```
 
-## Core Operations
+## Core API
 
-### Enqueue and Dequeue
+### createPriorityQueue<T>()
 
-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");
-
-// 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)
-```
-
-### Peek
-
-Inspect the next item without removing it from the queue.
+import { createPriorityQueue } from "@hardlydifficult/queue";
 
-```typescript
 const queue = createPriorityQueue<string>();
-queue.enqueue("first", "high");
-queue.enqueue("second", "low");
-
-queue.peek()?.data; // "first" (highest priority)
-queue.size; // Still 2
 ```
 
-### Queue Status
+### PriorityQueue<T> Methods
 
-Check the number of items and whether the queue is empty.
+| Method | Description |
+|--------|-------------|
+| `enqueue(data, priority?)` | Add an item to the queue (default priority: `"medium"`) |
+| `dequeue()` | Remove and return the highest-priority item (FIFO within same priority) |
+| `peek()` | View the next item without removing it |
+| `remove(id)` | Remove a specific item by its ID |
+| `size` | Number of items in the queue |
+| `isEmpty` | Whether the queue is empty |
+| `onEnqueue(callback)` | Register a callback for enqueue events |
+| `toArray()` | Get all items in dequeue order as an array |
+| `clear()` | Remove all items from the queue |
+| `updatePriority(id, newPriority)` | Change an item's priority |
+| `moveBefore(itemId, beforeItemId)` | Move an item before another in its priority bucket |
+| `moveToEnd(itemId)` | Move an item to the end of its priority bucket |
 
-```typescript
-const queue = createPriorityQueue<string>();
+### QueueItem<T>
 
-queue.isEmpty; // true
-queue.size; // 0
-
-queue.enqueue("item");
-queue.isEmpty; // false
-queue.size; // 1
-```
-
-## Item Management
-
-### Remove Items
-
-Remove a specific item by its ID. Returns `true` if the item was found and removed.
+Represents an item in the queue with metadata:
 
 ```typescript
-const queue = createPriorityQueue<string>();
-const item = queue.enqueue("task", "high");
-
-queue.remove(item.id); // true
-queue.size; // 0
+interface QueueItem<T> {
+  data: T;
+  priority: "high" | "medium" | "low";
+  enqueuedAt: number;
+  id: string;
+}
 ```
 
-### Update Priority
+### Priority Levels
 
-Change an item's priority level while keeping its data and enqueue timestamp intact.
-
-```typescript
-const queue = createPriorityQueue<string>();
-const item = queue.enqueue("task", "low");
-
-queue.updatePriority(item.id, "high"); // true
-queue.peek()?.data; // "task" (now highest priority)
-```
+Items are dequeued in priority order: `high` → `medium` → `low`. Within the same priority, items follow FIFO (first-in-first-out) order.
 
-### Reorder Within Priority
+## Observer Pattern
 
-Move an item before another item in the same priority bucket, or move it to the end of its bucket.
-
-```typescript
-const queue = createPriorityQueue<string>();
-const a = queue.enqueue("A", "high");
-const b = queue.enqueue("B", "high");
-const c = queue.enqueue("C", "high");
-
-// Move A before C
-queue.moveBefore(a.id, c.id); // true
-queue.toArray().map(i => i.data); // ["B", "A", "C"]
-
-// Move B to the end
-queue.moveToEnd(b.id); // true
-queue.toArray().map(i => i.data); // ["A", "C", "B"]
-```
-
-## Snapshots and Listeners
-
-### Get All Items
-
-Retrieve all items in dequeue order without modifying the queue.
-
-```typescript
-const queue = createPriorityQueue<string>();
-queue.enqueue("low", "low");
-queue.enqueue("high", "high");
-queue.enqueue("medium", "medium");
-
-const items = queue.toArray();
-items.map(i => i.data); // ["high", "medium", "low"]
-queue.size; // Still 3
-```
-
-### Listen for Enqueues
-
-Register a callback that fires whenever an item is enqueued. Returns an unsubscribe function.
+Register callbacks to be notified when items are enqueued:
 
 ```typescript
 const queue = createPriorityQueue<string>();
 
 const unsubscribe = queue.onEnqueue((item) => {
-  console.log(`Enqueued: ${item.data} (priority: ${item.priority})`);
+  console.log(`Enqueued item: ${item.data}`);
 });
 
-queue.enqueue("task", "high");
-// Logs: "Enqueued: task (priority: high)"
+queue.enqueue("new task");
 
-unsubscribe();
-queue.enqueue("another"); // No log
+unsubscribe(); // stop notifications
 ```
 
-### Clear the Queue
+## Priority Manipulation
 
-Remove all items from the queue.
+Update priority and reorder items after enqueue:
 
 ```typescript
 const queue = createPriorityQueue<string>();
-queue.enqueue("a");
-queue.enqueue("b");
 
-queue.clear();
-queue.isEmpty; // true
-```
+const a = queue.enqueue("task-a", "low");
+queue.enqueue("task-b", "low");
+queue.enqueue("task-c", "low");
 
-## Item Metadata
+// Move 'task-a' to high priority
+queue.updatePriority(a.id, "high");
 
-Each enqueued item includes metadata accessible via the returned `QueueItem` object:
-
-```typescript
-const queue = createPriorityQueue<string>();
-const item = queue.enqueue("my task", "high");
-
-item.data; // "my task"
-item.priority; // "high"
-item.id; // "q_1" (unique identifier)
-item.enqueuedAt; // 1699564800000 (epoch milliseconds)
+// Move 'task-c' before 'task-b' in the low bucket
+queue.moveBefore(queue.toArray()[2].id, queue.toArray()[1].id);
 ```
 
-## Priority Levels
+## Reference
 
-The queue supports three priority levels, dequeued in this order:
+### Priority Order
 
 | Priority | Dequeue Order |
 |----------|---------------|
-| `"high"` | 1st           |
-| `"medium"` | 2nd         |
-| `"low"`  | 3rd           |
+| `"high"` | First |
+| `"medium"` | Second |
+| `"low"` | Last |
+
+### Time Complexity
 
-When no priority is specified, `"medium"` is used as the default.
+- `enqueue`: O(1)
+- `dequeue`: O(1)
+- `remove`, `updatePriority`, `moveBefore`, `moveToEnd`: O(n)
+- `toArray`, `peek`: O(1)

package/package.json

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