queue-typed 2.4.3 → 2.4.5

package/dist/cjs-legacy/index.cjs

@@ -5,6 +5,54 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
+// src/common/error.ts
+var ERR = {
+  // Range / index
+  indexOutOfRange: /* @__PURE__ */ __name((index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`, "indexOutOfRange"),
+  invalidIndex: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`, "invalidIndex"),
+  // Type / argument
+  invalidArgument: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidArgument"),
+  comparatorRequired: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`, "comparatorRequired"),
+  invalidKey: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidKey"),
+  notAFunction: /* @__PURE__ */ __name((name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`, "notAFunction"),
+  invalidEntry: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`, "invalidEntry"),
+  invalidNaN: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`, "invalidNaN"),
+  invalidDate: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`, "invalidDate"),
+  reduceEmpty: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`, "reduceEmpty"),
+  callbackReturnType: /* @__PURE__ */ __name((expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`, "callbackReturnType"),
+  // State / operation
+  invalidOperation: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidOperation"),
+  // Matrix
+  matrixDimensionMismatch: /* @__PURE__ */ __name((op) => `Matrix: Dimensions must be compatible for ${op}.`, "matrixDimensionMismatch"),
+  matrixSingular: /* @__PURE__ */ __name(() => "Matrix: Singular matrix, inverse does not exist.", "matrixSingular"),
+  matrixNotSquare: /* @__PURE__ */ __name(() => "Matrix: Must be square for inversion.", "matrixNotSquare"),
+  matrixNotRectangular: /* @__PURE__ */ __name(() => "Matrix: Must be rectangular for transposition.", "matrixNotRectangular"),
+  matrixRowMismatch: /* @__PURE__ */ __name((expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`, "matrixRowMismatch")
+};
+
+// src/common/index.ts
+var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+  DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+  DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+  return DFSOperation2;
+})(DFSOperation || {});
+var _Range = class _Range {
+  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;
+  }
+};
+__name(_Range, "Range");
+var Range = _Range;
+
 // src/data-structures/base/iterable-element-base.ts
 var _IterableElementBase = class _IterableElementBase {
   /**
@@ -27,7 +75,7 @@ var _IterableElementBase = class _IterableElementBase {
     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"));
     }
   }
   /**
@@ -183,7 +231,7 @@ var _IterableElementBase = class _IterableElementBase {
       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;
     }
@@ -656,7 +704,7 @@ var _SinglyLinkedList = class _SinglyLinkedList extends LinearLinkedBase {
    */
   constructor(elements = [], options) {
     super(options);
-    __publicField(this, "_equals", Object.is);
+    __publicField(this, "_equals", /* @__PURE__ */ __name((a, b) => Object.is(a, b), "_equals"));
     __publicField(this, "_head");
     __publicField(this, "_tail");
     __publicField(this, "_length", 0);
@@ -744,6 +792,7 @@ var _SinglyLinkedList = class _SinglyLinkedList extends LinearLinkedBase {
    * @returns Removed element or undefined.
    */
   pop() {
+    var _a;
     if (!this.head) return void 0;
     if (this.head === this.tail) {
       const value2 = this.head.value;
@@ -753,8 +802,8 @@ var _SinglyLinkedList = class _SinglyLinkedList extends LinearLinkedBase {
       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--;
@@ -842,8 +891,8 @@ var _SinglyLinkedList = class _SinglyLinkedList extends LinearLinkedBase {
   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.
@@ -863,7 +912,7 @@ var _SinglyLinkedList = class _SinglyLinkedList extends LinearLinkedBase {
   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;
   }
   /**
@@ -1700,24 +1749,25 @@ __name(_LinkedListQueue, "LinkedListQueue");
 var LinkedListQueue = _LinkedListQueue;
 
 // src/utils/utils.ts
-var rangeCheck = /* @__PURE__ */ __name((index, min, max, message = "Index out of bounds.") => {
-  if (index < min || index > max) throw new RangeError(message);
+var rangeCheck = /* @__PURE__ */ __name((index, min, max, message) => {
+  if (index < min || index > max) {
+    throw new RangeError(message != null ? message : `Index ${index} is out of range [${min}, ${max}].`);
+  }
 }, "rangeCheck");
 var calcMinUnitsRequired = /* @__PURE__ */ __name((totalQuantity, unitSize) => Math.floor((totalQuantity + unitSize - 1) / unitSize), "calcMinUnitsRequired");
 
 // src/data-structures/queue/deque.ts
 var _Deque = class _Deque 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", /* @__PURE__ */ __name((a, b) => Object.is(a, b), "_equals"));
     __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);
@@ -1726,8 +1776,9 @@ var _Deque = class _Deque extends LinearBase {
     __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) {
@@ -1752,6 +1803,24 @@ var _Deque = class _Deque extends LinearBase {
   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)
@@ -1883,6 +1952,7 @@ var _Deque = class _Deque extends LinearBase {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
   /**
@@ -1905,6 +1975,7 @@ var _Deque = class _Deque extends LinearBase {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
   /**
@@ -2237,11 +2308,40 @@ var _Deque = class _Deque extends LinearBase {
    * @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]);
       }
@@ -2256,6 +2356,8 @@ var _Deque = class _Deque extends LinearBase {
     this._bucketFirst = 0;
     this._bucketLast = newBuckets.length - 1;
     this._buckets = newBuckets;
+    this._bucketCount = newBuckets.length;
+    this._compactCounter = 0;
   }
   /**
    * Deep clone this deque, preserving options.
@@ -2437,29 +2539,6 @@ var _Deque = class _Deque extends LinearBase {
 };
 __name(_Deque, "Deque");
 var Deque = _Deque;
-
-// src/common/index.ts
-var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
-  DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
-  DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
-  return DFSOperation2;
-})(DFSOperation || {});
-var _Range = class _Range {
-  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;
-  }
-};
-__name(_Range, "Range");
-var Range = _Range;
 /**
  * data-structure-typed
  *
@@ -2470,6 +2549,7 @@ var Range = _Range;
 
 exports.DFSOperation = DFSOperation;
 exports.Deque = Deque;
+exports.ERR = ERR;
 exports.LinkedListQueue = LinkedListQueue;
 exports.Queue = Queue;
 exports.Range = Range;