binary-tree-typed 2.4.4 → 2.4.5

package/src/data-structures/graph/abstract-graph.ts

@@ -8,6 +8,7 @@
 
 import type { DijkstraResult, EntryCallback, GraphOptions, VertexKey } from '../../types';
 import { uuidV4 } from '../../utils';
+import { ERR } from '../../common';
 import { IterableEntryBase } from '../base';
 import { IGraph } from '../../interfaces';
 import { Heap } from '../heap';
@@ -274,7 +275,7 @@ export abstract class AbstractGraph<
         const newEdge = this.createEdge(srcOrEdge, dest, weight, value);
         return this._addEdge(newEdge);
       } else {
-        throw new Error('dest must be a Vertex or vertex key while srcOrEdge is an Edge');
+        throw new TypeError(ERR.invalidArgument('dest must be a Vertex or vertex key when srcOrEdge is an Edge.', 'Graph'));
       }
     }
   }
@@ -1078,4 +1079,108 @@ export abstract class AbstractGraph<
   protected _getVertexKey(vertexOrKey: VO | VertexKey): VertexKey {
     return vertexOrKey instanceof AbstractVertex ? vertexOrKey.key : vertexOrKey;
   }
+
+  /**
+   * The edge connector string used in visual output.
+   * Override in subclasses (e.g., '--' for undirected, '->' for directed).
+   */
+  protected get _edgeConnector(): string {
+    return '--';
+  }
+
+  /**
+   * Generate a text-based visual representation of the graph.
+   *
+   * **Adjacency list format:**
+   * ```
+   * Graph (5 vertices, 6 edges):
+   * A -> B (1), C (2)
+   * B -> D (3)
+   * C -> (no outgoing edges)
+   * D -> A (1)
+   * E (isolated)
+   * ```
+   *
+   * @param options - Optional display settings.
+   * @param options.showWeight - Whether to show edge weights (default: true).
+   * @returns The visual string.
+   */
+  override toVisual(options?: { showWeight?: boolean }): string {
+    const showWeight = options?.showWeight ?? true;
+    const vertices = [...this._vertexMap.values()];
+    const vertexCount = vertices.length;
+    const edgeCount = this.edgeSet().length;
+
+    const lines: string[] = [`Graph (${vertexCount} vertices, ${edgeCount} edges):`];
+
+    for (const vertex of vertices) {
+      const neighbors = this.getNeighbors(vertex);
+      if (neighbors.length === 0) {
+        lines.push(`  ${vertex.key} (isolated)`);
+      } else {
+        const edgeStrs = neighbors.map(neighbor => {
+          const edge = this.getEdge(vertex, neighbor);
+          if (edge && showWeight && edge.weight !== undefined && edge.weight !== 1) {
+            return `${neighbor.key} (${edge.weight})`;
+          }
+          return `${neighbor.key}`;
+        });
+        lines.push(`  ${vertex.key} ${this._edgeConnector} ${edgeStrs.join(', ')}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate DOT language representation for Graphviz.
+   *
+   * @param options - Optional display settings.
+   * @param options.name - Graph name (default: 'G').
+   * @param options.showWeight - Whether to label edges with weight (default: true).
+   * @returns DOT format string.
+   */
+  toDot(options?: { name?: string; showWeight?: boolean }): string {
+    const name = options?.name ?? 'G';
+    const showWeight = options?.showWeight ?? true;
+    const isDirected = this._edgeConnector === '->';
+    const graphType = isDirected ? 'digraph' : 'graph';
+    const edgeOp = isDirected ? '->' : '--';
+
+    const lines: string[] = [`${graphType} ${name} {`];
+
+    // Add all vertices (ensures isolated vertices appear)
+    for (const vertex of this._vertexMap.values()) {
+      lines.push(`  "${vertex.key}";`);
+    }
+
+    // Add edges
+    const visited = new Set<string>();
+    for (const vertex of this._vertexMap.values()) {
+      for (const neighbor of this.getNeighbors(vertex)) {
+        const edgeId = isDirected
+          ? `${vertex.key}->${neighbor.key}`
+          : [vertex.key, neighbor.key].sort().join('--');
+        if (visited.has(edgeId)) continue;
+        visited.add(edgeId);
+
+        const edge = this.getEdge(vertex, neighbor);
+        const label = edge && showWeight && edge.weight !== undefined && edge.weight !== 1
+          ? ` [label="${edge.weight}"]`
+          : '';
+        lines.push(`  "${vertex.key}" ${edgeOp} "${neighbor.key}"${label};`);
+      }
+    }
+
+    lines.push('}');
+    return lines.join('\n');
+  }
+
+  /**
+   * Print the graph to console.
+   * @param options - Display settings passed to `toVisual`.
+   */
+  override print(options?: { showWeight?: boolean }): void {
+    console.log(this.toVisual(options));
+  }
 }

package/src/data-structures/graph/directed-graph.ts

@@ -180,6 +180,10 @@ export class DirectedGraph<
     super(options);
   }
 
+  protected override get _edgeConnector(): string {
+    return '->';
+  }
+
   protected _outEdgeMap: Map<VO, EO[]> = new Map<VO, EO[]>();
 
   get outEdgeMap(): Map<VO, EO[]> {

package/src/data-structures/graph/undirected-graph.ts

@@ -566,6 +566,101 @@ export class UndirectedGraph<
     };
   }
 
+  /**
+   * Find biconnected components using edge-stack Tarjan variant.
+   * A biconnected component is a maximal biconnected subgraph.
+   * @returns Array of edge arrays, each representing a biconnected component.
+   * @remarks Time O(V + E), Space O(V + E)
+   */
+  getBiconnectedComponents(): EO[][] {
+    const dfn = new Map<VO, number>();
+    const low = new Map<VO, number>();
+    const edgeStack: EO[] = [];
+    const components: EO[][] = [];
+    let time = 0;
+
+    const dfs = (vertex: VO, parent: VO | undefined) => {
+      dfn.set(vertex, time);
+      low.set(vertex, time);
+      time++;
+
+      const neighbors = this.getNeighbors(vertex);
+      let childCount = 0;
+
+      for (const neighbor of neighbors) {
+        const edge = this.getEdge(vertex, neighbor);
+        if (!edge) continue;
+
+        if (!dfn.has(neighbor)) {
+          childCount++;
+          edgeStack.push(edge);
+          dfs(neighbor, vertex);
+          low.set(vertex, Math.min(low.get(vertex)!, low.get(neighbor)!));
+
+          // Articulation point found — pop edges to form a component
+          if (
+            (parent === undefined && childCount > 1) ||
+            (parent !== undefined && low.get(neighbor)! >= dfn.get(vertex)!)
+          ) {
+            const component: EO[] = [];
+            let e: EO | undefined;
+            do {
+              e = edgeStack.pop();
+              if (e) component.push(e);
+            } while (e && e !== edge);
+            if (component.length > 0) components.push(component);
+          }
+        } else if (neighbor !== parent && dfn.get(neighbor)! < dfn.get(vertex)!) {
+          // Back edge (only push once per undirected edge)
+          edgeStack.push(edge);
+          low.set(vertex, Math.min(low.get(vertex)!, dfn.get(neighbor)!));
+        }
+      }
+    };
+
+    for (const vertex of this.vertexMap.values()) {
+      if (!dfn.has(vertex)) {
+        dfs(vertex, undefined);
+        // Remaining edges form a component
+        if (edgeStack.length > 0) {
+          components.push([...edgeStack]);
+          edgeStack.length = 0;
+        }
+      }
+    }
+
+    return components;
+  }
+
+  /**
+   * Detect whether the graph contains a cycle.
+   * Uses DFS with parent tracking.
+   * @returns `true` if a cycle exists, `false` otherwise.
+   * @remarks Time O(V + E), Space O(V)
+   */
+  hasCycle(): boolean {
+    const visited = new Set<VO>();
+
+    const dfs = (vertex: VO, parent: VO | undefined): boolean => {
+      visited.add(vertex);
+      for (const neighbor of this.getNeighbors(vertex)) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor, vertex)) return true;
+        } else if (neighbor !== parent) {
+          return true; // back edge = cycle
+        }
+      }
+      return false;
+    };
+
+    for (const vertex of this.vertexMap.values()) {
+      if (!visited.has(vertex)) {
+        if (dfs(vertex, undefined)) return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Get bridges discovered by `tarjan()`.
    * @returns Array of edges that are bridges.

package/src/data-structures/hash/hash-map.ts

@@ -15,6 +15,7 @@ import type {
 } from '../../types';
 import { IterableEntryBase } from '../base';
 import { isWeakKey, rangeCheck } from '../../utils';
+import { ERR } from '../../common';
 
 /**
  * Hash-based map. Supports object keys and custom hashing; offers O(1) average set/get/has.
@@ -534,8 +535,8 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
     if (this.isEntry(rawElement)) {
       return rawElement;
     }
-    throw new Error(
-      'If `entryOrRawElements` does not adhere to [key,value], provide `options.toEntryFn` to transform raw records.'
+    throw new TypeError(
+      ERR.invalidArgument('If elements do not adhere to [key, value], provide options.toEntryFn to transform raw records.', 'HashMap')
     );
   };
 
@@ -797,6 +798,16 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
   }
 
   protected _deleteNode(node: HashMapLinkedNode<K, V | undefined>): boolean {
+    // Remove from hash table
+    const key: unknown = node.key;
+    if (isWeakKey(key)) {
+      this._objMap.delete(key);
+    } else {
+      const hash = this._hashFn(key as K);
+      delete this._noObjMap[hash];
+    }
+
+    // Remove from linked list
     const { prev, next } = node;
     prev.next = next;
     next.prev = prev;

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

@@ -8,6 +8,7 @@
 
 import type { Comparator, DFSOrderPattern, ElementCallback, HeapOptions } from '../../types';
 import { IterableElementBase } from '../base';
+import { ERR } from '../../common';
 
 /**
  * Binary heap with pluggable comparator; supports fast insertion and removal of the top element.
@@ -611,7 +612,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     thisArg?: unknown
   ): Heap<EM, RM> {
     const { comparator, toElementFn, ...rest } = options ?? {};
-    if (!comparator) throw new TypeError('Heap.map requires options.comparator for EM');
+    if (!comparator) throw new TypeError(ERR.comparatorRequired('Heap.map'));
     const out = this._createLike<EM, RM>([], { ...rest, comparator, toElementFn });
     let i = 0;
     for (const x of this) {
@@ -641,7 +642,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
 
   protected readonly _DEFAULT_COMPARATOR: Comparator<E> = (a: E, b: E): number => {
     if (typeof a === 'object' || typeof b === 'object') {
-      throw TypeError('When comparing object types, define a custom comparator in options.');
+      throw new TypeError(ERR.comparatorRequired('Heap'));
     }
     if (a > b) return 1;
     if (a < b) return -1;
@@ -783,7 +784,7 @@ export class FibonacciHeap<E> {
   constructor(comparator?: Comparator<E>) {
     this.clear();
     this._comparator = comparator || this._defaultComparator;
-    if (typeof this.comparator !== 'function') throw new Error('FibonacciHeap: comparator must be a function.');
+    if (typeof this.comparator !== 'function') throw new TypeError(ERR.notAFunction('comparator', 'FibonacciHeap'));
   }
 
   protected _root?: FibonacciHeapNode<E>;

package/src/data-structures/heap/max-heap.ts

@@ -6,6 +6,7 @@
  */
 import type { HeapOptions } from '../../types';
 import { Heap } from './heap';
+import { ERR } from '../../common';
 
 /**
  * @template E
@@ -33,9 +34,7 @@ export class MaxHeap<E = any, R = any> extends Heap<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('MaxHeap'));
         }
         if (a < b) return 1;
         if (a > b) return -1;

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

@@ -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/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);
     }

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/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}].`);
+  }
 };
 
 /**