queue-typed 2.4.3 → 2.4.5

package/dist/umd/queue-typed.js

@@ -25,11 +25,58 @@ var queueTyped = (() => {
   __export(src_exports, {
     DFSOperation: () => DFSOperation,
     Deque: () => Deque,
+    ERR: () => ERR,
     LinkedListQueue: () => LinkedListQueue,
     Queue: () => Queue,
     Range: () => Range
   });
 
+  // src/common/error.ts
+  var ERR = {
+    // Range / index
+    indexOutOfRange: (index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`,
+    invalidIndex: (ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`,
+    // Type / argument
+    invalidArgument: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    comparatorRequired: (ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`,
+    invalidKey: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    notAFunction: (name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`,
+    invalidEntry: (ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`,
+    invalidNaN: (ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`,
+    invalidDate: (ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`,
+    reduceEmpty: (ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`,
+    callbackReturnType: (expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`,
+    // State / operation
+    invalidOperation: (reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`,
+    // Matrix
+    matrixDimensionMismatch: (op) => `Matrix: Dimensions must be compatible for ${op}.`,
+    matrixSingular: () => "Matrix: Singular matrix, inverse does not exist.",
+    matrixNotSquare: () => "Matrix: Must be square for inversion.",
+    matrixNotRectangular: () => "Matrix: Must be rectangular for transposition.",
+    matrixRowMismatch: (expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`
+  };
+
+  // src/common/index.ts
+  var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+    DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+    DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+    return DFSOperation2;
+  })(DFSOperation || {});
+  var Range = class {
+    constructor(low, high, includeLow = true, includeHigh = true) {
+      this.low = low;
+      this.high = high;
+      this.includeLow = includeLow;
+      this.includeHigh = includeHigh;
+    }
+    // Determine whether a key is within the range
+    isInRange(key, comparator) {
+      const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+      const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+      return lowCheck && highCheck;
+    }
+  };
+
   // src/data-structures/base/iterable-element-base.ts
   var IterableElementBase = class {
     /**
@@ -52,7 +99,7 @@ var queueTyped = (() => {
       if (options) {
         const { toElementFn } = options;
         if (typeof toElementFn === "function") this._toElementFn = toElementFn;
-        else if (toElementFn) throw new TypeError("toElementFn must be a function type");
+        else if (toElementFn) throw new TypeError(ERR.notAFunction("toElementFn"));
       }
     }
     /**
@@ -208,7 +255,7 @@ var queueTyped = (() => {
         acc = initialValue;
       } else {
         const first = iter.next();
-        if (first.done) throw new TypeError("Reduce of empty structure with no initial value");
+        if (first.done) throw new TypeError(ERR.reduceEmpty());
         acc = first.value;
         index = 1;
       }
@@ -671,7 +718,7 @@ var queueTyped = (() => {
      */
     constructor(elements = [], options) {
       super(options);
-      __publicField(this, "_equals", Object.is);
+      __publicField(this, "_equals", (a, b) => Object.is(a, b));
       __publicField(this, "_head");
       __publicField(this, "_tail");
       __publicField(this, "_length", 0);
@@ -759,6 +806,7 @@ var queueTyped = (() => {
      * @returns Removed element or undefined.
      */
     pop() {
+      var _a;
       if (!this.head) return void 0;
       if (this.head === this.tail) {
         const value2 = this.head.value;
@@ -768,8 +816,8 @@ var queueTyped = (() => {
         return value2;
       }
       let current = this.head;
-      while (current.next !== this.tail) current = current.next;
-      const value = this.tail.value;
+      while (current.next && current.next !== this.tail) current = current.next;
+      const value = (_a = this.tail) == null ? void 0 : _a.value;
       current.next = void 0;
       this._tail = current;
       this._length--;
@@ -857,8 +905,8 @@ var queueTyped = (() => {
     at(index) {
       if (index < 0 || index >= this._length) return void 0;
       let current = this.head;
-      for (let i = 0; i < index; i++) current = current.next;
-      return current.value;
+      for (let i = 0; i < index && current; i++) current = current.next;
+      return current == null ? void 0 : current.value;
     }
     /**
      * Type guard: check whether the input is a SinglyLinkedListNode.
@@ -878,7 +926,7 @@ var queueTyped = (() => {
     getNodeAt(index) {
       if (index < 0 || index >= this._length) return void 0;
       let current = this.head;
-      for (let i = 0; i < index; i++) current = current.next;
+      for (let i = 0; i < index && current; i++) current = current.next;
       return current;
     }
     /**
@@ -1708,24 +1756,25 @@ var queueTyped = (() => {
   };
 
   // src/utils/utils.ts
-  var rangeCheck = (index, min, max, message = "Index out of bounds.") => {
-    if (index < min || index > max) throw new RangeError(message);
+  var rangeCheck = (index, min, max, message) => {
+    if (index < min || index > max) {
+      throw new RangeError(message != null ? message : `Index ${index} is out of range [${min}, ${max}].`);
+    }
   };
   var calcMinUnitsRequired = (totalQuantity, unitSize) => Math.floor((totalQuantity + unitSize - 1) / unitSize);
 
   // src/data-structures/queue/deque.ts
   var Deque = class extends LinearBase {
-    /**
-     * Create a Deque and optionally bulk-insert elements.
-     * @remarks Time O(N), Space O(N)
-     * @param [elements] - Iterable (or iterable-like) of elements/records to insert.
-     * @param [options] - Options such as bucketSize, toElementFn, and maxLen.
-     * @returns New Deque instance.
-     */
     constructor(elements = [], options) {
       super(options);
-      __publicField(this, "_equals", Object.is);
+      __publicField(this, "_equals", (a, b) => Object.is(a, b));
       __publicField(this, "_bucketSize", 1 << 12);
+      __publicField(this, "_autoCompactRatio", 0.5);
+      /**
+       * Counter for shift/pop operations since last compaction check.
+       * Only checks ratio every `_bucketSize` operations to minimize overhead.
+       */
+      __publicField(this, "_compactCounter", 0);
       __publicField(this, "_bucketFirst", 0);
       __publicField(this, "_firstInBucket", 0);
       __publicField(this, "_bucketLast", 0);
@@ -1734,8 +1783,9 @@ var queueTyped = (() => {
       __publicField(this, "_buckets", []);
       __publicField(this, "_length", 0);
       if (options) {
-        const { bucketSize } = options;
+        const { bucketSize, autoCompactRatio } = options;
         if (typeof bucketSize === "number") this._bucketSize = bucketSize;
+        if (typeof autoCompactRatio === "number") this._autoCompactRatio = autoCompactRatio;
       }
       let _size;
       if ("length" in elements) {
@@ -1760,6 +1810,24 @@ var queueTyped = (() => {
     get bucketSize() {
       return this._bucketSize;
     }
+    /**
+     * Get the auto-compaction ratio.
+     * When `elements / (bucketCount * bucketSize)` drops below this ratio after
+     * enough shift/pop operations, the deque auto-compacts.
+     * @remarks Time O(1), Space O(1)
+     * @returns Current ratio threshold. 0 means auto-compact is disabled.
+     */
+    get autoCompactRatio() {
+      return this._autoCompactRatio;
+    }
+    /**
+     * Set the auto-compaction ratio.
+     * @remarks Time O(1), Space O(1)
+     * @param value - Ratio in [0,1]. 0 disables auto-compact.
+     */
+    set autoCompactRatio(value) {
+      this._autoCompactRatio = value;
+    }
     /**
      * Get the index of the first bucket in use.
      * @remarks Time O(1), Space O(1)
@@ -1891,6 +1959,7 @@ var queueTyped = (() => {
         }
       }
       this._length -= 1;
+      this._autoCompact();
       return element;
     }
     /**
@@ -1913,6 +1982,7 @@ var queueTyped = (() => {
         }
       }
       this._length -= 1;
+      this._autoCompact();
       return element;
     }
     /**
@@ -2245,11 +2315,40 @@ var queueTyped = (() => {
      * @remarks Time O(N), Space O(1)
      * @returns void
      */
+    /**
+     * (Protected) Trigger auto-compaction if space utilization drops below threshold.
+     * Only checks every `_bucketSize` operations to minimize hot-path overhead.
+     * Uses element-based ratio: `elements / (bucketCount * bucketSize)`.
+     */
+    _autoCompact() {
+      if (this._autoCompactRatio <= 0 || this._bucketCount <= 1) return;
+      this._compactCounter++;
+      if (this._compactCounter < this._bucketSize) return;
+      this._compactCounter = 0;
+      const utilization = this._length / (this._bucketCount * this._bucketSize);
+      if (utilization < this._autoCompactRatio) {
+        this.shrinkToFit();
+      }
+    }
+    /**
+     * Compact the deque by removing unused buckets.
+     * @remarks Time O(N), Space O(1)
+     * @returns True if compaction was performed (bucket count reduced).
+     */
+    /**
+     * Compact the deque by removing unused buckets.
+     * @remarks Time O(N), Space O(1)
+     * @returns True if compaction was performed (bucket count reduced).
+     */
+    compact() {
+      const before = this._bucketCount;
+      this.shrinkToFit();
+      return this._bucketCount < before;
+    }
     shrinkToFit() {
       if (this._length === 0) return;
       const newBuckets = [];
-      if (this._bucketFirst === this._bucketLast) return;
-      else if (this._bucketFirst < this._bucketLast) {
+      if (this._bucketFirst <= this._bucketLast) {
         for (let i = this._bucketFirst; i <= this._bucketLast; ++i) {
           newBuckets.push(this._buckets[i]);
         }
@@ -2264,6 +2363,8 @@ var queueTyped = (() => {
       this._bucketFirst = 0;
       this._bucketLast = newBuckets.length - 1;
       this._buckets = newBuckets;
+      this._bucketCount = newBuckets.length;
+      this._compactCounter = 0;
     }
     /**
      * Deep clone this deque, preserving options.
@@ -2443,27 +2544,6 @@ var queueTyped = (() => {
       }
     }
   };
-
-  // src/common/index.ts
-  var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
-    DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
-    DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
-    return DFSOperation2;
-  })(DFSOperation || {});
-  var Range = class {
-    constructor(low, high, includeLow = true, includeHigh = true) {
-      this.low = low;
-      this.high = high;
-      this.includeLow = includeLow;
-      this.includeHigh = includeHigh;
-    }
-    // Determine whether a key is within the range
-    isInRange(key, comparator) {
-      const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
-      const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
-      return lowCheck && highCheck;
-    }
-  };
   return __toCommonJS(src_exports);
 })();
 /**