bst-typed 2.0.5 → 2.1.1

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

@@ -1,25 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IterableEntryBase = void 0;
+/**
+ * Iterable view over key-value entries.
+ * @template K - Key type.
+ * @template V - Value type.
+ * @remarks Time O(1), Space O(1)
+ */
 class IterableEntryBase {
     /**
-     * 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) {
         yield* this._getIterator(...args);
     }
     /**
-     * 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() {
         for (const item of this) {
@@ -27,10 +27,9 @@ class IterableEntryBase {
         }
     }
     /**
-     * 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() {
         for (const item of this) {
@@ -38,10 +37,9 @@ class IterableEntryBase {
         }
     }
     /**
-     * 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() {
         for (const item of this) {
@@ -49,18 +47,11 @@ class IterableEntryBase {
         }
     }
     /**
-     * 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, thisArg) {
         let index = 0;
@@ -72,19 +63,11 @@ class IterableEntryBase {
         return true;
     }
     /**
-     * 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, thisArg) {
         let index = 0;
@@ -96,17 +79,10 @@ class IterableEntryBase {
         return false;
     }
     /**
-     * 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, thisArg) {
         let index = 0;
@@ -116,21 +92,11 @@ class IterableEntryBase {
         }
     }
     /**
-     * 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, thisArg) {
         let index = 0;
@@ -142,14 +108,10 @@ class IterableEntryBase {
         return;
     }
     /**
-     * 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) {
         for (const item of this) {
@@ -160,13 +122,10 @@ class IterableEntryBase {
         return false;
     }
     /**
-     * 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) {
         for (const [, elementValue] of this) {
@@ -176,14 +135,10 @@ class IterableEntryBase {
         return false;
     }
     /**
-     * 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) {
         for (const item of this) {
@@ -194,20 +149,11 @@ class IterableEntryBase {
         return;
     }
     /**
-     * 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(callbackfn, initialValue) {
         let accumulator = initialValue;
@@ -219,19 +165,16 @@ class IterableEntryBase {
         return accumulator;
     }
     /**
-     * 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() {
         return [...this];
     }
     /**
-     * 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() {
         console.log(this.toVisual());