bst-typed 1.51.7 → 1.51.8

package/dist/types/utils/utils.d.ts

@@ -5,4 +5,13 @@ export type Thunk = () => ReturnType<ToThunkFn> & {
 export type TrlFn = (...args: any[]) => any;
 export type TrlAsyncFn = (...args: any[]) => any;
 export type SpecifyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-export type Any = string | number | boolean | object | null | undefined | symbol;
+export type Any = string | number | bigint | boolean | symbol | undefined | object;
+export type Comparable = number | string | bigint | boolean | ({
+    [key in string]: any;
+} & {
+    valueOf(): Comparable;
+}) | ({
+    [key in string]: any;
+} & {
+    toString(): Comparable;
+}) | (() => Comparable);

package/dist/utils/utils.d.ts

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { Thunk, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
+import type { Comparable, Thunk, ToThunkFn, TrlAsyncFn, TrlFn } from '../types';
 export declare const uuidV4: () => string;
 export declare const arrayRemove: <T>(array: T[], predicate: (item: T, index: number, array: T[]) => boolean) => T[];
 export declare const THUNK_SYMBOL: unique symbol;
@@ -23,3 +23,4 @@ export declare const throwRangeError: (message?: string) => void;
 export declare const isWeakKey: (input: unknown) => input is object;
 export declare const calcMinUnitsRequired: (totalQuantity: number, unitSize: number) => number;
 export declare const roundFixed: (num: number, digit?: number) => number;
+export declare function isComparable(key: any): key is Comparable;

package/dist/utils/utils.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.roundFixed = exports.calcMinUnitsRequired = exports.isWeakKey = exports.throwRangeError = exports.rangeCheck = exports.getMSB = exports.trampolineAsync = exports.trampoline = exports.toThunk = exports.isThunk = exports.THUNK_SYMBOL = exports.arrayRemove = exports.uuidV4 = void 0;
+exports.isComparable = exports.roundFixed = exports.calcMinUnitsRequired = exports.isWeakKey = exports.throwRangeError = exports.rangeCheck = exports.getMSB = exports.trampolineAsync = exports.trampoline = exports.toThunk = exports.isThunk = exports.THUNK_SYMBOL = exports.arrayRemove = exports.uuidV4 = void 0;
 const uuidV4 = function () {
     return 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.replace(/[x]/g, function (c) {
         const r = (Math.random() * 16) | 0, v = c == 'x' ? r : (r & 0x3) | 0x8;
@@ -92,3 +92,31 @@ const roundFixed = (num, digit = 10) => {
     return Math.round(num * multiplier) / multiplier;
 };
 exports.roundFixed = roundFixed;
+function isComparable(key) {
+    const keyType = typeof key;
+    if (keyType === 'number')
+        return isNaN(key);
+    if (keyType === 'string')
+        return true;
+    if (keyType === 'bigint')
+        return true;
+    if (keyType === 'boolean')
+        return true;
+    if (keyType === 'symbol')
+        return false;
+    if (keyType === 'undefined')
+        return false;
+    if (keyType === 'function')
+        return isComparable(key());
+    if (keyType === 'object') {
+        if (key === null)
+            return true;
+        if (typeof key.valueOf === 'function')
+            return isComparable(key.valueOf());
+        if (typeof key.toString === 'function')
+            return isComparable(key.toString());
+        return false;
+    }
+    return false;
+}
+exports.isComparable = isComparable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bst-typed",
-  "version": "1.51.7",
+  "version": "1.51.8",
   "description": "BST (Binary Search Tree). Javascript & Typescript Data Structure.",
   "main": "dist/index.js",
   "scripts": {
@@ -144,6 +144,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^1.51.7"
+    "data-structure-typed": "^1.51.8"
   }
 }

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

@@ -12,6 +12,7 @@ import type {
   BinaryTreeDeleteResult,
   BSTNKeyOrNode,
   BTNCallback,
+  Comparable,
   IterationType,
   KeyOrNodeOrEntry
 } from '../../types';
@@ -19,7 +20,7 @@ import { IBinaryTree } from '../../interfaces';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 
 export class AVLTreeMultiMapNode<
-  K = any,
+  K extends Comparable,
   V = any,
   NODE extends AVLTreeMultiMapNode<K, V, NODE> = AVLTreeMultiMapNodeNested<K, V>
 > extends AVLTreeNode<K, V, NODE> {
@@ -62,7 +63,7 @@ export class AVLTreeMultiMapNode<
  * The only distinction between a AVLTreeMultiMap and a AVLTree lies in the ability of the former to store duplicate nodes through the utilization of counters.
  */
 export class AVLTreeMultiMap<
-  K = any,
+  K extends Comparable,
   V = any,
   NODE extends AVLTreeMultiMapNode<K, V, NODE> = AVLTreeMultiMapNode<K, V, AVLTreeMultiMapNodeNested<K, V>>,
   TREE extends AVLTreeMultiMap<K, V, NODE, TREE> = AVLTreeMultiMap<K, V, NODE, AVLTreeMultiMapNested<K, V, NODE>>
@@ -118,19 +119,10 @@ export class AVLTreeMultiMap<
     return new AVLTreeMultiMapNode(key, value, count) as NODE;
   }
 
-  /**
-   * The function creates a new AVLTreeMultiMap object with the specified options and returns it.
-   * @param [options] - The `options` parameter is an optional object that contains additional
-   * configuration options for creating the `AVLTreeMultiMap` object. It can include properties such as
-   * `iterationType` and `variant`, which are used to specify the type of iteration and the variant of
-   * the tree, respectively. These properties can be
-   * @returns a new instance of the `AVLTreeMultiMap` class, with the provided options merged with the
-   * default options. The returned value is casted as `TREE`.
-   */
   override createTree(options?: AVLTreeMultiMapOptions<K>): TREE {
     return new AVLTreeMultiMap<K, V, NODE, TREE>([], {
       iterationType: this.iterationType,
-      variant: this.variant,
+      comparator: this.comparator,
       ...options
     }) as TREE;
   }

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

@@ -13,12 +13,13 @@ import type {
   BinaryTreeDeleteResult,
   BSTNKeyOrNode,
   BTNCallback,
+  Comparable,
   KeyOrNodeOrEntry
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 
 export class AVLTreeNode<
-  K = any,
+  K extends Comparable,
   V = any,
   NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNodeNested<K, V>
 > extends BSTNode<K, V, NODE> {
@@ -65,7 +66,7 @@ export class AVLTreeNode<
  * 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.
  */
 export class AVLTree<
-  K = any,
+  K extends Comparable,
   V = any,
   NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNode<K, V, AVLTreeNodeNested<K, V>>,
   TREE extends AVLTree<K, V, NODE, TREE> = AVLTree<K, V, NODE, AVLTreeNested<K, V, NODE>>
@@ -109,7 +110,7 @@ export class AVLTree<
   override createTree(options?: AVLTreeOptions<K>): TREE {
     return new AVLTree<K, V, NODE, TREE>([], {
       iterationType: this.iterationType,
-      variant: this.variant,
+      comparator: this.comparator,
       ...options
     }) as TREE;
   }
@@ -195,26 +196,26 @@ export class AVLTree<
     srcNode: BSTNKeyOrNode<K, NODE>,
     destNode: BSTNKeyOrNode<K, NODE>
   ): NODE | undefined {
-    srcNode = this.ensureNode(srcNode);
-    destNode = this.ensureNode(destNode);
+    const srcNodeEnsured = this.ensureNode(srcNode);
+    const destNodeEnsured = this.ensureNode(destNode);
 
-    if (srcNode && destNode) {
-      const { key, value, height } = destNode;
+    if (srcNodeEnsured && destNodeEnsured) {
+      const { key, value, height } = destNodeEnsured;
       const tempNode = this.createNode(key, value);
 
       if (tempNode) {
         tempNode.height = height;
 
-        destNode.key = srcNode.key;
-        destNode.value = srcNode.value;
-        destNode.height = srcNode.height;
+        destNodeEnsured.key = srcNodeEnsured.key;
+        destNodeEnsured.value = srcNodeEnsured.value;
+        destNodeEnsured.height = srcNodeEnsured.height;
 
-        srcNode.key = tempNode.key;
-        srcNode.value = tempNode.value;
-        srcNode.height = tempNode.height;
+        srcNodeEnsured.key = tempNode.key;
+        srcNodeEnsured.value = tempNode.value;
+        srcNodeEnsured.height = tempNode.height;
       }
 
-      return destNode;
+      return destNodeEnsured;
     }
     return undefined;
   }

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

@@ -14,12 +14,14 @@ import type {
   BinaryTreePrintOptions,
   BTNCallback,
   BTNEntry,
+  Comparable,
   DFSOrderPattern,
   EntryCallback,
+  FamilyPosition,
+  IterationType,
   KeyOrNodeOrEntry,
   NodeDisplayLayout
 } from '../../types';
-import { FamilyPosition, IterationType } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { trampoline } from '../../utils';
 import { Queue } from '../queue';
@@ -31,7 +33,7 @@ import { IterableEntryBase } from '../base';
  * @template NODE - The type of the family relationship in the binary tree.
  */
 export class BinaryTreeNode<
-  K = any,
+  K extends Comparable,
   V = any,
   NODE extends BinaryTreeNode<K, V, NODE> = BinaryTreeNode<K, V, BinaryTreeNodeNested<K, V>>
 > {
@@ -129,7 +131,7 @@ export class BinaryTreeNode<
  */
 
 export class BinaryTree<
-  K = any,
+  K extends Comparable,
   V = any,
   NODE extends BinaryTreeNode<K, V, NODE> = BinaryTreeNode<K, V, BinaryTreeNodeNested<K, V>>,
   TREE extends BinaryTree<K, V, NODE, TREE> = BinaryTree<K, V, NODE, BinaryTreeNested<K, V, NODE>>
@@ -147,12 +149,11 @@ export class BinaryTree<
    * `Partial<BinaryTreeOptions>`, which means that not all properties of `BinaryTreeOptions` are
    * required.
    */
-  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: BinaryTreeOptions<K>) {
+  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: BinaryTreeOptions) {
     super();
     if (options) {
-      const { iterationType, extractor } = options;
+      const { iterationType } = options;
       if (iterationType) this.iterationType = iterationType;
-      if (extractor) this._extractor = extractor;
     }
 
     this._size = 0;
@@ -160,16 +161,6 @@ export class BinaryTree<
     if (keysOrNodesOrEntries) this.addMany(keysOrNodesOrEntries);
   }
 
-  protected _extractor = (key: K) => (typeof key === 'number' ? key : Number(key));
-
-  /**
-   * The function returns the value of the `_extractor` property.
-   * @returns The `_extractor` property is being returned.
-   */
-  get extractor() {
-    return this._extractor;
-  }
-
   protected _root?: NODE | null;
 
   /**
@@ -218,7 +209,7 @@ export class BinaryTree<
    * you can provide only a subset of the properties defined in the `BinaryTreeOptions` interface.
    * @returns a new instance of a binary tree.
    */
-  createTree(options?: Partial<BinaryTreeOptions<K>>): TREE {
+  createTree(options?: Partial<BinaryTreeOptions>): TREE {
     return new BinaryTree<K, V, NODE, TREE>([], { iterationType: this.iterationType, ...options }) as TREE;
   }
 
@@ -921,7 +912,7 @@ export class BinaryTree<
     if (iterationType === 'RECURSIVE') {
       const dfs = (cur: NODE | null | undefined, min: number, max: number): boolean => {
         if (!this.isRealNode(cur)) return true;
-        const numKey = this.extractor(cur.key);
+        const numKey = Number(cur.key);
         if (numKey <= min || numKey >= max) return false;
         return dfs(cur.left, min, numKey) && dfs(cur.right, numKey, max);
       };
@@ -941,7 +932,7 @@ export class BinaryTree<
             curr = curr.left;
           }
           curr = stack.pop()!;
-          const numKey = this.extractor(curr.key);
+          const numKey = Number(curr.key);
           if (!this.isRealNode(curr) || (!checkMax && prev >= numKey) || (checkMax && prev <= numKey)) return false;
           prev = numKey;
           curr = curr.right;
@@ -973,15 +964,15 @@ export class BinaryTree<
    * @returns the depth of the `dist` relative to the `beginRoot`.
    */
   getDepth(dist: KeyOrNodeOrEntry<K, V, NODE>, beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root): number {
-    dist = this.ensureNode(dist);
-    beginRoot = this.ensureNode(beginRoot);
+    let distEnsured = this.ensureNode(dist);
+    const beginRootEnsured = this.ensureNode(beginRoot);
     let depth = 0;
-    while (dist?.parent) {
-      if (dist === beginRoot) {
+    while (distEnsured?.parent) {
+      if (distEnsured === beginRootEnsured) {
         return depth;
       }
       depth++;
-      dist = dist.parent;
+      distEnsured = distEnsured.parent;
     }
     return depth;
   }
@@ -1124,17 +1115,17 @@ export class BinaryTree<
   getPathToRoot(beginNode: KeyOrNodeOrEntry<K, V, NODE>, isReverse = true): NODE[] {
     // TODO to support get path through passing key
     const result: NODE[] = [];
-    beginNode = this.ensureNode(beginNode);
+    let beginNodeEnsured = this.ensureNode(beginNode);
 
-    if (!beginNode) return result;
+    if (!beginNodeEnsured) return result;
 
-    while (beginNode.parent) {
+    while (beginNodeEnsured.parent) {
       // Array.push + Array.reverse is more efficient than Array.unshift
       // TODO may consider using Deque, so far this is not the performance bottleneck
-      result.push(beginNode);
-      beginNode = beginNode.parent;
+      result.push(beginNodeEnsured);
+      beginNodeEnsured = beginNodeEnsured.parent;
     }
-    result.push(beginNode);
+    result.push(beginNodeEnsured);
     return isReverse ? result.reverse() : result;
   }
 
@@ -1840,10 +1831,10 @@ export class BinaryTree<
       console.log(`U for undefined
       `);
     if (opts.isShowNull)
-      console.log(`NODE for null
+      console.log(`N for null
       `);
     if (opts.isShowRedBlackNIL)
-      console.log(`S for Sentinel Node
+      console.log(`S for Sentinel Node(NIL)
       `);
 
     const display = (root: NODE | null | undefined): void => {
@@ -1873,24 +1864,24 @@ export class BinaryTree<
       let current: NODE | null | undefined = node;
 
       while (current || stack.length > 0) {
-        while (current && !isNaN(this.extractor(current.key))) {
+        while (this.isRealNode(current)) {
           stack.push(current);
           current = current.left;
         }
 
         current = stack.pop();
 
-        if (current && !isNaN(this.extractor(current.key))) {
+        if (this.isRealNode(current)) {
           yield [current.key, current.value];
           current = current.right;
         }
       }
     } else {
-      if (node.left && !isNaN(this.extractor(node.key))) {
+      if (node.left && this.isRealNode(node)) {
         yield* this[Symbol.iterator](node.left);
       }
       yield [node.key, node.value];
-      if (node.right && !isNaN(this.extractor(node.key))) {
+      if (node.right && this.isRealNode(node)) {
         yield* this[Symbol.iterator](node.right);
       }
     }
@@ -1919,13 +1910,13 @@ export class BinaryTree<
       return emptyDisplayLayout;
     } else if (node === undefined && !isShowUndefined) {
       return emptyDisplayLayout;
-    } else if (node !== null && node !== undefined && isNaN(this.extractor(node.key)) && !isShowRedBlackNIL) {
+    } else if (this.isNIL(node) && !isShowRedBlackNIL) {
       return emptyDisplayLayout;
     } else if (node !== null && node !== undefined) {
       // Display logic of normal nodes
 
       const key = node.key,
-        line = isNaN(this.extractor(key)) ? 'S' : this.extractor(key).toString(),
+        line = this.isNIL(node) ? 'S' : key.toString(),
         width = line.length;
 
       return _buildNodeDisplay(