@byloth/core 2.0.0-rc.9 → 2.0.1

package/src/models/iterators/smart-iterator.ts

@@ -1,18 +1,119 @@
 import AggregatedIterator from "../aggregators/aggregated-iterator.js";
 import { ValueException } from "../exceptions/index.js";
 
-import type { GeneratorFunction, Iteratee, TypeGuardIteratee, Reducer, IteratorLike } from "./types.js";
+import type { GeneratorFunction, Iteratee, TypeGuardPredicate, Reducer, IteratorLike } from "./types.js";
 
+/**
+ * A wrapper class representing an enhanced and instantiable version
+ * of the native {@link Iterable} & {@link Iterator} interfaces.
+ *
+ * It provides a set of utility methods to better manipulate and
+ * transform iterators in a functional and highly performant way.  
+ * It takes inspiration from the native {@link Array} methods like
+ * {@link Array.map}, {@link Array.filter}, {@link Array.reduce}, etc...
+ *
+ * The class is lazy, meaning that the transformations are applied
+ * only when the resulting iterator is materialized, not before.  
+ * This allows to chain multiple transformations without
+ * the need to iterate over the elements multiple times.
+ *
+ * ```ts
+ * const result = new SmartIterator<number>(["-5", "-4", "-3", "-2", "-1", "0", "1", "2", "3", "4", "5"])
+ *     .map(Number)
+ *     .map((value) => value + Math.ceil(Math.abs(value / 2)))
+ *     .filter((value) => value >= 0)
+ *     .map((value) => value + 1)
+ *     .reduce((acc, value) => acc + value);
+ *
+ * console.log(result); // 31
+ * ```
+ *
+ * @template T The type of elements in the iterator.
+ * @template R The type of the final result of the iterator. Default is `void`.
+ * @template N The type of the argument required by the `next` method. Default is `undefined`.
+ */
 export default class SmartIterator<T, R = void, N = undefined> implements Iterator<T, R, N>
 {
+    /**
+     * The native {@link Iterator} object that is being wrapped by this instance.
+     */
     protected _iterator: Iterator<T, R, N>;
 
-    public return?: (value?: R) => IteratorResult<T, R>;
-    public throw?: (error?: unknown) => IteratorResult<T, R>;
-
+    /**
+     * Initializes a new instance of the {@link SmartIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<string>(["A", "B", "C"]);
+     * ```
+     *
+     * ---
+     *
+     * @param iterable The iterable object to wrap.
+     */
     public constructor(iterable: Iterable<T, R, N>);
+
+    /**
+     * Initializes a new instance of the {@link SmartIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number, void, number>({
+     *     _sum: 0, _count: 0,
+     *
+     *     next: function(value: number)
+     *     {
+     *         this._sum += value;
+     *         this._count += 1;
+     *
+     *         return { done: false, value: this._sum / this._count };
+     *     }
+     * })
+     * ```
+     *
+     * ---
+     *
+     * @param iterator The iterator object to wrap.
+     */
     public constructor(iterator: Iterator<T, R, N>);
+
+    /**
+     * Initializes a new instance of the {@link SmartIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>(function* ()
+     * {
+     *     for (let i = 2; i < 65_536; i *= 2) { yield (i - 1); }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param generatorFn The generator function to wrap.
+     */
     public constructor(generatorFn: GeneratorFunction<T, R, N>);
+
+    /**
+     * Initializes a new instance of the {@link SmartIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator(values);
+     * ```
+     *
+     * ---
+     *
+     * @param argument The iterable, iterator or generator function to wrap.
+     */
     public constructor(argument: IteratorLike<T, R, N> | GeneratorFunction<T, R, N>);
     public constructor(argument: IteratorLike<T, R, N> | GeneratorFunction<T, R, N>)
     {
@@ -28,11 +129,37 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         {
             this._iterator = argument;
         }
-
-        if (this._iterator.return) { this.return = (value) => this._iterator.return!(value); }
-        if (this._iterator.throw) { this.throw = (error) => this._iterator.throw!(error); }
     }
 
+    /**
+     * Determines whether all elements of the iterator satisfy a given condition.
+     * See also {@link SmartIterator.some}.
+     *
+     * This method will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * Once a single element doesn't satisfy the condition, the method will return `false` immediately.
+     *
+     * This may lead to an unknown final state of the iterator, which may be entirely or partially consumed.  
+     * For this reason, it's recommended to consider it as consumed in any case and to not use it anymore.  
+     * Consider using {@link SmartIterator.find} instead.
+     *
+     * If the iterator is infinite and every element satisfies the condition, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.every((value) => value < 0);
+     *
+     * console.log(result); // false
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns `true` if all elements satisfy the condition, `false` otherwise.
+     */
     public every(predicate: Iteratee<T, boolean>): boolean
     {
         let index = 0;
@@ -47,6 +174,36 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             index += 1;
         }
     }
+
+    /**
+     * Determines whether any element of the iterator satisfies a given condition.
+     * See also {@link SmartIterator.every}.
+     *
+     * This method will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * Once a single element satisfies the condition, the method will return `true` immediately.
+     *
+     * This may lead to an unknown final state of the iterator, which may be entirely or partially consumed.  
+     * For this reason, it's recommended to consider it as consumed in any case and to not use it anymore.  
+     * Consider using {@link SmartIterator.find} instead.
+     *
+     * If the iterator is infinite and no element satisfies the condition, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.some((value) => value < 0);
+     *
+     * console.log(result); // true
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns `true` if any element satisfies the condition, `false` otherwise.
+     */
     public some(predicate: Iteratee<T, boolean>): boolean
     {
         let index = 0;
@@ -62,8 +219,73 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }
     }
 
+    /**
+     * Filters the elements of the iterator using a given condition.
+     *
+     * This method will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * If the condition is met, the element will be included in the new iterator.
+     *
+     * Since the iterator is lazy, the filtering process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.filter((value) => value < 0);
+     *
+     * console.log(result.toArray()); // [-2, -1]
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns A new {@link SmartIterator} containing only the elements that satisfy the condition.
+     */
     public filter(predicate: Iteratee<T, boolean>): SmartIterator<T, R>;
-    public filter<S extends T>(predicate: TypeGuardIteratee<T, S>): SmartIterator<S, R>;
+
+    /**
+     * Filters the elements of the iterator using a given condition.
+     *
+     * This method will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * If the condition is met, the element will be included in the new iterator.
+     *
+     * Since the iterator is lazy, the filtering process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number | string>([-2, "-1", "0", 1, "2"]);
+     * const result = iterator.filter<number>((value) => typeof value === "number");
+     *
+     * console.log(result.toArray()); // [-2, 1]
+     * ```
+     *
+     * ---
+     *
+     * @template S
+     * The type of the elements that satisfy the condition.  
+     * This allows the type-system to infer the correct type of the new iterator.
+     *
+     * It must be a subtype of the original type of the elements.
+     *
+     * @param predicate The type guard condition to check for each element of the iterator.
+     *
+     * @returns A new {@link SmartIterator} containing only the elements that satisfy the condition.
+     */
+    public filter<S extends T>(predicate: TypeGuardPredicate<T, S>): SmartIterator<S, R>;
     public filter(predicate: Iteratee<T, boolean>): SmartIterator<T, R>
     {
         const iterator = this._iterator;
@@ -71,11 +293,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         return new SmartIterator<T, R>(function* ()
         {
             let index = 0;
-
             while (true)
             {
                 const result = iterator.next();
-
                 if (result.done) { return result.value; }
                 if (predicate(result.value, index)) { yield result.value; }
 
@@ -83,6 +303,38 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             }
         });
     }
+
+    /**
+     * Maps the elements of the iterator using a given transformation function.
+     *
+     * This method will iterate over all elements of the iterator applying the transformation function.  
+     * The result of each transformation will be included in the new iterator.
+     *
+     * Since the iterator is lazy, the mapping process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.map((value) => Math.abs(value));
+     *
+     * console.log(result.toArray()); // [2, 1, 0, 1, 2]
+     * ```
+     *
+     * ---
+     *
+     * @template V The type of the elements after the transformation.
+     *
+     * @param iteratee The transformation function to apply to each element of the iterator.
+     *
+     * @returns A new {@link SmartIterator} containing the transformed elements.
+     */
     public map<V>(iteratee: Iteratee<T, V>): SmartIterator<V, R>
     {
         const iterator = this._iterator;
@@ -90,7 +342,6 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         return new SmartIterator<V, R>(function* ()
         {
             let index = 0;
-
             while (true)
             {
                 const result = iterator.next();
@@ -102,7 +353,70 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             }
         });
     }
+
+    /**
+     * Reduces the elements of the iterator using a given reducer function.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all elements of the iterator applying the reducer function.  
+     * The result of each iteration will be passed as the accumulator to the next one.
+     *
+     * The first accumulator value will be the first element of the iterator.  
+     * The last accumulator value will be the final result of the reduction.
+     *
+     * Also note that:
+     * - If an empty iterator is provided, a {@link ValueException} will be thrown.
+     * - If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
+     * const result = iterator.reduce((acc, value) => acc + value);
+     *
+     * console.log(result); // 15
+     * ```
+     *
+     * ---
+     *
+     * @param reducer The reducer function to apply to each element of the iterator.
+     *
+     * @returns The final result of the reduction.
+     */
     public reduce(reducer: Reducer<T, T>): T;
+
+    /**
+     * Reduces the elements of the iterator using a given reducer function.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all elements of the iterator applying the reducer function.  
+     * The result of each iteration will be passed as the accumulator to the next one.
+     *
+     * The first accumulator value will be the provided initial value.  
+     * The last accumulator value will be the final result of the reduction.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
+     * const result = iterator.reduce((acc, value) => acc + value, 10);
+     *
+     * console.log(result); // 25
+     * ```
+     *
+     * ---
+     *
+     * @template A The type of the accumulator value which will also be the type of the final result of the reduction.
+     *
+     * @param reducer The reducer function to apply to each element of the iterator.
+     * @param initialValue The initial value of the accumulator.
+     *
+     * @returns The final result of the reduction.
+     */
     public reduce<A>(reducer: Reducer<T, A>, initialValue: A): A;
     public reduce<A>(reducer: Reducer<T, A>, initialValue?: A): A
     {
@@ -128,30 +442,92 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }
     }
 
-    public flatMap<V>(iteratee: Iteratee<T, Iterable<V>>): SmartIterator<V, R>
+    /**
+     * Flattens the elements of the iterator using a given transformation function.
+     *
+     * This method will iterate over all elements of the iterator applying the transformation function.  
+     * The result of each transformation will be flattened into the new iterator.
+     *
+     * Since the iterator is lazy, the flattening process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number[]>([[-2, -1], 0, 1, 2, [3, 4, 5]]);
+     * const result = iterator.flatMap((value) => value);
+     *
+     * console.log(result.toArray()); // [-2, -1, 0, 1, 2, 3, 4, 5]
+     * ```
+     *
+     * ---
+     *
+     * @template V The type of the elements after the transformation.
+     *
+     * @param iteratee The transformation function to apply to each element of the iterator.
+     *
+     * @returns A new {@link SmartIterator} containing the flattened elements.
+     */
+    public flatMap<V>(iteratee: Iteratee<T, V | readonly V[]>): SmartIterator<V, R>
     {
         const iterator = this._iterator;
 
         return new SmartIterator<V, R>(function* ()
         {
             let index = 0;
-
             while (true)
             {
                 const result = iterator.next();
                 if (result.done) { return result.value; }
 
-                const iterable = iteratee(result.value, index);
-                for (const value of iterable)
+                const elements = iteratee(result.value, index);
+                if (elements instanceof Array)
                 {
-                    yield value;
+                    for (const value of elements) { yield value; }
                 }
+                else { yield elements; }
 
                 index += 1;
             }
         });
     }
 
+    /**
+     * Drops a given number of elements at the beginning of the iterator.  
+     * The remaining elements will be included in a new iterator.
+     * See also {@link SmartIterator.take}.
+     *
+     * Since the iterator is lazy, the dropping process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * Only the dropped elements will be consumed in the process.  
+     * The rest of the iterator will be consumed only once the new one is.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.drop(3);
+     *
+     * console.log(result.toArray()); // [1, 2]
+     * ```
+     *
+     * ---
+     *
+     * @param count The number of elements to drop.
+     *
+     * @returns A new {@link SmartIterator} containing the remaining elements.
+     */
     public drop(count: number): SmartIterator<T, R | undefined>
     {
         const iterator = this._iterator;
@@ -176,6 +552,39 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
             }
         });
     }
+
+    /**
+     * Takes a given number of elements at the beginning of the iterator.  
+     * These elements will be included in a new iterator.
+     * See also {@link SmartIterator.drop}.
+     *
+     * Since the iterator is lazy, the taking process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * Only the taken elements will be consumed from the original iterator.  
+     * The rest of the original iterator will be available for further consumption.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.take(3);
+     *
+     * console.log(result.toArray()); // [-2, -1, 0]
+     * console.log(iterator.toArray()); // [1, 2]
+     * ```
+     *
+     * ---
+     *
+     * @param limit The number of elements to take.
+     *
+     * @returns A new {@link SmartIterator} containing the taken elements.
+     */
     public take(limit: number): SmartIterator<T, R | undefined>
     {
         const iterator = this._iterator;
@@ -197,8 +606,75 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         });
     }
 
+    /**
+     * Finds the first element of the iterator that satisfies a given condition.
+     *
+     * This method will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * The first element that satisfies the condition will be returned immediately.
+     *
+     * Only the elements that are necessary to find the first
+     * satisfying one will be consumed from the original iterator.  
+     * The rest of the original iterator will be available for further consumption.
+     *
+     * Also note that:
+     * - If no element satisfies the condition, `undefined` will be returned once the entire iterator is consumed.
+     * - If the iterator is infinite and no element satisfies the condition, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
+     * const result = iterator.find((value) => value > 0);
+     *
+     * console.log(result); // 1
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns The first element that satisfies the condition, `undefined` otherwise.
+     */
     public find(predicate: Iteratee<T, boolean>): T | undefined;
-    public find<S extends T>(predicate: TypeGuardIteratee<T, S>): S | undefined;
+
+    /**
+     * Finds the first element of the iterator that satisfies a given condition.
+     *
+     * This method will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * The first element that satisfies the condition will be returned immediately.
+     *
+     * Only the elements that are necessary to find the first
+     * satisfying one will be consumed from the original iterator.  
+     * The rest of the original iterator will be available for further consumption.
+     *
+     * Also note that:
+     * - If no element satisfies the condition, `undefined` will be returned once the entire iterator is consumed.
+     * - If the iterator is infinite and no element satisfies the condition, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number | string>([-2, "-1", "0", 1, "2"]);
+     * const result = iterator.find<number>((value) => typeof value === "number");
+     *
+     * console.log(result); // -2
+     * ```
+     *
+     * ---
+     *
+     * @template S
+     * The type of the element that satisfies the condition.  
+     * This allows the type-system to infer the correct type of the result.
+     *
+     * It must be a subtype of the original type of the elements.
+     *
+     * @param predicate The type guard condition to check for each element of the iterator.
+     *
+     * @returns The first element that satisfies the condition, `undefined` otherwise.
+     */
+    public find<S extends T>(predicate: TypeGuardPredicate<T, S>): S | undefined;
     public find(predicate: Iteratee<T, boolean>): T | undefined
     {
         let index = 0;
@@ -214,10 +690,61 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }
     }
 
+    /**
+     * Enumerates the elements of the iterator.  
+     * Each element is be paired with its index in a new iterator.
+     *
+     * Since the iterator is lazy, the enumeration process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<string>(["A", "M", "N", "Z"]);
+     * const result = iterator.enumerate();
+     *
+     * console.log(result.toArray()); // [[0, "A"], [1, "M"], [2, "N"], [3, "Z"]]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartIterator} containing the enumerated elements.
+     */
     public enumerate(): SmartIterator<[number, T], R>
     {
         return this.map((value, index) => [index, value]);
     }
+
+    /**
+     * Removes all duplicate elements from the iterator.  
+     * The first occurrence of each element will be kept.
+     *
+     * Since the iterator is lazy, the deduplication process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([1, 1, 2, 3, 2, 3, 4, 5, 5, 4]);
+     * const result = iterator.unique();
+     *
+     * console.log(result.toArray()); // [1, 2, 3, 4, 5]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartIterator} containing only the unique elements.
+     */
     public unique(): SmartIterator<T, R>
     {
         const iterator = this._iterator;
@@ -225,14 +752,11 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         return new SmartIterator<T, R>(function* ()
         {
             const values = new Set<T>();
-
             while (true)
             {
                 const result = iterator.next();
-
                 if (result.done) { return result.value; }
                 if (values.has(result.value)) { continue; }
-
                 values.add(result.value);
 
                 yield result.value;
@@ -240,6 +764,26 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         });
     }
 
+    /**
+     * Counts the number of elements in the iterator.  
+     * This method will consume the entire iterator in the process.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
+     * const result = iterator.count();
+     *
+     * console.log(result); // 5
+     * ```
+     *
+     * ---
+     *
+     * @returns The number of elements in the iterator.
+     */
     public count(): number
     {
         let index = 0;
@@ -253,6 +797,28 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }
     }
 
+    /**
+     * Iterates over all elements of the iterator.  
+     * The elements are passed to the function along with their index.
+     *
+     * This method will consume the entire iterator in the process.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>(["A", "M", "N", "Z"]);
+     * iterator.forEach((value, index) =>
+     * {
+     *     console.log(`${index}: ${value}`); // "0: A", "1: M", "2: N", "3: Z"
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @param iteratee The function to apply to each element of the iterator.
+     */
     public forEach(iteratee: Iteratee<T>): void
     {
         let index = 0;
@@ -268,11 +834,157 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }
     }
 
+    /**
+     * Advances the iterator to the next element and returns the result.  
+     * If the iterator requires it, a value must be provided to be passed to the next element.
+     *
+     * Once the iterator is done, the method will return an object with the `done` property set to `true`.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
+     *
+     * let result = iterator.next();
+     * while (!result.done)
+     * {
+     *     console.log(result.value); // 1, 2, 3, 4, 5
+     *
+     *     result = iterator.next();
+     * }
+     *
+     * console.log(result); // { done: true, value: undefined }
+     * ```
+     *
+     * ---
+     *
+     * @param values The value to pass to the next element, if required.
+     *
+     * @returns The result of the iteration, containing the value of the operation.
+     */
     public next(...values: N extends undefined ? [] : [N]): IteratorResult<T, R>
     {
         return this._iterator.next(...values);
     }
 
+    /**
+     * An utility method that may be used to close the iterator gracefully,
+     * free the resources and perform any cleanup operation.  
+     * It may also be used to signal the end or to compute a specific final result of the iteration process.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>({
+     *     _index: 0,
+     *     next: function()
+     *     {
+     *         return { done: false, value: this._index += 1 };
+     *     },
+     *     return: function() { console.log("Closing the iterator..."); }
+     * });
+     *
+     * for (const value of iterator)
+     * {
+     *     if (value > 5) { break; } // Closing the iterator...
+     *
+     *     console.log(value); // 1, 2, 3, 4, 5
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @param value The final value of the iterator.
+     *
+     * @returns The result of the iterator.
+     */
+    public return(value?: R): IteratorResult<T, R>
+    {
+        if (this._iterator.return) { return this._iterator.return(value); }
+
+        return { done: true, value: value as R };
+    }
+
+    /**
+     * An utility method that may be used to close the iterator due to an error,
+     * free the resources and perform any cleanup operation.  
+     * It may also be used to signal that an error occurred during the iteration process or to handle it.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>({
+     *     _index: 0,
+     *     next: function()
+     *     {
+     *         return { done: this._index > 10, value: this._index += 1 };
+     *     },
+     *     throw: function(error)
+     *     {
+     *         console.warn(error.message);
+     *
+     *         this._index = 0;
+     *     }
+     * });
+     *
+     * for (const value of iterator) // 1, 2, 3, 4, 5, "The index is too high.", 1, 2, 3, 4, 5, ...
+     * {
+     *     try
+     *     {
+     *         if (value > 5) { throw new Error("The index is too high."); }
+     *
+     *         console.log(value); // 1, 2, 3, 4, 5
+     *     }
+     *     catch (error) { iterator.throw(error); }
+     * }
+     * ```
+     *
+     * ---
+     *
+     * @param error The error to throw into the iterator.
+     *
+     * @returns The final result of the iterator.
+     */
+    public throw(error: unknown): IteratorResult<T, R>
+    {
+        if (this._iterator.throw) { return this._iterator.throw(error); }
+
+        throw error;
+    }
+
+    /**
+     * An utility method that aggregates the elements of the iterator using a given key function.  
+     * The elements will be grouped by the resulting keys in a new specialized iterator.
+     * See {@link AggregatedIterator}.
+     *
+     * Since the iterator is lazy, the grouping process will
+     * be executed once the resulting iterator is materialized.
+     *
+     * A new iterator will be created, holding the reference to the original one.  
+     * This means that the original iterator won't be consumed until the
+     * the new one is and that consuming one of them will consume the other as well.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+     * const result = iterator.groupBy<string>((value) => value % 2 === 0 ? "even" : "odd");
+     *
+     * console.log(result.toObject()); // { odd: [1, 3, 5, 7, 9], even: [2, 4, 6, 8, 10] }
+     * ```
+     *
+     * ---
+     *
+     * @template K The type of the keys used to group the elements.
+     *
+     * @param iteratee The key function to apply to each element of the iterator.
+     *
+     * @returns A new instance of the {@link AggregatedIterator} class containing the grouped elements.
+     */
     public groupBy<K extends PropertyKey>(iteratee: Iteratee<T, K>): AggregatedIterator<K, T>
     {
         return new AggregatedIterator(this.map((element, index) =>
@@ -283,6 +995,29 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
         }));
     }
 
+    /**
+     * Materializes the iterator into an array.  
+     * This method will consume the entire iterator in the process.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new SmartIterator(function* ()
+     * {
+     *     for (let i = 0; i < 5; i += 1) { yield i; }
+     * });
+     * const result = iterator.toArray();
+     *
+     * console.log(result); // [0, 1, 2, 3, 4]
+     * ```
+     *
+     * ---
+     *
+     * @returns The {@link Array} containing all elements of the iterator.
+     */
     public toArray(): T[]
     {
         return Array.from(this as Iterable<T>);