stack-typed 2.0.5 → 2.1.1

package/src/data-structures/base/iterable-entry-base.ts

@@ -1,27 +1,32 @@
-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 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]> {
     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(): IterableIterator<[K, V | undefined]> {
     for (const item of this) {
@@ -30,10 +35,9 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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> {
     for (const item of this) {
@@ -42,10 +46,9 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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> {
     for (const item of this) {
@@ -54,18 +57,11 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     let index = 0;
@@ -78,19 +74,11 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     let index = 0;
@@ -103,17 +91,10 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     let index = 0;
@@ -124,21 +105,11 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     let index = 0;
@@ -150,14 +121,10 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     for (const item of this) {
@@ -168,13 +135,10 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     for (const [, elementValue] of this) {
@@ -184,14 +148,10 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     for (const item of this) {
@@ -202,20 +162,11 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     let accumulator = initialValue;
@@ -228,34 +179,59 @@ export abstract class IterableEntryBase<K = any, V = any> {
   }
 
   /**
-   * 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 {
     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(): void {
     console.log(this.toVisual());
   }
 
+  /**
+   * 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]>;
 }