data-structure-typed 2.4.3 → 2.4.5

package/src/data-structures/linked-list/doubly-linked-list.ts

@@ -182,7 +182,7 @@ export class DoublyLinkedListNode<E = any> extends LinkedListNode<E> {
  *     console.log(foundEntry?.value); // 'Bob';
  */
 export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, DoublyLinkedListNode<E>> {
-  protected _equals: (a: E, b: E) => boolean = Object.is as unknown as (a: E, b: E) => boolean;
+  protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
 
   /**
    * Create a DoublyLinkedList and optionally bulk-insert elements.
@@ -423,8 +423,8 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
   at(index: number): E | undefined {
     if (index < 0 || index >= this._length) return undefined;
     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?.value;
   }
 
   /**
@@ -437,7 +437,7 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
   getNodeAt(index: number): DoublyLinkedListNode<E> | undefined {
     if (index < 0 || index >= this._length) return undefined;
     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;
   }
 

package/src/data-structures/linked-list/singly-linked-list.ts

@@ -246,7 +246,7 @@ export class SinglyLinkedListNode<E = any> extends LinkedListNode<E> {
  *     console.log(editor.getText()); // 'Haello';
  */
 export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, SinglyLinkedListNode<E>> {
-  protected _equals: (a: E, b: E) => boolean = Object.is as unknown as (a: E, b: E) => boolean;
+  protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
 
   /**
    * Create a SinglyLinkedList and optionally bulk-insert elements.
@@ -381,8 +381,8 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
       return value;
     }
     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 = this.tail?.value;
     current.next = undefined;
     this._tail = current;
     this._length--;
@@ -484,8 +484,8 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
   at(index: number): E | undefined {
     if (index < 0 || index >= this._length) return undefined;
     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?.value;
   }
 
   /**
@@ -511,7 +511,7 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
   getNodeAt(index: number): SinglyLinkedListNode<E> | undefined {
     if (index < 0 || index >= this._length) return undefined;
     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;
   }
 
@@ -1003,7 +1003,10 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    */
 
   protected _createInstance(options?: SinglyLinkedListOptions<E, R>): this {
-    const Ctor: any = this.constructor;
+    const Ctor = this.constructor as new (
+      elements?: Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>,
+      options?: SinglyLinkedListOptions<E, R>
+    ) => this;
     return new Ctor([], options);
   }
 
@@ -1021,8 +1024,11 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
     elements: Iterable<EM> | Iterable<RM> | Iterable<SinglyLinkedListNode<EM>> = [],
     options?: SinglyLinkedListOptions<EM, RM>
   ): SinglyLinkedList<EM, RM> {
-    const Ctor: any = this.constructor;
-    return new Ctor(elements, options) as SinglyLinkedList<EM, RM>;
+    const Ctor = this.constructor as new (
+      elements?: Iterable<EM> | Iterable<RM> | Iterable<SinglyLinkedListNode<EM>>,
+      options?: SinglyLinkedListOptions<EM, RM>
+    ) => SinglyLinkedList<EM, RM>;
+    return new Ctor(elements, options);
   }
 
   /**

package/src/data-structures/matrix/matrix.ts

@@ -6,6 +6,7 @@
  * @license MIT License
  */
 import type { MatrixOptions } from '../../types';
+import { ERR } from '../../common';
 
 /**
  *
@@ -150,7 +151,7 @@ export class Matrix {
    */
   add(matrix: Matrix): Matrix | undefined {
     if (!this.isMatchForCalculate(matrix)) {
-      throw new Error('Matrix dimensions must match for addition.');
+      throw new Error(ERR.matrixDimensionMismatch('addition'));
     }
 
     const resultData: number[][] = [];
@@ -186,7 +187,7 @@ export class Matrix {
    */
   subtract(matrix: Matrix): Matrix | undefined {
     if (!this.isMatchForCalculate(matrix)) {
-      throw new Error('Matrix dimensions must match for subtraction.');
+      throw new Error(ERR.matrixDimensionMismatch('subtraction'));
     }
 
     const resultData: number[][] = [];
@@ -221,7 +222,7 @@ export class Matrix {
    */
   multiply(matrix: Matrix): Matrix | undefined {
     if (this.cols !== matrix.rows) {
-      throw new Error('Matrix dimensions must be compatible for multiplication (A.cols = B.rows).');
+      throw new Error(ERR.matrixDimensionMismatch('multiplication (A.cols must equal B.rows)'));
     }
 
     const resultData: number[][] = [];
@@ -259,7 +260,7 @@ export class Matrix {
    */
   transpose(): Matrix {
     if (this.data.some(row => row.length !== this.rows)) {
-      throw new Error('Matrix must be rectangular for transposition.');
+      throw new Error(ERR.matrixNotRectangular());
     }
 
     const resultData: number[][] = [];
@@ -288,7 +289,7 @@ export class Matrix {
   inverse(): Matrix | undefined {
     // Check if the matrix is square
     if (this.rows !== this.cols) {
-      throw new Error('Matrix must be square for inversion.');
+      throw new Error(ERR.matrixNotSquare());
     }
 
     // Create an augmented matrix [this | I]
@@ -318,7 +319,7 @@ export class Matrix {
 
       if (pivotRow === this.rows) {
         // Matrix is singular, and its inverse does not exist
-        throw new Error('Matrix is singular, and its inverse does not exist.');
+        throw new Error(ERR.matrixSingular());
       }
 
       // Swap rows to make the pivot the current row
@@ -329,7 +330,7 @@ export class Matrix {
 
       if (pivotElement === 0) {
         // Handle division by zero
-        throw new Error('Matrix is singular, and its inverse does not exist (division by zero).');
+        throw new Error(ERR.matrixSingular());
       }
 
       augmentedMatrix._scaleRow(i, 1 / pivotElement);
@@ -367,9 +368,7 @@ export class Matrix {
    */
   dot(matrix: Matrix): Matrix | undefined {
     if (this.cols !== matrix.rows) {
-      throw new Error(
-        'Number of columns in the first matrix must be equal to the number of rows in the second matrix for dot product.'
-      );
+      throw new Error(ERR.matrixDimensionMismatch('dot product (A.cols must equal B.rows)'));
     }
 
     const resultData: number[][] = [];

package/src/data-structures/priority-queue/max-priority-queue.ts

@@ -7,6 +7,7 @@
  */
 import type { PriorityQueueOptions } from '../../types';
 import { PriorityQueue } from './priority-queue';
+import { ERR } from '../../common';
 
 /**
  * Max-oriented priority queue (max-heap) built on {@link PriorityQueue}.
@@ -28,9 +29,7 @@ export class MaxPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
     super(elements, {
       comparator: (a: E, b: E): number => {
         if (typeof a === 'object' || typeof b === 'object') {
-          throw TypeError(
-            `When comparing object types, a custom comparator must be defined in the constructor's options parameter.`
-          );
+          throw new TypeError(ERR.comparatorRequired('MaxPriorityQueue'));
         }
         if (a < b) return 1;
         if (a > b) return -1;

package/src/data-structures/queue/deque.ts

@@ -144,7 +144,7 @@ import { LinearBase } from '../base/linear-base';
  *     console.log(dataWindow.length); // 3;
  */
 export class Deque<E = any, R = any> extends LinearBase<E, R> {
-  protected _equals: (a: E, b: E) => boolean = Object.is as unknown as (a: E, b: E) => boolean;
+  protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
 
   /**
    * Create a Deque and optionally bulk-insert elements.
@@ -154,12 +154,15 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @returns New Deque instance.
    */
 
+  constructor(elements?: IterableWithSizeOrLength<E>, options?: DequeOptions<E, R>);
+  constructor(elements: IterableWithSizeOrLength<R>, options: DequeOptions<E, R> & { toElementFn: (rawElement: R) => E });
   constructor(elements: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R> = [], options?: DequeOptions<E, R>) {
     super(options);
 
     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: number;
@@ -191,6 +194,34 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
     return this._bucketSize;
   }
 
+  protected _autoCompactRatio = 0.5;
+
+  /**
+   * 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(): number {
+    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: number) {
+    this._autoCompactRatio = value;
+  }
+
+  /**
+   * Counter for shift/pop operations since last compaction check.
+   * Only checks ratio every `_bucketSize` operations to minimize overhead.
+   */
+  protected _compactCounter = 0;
+
   protected _bucketFirst = 0;
 
   /**
@@ -366,6 +397,7 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
 
@@ -390,6 +422,7 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
 
@@ -768,11 +801,44 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @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)`.
+   */
+  protected _autoCompact(): void {
+    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(): boolean {
+    const before = this._bucketCount;
+    this.shrinkToFit();
+    return this._bucketCount < before;
+  }
+
   shrinkToFit(): void {
     if (this._length === 0) return;
     const newBuckets = [] as E[][];
-    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]);
       }
@@ -787,6 +853,8 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
     this._bucketFirst = 0;
     this._bucketLast = newBuckets.length - 1;
     this._buckets = newBuckets;
+    this._bucketCount = newBuckets.length;
+    this._compactCounter = 0;
   }
 
   /**

package/src/data-structures/stack/stack.ts

@@ -161,7 +161,7 @@ import { IterableElementBase } from '../base';
  *     console.log(stack.elements.join('/')); // 'c';
  */
 export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
-  protected _equals: (a: E, b: E) => boolean = Object.is as unknown as (a: E, b: E) => boolean;
+  protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
 
   /**
    * Create a Stack and optionally bulk-push elements.

package/src/data-structures/trie/trie.ts

@@ -8,6 +8,7 @@
 
 import type { ElementCallback, TrieOptions } from '../../types';
 import { IterableElementBase } from '../base';
+import { ERR } from '../../common';
 
 /**
  * Node used by Trie to store one character and its children.
@@ -651,7 +652,7 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
     for (const x of this) {
       const v = thisArg === undefined ? callback(x, i++, this) : callback.call(thisArg, x, i++, this);
       if (typeof v !== 'string') {
-        throw new TypeError(`Trie.map callback must return string; got ${typeof v}`);
+        throw new TypeError(ERR.callbackReturnType('string', typeof v, 'Trie.map'));
       }
       newTrie.add(v);
     }
@@ -684,13 +685,15 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    */
 
   protected _createInstance(options?: TrieOptions<R>): this {
-    const Ctor: any = this.constructor;
-    const next: any = new Ctor([], {
+    const Ctor = this.constructor as new (
+      elements?: Iterable<string> | Iterable<R>,
+      options?: TrieOptions<R>
+    ) => this;
+    return new Ctor([], {
       toElementFn: this.toElementFn,
       caseSensitive: this.caseSensitive,
       ...(options ?? {})
     });
-    return next as this;
   }
 
   /**
@@ -703,8 +706,11 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    */
 
   protected _createLike<RM>(elements: Iterable<string> | Iterable<RM> = [], options?: TrieOptions<RM>): Trie<RM> {
-    const Ctor: any = this.constructor;
-    return new Ctor(elements, options) as Trie<RM>;
+    const Ctor = this.constructor as new (
+      elements?: Iterable<string> | Iterable<RM>,
+      options?: TrieOptions<RM>
+    ) => Trie<RM>;
+    return new Ctor(elements, options);
   }
 
   /**

package/src/types/data-structures/binary-tree/avl-tree.ts

@@ -1,3 +1,3 @@
 import { BSTOptions } from './bst';
 
-export type AVLTreeOptions<K, V, R> = BSTOptions<K, V, R> & {};
+export type AVLTreeOptions<K, V, R> = BSTOptions<K, V, R>;

package/src/types/data-structures/binary-tree/red-black-tree.ts

@@ -2,4 +2,4 @@ import type { BSTOptions } from './bst';
 
 export type RBTNColor = 'RED' | 'BLACK';
 
-export type RedBlackTreeOptions<K, V, R> = BSTOptions<K, V, R> & {};
+export type RedBlackTreeOptions<K, V, R> = BSTOptions<K, V, R>;

package/src/types/data-structures/linked-list/doubly-linked-list.ts

@@ -1,3 +1,3 @@
 import { LinearBaseOptions } from '../base';
 
-export type DoublyLinkedListOptions<E, R> = LinearBaseOptions<E, R> & {};
+export type DoublyLinkedListOptions<E, R> = LinearBaseOptions<E, R>;

package/src/types/data-structures/linked-list/singly-linked-list.ts

@@ -1,3 +1,3 @@
 import { LinearBaseOptions } from '../base';
 
-export type SinglyLinkedListOptions<E, R> = LinearBaseOptions<E, R> & {};
+export type SinglyLinkedListOptions<E, R> = LinearBaseOptions<E, R>;

package/src/types/data-structures/priority-queue/priority-queue.ts

@@ -1,3 +1,3 @@
 import { HeapOptions } from '../heap';
 
-export type PriorityQueueOptions<E, R> = HeapOptions<E, R> & {};
+export type PriorityQueueOptions<E, R> = HeapOptions<E, R>;

package/src/types/data-structures/queue/deque.ts

@@ -2,4 +2,11 @@ import { LinearBaseOptions } from '../base';
 
 export type DequeOptions<E, R> = {
   bucketSize?: number;
+
+  /**
+   * When the ratio of used buckets to total buckets falls below this threshold
+   * after a shift/pop, auto-compact is triggered. Set to 0 to disable.
+   * Default: 0.5 (compact when less than half the buckets are in use).
+   */
+  autoCompactRatio?: number;
 } & LinearBaseOptions<E, R>;

package/src/types/data-structures/stack/stack.ts

@@ -1,3 +1,3 @@
 import { IterableElementBaseOptions } from '../base';
 
-export type StackOptions<E, R> = IterableElementBaseOptions<E, R> & {};
+export type StackOptions<E, R> = IterableElementBaseOptions<E, R>;

package/src/utils/utils.ts

@@ -77,8 +77,10 @@ export const getMSB = (value: number): number => {
  * error message to be thrown if the index is out of bounds. By default, if no message is provided when
  * calling the `rangeCheck` function, the message "Index out of bounds." will be used.
  */
-export const rangeCheck = (index: number, min: number, max: number, message = 'Index out of bounds.'): void => {
-  if (index < min || index > max) throw new RangeError(message);
+export const rangeCheck = (index: number, min: number, max: number, message?: string): void => {
+  if (index < min || index > max) {
+    throw new RangeError(message ?? `Index ${index} is out of range [${min}, ${max}].`);
+  }
 };
 
 /**