@byloth/core 2.0.0-rc.9 → 2.0.1

package/src/models/aggregators/reduced-iterator.ts

@@ -3,21 +3,161 @@ import { SmartIterator } from "../iterators/index.js";
 import type { GeneratorFunction } from "../iterators/types.js";
 
 import AggregatedIterator from "./aggregated-iterator.js";
-import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardIteratee } from "./types.js";
+import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardPredicate } from "./types.js";
 
+/**
+ * A class representing an aggregated iterator that has been reduced in a lazy and optimized way.
+ *
+ * It's part of the {@link AggregatedIterator} and {@link AggregatedAsyncIterator} implementations,
+ * providing a way to reduce them into a single value or another aggregated iterable.  
+ * For this reason, it isn't recommended to instantiate this class directly
+ * (although it's still possible), but rather use the reducing methods provided by the aggregated iterators.
+ *
+ * It isn't directly iterable, just like its parent class, and needs to specify on what you want to iterate.  
+ * See the {@link ReducedIterator.keys}, {@link ReducedIterator.entries}
+ * & {@link ReducedIterator.values} methods.  
+ * It does, however, provide the same set of methods to perform
+ * operations and transformation on the elements of the iterator,  
+ * having also the knowledge and context of the groups to which
+ * they belong, allowing to handle them in a grouped manner.
+ *
+ * This is particularly useful when you have group elements and
+ * need perform specific operations on the reduced elements.
+ *
+ * ```ts
+ * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .count();
+ *
+ * console.log(results.toObject()); // { odd: 4, even: 4 }
+ * ```
+ *
+ * @template K The type of the key used to group the elements.
+ * @template T The type of the elements in the iterator.
+ */
 export default class ReducedIterator<K extends PropertyKey, T>
 {
+    /**
+     * The internal {@link SmartIterator} object that holds the reduced elements.
+     */
     protected _elements: SmartIterator<[K, T]>;
 
+    /**
+     * Initializes a new instance of the {@link ReducedIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new ReducedIterator<string, number>([["A", 1], ["B", 2], ["C", 4]]);
+     * ```
+     *
+     * ---
+     *
+     * @param iterable A reduced iterable object.
+     */
     public constructor(iterable: Iterable<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link ReducedIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new ReducedIterator<string, number>({
+     *     _index: 0,
+     *     next: () =>
+     *     {
+     *         if (this._index >= 3) { return { done: true, value: undefined }; }
+     *         this._index += 1;
+     *
+     *         return { done: false, value: [["A", "B", "C"][this._index], (this._index + 1)] };
+     *     }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param iterator An reduced iterator object.
+     */
     public constructor(iterator: Iterator<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link ReducedIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * import { range, Random } from "@byloth/core";
+     *
+     * const results = new ReducedIterator<string, number>(function* ()
+     * {
+     *     for (const index of range(3))
+     *     {
+     *         yield [["A", "B", "C"][index], (index + 1)];
+     *     }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param generatorFn A generator function that produces the reduced elements.
+     */
     public constructor(generatorFn: GeneratorFunction<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link ReducedIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new ReducedIterator(reducedValues);
+     * ```
+     *
+     * ---
+     *
+     * @param argument An iterable, iterator or generator function that produces the reduced elements.
+     */
     public constructor(argument: Iterable<[K, T]> | Iterator<[K, T]> | GeneratorFunction<[K, T]>);
     public constructor(argument: Iterable<[K, T]> | Iterator<[K, T]> | GeneratorFunction<[K, T]>)
     {
         this._elements = new SmartIterator(argument);
     }
 
+    /**
+     * Determines whether all elements of the reduced iterator satisfy the given condition.
+     * See also {@link ReducedIterator.some}.
+     *
+     * This method will iterate over all the 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 ReducedIterator.find} instead.
+     *
+     * If the iterator is infinite and every element satisfies the condition, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .every((key, value) => value > 0);
+     *
+     * console.log(results); // true
+     * ```
+     *
+     * ---
+     *
+     * @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: KeyedIteratee<K, T, boolean>): boolean
     {
         for (const [index, [key, element]] of this._elements.enumerate())
@@ -27,6 +167,38 @@ export default class ReducedIterator<K extends PropertyKey, T>
 
         return true;
     }
+
+    /**
+     * Determines whether any element of the reduced iterator satisfies the given condition.
+     * See also {@link ReducedIterator.every}.
+     *
+     * This method will iterate over all the 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 ReducedIterator.find} instead.
+     *
+     * If the iterator is infinite and no element satisfies the condition, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .some((key, value) => value > 0);
+     *
+     * console.log(results); // 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: KeyedIteratee<K, T, boolean>): boolean
     {
         for (const [index, [key, element]] of this._elements.enumerate())
@@ -37,8 +209,77 @@ export default class ReducedIterator<K extends PropertyKey, T>
         return false;
     }
 
+    /**
+     * Filters the elements of the reduced iterator using a given condition.
+     *
+     * This method will iterate over all the 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 results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .filter((key, value) => value > 0);
+     *
+     * console.log(results.toObject()); // { odd: 4, even: 16 }
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns A new {@link ReducedIterator} containing only the elements that satisfy the condition.
+     */
     public filter(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, T>;
-    public filter<S extends T>(predicate: KeyedTypeGuardIteratee<K, T, S>): ReducedIterator<K, S>;
+
+    /**
+     * Filters the elements of the reduced iterator using a given type guard predicate.
+     *
+     * This method will iterate over all the 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 results = new SmartIterator<number | string>([-3, -1, "0", "2", 3, 5, "6", "8"])
+     *     .groupBy((value) => Number(value) % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .filter<number>((key, value) => typeof value === "number");
+     *
+     * console.log(results.toObject()); // { odd: 4 }
+     * ```
+     *
+     * ---
+     *
+     * @template S
+     * The type of the elements that satisfy the condition.  
+     * This allows the type-system to infer the correct type of the 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 ReducedIterator} containing only the elements that satisfy the condition.
+     */
+    public filter<S extends T>(predicate: KeyedTypeGuardPredicate<K, T, S>): ReducedIterator<K, S>;
     public filter(predicate: KeyedIteratee<K, T, boolean>): ReducedIterator<K, T>
     {
         const elements = this._elements.enumerate();
@@ -51,6 +292,40 @@ export default class ReducedIterator<K extends PropertyKey, T>
             }
         });
     }
+
+    /**
+     * Maps the elements of the reduced iterator using a given transformation function.
+     *
+     * This method will iterate over all the elements of the iterator applying the transformation function.  
+     * The result of the 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 results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .map((key, value) => value * 2);
+     *
+     * console.log(results.toObject()); // { odd: 8, even: 32 }
+     * ```
+     *
+     * ---
+     *
+     * @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 ReducedIterator} containing the transformed elements.
+     */
     public map<V>(iteratee: KeyedIteratee<K, T, V>): ReducedIterator<K, V>
     {
         const elements = this._elements.enumerate();
@@ -63,7 +338,74 @@ export default class ReducedIterator<K extends PropertyKey, T>
             }
         });
     }
+
+    /**
+     * Reduces the elements of the reduced iterator using a given reducer function.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all the 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 result = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .reduce((key, accumulator, value) => accumulator + value);
+     *
+     * console.log(result); // 20
+     * ```
+     *
+     * ---
+     *
+     * @param reducer The reducer function to apply to the elements of the iterator.
+     *
+     * @returns The final value after reducing all the elements of the iterator.
+     */
     public reduce(reducer: KeyedReducer<K, T, T>): T;
+
+    /**
+     * Reduces the elements of the reduced iterator using a given reducer function.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all the 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 result = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .reduce((key, { value }, currentValue) => ({ value: value + currentValue }), { value: 0 });
+     *
+     * console.log(result); // { value: 20 }
+     * ```
+     *
+     * ---
+     *
+     * @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 the elements of the iterator.
+     * @param initialValue The initial value of the accumulator.
+     *
+     * @returns The final result of the reduction.
+     */
     public reduce<A>(reducer: KeyedReducer<K, T, A>, initialValue: A): A;
     public reduce<A>(reducer: KeyedReducer<K, T, A>, initialValue?: A): A
     {
@@ -88,7 +430,40 @@ export default class ReducedIterator<K extends PropertyKey, T>
         return accumulator;
     }
 
-    public flatMap<V>(iteratee: KeyedIteratee<K, T, Iterable<V>>): AggregatedIterator<K, V>
+    /**
+     * Flattens the elements of the reduced iterator using a given transformation function.
+     *
+     * This method will iterate over all the 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 results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator.concat([value]), () => [])
+     *     .flatMap((key, value) => value);
+     *
+     * console.log(results.toObject()); // { odd: [-3, -1, 3, 5], even: [0, 2, 6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @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 AggregatedIterator} containing the flattened elements.
+     */
+    public flatMap<V>(iteratee: KeyedIteratee<K, T, V | readonly V[]>): AggregatedIterator<K, V>
     {
         const elements = this._elements.enumerate();
 
@@ -96,11 +471,48 @@ export default class ReducedIterator<K extends PropertyKey, T>
         {
             for (const [index, [key, element]] of elements)
             {
-                for (const value of iteratee(key, element, index)) { yield [key, value]; }
+                const values = iteratee(key, element, index);
+
+                if (values instanceof Array)
+                {
+                    for (const value of values) { yield [key, value]; }
+                }
+                else { yield [key, values]; }
             }
         });
     }
 
+    /**
+     * Drops a given number of elements at the beginning of the reduced iterator.  
+     * The remaining elements will be included in the new iterator.
+     * See also {@link ReducedIterator.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 once the new iterator is.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator.concat(value), () => [])
+     *     .drop(1);
+     *
+     * console.log(results.toObject()); // { even: [0, 2, 6, 8] }
+     * ```
+     * 
+     * @param count The number of elements to drop.
+     *
+     * @returns A new {@link ReducedIterator} containing the remaining elements.
+     */
     public drop(count: number): ReducedIterator<K, T>
     {
         const elements = this._elements.enumerate();
@@ -113,7 +525,43 @@ export default class ReducedIterator<K extends PropertyKey, T>
             }
         });
     }
-    public take(count: number): ReducedIterator<K, T>
+
+    /**
+     * Takes a given number of elements at the beginning of the reduced iterator.  
+     * The elements will be included in the new iterator.
+     * See also {@link ReducedIterator.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 reduced iterator.  
+     * The rest of the original reduced iterator will be available for further consumption.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator.concat(value), () => []);
+     *
+     * const results = iterator.take(1);
+     *
+     * console.log(results.toObject()); // { odd: [-3, -1, 3, 5] }
+     * console.log(reduced.toObject()); // { even: [0, 2, 6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @param limit The number of elements to take.
+     *
+     * @returns A new {@link ReducedIterator} containing the taken elements.
+     */
+    public take(limit: number): ReducedIterator<K, T>
     {
         const elements = this._elements.enumerate();
 
@@ -121,17 +569,146 @@ export default class ReducedIterator<K extends PropertyKey, T>
         {
             for (const [index, [key, element]] of elements)
             {
-                if (index >= count) { break; }
-
+                if (index >= limit) { break; }
                 yield [key, element];
             }
         });
     }
 
+    /**
+     * Finds the first element of the reduced iterator that satisfies the given condition.
+     *
+     * This method will iterate over all the 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 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 results = new SmartIterator<number>([-3, -3, -1, 0, 1, 2, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .find((key, value) => value > 0);
+     * 
+     * console.log(results); // 16
+     * 
+     * @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: KeyedIteratee<K, T, boolean>): T | undefined;
+
+    /**
+     * Finds the first element of the reduced iterator that satisfies the given type guard predicate.
+     *
+     * This method will iterate over all the 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 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 results = new SmartIterator<number | string>(["-3", -3, "-1", 0, 1, 2, "5", 6, 8])
+     *     .groupBy((value) => Number(value) % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .find<number>((key, value) => typeof value === "number");
+     * 
+     * console.log(results); // 16
+     *
+     * @template S
+     * The type of the elements that satisfy 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: KeyedTypeGuardPredicate<K, T, S>): S | undefined;
+    public find(predicate: KeyedIteratee<K, T, boolean>): T | undefined
+    {
+        for (const [index, [key, element]] of this._elements.enumerate())
+        {
+            if (predicate(key, element, index)) { return element; }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Enumerates the elements of the reduced iterator.  
+     * Each element is 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 results = new ReducedIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .enumerate();
+     *
+     * console.log(results.toObject()); // [[0, 4], [1, 16]]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link ReducedIterator} object containing the enumerated elements.
+     */
     public enumerate(): ReducedIterator<K, [number, T]>
     {
         return this.map((_, element, index) => [index, element]);
     }
+
+    /**
+     * Removes all duplicate elements from the reduced 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 results = new ReducedIterator<number>([-3, -1, 0, 2, 3, 6, -3, -1, 1, 5, 6, 8, 7, 2])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .map((key, value) => Math.abs(value))
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .unique();
+     *
+     * console.log(results.toObject()); // { odd: 24 }
+     *
+     * @returns A new {@link ReducedIterator} containing only the unique elements.
+     */
     public unique(): ReducedIterator<K, T>
     {
         const elements = this._elements;
@@ -139,7 +716,6 @@ export default class ReducedIterator<K extends PropertyKey, T>
         return new ReducedIterator(function* ()
         {
             const values = new Set<T>();
-
             for (const [key, element] of elements)
             {
                 if (values.has(element)) { continue; }
@@ -150,6 +726,28 @@ export default class ReducedIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Counts the number of elements in the reduced iterator.  
+     * This method will consume the entire iterator in the process.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .count();
+     *
+     * console.log(results); // 2
+     * ```
+     *
+     * ---
+     *
+     * @returns The number of elements in the iterator.
+     */
     public count(): number
     {
         let index = 0;
@@ -159,6 +757,31 @@ export default class ReducedIterator<K extends PropertyKey, T>
         return index;
     }
 
+    /**
+     * Iterates over all elements of the reduced iterator.  
+     * The elements are passed to the function along with their key and index.
+     *
+     * This method will consume the entire iterator in the process.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value);
+     * 
+     * reduced.forEach((key, value, index) =>
+     * {
+     *     console.log(`#${index} - ${key}: ${value}`); // "#0 - odd: 4", "#1 - even: 16"
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param iteratee The function to apply to each element of the reduced iterator.
+     */
     public forEach(iteratee: KeyedIteratee<K, T>): void
     {
         for (const [index, [key, element]] of this._elements.enumerate())
@@ -167,6 +790,77 @@ export default class ReducedIterator<K extends PropertyKey, T>
         }
     }
 
+    /**
+     * Reaggregates the elements of the reduced iterator.  
+     * The elements are grouped by a new key computed by the given iteratee function.
+     *
+     * Since the iterator is lazy, the reorganizing 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 results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, -6, -8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .reorganizeBy((key, value) => value > 0 ? "positive" : "negative");
+     *
+     * console.log(results.toObject()); // { positive: 4, negative: -12 }
+     * ```
+     *
+     * ---
+     *
+     * @template J The type of the new keys used to group the elements.
+     *
+     * @param iteratee The function to determine the new key of each element of the iterator.
+     *
+     * @returns A new {@link AggregatedIterator} containing the elements reorganized by the new keys.
+     */
+    public reorganizeBy<J extends PropertyKey>(iteratee: KeyedIteratee<K, T, J>): AggregatedIterator<J, T>
+    {
+        const elements = this._elements.enumerate();
+
+        return new AggregatedIterator(function* ()
+        {
+            for (const [index, [key, element]] of elements)
+            {
+                yield [iteratee(key, element, index), element];
+            }
+        });
+    }
+
+    /**
+     * An utility method that returns a new {@link SmartIterator}
+     * object containing all the keys of the iterator.
+     *
+     * Since the iterator is lazy, the keys will be extracted
+     * 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 keys = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .keys();
+     *
+     * console.log(keys.toArray()); // ["odd", "even"]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartIterator} containing all the keys of the iterator.
+     */
     public keys(): SmartIterator<K>
     {
         const elements = this._elements;
@@ -179,10 +873,67 @@ export default class ReducedIterator<K extends PropertyKey, T>
             }
         });
     }
-    public items(): SmartIterator<[K, T]>
+
+    /**
+     * An utility method that returns a new {@link SmartIterator}
+     * object containing all the entries of the iterator.  
+     * Each entry is a tuple containing the key and the element.
+     *
+     * Since the iterator is lazy, the entries will be extracted
+     * 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 entries = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .entries();
+     *
+     * console.log(entries.toArray()); // [["odd", 4], ["even", 16]]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartIterator} containing all the entries of the iterator.
+     */
+    public entries(): SmartIterator<[K, T]>
     {
         return this._elements;
     }
+
+    /**
+     * An utility method that returns a new {@link SmartIterator}
+     * object containing all the values of the iterator.
+     *
+     * Since the iterator is lazy, the values will be extracted
+     * 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 values = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value)
+     *     .values();
+     *
+     * console.log(values.toArray()); // [4, 16]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartIterator} containing all the values of the iterator.
+     */
     public values(): SmartIterator<T>
     {
         const elements = this._elements;
@@ -196,17 +947,82 @@ export default class ReducedIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * 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 reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value);
+     *
+     * console.log(reduced.toArray()); // [4, 16]
+     * ```
+     *
+     * ---
+     *
+     * @returns The {@link Array} containing all elements of the iterator.
+     */
     public toArray(): T[]
     {
         return Array.from(this.values());
     }
+
+    /**
+     * Materializes the iterator into a map.  
+     * This method will consume the entire iterator in the process.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value);
+     *
+     * console.log(reduced.toMap()); // Map(2) { "odd" => 4, "even" => 16 }
+     * ```
+     *
+     * ---
+     *
+     * @returns The {@link Map} containing all elements of the iterator.
+     */
     public toMap(): Map<K, T>
     {
-        return new Map(this.items());
+        return new Map(this.entries());
     }
+
+    /**
+     * Materializes the iterator into an object.  
+     * This method will consume the entire iterator in the process.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce((key, accumulator, value) => accumulator + value);
+     *
+     * console.log(reduced.toObject()); // { odd: 4, even: 16 }
+     * ```
+     *
+     * ---
+     *
+     * @returns The {@link Object} containing all elements of the iterator.
+     */
     public toObject(): Record<K, T>
     {
-        return Object.fromEntries(this.items()) as Record<K, T>;
+        return Object.fromEntries(this.entries()) as Record<K, T>;
     }
 
     public readonly [Symbol.toStringTag]: string = "ReducedIterator";