bst-typed 2.0.4 → 2.1.0

package/dist/data-structures/base/iterable-element-base.js

@@ -1,11 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IterableElementBase = void 0;
+/**
+ * Base class that makes a data structure iterable and provides common
+ * element-wise utilities (e.g., map/filter/reduce/find).
+ *
+ * @template E The public element type yielded by the structure.
+ * @template R The underlying "raw" element type used internally or by converters.
+ *
+ * @remarks
+ * This class implements the JavaScript iteration protocol (via `Symbol.iterator`)
+ * and offers array-like helpers with predictable time/space complexity.
+ */
 class IterableElementBase {
     /**
-     * The protected constructor initializes the options for the IterableElementBase class, including the
-     * toElementFn function.
-     * @param [options] - An optional object that contains the following properties:
+     * Create a new iterable base.
+     *
+     * @param options Optional behavior overrides. When provided, a `toElementFn`
+     * is used to convert a raw element (`R`) into a public element (`E`).
+     *
+     * @remarks
+     * Time O(1), Space O(1).
      */
     constructor(options) {
         if (options) {
@@ -16,183 +31,210 @@ class IterableElementBase {
                 throw new TypeError('toElementFn must be a function type');
         }
     }
+    /**
+     * Exposes the current `toElementFn`, if configured.
+     *
+     * @returns The converter function or `undefined` when not set.
+     * @remarks
+     * Time O(1), Space O(1).
+     */
     get toElementFn() {
         return this._toElementFn;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
+     * Returns an iterator over the structure's elements.
      *
-     * The function is an implementation of the Symbol.iterator method that returns an IterableIterator.
-     * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
-     * allows the function to accept any number of arguments as an array. In this case, the `args`
-     * parameter is used to pass any number of arguments to the `_getIterator` method.
+     * @param args Optional iterator arguments forwarded to the internal iterator.
+     * @returns An `IterableIterator<E>` that yields the elements in traversal order.
+     *
+     * @remarks
+     * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
      */
     *[Symbol.iterator](...args) {
         yield* this._getIterator(...args);
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
+     * Returns an iterator over the values (alias of the default iterator).
      *
-     * The function returns an iterator that yields all the values in the object.
+     * @returns An `IterableIterator<E>` over all elements.
+     * @remarks
+     * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
      */
     *values() {
-        for (const item of this) {
+        for (const item of this)
             yield item;
-        }
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `every` function checks if every element in the array satisfies a given predicate.
-     * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-     * the current element being processed, its index, and the array it belongs to. It should return a
-     * boolean value indicating whether the element satisfies a certain condition or not.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
-     * passed as the `this` value to the `predicate` function. If `thisArg` is
-     * @returns The `every` method is returning a boolean value. It returns `true` if every element in
-     * the array satisfies the provided predicate function, and `false` otherwise.
+     * Tests whether all elements satisfy the predicate.
+     *
+     * @template TReturn
+     * @param predicate Function invoked for each element with signature `(value, index, self)`.
+     * @param thisArg Optional `this` binding for the predicate.
+     * @returns `true` if every element passes; otherwise `false`.
+     *
+     * @remarks
+     * Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).
      */
     every(predicate, thisArg) {
         let index = 0;
         for (const item of this) {
-            if (!predicate.call(thisArg, item, index++, this)) {
-                return false;
+            if (thisArg === undefined) {
+                if (!predicate(item, index++, this))
+                    return false;
+            }
+            else {
+                const fn = predicate;
+                if (!fn.call(thisArg, item, index++, this))
+                    return false;
             }
         }
         return true;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The "some" function checks if at least one element in a collection satisfies a given predicate.
-     * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-     * `value`, `index`, and `array`. It should return a boolean value indicating whether the current
-     * element satisfies the condition.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
-     * it will be passed as the `this` value to the `predicate` function. If `thisArg
-     * @returns a boolean value. It returns true if the predicate function returns true for any element
-     * in the collection, and false otherwise.
+     * Tests whether at least one element satisfies the predicate.
+     *
+     * @param predicate Function invoked for each element with signature `(value, index, self)`.
+     * @param thisArg Optional `this` binding for the predicate.
+     * @returns `true` if any element passes; otherwise `false`.
+     *
+     * @remarks
+     * Time O(n) in the worst case; may exit early on first success. Space O(1).
      */
     some(predicate, thisArg) {
         let index = 0;
         for (const item of this) {
-            if (predicate.call(thisArg, item, index++, this)) {
-                return true;
+            if (thisArg === undefined) {
+                if (predicate(item, index++, this))
+                    return true;
+            }
+            else {
+                const fn = predicate;
+                if (fn.call(thisArg, item, index++, this))
+                    return true;
             }
         }
         return false;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `forEach` function iterates over each element in an array-like object and calls a callback
-     * function for each element.
-     * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
-     * the array. It takes three arguments: the current element being processed, the index of the current
-     * element, and the array that forEach was called upon.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
-     * be passed as the `this` value to the `callbackfn` function. If `thisArg
+     * Invokes a callback for each element in iteration order.
+     *
+     * @param callbackfn Function invoked per element with signature `(value, index, self)`.
+     * @param thisArg Optional `this` binding for the callback.
+     * @returns `void`.
+     *
+     * @remarks
+     * Time O(n), Space O(1).
      */
     forEach(callbackfn, thisArg) {
         let index = 0;
         for (const item of this) {
-            callbackfn.call(thisArg, item, index++, this);
+            if (thisArg === undefined) {
+                callbackfn(item, index++, this);
+            }
+            else {
+                const fn = callbackfn;
+                fn.call(thisArg, item, index++, this);
+            }
         }
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `find` function iterates over the elements of an array-like object and returns the first
-     * element that satisfies the provided callback function.
-     * @param predicate - The predicate parameter is a function that will be called for each element in
-     * the array. It takes three arguments: the current element being processed, the index of the current
-     * element, and the array itself. The function should return a boolean value indicating whether the
-     * current element matches the desired condition.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
-     * be passed as the `this` value to the `callbackfn` function. If `thisArg
-     * @returns The `find` method returns the first element in the array that satisfies the provided
-     * callback function. If no element satisfies the callback function, `undefined` is returned.
-     */
+    // Implementation signature
     find(predicate, thisArg) {
         let index = 0;
         for (const item of this) {
-            if (predicate.call(thisArg, item, index++, this))
-                return item;
+            if (thisArg === undefined) {
+                if (predicate(item, index++, this))
+                    return item;
+            }
+            else {
+                const fn = predicate;
+                if (fn.call(thisArg, item, index++, this))
+                    return item;
+            }
         }
         return;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function checks if a given element exists in a collection.
-     * @param {E} element - The parameter "element" is of type E, which means it can be any type. It
-     * represents the element that we want to check for existence in the collection.
-     * @returns a boolean value. It returns true if the element is found in the collection, and false
-     * otherwise.
+     * Checks whether a strictly-equal element exists in the structure.
+     *
+     * @param element The element to test with `===` equality.
+     * @returns `true` if an equal element is found; otherwise `false`.
+     *
+     * @remarks
+     * Time O(n) in the worst case. Space O(1).
      */
     has(element) {
-        for (const ele of this) {
+        for (const ele of this)
             if (ele === element)
                 return true;
-        }
         return false;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `reduce` function iterates over the elements of an array-like object and applies a callback
-     * function to reduce them into a single value.
-     * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
-     * the array. It takes four arguments:
-     * @param {U} initialValue - The initialValue parameter is the initial value of the accumulator. It
-     * is the value that the accumulator starts with before the reduction operation begins.
-     * @returns The `reduce` method is returning the final value of the accumulator after iterating over
-     * all the elements in the array and applying the callback function to each element.
+     * Reduces all elements to a single accumulated value.
+     *
+     * @overload
+     * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.
+     * @returns The final accumulated value typed as `E`.
+     *
+     * @overload
+     * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`.
+     * @param initialValue The initial accumulator value of type `E`.
+     * @returns The final accumulated value typed as `E`.
+     *
+     * @overload
+     * @template U The accumulator type when it differs from `E`.
+     * @param callbackfn Reducer of signature `(acc: U, value, index, self) => U`.
+     * @param initialValue The initial accumulator value of type `U`.
+     * @returns The final accumulated value typed as `U`.
+     *
+     * @remarks
+     * Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.
      */
     reduce(callbackfn, initialValue) {
-        let accumulator = initialValue !== null && initialValue !== void 0 ? initialValue : 0;
         let index = 0;
-        for (const item of this) {
-            accumulator = callbackfn(accumulator, item, index++, this);
+        const iter = this[Symbol.iterator]();
+        let acc;
+        if (arguments.length >= 2) {
+            acc = initialValue;
+        }
+        else {
+            const first = iter.next();
+            if (first.done)
+                throw new TypeError('Reduce of empty structure with no initial value');
+            acc = first.value;
+            index = 1;
+        }
+        for (const value of iter) {
+            acc = callbackfn(acc, value, index++, this);
         }
-        return accumulator;
+        return acc;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
+     * Materializes the elements into a new array.
      *
-     * The `toArray` function converts a linked list into an array.
-     * @returns The `toArray()` method is returning an array of type `E[]`.
+     * @returns A shallow array copy of the iteration order.
+     * @remarks
+     * Time O(n), Space O(n).
      */
     toArray() {
         return [...this];
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
+     * Returns a representation of the structure suitable for quick visualization.
+     * Defaults to an array of elements; subclasses may override to provide richer visuals.
      *
-     * The print function logs the elements of an array to the console.
+     * @returns A visual representation (array by default).
+     * @remarks
+     * Time O(n), Space O(n).
      */
     toVisual() {
         return [...this];
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
+     * Prints `toVisual()` to the console. Intended for quick debugging.
      *
-     * The print function logs the elements of an array to the console.
+     * @returns `void`.
+     * @remarks
+     * Time O(n) due to materialization, Space O(n) for the intermediate representation.
      */
     print() {
         console.log(this.toVisual());

package/dist/data-structures/base/iterable-entry-base.d.ts

@@ -1,168 +1,144 @@
-import { EntryCallback, ReduceEntryCallback } from '../../types';
+import type { EntryCallback, ReduceEntryCallback } from '../../types';
+/**
+ * Iterable view over key-value entries.
+ * @template K - Key type.
+ * @template V - Value type.
+ * @remarks Time O(1), Space O(1)
+ */
 export declare abstract class IterableEntryBase<K = any, V = any> {
+    /**
+     * Total number of entries.
+     * @returns Entry count.
+     * @remarks Time O(1), Space O(1)
+     */
     abstract get size(): number;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function is an implementation of the Symbol.iterator method that returns an iterable iterator.
-     * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
-     * allows the function to accept any number of arguments as an array. In this case, the `args`
-     * parameter is used to pass any additional arguments to the `_getIterator` method.
+     * Default iterator yielding `[key, value]` entries.
+     * @returns Iterator of `[K, V]`.
+     * @remarks Time O(n) to iterate, Space O(1)
      */
     [Symbol.iterator](...args: any[]): IterableIterator<[K, V]>;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The function returns an iterator that yields key-value pairs from the object, where the value can
-     * be undefined.
+     * Iterate over `[key, value]` pairs (may yield `undefined` values).
+     * @returns Iterator of `[K, V | undefined]`.
+     * @remarks Time O(n), Space O(1)
      */
     entries(): IterableIterator<[K, V | undefined]>;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The function returns an iterator that yields the keys of a data structure.
+     * Iterate over keys only.
+     * @returns Iterator of keys.
+     * @remarks Time O(n), Space O(1)
      */
     keys(): IterableIterator<K>;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The function returns an iterator that yields the values of a collection.
+     * Iterate over values only.
+     * @returns Iterator of values.
+     * @remarks Time O(n), Space O(1)
      */
     values(): IterableIterator<V>;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `every` function checks if every element in a collection satisfies a given condition.
-     * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-     * `value`, `key`, and `index`. It should return a boolean value indicating whether the condition is
-     * met for the current element in the iteration.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
-     * passed as the first argument to the `predicate` function. If `thisArg` is not provided
-     * @returns The `every` method is returning a boolean value. It returns `true` if every element in
-     * the collection satisfies the provided predicate function, and `false` otherwise.
+     * Test whether all entries satisfy the predicate.
+     * @param predicate - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns `true` if all pass; otherwise `false`.
+     * @remarks Time O(n), Space O(1)
      */
     every(predicate: EntryCallback<K, V, boolean>, thisArg?: any): boolean;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The "some" function iterates over a collection and returns true if at least one element satisfies
-     * a given predicate.
-     * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-     * `value`, `key`, and `index`. It should return a boolean value indicating whether the condition is
-     * met for the current element in the iteration.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
-     * it will be passed as the first argument to the `predicate` function. If `thisArg` is
-     * @returns a boolean value. It returns true if the predicate function returns true for any pair in
-     * the collection, and false otherwise.
+     * Test whether any entry satisfies the predicate.
+     * @param predicate - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns `true` if any passes; otherwise `false`.
+     * @remarks Time O(n), Space O(1)
      */
     some(predicate: EntryCallback<K, V, boolean>, thisArg?: any): boolean;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `forEach` function iterates over each key-value pair in a collection and executes a callback
-     * function for each pair.
-     * @param callbackfn - The callback function that will be called for each element in the collection.
-     * It takes four parameters: the value of the current element, the key of the current element, the
-     * index of the current element, and the collection itself.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
-     * specify the value of `this` within the callback function. If `thisArg` is provided, it will be
-     * used as the `this` value when calling the callback function. If `thisArg` is not provided, `
+     * Visit each entry, left-to-right.
+     * @param callbackfn - `(key, value, index, self) => void`.
+     * @param thisArg - Optional `this` for callback.
+     * @remarks Time O(n), Space O(1)
      */
     forEach(callbackfn: EntryCallback<K, V, void>, thisArg?: any): void;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `find` function iterates over the entries of a collection and returns the first value for
-     * which the callback function returns true.
-     * @param callbackfn - The callback function that will be called for each entry in the collection. It
-     * takes three arguments: the value of the entry, the key of the entry, and the index of the entry in
-     * the collection. It should return a boolean value indicating whether the current entry matches the
-     * desired condition.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
-     * be passed as the `this` value to the `callbackfn` function. If `thisArg
-     * @returns The method `find` returns the value of the first element in the iterable that satisfies
-     * the provided callback function. If no element satisfies the callback function, `undefined` is
-     * returned.
+     * Find the first entry that matches a predicate.
+     * @param callbackfn - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns Matching `[key, value]` or `undefined`.
+     * @remarks Time O(n), Space O(1)
      */
     find(callbackfn: EntryCallback<K, V, boolean>, thisArg?: any): [K, V] | undefined;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function checks if a given key exists in a collection.
-     * @param {K} key - The parameter "key" is of type K, which means it can be any type. It represents
-     * the key that we want to check for existence in the data structure.
-     * @returns a boolean value. It returns true if the key is found in the collection, and false
-     * otherwise.
+     * Whether the given key exists.
+     * @param key - Key to test.
+     * @returns `true` if found; otherwise `false`.
+     * @remarks Time O(n) generic, Space O(1)
      */
     has(key: K): boolean;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function checks if a given value exists in a collection.
-     * @param {V} value - The parameter "value" is the value that we want to check if it exists in the
-     * collection.
-     * @returns a boolean value, either true or false.
+     * Whether there exists an entry with the given value.
+     * @param value - Value to test.
+     * @returns `true` if found; otherwise `false`.
+     * @remarks Time O(n), Space O(1)
      */
     hasValue(value: V): boolean;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `get` function retrieves the value associated with a given key from a collection.
-     * @param {K} key - K (the type of the key) - This parameter represents the key that is being
-     * searched for in the collection.
-     * @returns The `get` method returns the value associated with the specified key if it exists in the
-     * collection, otherwise it returns `undefined`.
+     * Get the value under a key.
+     * @param key - Key to look up.
+     * @returns Value or `undefined`.
+     * @remarks Time O(n) generic, Space O(1)
      */
     get(key: K): V | undefined;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `reduce` function iterates over key-value pairs and applies a callback function to each pair,
-     * accumulating a single value.
-     * @param callbackfn - The callback function that will be called for each element in the collection.
-     * It takes four arguments: the current accumulator value, the current value of the element, the key
-     * of the element, and the index of the element in the collection. It should return the updated
-     * accumulator value.
-     * @param {U} initialValue - The `initialValue` parameter is the initial value of the accumulator. It
-     * is the value that will be used as the first argument to the `callbackfn` function when reducing
-     * the elements of the collection.
-     * @returns The `reduce` method is returning the final value of the accumulator after iterating over
-     * all the elements in the collection.
+     * Reduce entries into a single accumulator.
+     * @param callbackfn - `(acc, value, key, index, self) => acc`.
+     * @param initialValue - Initial accumulator.
+     * @returns Final accumulator.
+     * @remarks Time O(n), Space O(1)
      */
     reduce<U>(callbackfn: ReduceEntryCallback<K, V, U>, initialValue: U): U;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The print function logs the elements of an array to the console.
+     * Visualize the iterable as an array of `[key, value]` pairs (or a custom string).
+     * @returns Array of entries (default) or a string.
+     * @remarks Time O(n), Space O(n)
      */
     toVisual(): [K, V][] | string;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The print function logs the elements of an array to the console.
+     * Print a human-friendly representation to the console.
+     * @remarks Time O(n), Space O(n)
      */
     print(): void;
+    /**
+     * Whether there are no entries.
+     * @returns `true` if empty; `false` otherwise.
+     * @remarks Time O(1) typical, Space O(1)
+     */
     abstract isEmpty(): boolean;
+    /**
+     * Remove all entries.
+     * @remarks Time O(n) typical, Space O(1)
+     */
     abstract clear(): void;
-    abstract clone(): any;
+    /**
+     * Deep clone preserving the concrete subtype.
+     * @returns A new instance of the same concrete class (`this` type).
+     * @remarks Time O(n) typical, Space O(n)
+     */
+    abstract clone(): this;
+    /**
+     * Map entries using an implementation-specific strategy.
+     * @remarks Time O(n), Space O(n)
+     */
     abstract map(...args: any[]): any;
-    abstract filter(...args: any[]): any;
+    /**
+     * Filter entries and return the same-species structure.
+     * @returns A new instance of the same concrete class (`this` type).
+     * @remarks Time O(n), Space O(n)
+     */
+    abstract filter(...args: any[]): this;
+    /**
+     * Underlying iterator for the default iteration protocol.
+     * @returns Iterator of `[K, V]`.
+     * @remarks Time O(n), Space O(1)
+     */
     protected abstract _getIterator(...args: any[]): IterableIterator<[K, V]>;
 }