stack-typed 1.54.0 → 1.54.2

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

@@ -4,391 +4,186 @@ exports.AVLTreeMultiMap = exports.AVLTreeMultiMapNode = void 0;
 const avl_tree_1 = require("./avl-tree");
 class AVLTreeMultiMapNode extends avl_tree_1.AVLTreeNode {
     /**
-     * The constructor function initializes a BinaryTreeNode object with a key, value, and count.
-     * @param {K} key - The `key` parameter is of type `K` and represents the unique identifier
-     * of the binary tree node.
-     * @param {V} [value] - The `value` parameter is an optional parameter of type `V`. It represents the value of the binary
-     * tree node. If no value is provided, it will be `undefined`.
-     * @param {number} [count=1] - The `count` parameter is a number that represents the number of times a particular value
-     * occurs in a binary tree node. It has a default value of 1, which means that if no value is provided for the `count`
-     * parameter when creating a new instance of the `BinaryTreeNode` class.
-     */
-    constructor(key, value, count = 1) {
+     * 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`.
+     */
+    constructor(key, value) {
         super(key, value);
-        this.count = count;
+        this.parent = undefined;
+        this._left = undefined;
+        this._right = undefined;
+    }
+    get left() {
+        return this._left;
+    }
+    set left(v) {
+        if (v) {
+            v.parent = this;
+        }
+        this._left = v;
+    }
+    get right() {
+        return this._right;
+    }
+    set right(v) {
+        if (v) {
+            v.parent = this;
+        }
+        this._right = v;
     }
 }
 exports.AVLTreeMultiMapNode = 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.
+ *
  */
 class AVLTreeMultiMap extends avl_tree_1.AVLTree {
     /**
-     * The constructor initializes a new AVLTreeMultiMap object with optional initial elements.
-     * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter is an
-     * iterable object that can contain either keys, nodes, entries, or raw elements.
-     * @param [options] - The `options` parameter is an optional object that can be used to customize the
-     * behavior of the AVLTreeMultiMap. It can include properties such as `compareKeys` and
-     * `compareValues` functions to define custom comparison logic for keys and values, respectively.
+     * 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.
      */
     constructor(keysNodesEntriesOrRaws = [], options) {
-        super([], options);
-        this._count = 0;
-        if (keysNodesEntriesOrRaws)
+        super([], Object.assign(Object.assign({}, options), { isMapMode: true }));
+        if (keysNodesEntriesOrRaws) {
             this.addMany(keysNodesEntriesOrRaws);
+        }
     }
     /**
-     * The function calculates the sum of the count property of all nodes in a tree using depth-first
-     * search.
-     * @returns the sum of the count property of all nodes in the tree.
-     */
-    get count() {
-        return this._count;
-    }
-    /**
-     * Time Complexity: O(n)
+     * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function calculates the sum of the count property of all nodes in a tree using depth-first
-     * search.
-     * @returns the sum of the count property of all nodes in the tree.
-     */
-    getComputedCount() {
-        let sum = 0;
-        this.dfs(node => (sum += node.count));
-        return sum;
-    }
-    /**
-     * The function creates a new AVLTreeMultiMapNode with the specified key, value, and count.
-     * @param {K} key - The key parameter represents the key of the node being created. It is of type K,
-     * which is a generic type that can be replaced with any specific type when using the function.
-     * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
-     * associated with the key in the node. It is of type `V`, which can be any data type.
-     * @param {number} [count] - The `count` parameter represents the number of occurrences of a
-     * key-value pair in the AVLTreeMultiMapNode. It is an optional parameter, so it can be omitted when
-     * calling the `createNode` method. If provided, it specifies the initial count for the node.
-     * @returns a new instance of the AVLTreeMultiMapNode class, casted as NODE.
-     */
-    createNode(key, value, count) {
-        return new AVLTreeMultiMapNode(key, this._isMapMode ? undefined : value, count);
-    }
-    /**
-     * 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. It can have the following properties:
-     * @returns a new instance of the AVLTreeMultiMap class, with the specified options, as a TREE
-     * object.
+     * 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, isMapMode: this._isMapMode, specifyComparable: this._specifyComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse }, options));
+        return new AVLTreeMultiMap([], Object.assign({ iterationType: this.iterationType, specifyComparable: this._specifyComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse }, options));
     }
     /**
-     * The function checks if the input is an instance of AVLTreeMultiMapNode.
-     * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The parameter
-     * `keyNodeEntryOrRaw` can be of type `R` or `BTNRep<K, V, NODE>`.
-     * @returns a boolean value indicating whether the input parameter `keyNodeEntryOrRaw` is
-     * an instance of the `AVLTreeMultiMapNode` class.
-     */
-    isNode(keyNodeEntryOrRaw) {
-        return keyNodeEntryOrRaw instanceof AVLTreeMultiMapNode;
-    }
-    /**
-     * Time Complexity: O(log n)
+     * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function overrides the add method of a TypeScript class to add a new node to a data structure
-     * and update the count.
-     * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The
-     * `keyNodeEntryOrRaw` parameter can accept a value of type `R`, which can be any type. It
-     * can also accept a value of type `BTNRep<K, V, NODE>`, which represents a key, node,
-     * entry, or raw element
-     * @param {V} [value] - The `value` parameter represents the value associated with the key in the
-     * data structure. It is an optional parameter, so it can be omitted if not needed.
-     * @param [count=1] - The `count` parameter represents the number of times the key-value pair should
-     * be added to the data structure. By default, it is set to 1, meaning that the key-value pair will
-     * be added once. However, you can specify a different value for `count` if you want to add
-     * @returns a boolean value.
+     * The function `createNode` overrides the method to create a new AVLTreeMultiMapNode with a
+     * specified key and an empty array of values.
+     * @param {K} key - The `key` parameter in the `createNode` method represents the key of the node
+     * that will be created in the AVLTreeMultiMap.
+     * @returns An AVLTreeMultiMapNode object is being returned, initialized with the provided key and an
+     * empty array.
      */
-    add(keyNodeEntryOrRaw, value, count = 1) {
-        const [newNode, newValue] = this._keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count);
-        if (newNode === undefined)
-            return false;
-        const orgNodeCount = (newNode === null || newNode === void 0 ? void 0 : newNode.count) || 0;
-        const inserted = super.add(newNode, newValue);
-        if (inserted) {
-            this._count += orgNodeCount;
-        }
-        return true;
+    createNode(key) {
+        return new AVLTreeMultiMapNode(key, []);
     }
     /**
      * Time Complexity: O(log n)
-     * Space Complexity: O(1)
+     * Space Complexity: O(log n)
      *
-     * The function overrides the delete method in a binary tree data structure, handling deletion of
-     * nodes and maintaining balance in the tree.
-     * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The `predicate`
-     * parameter in the `delete` method is used to specify the condition for deleting a node from the
-     * binary tree. It can be a key, node, or entry that determines which
-     * node(s) should be deleted.
-     * @param [ignoreCount=false] - The `ignoreCount` parameter in the `override delete` method is a
-     * boolean flag that determines whether to ignore the count of the node being deleted. If
-     * `ignoreCount` is set to `true`, the method will delete the node regardless of its count. If
-     * `ignoreCount` is set to
-     * @returns The `delete` method overrides the default delete behavior in a binary tree data
-     * structure. It takes a predicate or node to be deleted and an optional flag to ignore count. The
-     * method returns an array of `BinaryTreeDeleteResult` objects, each containing information about the
-     * deleted node and whether balancing is needed in the tree.
-     */
-    delete(keyNodeEntryOrRaw, ignoreCount = false) {
-        var _a;
-        const deletedResult = [];
-        if (!this.root)
-            return deletedResult;
-        const curr = (_a = this.getNode(keyNodeEntryOrRaw)) !== null && _a !== void 0 ? _a : undefined;
-        if (!curr)
-            return deletedResult;
-        const parent = (curr === null || curr === void 0 ? void 0 : curr.parent) ? curr.parent : undefined;
-        let needBalanced = undefined, orgCurrent = curr;
-        if (curr.count > 1 && !ignoreCount) {
-            curr.count--;
-            this._count--;
-        }
-        else {
-            if (!curr.left) {
-                if (!parent) {
-                    if (curr.right !== undefined && curr.right !== null)
-                        this._setRoot(curr.right);
+     * The function `add` in TypeScript overrides the superclass method to add key-value pairs to an AVL
+     * tree multi-map.
+     * @param {BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | K} keyNodeOrEntry - The `keyNodeOrEntry`
+     * parameter in the `override add` method can be either a key-value pair entry or just a key. If it
+     * is a key-value pair entry, it will be in the format `[key, values]`, where `key` is the key and
+     * `values`
+     * @param {V} [value] - The `value` parameter in the `override add` method represents the value that
+     * you want to add to the AVLTreeMultiMap. It can be a single value or an array of values associated
+     * with a specific key.
+     * @returns The `override add` method is returning a boolean value, which indicates whether the
+     * addition operation was successful or not.
+     */
+    add(keyNodeOrEntry, value) {
+        if (this.isRealNode(keyNodeOrEntry))
+            return super.add(keyNodeOrEntry);
+        const _commonAdd = (key, values) => {
+            if (key === undefined || key === null)
+                return false;
+            const existingValues = this.get(key);
+            if (existingValues !== undefined && values !== undefined) {
+                for (const value of values)
+                    existingValues.push(value);
+                return true;
+            }
+            const existingNode = this.getNode(key);
+            if (this.isRealNode(existingNode)) {
+                if (existingValues === undefined) {
+                    super.add(key, values);
+                    return true;
+                }
+                if (values !== undefined) {
+                    for (const value of values)
+                        existingValues.push(value);
+                    return true;
                 }
                 else {
-                    const { familyPosition: fp } = curr;
-                    if (fp === 'LEFT' || fp === 'ROOT_LEFT') {
-                        parent.left = curr.right;
-                    }
-                    else if (fp === 'RIGHT' || fp === 'ROOT_RIGHT') {
-                        parent.right = curr.right;
-                    }
-                    needBalanced = parent;
+                    return false;
                 }
             }
             else {
-                const leftSubTreeRightMost = curr.left ? this.getRightMost(node => node, curr.left) : undefined;
-                if (leftSubTreeRightMost) {
-                    const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
-                    orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
-                    if (parentOfLeftSubTreeMax) {
-                        if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost) {
-                            parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
-                        }
-                        else {
-                            parentOfLeftSubTreeMax.left = leftSubTreeRightMost.left;
-                        }
-                        needBalanced = parentOfLeftSubTreeMax;
-                    }
-                }
+                return super.add(key, values);
             }
-            this._size = this._size - 1;
-            // TODO How to handle when the count of target node is lesser than current node's count
-            if (orgCurrent)
-                this._count -= orgCurrent.count;
-        }
-        deletedResult.push({ deleted: orgCurrent, needBalanced });
-        if (needBalanced) {
-            this._balancePath(needBalanced);
+        };
+        if (this.isEntry(keyNodeOrEntry)) {
+            const [key, values] = keyNodeOrEntry;
+            return _commonAdd(key, value !== undefined ? [value] : values);
         }
-        return deletedResult;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The "clear" function overrides the parent class's "clear" function and also resets the count to
-     * zero.
-     */
-    clear() {
-        super.clear();
-        this._count = 0;
+        return _commonAdd(keyNodeOrEntry, value !== undefined ? [value] : undefined);
     }
     /**
-     * Time Complexity: O(n log n)
+     * Time Complexity: O(log n)
      * Space Complexity: O(log n)
-     * The `perfectlyBalance` function takes a sorted array of nodes and builds a balanced binary search
-     * tree using either a recursive or iterative approach.
-     * @param {IterationType} iterationType - The `iterationType` parameter is an optional parameter that
-     * specifies the type of iteration to use when building the balanced binary search tree. It has a
-     * default value of `this.iterationType`, which means it will use the iteration type currently set in
-     * the object.
-     * @returns The function `perfectlyBalance` returns a boolean value. It returns `true` if the
-     * balancing operation is successful, and `false` if there are no nodes to balance.
-     */
-    perfectlyBalance(iterationType = this.iterationType) {
-        const sorted = this.dfs(node => node, 'IN'), n = sorted.length;
-        if (sorted.length < 1)
-            return false;
-        this.clear();
-        if (iterationType === 'RECURSIVE') {
-            const buildBalanceBST = (l, r) => {
-                if (l > r)
-                    return;
-                const m = l + Math.floor((r - l) / 2);
-                const midNode = sorted[m];
-                if (this._isMapMode)
-                    this.add(midNode.key, undefined, midNode.count);
-                else
-                    this.add(midNode.key, midNode.value, midNode.count);
-                buildBalanceBST(l, m - 1);
-                buildBalanceBST(m + 1, r);
-            };
-            buildBalanceBST(0, n - 1);
-            return true;
-        }
-        else {
-            const stack = [[0, n - 1]];
-            while (stack.length > 0) {
-                const popped = stack.pop();
-                if (popped) {
-                    const [l, r] = popped;
-                    if (l <= r) {
-                        const m = l + Math.floor((r - l) / 2);
-                        const midNode = sorted[m];
-                        if (this._isMapMode)
-                            this.add(midNode.key, undefined, midNode.count);
-                        else
-                            this.add(midNode.key, midNode.value, midNode.count);
-                        stack.push([m + 1, r]);
-                        stack.push([l, m - 1]);
-                    }
-                }
-            }
+     *
+     * 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 {BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | 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`.
+     */
+    deleteValue(keyNodeOrEntry, value) {
+        const values = this.get(keyNodeOrEntry);
+        if (Array.isArray(values)) {
+            const index = values.indexOf(value);
+            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;
         }
+        return false;
     }
     /**
-     * Time complexity: O(n)
-     * Space complexity: O(n)
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
      *
-     * The function overrides the clone method to create a deep copy of a tree object.
-     * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
+     * 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.
      */
     clone() {
         const cloned = this.createTree();
-        if (this._isMapMode)
-            this.bfs(node => cloned.add(node.key, undefined, node.count));
-        else
-            this.bfs(node => cloned.add(node.key, node.value, node.count));
-        if (this._isMapMode)
-            cloned._store = this._store;
+        this._clone(cloned);
         return cloned;
     }
-    /**
-     * The `map` function in TypeScript overrides the default behavior to create a new AVLTreeMultiMap
-     * with modified entries based on a provided callback.
-     * @param callback - The `callback` parameter is a function that will be called for each entry in the
-     * AVLTreeMultiMap. It takes four arguments:
-     * @param [options] - The `options` parameter in the `override map` function is of type
-     * `AVLTreeMultiMapOptions<MK, MV, MR>`. This parameter allows you to provide additional
-     * configuration options when creating a new `AVLTreeMultiMap` instance within the `map` function.
-     * These options
-     * @param {any} [thisArg] - The `thisArg` parameter in the `override map` function is used to specify
-     * the value of `this` when executing the `callback` function. It allows you to set the context
-     * (value of `this`) for the callback function. This can be useful when you want to access properties
-     * or
-     * @returns The `map` method is returning a new `AVLTreeMultiMap` instance with the entries
-     * transformed by the provided `callback` function. Each entry in the original tree is passed to the
-     * `callback` function along with the index and the original tree itself. The transformed entries are
-     * then added to the new `AVLTreeMultiMap` instance, which is returned at the end.
-     */
-    map(callback, options, thisArg) {
-        const newTree = new AVLTreeMultiMap([], options);
-        let index = 0;
-        for (const [key, value] of this) {
-            newTree.add(callback.call(thisArg, key, value, index++, this));
-        }
-        return newTree;
-    }
-    /**
-     * The function `keyValueNodeEntryRawToNodeAndValue` converts a key, value, entry, or raw element into
-     * a node object.
-     * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The
-     * `keyNodeEntryOrRaw` parameter can be of type `R` or `BTNRep<K, V, NODE>`.
-     * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
-     * `override` function. It represents the value associated with the key in the data structure. If no
-     * value is provided, it will default to `undefined`.
-     * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
-     * times the key-value pair should be added to the data structure. If not provided, it defaults to 1.
-     * @returns either a NODE object or undefined.
-     */
-    _keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count = 1) {
-        if (keyNodeEntryOrRaw === undefined || keyNodeEntryOrRaw === null)
-            return [undefined, undefined];
-        if (this.isNode(keyNodeEntryOrRaw))
-            return [keyNodeEntryOrRaw, value];
-        if (this.isEntry(keyNodeEntryOrRaw)) {
-            const [key, entryValue] = keyNodeEntryOrRaw;
-            if (key === undefined || key === null)
-                return [undefined, undefined];
-            const finalValue = value !== null && value !== void 0 ? value : entryValue;
-            return [this.createNode(key, finalValue, count), finalValue];
-        }
-        if (this.isRaw(keyNodeEntryOrRaw)) {
-            const [key, entryValue] = this._toEntryFn(keyNodeEntryOrRaw);
-            const finalValue = value !== null && value !== void 0 ? value : entryValue;
-            if (this.isKey(key))
-                return [this.createNode(key, finalValue, count), finalValue];
-        }
-        if (this.isKey(keyNodeEntryOrRaw))
-            return [this.createNode(keyNodeEntryOrRaw, value, count), value];
-        return [undefined, undefined];
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `_swapProperties` function swaps the properties (key, value, count, height) between two nodes
-     * in a binary search tree.
-     * @param {R | BSTNOptKeyOrNode<K, NODE>} srcNode - The `srcNode` parameter represents the source node
-     * that will be swapped with the `destNode`.
-     * @param {R | BSTNOptKeyOrNode<K, NODE>} destNode - The `destNode` parameter represents the destination
-     * node where the properties will be swapped with the source node.
-     * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
-     * If either `srcNode` or `destNode` is undefined, it returns `undefined`.
-     */
-    _swapProperties(srcNode, destNode) {
-        srcNode = this.ensureNode(srcNode);
-        destNode = this.ensureNode(destNode);
-        if (srcNode && destNode) {
-            const { key, value, count, height } = destNode;
-            const tempNode = this.createNode(key, value, count);
-            if (tempNode) {
-                tempNode.height = height;
-                destNode.key = srcNode.key;
-                if (!this._isMapMode)
-                    destNode.value = srcNode.value;
-                destNode.count = srcNode.count;
-                destNode.height = srcNode.height;
-                srcNode.key = tempNode.key;
-                if (!this._isMapMode)
-                    srcNode.value = tempNode.value;
-                srcNode.count = tempNode.count;
-                srcNode.height = tempNode.height;
-            }
-            return destNode;
-        }
-        return undefined;
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function replaces an old node with a new node and updates the count property of the new node.
-     * @param {NODE} oldNode - The oldNode parameter represents the node that needs to be replaced in the
-     * data structure. It is of type NODE.
-     * @param {NODE} newNode - The `newNode` parameter is an instance of the `NODE` class.
-     * @returns The method is returning the result of calling the `_replaceNode` method from the
-     * superclass, which is of type `NODE`.
-     */
-    _replaceNode(oldNode, newNode) {
-        newNode.count = oldNode.count + newNode.count;
-        return super._replaceNode(oldNode, newNode);
-    }
 }
 exports.AVLTreeMultiMap = AVLTreeMultiMap;