undirected-graph-typed 2.0.4 → 2.1.0

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

@@ -5,100 +5,131 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import { AVLTreeMultiMapOptions } from '../../types';
+import type { AVLTreeMultiMapOptions, AVLTreeOptions, ElemOf, EntryCallback, IterationType } from '../../types';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 import { IBinaryTree } from '../../interfaces';
+/**
+ * Node used by AVLTreeMultiMap; stores the key with a bucket of values (array).
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ */
 export declare class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K, V[]> {
     parent?: AVLTreeMultiMapNode<K, V>;
     /**
-     * This TypeScript constructor initializes an object with a key of type K and an array of values of
-     * type V.
-     * @param {K} key - The `key` parameter is typically used to store a unique identifier or key for the
-     * data being stored in the data structure. It helps in quickly accessing or retrieving the
-     * associated value in the data structure.
-     * @param {V[]} value - The `value` parameter in the constructor represents an array of values of
-     * type `V`.
+     * Create an AVLTreeMultiMap node with a value bucket.
+     * @remarks Time O(1), Space O(1)
+     * @param key - Key of the node.
+     * @param value - Initial array of values.
+     * @returns New AVLTreeMultiMapNode instance.
      */
     constructor(key: K, value: V[]);
     _left?: AVLTreeMultiMapNode<K, V> | null | undefined;
+    /**
+     * Get the left child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Left child node, or null/undefined.
+     */
     get left(): AVLTreeMultiMapNode<K, V> | null | undefined;
+    /**
+     * Set the left child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New left child node, or null/undefined.
+     * @returns void
+     */
     set left(v: AVLTreeMultiMapNode<K, V> | null | undefined);
     _right?: AVLTreeMultiMapNode<K, V> | null | undefined;
+    /**
+     * Get the right child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Right child node, or null/undefined.
+     */
     get right(): AVLTreeMultiMapNode<K, V> | null | undefined;
+    /**
+     * Set the right child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New right child node, or null/undefined.
+     * @returns void
+     */
     set right(v: AVLTreeMultiMapNode<K, V> | null | undefined);
 }
 /**
- *
+ * AVL-tree–based multimap (key → array of values). Preserves O(log N) updates and supports map-like mode.
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ * @template R
  */
-export declare class AVLTreeMultiMap<K = any, V = any, R = object, MK = any, MV = any, MR = object> extends AVLTree<K, V[], R, MK, MV[], MR> implements IBinaryTree<K, V[], R, MK, MV, MR> {
+export declare class AVLTreeMultiMap<K = any, V = any, R extends object = object> extends AVLTree<K, V[], R> implements IBinaryTree<K, V[], R> {
     /**
-     * The constructor initializes an AVLTreeMultiMap with the provided keys, nodes, entries, or raw data
-     * and options.
-     * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
-     * iterable that can contain either key-value pairs represented as `BTNRep<K, V[],
-     * AVLTreeMultiMapNode<K, V>>` or raw data represented as `R`. This parameter is used to initialize
-     * the AVLTreeMulti
-     * @param [options] - The `options` parameter in the constructor is of type
-     * `AVLTreeMultiMapOptions<K, V[], R>`. It is an optional parameter that allows you to specify
-     * additional options for configuring the AVLTreeMultiMap instance.
+     * Create an AVLTreeMultiMap and optionally bulk-insert items.
+     * @remarks Time O(N log N), Space O(N)
+     * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
+     * @param [options] - Options for AVLTreeMultiMap (comparator, reverse, map mode).
+     * @returns New AVLTreeMultiMap instance.
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | R>, options?: AVLTreeMultiMapOptions<K, V[], R>);
+    _createNode(key: K, value?: V[]): AVLTreeMultiMapNode<K, V>;
+    add(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
+    add(key: K, value: V): boolean;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function `createTree` in TypeScript overrides the creation of an AVLTreeMultiMap with
-     * specified options.
-     * @param [options] - The `options` parameter in the `createTree` function is of type
-     * `AVLTreeMultiMapOptions<K, V[], R>`. This means it is an object that can have properties of type
-     * `K`, `V[]`, and `R`. The function creates a new `AVL
-     * @returns The `createTree` method is returning a new instance of `AVLTreeMultiMap` with the
-     * provided options.
+     * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
+     * @remarks Time O(log N), Space O(1)
+     * @param keyNodeOrEntry - Key, node, or [key, values] entry to locate the bucket.
+     * @param value - Value to remove from the bucket.
+     * @returns True if the value was removed; false if not found.
      */
-    createTree(options?: AVLTreeMultiMapOptions<K, V[], R>): AVLTreeMultiMap<K, V, R, MK, MV, MR>;
+    deleteValue(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined, value: V): boolean;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `createNode` function in TypeScript overrides the default implementation to create a new
-     * AVLTreeMultiMapNode with a specified key and value array.
-     * @param {K} key - The `key` parameter represents the key of the node being created in the
-     * AVLTreeMultiMap.
-     * @param {V[]} value - The `value` parameter in the `createNode` method represents an array of
-     * values associated with a specific key in the AVLTreeMultiMapNode. If no value is provided when
-     * calling the method, an empty array `[]` is used as the default value.
-     * @returns An AVLTreeMultiMapNode object is being returned, with the specified key and value. If the
-     * AVLTreeMultiMap is in map mode, an empty array is used as the value, otherwise the provided value
-     * array is used.
+     * Rebuild the tree into a perfectly balanced form using in-order nodes.
+     * @remarks Time O(N), Space O(N)
+     * @param [iterationType] - Traversal style to use when constructing the balanced tree.
+     * @returns True if rebalancing succeeded (tree not empty).
      */
-    createNode(key: K, value?: V[]): AVLTreeMultiMapNode<K, V>;
-    add(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
-    add(key: K, value: V): boolean;
+    perfectlyBalance(iterationType?: IterationType): boolean;
+    /**
+     * Create a new tree by mapping each [key, values] bucket.
+     * @remarks Time O(N log N), Space O(N)
+     * @template MK
+     * @template MVArr
+     * @template MR
+     * @param callback - Function mapping (key, values, index, tree) → [newKey, newValue].
+     * @param [options] - Options for the output tree.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new AVLTreeMultiMap when mapping to array values; see overloads.
+     */
+    map<MK = K, MVArr extends unknown[] = V[], MR extends object = object>(callback: EntryCallback<K, V[] | undefined, [MK, MVArr]>, options?: Partial<AVLTreeOptions<MK, MVArr, MR>>, thisArg?: unknown): AVLTreeMultiMap<MK, ElemOf<MVArr>, MR>;
+    /**
+     * Create a new tree by mapping each [key, values] bucket.
+     * @remarks Time O(N log N), Space O(N)
+     * @template MK
+     * @template MV
+     * @template MR
+     * @param callback - Function mapping (key, values, index, tree) → [newKey, newValue].
+     * @param [options] - Options for the output tree.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new AVLTree when mapping to non-array values; see overloads.
+     */
+    map<MK = K, MV = V[], MR extends object = object>(callback: EntryCallback<K, V[] | undefined, [MK, MV]>, options?: Partial<AVLTreeOptions<MK, MV, MR>>, thisArg?: unknown): AVLTree<MK, MV, MR>;
     /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     *
-     * The function `deleteValue` removes a specific value from a key in an AVLTreeMultiMap data
-     * structure and deletes the entire node if no values are left for that key.
-     * @param {K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | K} keyNodeOrEntry - The `keyNodeOrEntry`
-     * parameter in the `deleteValue` function can be either a `BTNRep` object representing a key-value
-     * pair in the AVLTreeMultiMapNode, or just the key itself.
-     * @param {V} value - The `value` parameter in the `deleteValue` function represents the specific
-     * value that you want to delete from the multi-map data structure associated with a particular key.
-     * The function checks if the value exists in the array of values associated with the key, and if
-     * found, removes it from the array.
-     * @returns The `deleteValue` function returns a boolean value. It returns `true` if the specified
-     * `value` was successfully deleted from the array of values associated with the `keyNodeOrEntry`. If
-     * the value was not found in the array, it returns `false`.
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @template TK
+     * @template TV
+     * @template TR
+     * @param [options] - Optional constructor options for the like-kind instance.
+     * @returns An empty like-kind instance.
      */
-    deleteValue(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | K, value: V): boolean;
+    protected _createInstance<TK = K, TV = V, TR extends object = R>(options?: Partial<AVLTreeOptions<TK, TV, TR>>): this;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The function `clone` overrides the default cloning behavior to create a deep copy of a tree
-     * structure.
-     * @returns A cloned tree object is being returned.
+     * (Protected) Create a like-kind instance and seed it from an iterable.
+     * @remarks Time O(N log N), Space O(N)
+     * @template TK
+     * @template TV
+     * @template TR
+     * @param iter - Iterable used to seed the new tree.
+     * @param [options] - Options merged with the current snapshot.
+     * @returns A like-kind AVLTree built from the iterable.
      */
-    clone(): AVLTreeMultiMap<K, V, R, MK, MV, MR>;
+    protected _createLike<TK = K, TV = V, TR extends object = R>(iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<AVLTreeOptions<TK, TV, TR>>): AVLTree<TK, TV, TR>;
 }

package/dist/data-structures/binary-tree/avl-tree-multi-map.js

@@ -1,16 +1,27 @@
 "use strict";
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AVLTreeMultiMap = exports.AVLTreeMultiMapNode = void 0;
 const avl_tree_1 = require("./avl-tree");
+/**
+ * Node used by AVLTreeMultiMap; stores the key with a bucket of values (array).
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ */
 class AVLTreeMultiMapNode extends avl_tree_1.AVLTreeNode {
     /**
-     * This TypeScript constructor initializes an object with a key of type K and an array of values of
-     * type V.
-     * @param {K} key - The `key` parameter is typically used to store a unique identifier or key for the
-     * data being stored in the data structure. It helps in quickly accessing or retrieving the
-     * associated value in the data structure.
-     * @param {V[]} value - The `value` parameter in the constructor represents an array of values of
-     * type `V`.
+     * Create an AVLTreeMultiMap node with a value bucket.
+     * @remarks Time O(1), Space O(1)
+     * @param key - Key of the node.
+     * @param value - Initial array of values.
+     * @returns New AVLTreeMultiMapNode instance.
      */
     constructor(key, value) {
         super(key, value);
@@ -18,18 +29,40 @@ class AVLTreeMultiMapNode extends avl_tree_1.AVLTreeNode {
         this._left = undefined;
         this._right = undefined;
     }
+    /**
+     * Get the left child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Left child node, or null/undefined.
+     */
     get left() {
         return this._left;
     }
+    /**
+     * Set the left child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New left child node, or null/undefined.
+     * @returns void
+     */
     set left(v) {
         if (v) {
             v.parent = this;
         }
         this._left = v;
     }
+    /**
+     * Get the right child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Right child node, or null/undefined.
+     */
     get right() {
         return this._right;
     }
+    /**
+     * Set the right child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New right child node, or null/undefined.
+     * @returns void
+     */
     set right(v) {
         if (v) {
             v.parent = this;
@@ -39,19 +72,19 @@ class AVLTreeMultiMapNode extends avl_tree_1.AVLTreeNode {
 }
 exports.AVLTreeMultiMapNode = AVLTreeMultiMapNode;
 /**
- *
+ * AVL-tree–based multimap (key → array of values). Preserves O(log N) updates and supports map-like mode.
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ * @template R
  */
 class AVLTreeMultiMap extends avl_tree_1.AVLTree {
     /**
-     * The constructor initializes an AVLTreeMultiMap with the provided keys, nodes, entries, or raw data
-     * and options.
-     * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
-     * iterable that can contain either key-value pairs represented as `BTNRep<K, V[],
-     * AVLTreeMultiMapNode<K, V>>` or raw data represented as `R`. This parameter is used to initialize
-     * the AVLTreeMulti
-     * @param [options] - The `options` parameter in the constructor is of type
-     * `AVLTreeMultiMapOptions<K, V[], R>`. It is an optional parameter that allows you to specify
-     * additional options for configuring the AVLTreeMultiMap instance.
+     * Create an AVLTreeMultiMap and optionally bulk-insert items.
+     * @remarks Time O(N log N), Space O(N)
+     * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
+     * @param [options] - Options for AVLTreeMultiMap (comparator, reverse, map mode).
+     * @returns New AVLTreeMultiMap instance.
      */
     constructor(keysNodesEntriesOrRaws = [], options) {
         super([], Object.assign(Object.assign({}, options), { isMapMode: true }));
@@ -59,53 +92,15 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
             this.addMany(keysNodesEntriesOrRaws);
         }
     }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function `createTree` in TypeScript overrides the creation of an AVLTreeMultiMap with
-     * specified options.
-     * @param [options] - The `options` parameter in the `createTree` function is of type
-     * `AVLTreeMultiMapOptions<K, V[], R>`. This means it is an object that can have properties of type
-     * `K`, `V[]`, and `R`. The function creates a new `AVL
-     * @returns The `createTree` method is returning a new instance of `AVLTreeMultiMap` with the
-     * provided options.
-     */
-    createTree(options) {
-        return new AVLTreeMultiMap([], Object.assign({ iterationType: this.iterationType, specifyComparable: this._specifyComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse, isMapMode: this._isMapMode }, options));
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `createNode` function in TypeScript overrides the default implementation to create a new
-     * AVLTreeMultiMapNode with a specified key and value array.
-     * @param {K} key - The `key` parameter represents the key of the node being created in the
-     * AVLTreeMultiMap.
-     * @param {V[]} value - The `value` parameter in the `createNode` method represents an array of
-     * values associated with a specific key in the AVLTreeMultiMapNode. If no value is provided when
-     * calling the method, an empty array `[]` is used as the default value.
-     * @returns An AVLTreeMultiMapNode object is being returned, with the specified key and value. If the
-     * AVLTreeMultiMap is in map mode, an empty array is used as the value, otherwise the provided value
-     * array is used.
-     */
-    createNode(key, value = []) {
+    _createNode(key, value = []) {
         return new AVLTreeMultiMapNode(key, this._isMapMode ? [] : value);
     }
     /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     *
-     * The function `add` in this TypeScript code overrides the superclass method to add key-value pairs
-     * to an AVLTreeMultiMap, handling different input types and scenarios.
-     * @param [key] - The `key` parameter in the `override add` method represents the key of the entry to
-     * be added to the AVLTreeMultiMap. It can be of type `K`, which is the key type of the map. The key
-     * can be a single key value, a node of the AVLTree
-     * @param {V[]} [values] - The `values` parameter in the `add` method represents an array of values
-     * that you want to add to the AVLTreeMultiMap. It can contain one or more values associated with a
-     * specific key.
-     * @returns The `add` method is returning a boolean value, which indicates whether the operation was
-     * successful or not.
+     * Insert a value or a list of values into the multimap. If the key exists, values are appended.
+     * @remarks Time O(log N + M), Space O(1)
+     * @param keyNodeOrEntry - Key, node, or [key, values] entry.
+     * @param [value] - Single value to add when a bare key is provided.
+     * @returns True if inserted or appended; false if ignored.
      */
     add(keyNodeOrEntry, value) {
         if (this.isRealNode(keyNodeOrEntry))
@@ -155,21 +150,11 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
         return _commonAdd(keyNodeOrEntry, value !== undefined ? [value] : undefined);
     }
     /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     *
-     * The function `deleteValue` removes a specific value from a key in an AVLTreeMultiMap data
-     * structure and deletes the entire node if no values are left for that key.
-     * @param {K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | K} keyNodeOrEntry - The `keyNodeOrEntry`
-     * parameter in the `deleteValue` function can be either a `BTNRep` object representing a key-value
-     * pair in the AVLTreeMultiMapNode, or just the key itself.
-     * @param {V} value - The `value` parameter in the `deleteValue` function represents the specific
-     * value that you want to delete from the multi-map data structure associated with a particular key.
-     * The function checks if the value exists in the array of values associated with the key, and if
-     * found, removes it from the array.
-     * @returns The `deleteValue` function returns a boolean value. It returns `true` if the specified
-     * `value` was successfully deleted from the array of values associated with the `keyNodeOrEntry`. If
-     * the value was not found in the array, it returns `false`.
+     * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
+     * @remarks Time O(log N), Space O(1)
+     * @param keyNodeOrEntry - Key, node, or [key, values] entry to locate the bucket.
+     * @param value - Value to remove from the bucket.
+     * @returns True if the value was removed; false if not found.
      */
     deleteValue(keyNodeOrEntry, value) {
         const values = this.get(keyNodeOrEntry);
@@ -178,7 +163,6 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
             if (index === -1)
                 return false;
             values.splice(index, 1);
-            // If no values left, remove the entire node
             if (values.length === 0)
                 this.delete(keyNodeOrEntry);
             return true;
@@ -186,17 +170,81 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
         return false;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The function `clone` overrides the default cloning behavior to create a deep copy of a tree
-     * structure.
-     * @returns A cloned tree object is being returned.
+     * Rebuild the tree into a perfectly balanced form using in-order nodes.
+     * @remarks Time O(N), Space O(N)
+     * @param [iterationType] - Traversal style to use when constructing the balanced tree.
+     * @returns True if rebalancing succeeded (tree not empty).
+     */
+    perfectlyBalance(iterationType = this.iterationType) {
+        const nodes = this.dfs(node => node, 'IN', false, this._root, iterationType);
+        const n = nodes.length;
+        if (n === 0)
+            return false;
+        this._clearNodes();
+        const build = (l, r, parent) => {
+            if (l > r)
+                return undefined;
+            const m = l + ((r - l) >> 1);
+            const root = nodes[m];
+            root.left = build(l, m - 1, root);
+            root.right = build(m + 1, r, root);
+            root.parent = parent;
+            const lh = root.left ? root.left.height : -1;
+            const rh = root.right ? root.right.height : -1;
+            root.height = Math.max(lh, rh) + 1;
+            return root;
+        };
+        const newRoot = build(0, n - 1, undefined);
+        this._setRoot(newRoot);
+        this._size = n;
+        return true;
+    }
+    /**
+     * Create a new tree by mapping each [key, values] bucket.
+     * @remarks Time O(N log N), Space O(N)
+     * @template MK
+     * @template MV
+     * @template MR
+     * @param callback - Function mapping (key, values, index, tree) → [newKey, newValue].
+     * @param [options] - Options for the output tree.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns The mapped AVLTree or AVLTreeMultiMap depending on MV; see overloads.
+     */
+    map(callback, options, thisArg) {
+        const out = this._createLike([], options);
+        let i = 0;
+        for (const [k, v] of this)
+            out.add(callback.call(thisArg, k, v, i++, this));
+        return out;
+    }
+    /**
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @template TK
+     * @template TV
+     * @template TR
+     * @param [options] - Optional constructor options for the like-kind instance.
+     * @returns An empty like-kind instance.
+     */
+    _createInstance(options) {
+        var _a, _b;
+        const Ctor = this.constructor;
+        return new Ctor([], Object.assign(Object.assign({}, ((_b = (_a = this._snapshotOptions) === null || _a === void 0 ? void 0 : _a.call(this)) !== null && _b !== void 0 ? _b : {})), (options !== null && options !== void 0 ? options : {})));
+    }
+    /**
+     * (Protected) Create a like-kind instance and seed it from an iterable.
+     * @remarks Time O(N log N), Space O(N)
+     * @template TK
+     * @template TV
+     * @template TR
+     * @param iter - Iterable used to seed the new tree.
+     * @param [options] - Options merged with the current snapshot.
+     * @returns A like-kind AVLTree built from the iterable.
      */
-    clone() {
-        const cloned = this.createTree();
-        this._clone(cloned);
-        return cloned;
+    _createLike(iter = [], options) {
+        var _a, _b;
+        const Ctor = this.constructor;
+        return new Ctor(iter, Object.assign(Object.assign({}, ((_b = (_a = this._snapshotOptions) === null || _a === void 0 ? void 0 : _a.call(this)) !== null && _b !== void 0 ? _b : {})), (options !== null && options !== void 0 ? options : {})));
     }
 }
 exports.AVLTreeMultiMap = AVLTreeMultiMap;