@hardlydifficult/queue 1.0.0

package/dist/PriorityQueue.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Prioritized FIFO queue.
+ *
+ * Items with higher priority are dequeued first.
+ * Within the same priority level, items are dequeued in insertion order (FIFO).
+ *
+ * Uses a multi-bucket approach: one array per priority level.
+ * O(1) enqueue, O(1) dequeue.
+ */
+/**
+ * Priority levels for the queue.
+ * Dequeue order: high first, then medium, then low.
+ */
+export type Priority = "high" | "medium" | "low";
+/**
+ * An item in the queue with metadata.
+ */
+export interface QueueItem<T> {
+    /** The queued data */
+    readonly data: T;
+    /** Priority level */
+    readonly priority: Priority;
+    /** When the item was enqueued (epoch ms) */
+    readonly enqueuedAt: number;
+    /** Unique identifier for this queue entry */
+    readonly id: string;
+}
+/**
+ * A prioritized FIFO queue.
+ *
+ * Items with higher priority are dequeued first.
+ * Within the same priority, items are dequeued in insertion order (FIFO).
+ */
+export interface PriorityQueue<T> {
+    /**
+     * Add an item to the queue.
+     * @param data - The item data
+     * @param priority - Priority level (default: 'medium')
+     * @returns The queued item with metadata
+     */
+    enqueue(data: T, priority?: Priority): QueueItem<T>;
+    /**
+     * Remove and return the highest-priority item (FIFO within same priority).
+     * Returns undefined if the queue is empty.
+     */
+    dequeue(): QueueItem<T> | undefined;
+    /**
+     * Peek at the next item without removing it.
+     * Returns undefined if the queue is empty.
+     */
+    peek(): QueueItem<T> | undefined;
+    /**
+     * Remove a specific item by its ID.
+     * @returns true if the item was found and removed
+     */
+    remove(id: string): boolean;
+    /** Number of items currently in the queue. */
+    readonly size: number;
+    /** Whether the queue is empty. */
+    readonly isEmpty: boolean;
+    /**
+     * Register a callback invoked whenever an item is enqueued.
+     * @returns An unsubscribe function.
+     */
+    onEnqueue(callback: (item: QueueItem<T>) => void): () => void;
+    /**
+     * Get all items in the queue ordered by dequeue priority.
+     * Returns a snapshot; does not modify the queue.
+     */
+    toArray(): readonly QueueItem<T>[];
+    /** Clear all items from the queue. */
+    clear(): void;
+}
+/**
+ * Create a new priority queue.
+ */
+export declare function createPriorityQueue<T>(): PriorityQueue<T>;
+//# sourceMappingURL=PriorityQueue.d.ts.map

package/dist/PriorityQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PriorityQueue.d.ts","sourceRoot":"","sources":["../src/PriorityQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAKjD;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAEpD;;;OAGG;IACH,OAAO,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpC;;;OAGG;IACH,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEjC;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAE9D;;;OAGG;IACH,OAAO,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IAEnC,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAkFzD"}

package/dist/PriorityQueue.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Prioritized FIFO queue.
+ *
+ * Items with higher priority are dequeued first.
+ * Within the same priority level, items are dequeued in insertion order (FIFO).
+ *
+ * Uses a multi-bucket approach: one array per priority level.
+ * O(1) enqueue, O(1) dequeue.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPriorityQueue = createPriorityQueue;
+/** All priority levels in dequeue order (highest first). */
+const PRIORITY_ORDER = ["high", "medium", "low"];
+/**
+ * Create a new priority queue.
+ */
+function createPriorityQueue() {
+    const buckets = {
+        high: [],
+        medium: [],
+        low: [],
+    };
+    const listeners = new Set();
+    let counter = 0;
+    function getSize() {
+        return buckets.high.length + buckets.medium.length + buckets.low.length;
+    }
+    return {
+        enqueue(data, priority = "medium") {
+            const item = {
+                data,
+                priority,
+                enqueuedAt: Date.now(),
+                id: `q_${String(++counter)}`,
+            };
+            buckets[priority].push(item);
+            for (const cb of listeners) {
+                cb(item);
+            }
+            return item;
+        },
+        dequeue() {
+            for (const p of PRIORITY_ORDER) {
+                if (buckets[p].length > 0) {
+                    return buckets[p].shift();
+                }
+            }
+            return undefined;
+        },
+        peek() {
+            for (const p of PRIORITY_ORDER) {
+                if (buckets[p].length > 0) {
+                    return buckets[p][0];
+                }
+            }
+            return undefined;
+        },
+        remove(id) {
+            for (const p of PRIORITY_ORDER) {
+                const idx = buckets[p].findIndex((item) => item.id === id);
+                if (idx !== -1) {
+                    buckets[p].splice(idx, 1);
+                    return true;
+                }
+            }
+            return false;
+        },
+        get size() {
+            return getSize();
+        },
+        get isEmpty() {
+            return getSize() === 0;
+        },
+        onEnqueue(callback) {
+            listeners.add(callback);
+            return () => {
+                listeners.delete(callback);
+            };
+        },
+        toArray() {
+            return [...buckets.high, ...buckets.medium, ...buckets.low];
+        },
+        clear() {
+            buckets.high.length = 0;
+            buckets.medium.length = 0;
+            buckets.low.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=PriorityQueue.js.map

package/dist/PriorityQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PriorityQueue.js","sourceRoot":"","sources":["../src/PriorityQueue.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createPriorityQueue, type PriorityQueue, type QueueItem, type Priority, } from "./PriorityQueue";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,QAAQ,GACd,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPriorityQueue = void 0;
+var PriorityQueue_1 = require("./PriorityQueue");
+Object.defineProperty(exports, "createPriorityQueue", { enumerable: true, get: function () { return PriorityQueue_1.createPriorityQueue; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAKyB;AAJvB,oHAAA,mBAAmB,OAAA"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hardlydifficult/queue",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.31",
+    "typescript": "5.8.3",
+    "vitest": "1.6.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}