add type-checking and first-class TypeScript types

Author: mourner

.gitignore

@@ -1,6 +1,3 @@
 *.log
-yarn.lock
-pnpm-lock.yaml
-pacakge-lock.json
 node_modules
-index.umd.js
+index.d.ts

index.d.ts

@@ -1,32 +1,56 @@
 
+/** @template T */
 export default class FlatQueue {
 
     constructor() {
+        /** @type T[] */
         this.ids = [];
+
+        /** @type number[] */
         this.values = [];
+
+        /** Number of items in the queue. */
         this.length = 0;
     }
 
+    /**
+     * Removes all items from the queue.
+     */
     clear() {
         this.length = 0;
     }
 
-    push(id, value) {
+    /**
+     * Adds `item` to the queue with the specified `priority`.
+     *
+     * `priority` must be a number. Items are sorted and returned from low to
+     * high priority. Multiple items with the same priority value can be added
+     * to the queue, but there is no guaranteed order between these items.
+     *
+     * @param {T} item
+     * @param {number} priority
+     */
+    push(item, priority) {
         let pos = this.length++;
 
         while (pos > 0) {
             const parent = (pos - 1) >> 1;
             const parentValue = this.values[parent];
-            if (value >= parentValue) break;
+            if (priority >= parentValue) break;
             this.ids[pos] = this.ids[parent];
             this.values[pos] = parentValue;
             pos = parent;
         }
 
-        this.ids[pos] = id;
-        this.values[pos] = value;
+        this.ids[pos] = item;
+        this.values[pos] = priority;
     }
 
+    /**
+     * Removes and returns the item from the head of this queue, which is one of
+     * the items with the lowest priority. If this queue is empty, returns
+     * `undefined`.
+     */
     pop() {
         if (this.length === 0) return undefined;
 
@@ -58,16 +82,32 @@ export default class FlatQueue {
         return top;
     }
 
+    /**
+     * Returns the item from the head of this queue without removing it. If this
+     * queue is empty, returns `undefined`.
+     */
     peek() {
         if (this.length === 0) return undefined;
         return this.ids[0];
     }
 
+    /**
+     * Returns the priority value of the item at the head of this queue without
+     * removing it. If this queue is empty, returns `undefined`.
+     */
     peekValue() {
         if (this.length === 0) return undefined;
         return this.values[0];
     }
 
+    /**
+     * Shrinks the internal arrays to `this.length`.
+     *
+     * `pop()` and `clear()` calls don't free memory automatically to avoid
+     * unnecessary resize operations. This also means that items that have been
+     * added to the queue can't be garbage collected until a new item is pushed
+     * in their place, or this method is called.
+     */
     shrink() {
         this.ids.length = this.values.length = this.length;
     }

index.js

@@ -12,11 +12,12 @@
   "types": "./index.d.ts",
   "devDependencies": {
     "eslint": "^9.32.0",
-    "eslint-config-mourner": "^4.1.0"
+    "eslint-config-mourner": "^4.1.0",
+    "typescript": "^5.9.2"
   },
   "scripts": {
     "pretest": "eslint index.js test.js",
-    "test": "node test.js"
+    "test": "tsc && node test.js"
   },
   "files": [
     "index.js",

package-lock.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "allowJs": true,
+        "checkJs": true,
+        "strict": true,
+        "emitDeclarationOnly": true,
+        "declaration": true,
+        "target": "es2017",
+        "module": "nodenext",
+        "moduleResolution": "nodenext"
+    },
+    "files": [
+        "index.js"
+    ]
+}