data-structure-typed 2.4.4 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "description": "Standard data structure",
   "browser": "dist/umd/data-structure-typed.min.js",
   "umd:main": "dist/umd/data-structure-typed.min.js",
@@ -44,8 +44,9 @@
     "build:types": "rm -rf dist/types && tsc -p tsconfig.types.json",
     "build:ecut": "npm run build:node && npm run build:types && npm run build:umd",
     "build:leetcode": "tsup --config tsup.leetcode.config.js",
-    "build:docs": "npm run gen:examples && npm run generate:schema && typedoc --out docs/api ./src",
-    "build:docs-class": "npm run gen:examples && typedoc --out docs/api ./src/data-structures",
+    "build:typedoc-plugin": "tsc scripts/typedoc-plugin-example-rewrite.ts --outDir scripts --esModuleInterop --module commonjs --target es2020 --moduleResolution node --skipLibCheck",
+    "build:docs": "npm run gen:examples && npm run generate:schema && npm run build:typedoc-plugin && typedoc --plugin ./scripts/typedoc-plugin-example-rewrite.js --out docs/api ./src",
+    "build:docs-class": "npm run gen:examples && npm run build:typedoc-plugin && typedoc --plugin ./scripts/typedoc-plugin-example-rewrite.js --out docs/api ./src/data-structures",
     "gen:examples": "ts-node scripts/test-to-example.ts",
     "test:in-band": "jest --runInBand",
     "test": "npm run test:in-band",
@@ -105,7 +106,7 @@
     "benchmark": "^2.1.4",
     "binary-tree-typed": "^1.54.3",
     "bst-typed": "^1.54.3",
-    "data-structure-typed": "^2.4.3",
+    "data-structure-typed": "^2.4.5",
     "dependency-cruiser": "^16.5.0",
     "doctoc": "^2.2.1",
     "eslint": "^9.13.0",

package/src/common/error.ts

@@ -0,0 +1,60 @@
+/**
+ * Centralized error message templates.
+ * Keep using native Error/TypeError/RangeError — this only standardizes messages.
+ */
+export const ERR = {
+  // Range / index
+  indexOutOfRange: (index: number, min: number, max: number, ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Index ${index} is out of range [${min}, ${max}].`,
+
+  invalidIndex: (ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Index must be an integer.`,
+
+  // Type / argument
+  invalidArgument: (reason: string, ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}${reason}`,
+
+  comparatorRequired: (ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Comparator is required for non-number/non-string/non-Date keys.`,
+
+  invalidKey: (reason: string, ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}${reason}`,
+
+  notAFunction: (name: string, ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}${name} must be a function.`,
+
+  invalidEntry: (ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Each entry must be a [key, value] tuple.`,
+
+  invalidNaN: (ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}NaN is not a valid key.`,
+
+  invalidDate: (ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Invalid Date key.`,
+
+  reduceEmpty: (ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Reduce of empty structure with no initial value.`,
+
+  callbackReturnType: (expected: string, got: string, ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}Callback must return ${expected}; got ${got}.`,
+
+  // State / operation
+  invalidOperation: (reason: string, ctx?: string) =>
+    `${ctx ? ctx + ': ' : ''}${reason}`,
+
+  // Matrix
+  matrixDimensionMismatch: (op: string) =>
+    `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: number, got: number) =>
+    `Matrix: Expected row length ${expected}, but got ${got}.`
+} as const;

package/src/common/index.ts

@@ -1,3 +1,5 @@
+export { ERR } from './error';
+
 export enum DFSOperation {
   VISIT = 0,
   PROCESS = 1

package/src/data-structures/base/iterable-element-base.ts

@@ -35,7 +35,7 @@ export abstract class IterableElementBase<E, R> implements Iterable<E> {
    * @remarks
    * Time O(1), Space O(1).
    */
-  protected readonly _toElementFn?: (rawElement: R) => E;
+  protected _toElementFn?: (rawElement: R) => E;
 
   /**
    * Exposes the current `toElementFn`, if configured.
@@ -229,7 +229,7 @@ export abstract class IterableElementBase<E, R> implements Iterable<E> {
       index = 1;
     }
 
-    for (const value of iter) {
+    for (const value of iter as unknown as Iterable<E>) {
       acc = callbackfn(acc, value, index++, this);
     }
     return acc;

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

@@ -123,16 +123,12 @@ export class AVLTreeNode<K = any, V = any> {
    *
    * @returns The node's color.
    */
+  /* istanbul ignore next -- inherited field, used by RedBlackTree subclass */  /* istanbul ignore next -- inherited field, not used by AVLTree */
   get color(): RBTNColor {
     return this._color;
   }
 
-  /**
-   * Sets the color of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new color.
-   */
+  /* istanbul ignore next -- inherited field, not used by AVLTree */
   set color(value: RBTNColor) {
     this._color = value;
   }
@@ -145,16 +141,12 @@ export class AVLTreeNode<K = any, V = any> {
    *
    * @returns The subtree node count.
    */
+  /* istanbul ignore next -- inherited field, not used by AVLTree */
   get count(): number {
     return this._count;
   }
 
-  /**
-   * Sets the count of nodes in the subtree.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new count.
-   */
+  /* istanbul ignore next -- inherited field, not used by AVLTree */
   set count(value: number) {
     this._count = value;
   }
@@ -176,6 +168,7 @@ export class AVLTreeNode<K = any, V = any> {
       return this.left || this.right ? 'ROOT_RIGHT' : 'RIGHT';
     }
 
+    /* istanbul ignore next -- defensive: unreachable if tree structure is correct */
     return 'MAL_NODE';
   }
 }
@@ -197,28 +190,6 @@ export class AVLTreeNode<K = any, V = any> {
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
  *
  * @example
- * // basic AVLTree creation and add operation
- *  // Create a simple AVLTree with initial values
- *     const tree = new AVLTree([5, 2, 8, 1, 9]);
- *
- *     tree.print();
- *     //   _2___
- *     //  /     \
- *     //  1    _8_
- *     //      /   \
- *     //      5   9
- *
- *     // Verify the tree maintains sorted order
- *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
- *
- *     // Check size
- *     console.log(tree.size); // 5;
- *
- *     // Add a new element
- *     tree.set(3);
- *     console.log(tree.size); // 6;
- *     console.log([...tree.keys()]); // [1, 2, 3, 5, 8, 9];
- * @example
  * // AVLTree has and get operations
  *  const tree = new AVLTree<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
  *
@@ -233,23 +204,6 @@ export class AVLTreeNode<K = any, V = any> {
  *     // Verify tree is balanced
  *     console.log(tree.isAVLBalanced()); // true;
  * @example
- * // AVLTree delete and balance verification
- *  const tree = new AVLTree([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
- *
- *     // Delete an element
- *     tree.delete(10);
- *     console.log(tree.has(10)); // false;
- *
- *     // Tree should remain balanced after deletion
- *     console.log(tree.isAVLBalanced()); // true;
- *
- *     // Size decreased
- *     console.log(tree.size); // 15;
- *
- *     // Remaining elements are still sorted
- *     const keys = [...tree.keys()];
- *     console.log(keys); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16];
- * @example
  * // AVLTree for university ranking system with strict balance
  *  interface University {
  *       name: string;
@@ -406,6 +360,52 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    * @param keyNodeOrEntry - The key, node, or entry to set.
    * @param [value] - The value, if providing just a key.
    * @returns True if the addition was successful, false otherwise.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Set a key-value pair
+ *  const avl = new AVLTree<number, string>();
+ *     avl.set(1, 'one');
+ *     avl.set(2, 'two');
+ *     console.log(avl.get(1)); // 'one';
    */
   override set(
     keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
@@ -424,6 +424,48 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    *
    * @param keyNodeOrEntry - The node to delete.
    * @returns An array containing deletion results.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove nodes and verify structure
+ *  const avl = new AVLTree<number>([5, 3, 7, 1, 4, 6, 8]);
+ *     avl.delete(3);
+ *     console.log(avl.has(3)); // false;
+ *     console.log(avl.size); // 6;
    */
   override delete(
     keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
@@ -445,6 +487,28 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    *
    * @param [iterationType=this.iterationType] - The traversal method for the initial node export.
    * @returns True if successful, false if the tree was empty.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Rebalance the tree
+ *  const avl = new AVLTree<number>();
+ *     // Insert in sorted order (worst case for BST)
+ *     for (let i = 1; i <= 7; i++) avl.add(i);
+ *     console.log(avl.isAVLBalanced()); // false;
+ *     avl.perfectlyBalance();
+ *     console.log(avl.isAVLBalanced()); // true;
    */
   override perfectlyBalance(iterationType: IterationType = this.iterationType): boolean {
     const nodes = this.dfs(node => node, 'IN', false, this._root, iterationType);
@@ -486,6 +550,36 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    * @param [options] - Options for the new AVLTree.
    * @param [thisArg] - `this` context for the callback.
    * @returns A new, mapped AVLTree.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform to new tree
+ *  const avl = new AVLTree<number, number>([[1, 10], [2, 20], [3, 30]]);
+ *     const doubled = avl.map((value, key) => [key, (value ?? 0) * 2] as [number, number]);
+ *     console.log([...doubled.values()]); // [20, 40, 60];
    */
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
@@ -574,6 +668,7 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
 
       return destNodeEnsured;
     }
+    /* istanbul ignore next -- defensive: srcNode/destNode are always valid when called internally */
     return undefined;
   }