doubly-linked-list-typed 2.0.4 → 2.1.0

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

@@ -5,30 +5,60 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { TreeMultiMapOptions } from '../../types';
+import type { ElemOf, EntryCallback, RedBlackTreeOptions, TreeMultiMapOptions } from '../../types';
 import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
 import { IBinaryTree } from '../../interfaces';
+/**
+ * Node used by TreeMultiMap; stores the key with a bucket of values (array).
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ */
 export declare class TreeMultiMapNode<K = any, V = any> extends RedBlackTreeNode<K, V[]> {
     parent?: TreeMultiMapNode<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 a TreeMultiMap node with an optional value bucket.
+     * @remarks Time O(1), Space O(1)
+     * @param key - Key of the node.
+     * @param [value] - Initial array of values.
+     * @returns New TreeMultiMapNode instance.
      */
     constructor(key: K, value?: V[]);
     _left?: TreeMultiMapNode<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(): TreeMultiMapNode<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: TreeMultiMapNode<K, V> | null | undefined);
     _right?: TreeMultiMapNode<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(): TreeMultiMapNode<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: TreeMultiMapNode<K, V> | null | undefined);
 }
 /**
- *
+ * Red-Black 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
  * @example
  * // players ranked by score with their equipment
  *     type Equipment = {
@@ -194,74 +224,47 @@ export declare class TreeMultiMapNode<K = any, V = any> extends RedBlackTreeNode
  *  //      ]
  *  //    ]
  */
-export declare class TreeMultiMap<K = any, V = any, R = object, MK = any, MV = any, MR = object> extends RedBlackTree<K, V[], R, MK, MV[], MR> implements IBinaryTree<K, V[], R, MK, MV, MR> {
+export declare class TreeMultiMap<K = any, V = any, R extends object = object> extends RedBlackTree<K, V[], R> implements IBinaryTree<K, V[], R> {
     /**
-     * The constructor initializes an TreeMultiMap 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[],
-     * TreeMultiMapNode<K, V>>` or raw data represented as `R`. This parameter is used to initialize
-     * the RedBlackTreeMulti
-     * @param [options] - The `options` parameter in the constructor is of type
-     * `TreeMultiMapOptions<K, V[], R>`. It is an optional parameter that allows you to specify
-     * additional options for configuring the TreeMultiMap instance.
+     * Create a TreeMultiMap 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 TreeMultiMap (comparator, reverse, map mode).
+     * @returns New TreeMultiMap instance.
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | R>, options?: TreeMultiMapOptions<K, V[], R>);
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `createTree` function in TypeScript overrides the default implementation to create a new
-     * TreeMultiMap with specified options.
-     * @param [options] - The `options` parameter in the `createTree` method is of type
-     * `TreeMultiMapOptions<K, V[], R>`. This parameter allows you to pass additional configuration
-     * options when creating a new `TreeMultiMap` instance. It includes properties such as
-     * `iterationType`, `specifyComparable
-     * @returns A new instance of `TreeMultiMap` is being returned, with an empty array as the initial
-     * data and the provided options merged with the existing properties of the current object.
-     */
-    createTree(options?: TreeMultiMapOptions<K, V[], R>): TreeMultiMap<K, V, R, MK, MV, MR>;
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function `createNode` overrides the creation of a new TreeMultiMapNode with a specified key
-     * and value array.
-     * @param {K} key - The `key` parameter represents the key of the node being created in the
-     * `TreeMultiMap`.
-     * @param {V[]} value - The `value` parameter in the `createNode` method represents an array of
-     * values associated with a specific key in the TreeMultiMap data structure.
-     * @returns A new instance of `TreeMultiMapNode<K, V>` is being returned with the specified key and
-     * value. If `_isMapMode` is true, an empty array is passed as the value, otherwise the provided
-     * value is used.
-     */
-    createNode(key: K, value?: V[]): TreeMultiMapNode<K, V>;
+    _createNode(key: K, value?: V[]): TreeMultiMapNode<K, V>;
     add(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
     add(key: K, value: V): boolean;
     /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     *
-     * The function `deleteValue` removes a specific value from a key in a TreeMultiMap data structure
-     * and deletes the entire node if no values are left for that key.
-     * @param {K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined} keyNodeOrEntry - The `keyNodeOrEntry`
-     * parameter in the `deleteValue` function can be either a `BTNRep` object containing a key and an
-     * array of values, or just a key itself.
-     * @param {V} value - The `value` parameter in the `deleteValue` function represents the specific
-     * value that you want to remove 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 - `true` if the specified `value` was
-     * successfully deleted from the values associated with the `keyNodeOrEntry`, and `false` otherwise.
+     * 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: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined, value: V): boolean;
+    map<MK = K, MVArr extends unknown[] = V[], MR extends object = object>(callback: EntryCallback<K, V[] | undefined, [MK, MVArr]>, options?: Partial<RedBlackTreeOptions<MK, MVArr, MR>>, thisArg?: unknown): TreeMultiMap<MK, ElemOf<MVArr>, MR>;
+    map<MK = K, MV = V[], MR extends object = object>(callback: EntryCallback<K, V[] | undefined, [MK, MV]>, options?: Partial<RedBlackTreeOptions<MK, MV, MR>>, thisArg?: unknown): RedBlackTree<MK, MV, MR>;
+    /**
+     * (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.
+     */
+    protected _createInstance<TK = K, TV = V, TR extends object = R>(options?: Partial<RedBlackTreeOptions<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 The `cloned` 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 RedBlackTree built from the iterable.
      */
-    clone(): TreeMultiMap<K, V, R, MK, MV, MR>;
+    protected _createLike<TK = K, TV = V, TR extends object = R>(iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): RedBlackTree<TK, TV, TR>;
 }

package/dist/data-structures/binary-tree/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.TreeMultiMap = exports.TreeMultiMapNode = void 0;
 const red_black_tree_1 = require("./red-black-tree");
+/**
+ * Node used by TreeMultiMap; stores the key with a bucket of values (array).
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ */
 class TreeMultiMapNode extends red_black_tree_1.RedBlackTreeNode {
     /**
-     * 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 a TreeMultiMap node with an optional value bucket.
+     * @remarks Time O(1), Space O(1)
+     * @param key - Key of the node.
+     * @param [value] - Initial array of values.
+     * @returns New TreeMultiMapNode instance.
      */
     constructor(key, value) {
         super(key, value);
@@ -18,18 +29,40 @@ class TreeMultiMapNode extends red_black_tree_1.RedBlackTreeNode {
         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,7 +72,11 @@ class TreeMultiMapNode extends red_black_tree_1.RedBlackTreeNode {
 }
 exports.TreeMultiMapNode = TreeMultiMapNode;
 /**
- *
+ * Red-Black 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
  * @example
  * // players ranked by score with their equipment
  *     type Equipment = {
@@ -207,15 +244,11 @@ exports.TreeMultiMapNode = TreeMultiMapNode;
  */
 class TreeMultiMap extends red_black_tree_1.RedBlackTree {
     /**
-     * The constructor initializes an TreeMultiMap 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[],
-     * TreeMultiMapNode<K, V>>` or raw data represented as `R`. This parameter is used to initialize
-     * the RedBlackTreeMulti
-     * @param [options] - The `options` parameter in the constructor is of type
-     * `TreeMultiMapOptions<K, V[], R>`. It is an optional parameter that allows you to specify
-     * additional options for configuring the TreeMultiMap instance.
+     * Create a TreeMultiMap 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 TreeMultiMap (comparator, reverse, map mode).
+     * @returns New TreeMultiMap instance.
      */
     constructor(keysNodesEntriesOrRaws = [], options) {
         super([], Object.assign({}, options));
@@ -223,52 +256,15 @@ class TreeMultiMap extends red_black_tree_1.RedBlackTree {
             this.addMany(keysNodesEntriesOrRaws);
         }
     }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `createTree` function in TypeScript overrides the default implementation to create a new
-     * TreeMultiMap with specified options.
-     * @param [options] - The `options` parameter in the `createTree` method is of type
-     * `TreeMultiMapOptions<K, V[], R>`. This parameter allows you to pass additional configuration
-     * options when creating a new `TreeMultiMap` instance. It includes properties such as
-     * `iterationType`, `specifyComparable
-     * @returns A new instance of `TreeMultiMap` is being returned, with an empty array as the initial
-     * data and the provided options merged with the existing properties of the current object.
-     */
-    createTree(options) {
-        return new TreeMultiMap([], 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 function `createNode` overrides the creation of a new TreeMultiMapNode with a specified key
-     * and value array.
-     * @param {K} key - The `key` parameter represents the key of the node being created in the
-     * `TreeMultiMap`.
-     * @param {V[]} value - The `value` parameter in the `createNode` method represents an array of
-     * values associated with a specific key in the TreeMultiMap data structure.
-     * @returns A new instance of `TreeMultiMapNode<K, V>` is being returned with the specified key and
-     * value. If `_isMapMode` is true, an empty array is passed as the value, otherwise the provided
-     * value is used.
-     */
-    createNode(key, value = []) {
+    _createNode(key, value = []) {
         return new TreeMultiMapNode(key, this._isMapMode ? [] : value);
     }
     /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     *
-     * The function overrides the add method to handle different types of input for a TreeMultiMap data
-     * structure.
-     * @param [key] - The `key` parameter in the `override add` method represents the key of the entry to
-     * be added to the TreeMultiMap. It can be of type `K`, which is the key type of the TreeMultiMap, or
-     * it can be a TreeMultiMapNode containing the key and its
-     * @param {V[]} [values] - The `values` parameter in the `add` method represents an array of values
-     * that you want to add to the TreeMultiMap. It can contain one or more values of type `V`.
-     * @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))
@@ -318,20 +314,11 @@ class TreeMultiMap extends red_black_tree_1.RedBlackTree {
         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 a TreeMultiMap data structure
-     * and deletes the entire node if no values are left for that key.
-     * @param {K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined} keyNodeOrEntry - The `keyNodeOrEntry`
-     * parameter in the `deleteValue` function can be either a `BTNRep` object containing a key and an
-     * array of values, or just a key itself.
-     * @param {V} value - The `value` parameter in the `deleteValue` function represents the specific
-     * value that you want to remove 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 - `true` if the specified `value` was
-     * successfully deleted from the values associated with the `keyNodeOrEntry`, and `false` otherwise.
+     * 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);
@@ -340,7 +327,6 @@ class TreeMultiMap extends red_black_tree_1.RedBlackTree {
             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;
@@ -348,17 +334,51 @@ class TreeMultiMap extends red_black_tree_1.RedBlackTree {
         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 The `cloned` object is being returned.
+     * 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 RedBlackTree (or TreeMultiMap when mapping to array values; 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 RedBlackTree 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.TreeMultiMap = TreeMultiMap;