@byloth/core 2.0.0-rc.9 → 2.0.1

package/src/models/aggregators/aggregated-async-iterator.ts

@@ -9,24 +9,232 @@ import type {
 import type { MaybePromise } from "../types.js";
 
 import ReducedIterator from "./reduced-iterator.js";
-import type { MaybeAsyncKeyedIteratee, MaybeAsyncKeyedTypeGuardIteratee, MaybeAsyncKeyedReducer } from "./types.js";
-
+import type { MaybeAsyncKeyedIteratee, MaybeAsyncKeyedReducer } from "./types.js";
+
+/**
+ * A class representing an iterator that aggregates elements in a lazy and optimized way.
+ *
+ * It's part of the {@link SmartAsyncIterator} implementation,
+ * providing a way to group elements of an iterable by key.  
+ * For this reason, it isn't recommended to instantiate this class directly
+ * (although it's still possible), but rather use the {@link SmartAsyncIterator.groupBy} method.
+ *
+ * It isn't directly iterable like its parent class but rather needs to specify on what you want to iterate.  
+ * See the {@link AggregatedAsyncIterator.keys}, {@link AggregatedAsyncIterator.entries}
+ * & {@link AggregatedAsyncIterator.values} methods.  
+ * It does, however, provide the same set of methods to perform
+ * operations and transformations 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 need to group elements and
+ * then perform specific operations on the groups themselves.
+ *
+ * ```ts
+ * const elements = fetch([...]); // Promise<[-3, -1, 0, 2, 3, 5, 6, 8]>;
+ * const results = new SmartAsyncIterator(elements)
+ *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+ *     .count();
+ *
+ * console.log(await results.toObject()); // { odd: 4, even: 4 }
+ * ```
+ *
+ * @template K The type of the keys used to group the elements.
+ * @template T The type of the elements to aggregate.
+ */
 export default class AggregatedAsyncIterator<K extends PropertyKey, T>
 {
+    /**
+     * The internal {@link SmartAsyncIterator} object that holds the elements to aggregate.
+     */
     protected _elements: SmartAsyncIterator<[K, T]>;
 
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new AggregatedAsyncIterator<string, number>([["A", 1], ["B", 2], ["A", 3], ["C", 4], ["B", 5]]);
+     * ```
+     *
+     * ---
+     *
+     * @param iterable The iterable to aggregate.
+     */
     public constructor(iterable: Iterable<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const elements = fetch([...]); // Promise<[["A", 1], ["B", 2], ["A", 3], ["C", 4], ["B", 5]]>
+     * const iterator = new AggregatedAsyncIterator<string, number>(elements);
+     * ```
+     *
+     * ---
+     *
+     * @param iterable The iterable to aggregate.
+     */
     public constructor(iterable: AsyncIterable<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * import { Random } from "@byloth/core";
+     *
+     * const iterator = new AggregatedAsyncIterator<string, number>({
+     *     _index: 0,
+     *     next: () =>
+     *     {
+     *         if (this._index >= 5) { return { done: true, value: undefined }; }
+     *         this._index += 1;
+     *
+     *         return { done: false, value: [Random.Choice(["A", "B", "C"]), (this._index + 1)] };
+     *     }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param iterator The iterator to aggregate.
+     */
     public constructor(iterator: Iterator<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * import { Random } from "@byloth/core";
+     *
+     * const iterator = new AggregatedAsyncIterator<string, number>({
+     *     _index: 0,
+     *     next: async () =>
+     *     {
+     *         if (this._index >= 5) { return { done: true, value: undefined }; }
+     *         this._index += 1;
+     *
+     *         return { done: false, value: [Random.Choice(["A", "B", "C"]), (this._index + 1)] };
+     *     }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param iterator The iterator to aggregate.
+     */
     public constructor(iterator: AsyncIterator<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * import { range, Random } from "@byloth/core";
+     *
+     * const iterator = new AggregatedAsyncIterator<string, number>(function* ()
+     * {
+     *     for (const index of range(5))
+     *     {
+     *         yield [Random.Choice(["A", "B", "C"]), (index + 1)];
+     *     }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param generatorFn The generator function to aggregate.
+     */
     public constructor(generatorFn: GeneratorFunction<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * import { range, Random } from "@byloth/core";
+     *
+     * const iterator = new AggregatedAsyncIterator<string, number>(async function* ()
+     * {
+     *     for await (const index of range(5))
+     *     {
+     *         yield [Random.Choice(["A", "B", "C"]), (index + 1)];
+     *     }
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @param generatorFn The generator function to aggregate.
+     */
     public constructor(generatorFn: AsyncGeneratorFunction<[K, T]>);
+
+    /**
+     * Initializes a new instance of the {@link AggregatedAsyncIterator} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const iterator = new AggregatedAsyncIterator(asyncKeyedValues);
+     * ```
+     *
+     * ---
+     *
+     * @param argument The iterable, iterator or generator function to aggregate.
+     */
     public constructor(argument: MaybeAsyncIteratorLike<[K, T]> | MaybeAsyncGeneratorFunction<[K, T]>);
     public constructor(argument: MaybeAsyncIteratorLike<[K, T]> | MaybeAsyncGeneratorFunction<[K, T]>)
     {
         this._elements = new SmartAsyncIterator(argument);
     }
 
+    /**
+     * Determines whether all elements of each group of the iterator satisfy a given condition.
+     * See also {@link AggregatedAsyncIterator.some}.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all elements of the iterator checjing if they satisfy the condition.  
+     * Once a single element of one group doesn't satisfy the condition,
+     * the result for the respective group will be `false`.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain all the boolean results for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .every(async (key, value) => value >= 0);
+     *
+     * console.log(await results.toObject()); // { odd: false, even: true }
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing the boolean results for each group.
+     */
     public async every(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): Promise<ReducedIterator<K, boolean>>
     {
         const values = new Map<K, [number, boolean]>();
@@ -45,6 +253,38 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             for (const [key, [_, result]] of values) { yield [key, result]; }
         });
     }
+
+    /**
+     * Determines whether any element of each group of the iterator satisfies a given condition.
+     * See also {@link AggregatedAsyncIterator.every}.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all elements of the iterator checjing if they satisfy the condition.  
+     * Once a single element of one group satisfies the condition,
+     * the result for the respective group will be `true`.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain all the boolean results for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-5, -4, -3, -2, -1, 0])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .some(async (key, value) => value >= 0);
+     *
+     * console.log(await results.toObject()); // { odd: false, even: true }
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing the boolean results for each group.
+     */
     public async some(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): Promise<ReducedIterator<K, boolean>>
     {
         const values = new Map<K, [number, boolean]>();
@@ -64,8 +304,69 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Filters the elements of the iterator based on 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.
+     *
+     * 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 SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .filter(async (key, value) => value >= 0);
+     *
+     * console.log(await results.toObject()); // { odd: [3, 5], even: [0, 2, 6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns A new {@link AggregatedAsyncIterator} containing the elements that satisfy the condition.
+     */
     public filter(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): AggregatedAsyncIterator<K, T>;
-    public filter<S extends T>(predicate: MaybeAsyncKeyedTypeGuardIteratee<K, T, S>): AggregatedAsyncIterator<K, S>;
+
+    /**
+     * Filters the elements of the iterator based on 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.
+     *
+     * 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 SmartAsyncIterator<number>([-3, "-1", 0, "2", "3", 5, 6, "8"])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .filter<number>(async (key, value) => typeof value === "number");
+     *
+     * console.log(await results.toObject()); // { odd: [-3, 5], even: [0, 6] }
+     * ```
+     *
+     * ---
+     *
+     * @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 AggregatedAsyncIterator} containing the elements that satisfy the condition.
+     */
+    public filter<S extends T>(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): AggregatedAsyncIterator<K, S>;
     public filter(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): AggregatedAsyncIterator<K, T>
     {
         const elements = this._elements;
@@ -73,17 +374,48 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[K, T]>
         {
             const indexes = new Map<K, number>();
-
             for await (const [key, element] of elements)
             {
                 const index = indexes.get(key) ?? 0;
-
                 if (await predicate(key, element, index)) { yield [key, element]; }
 
                 indexes.set(key, index + 1);
             }
         });
     }
+
+    /**
+     * Maps the elements of the iterator using a given transformation function.
+     *
+     * This method will iterate over all elements of the iterator applying the condition.  
+     * 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 results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .map(async (key, value) => Math.abs(value));
+     *
+     * console.log(await 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 AggregatedAsyncIterator} containing the transformed elements.
+     */
     public map<V>(iteratee: MaybeAsyncKeyedIteratee<K, T, V>): AggregatedAsyncIterator<K, V>
     {
         const elements = this._elements;
@@ -91,22 +423,128 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[K, V]>
         {
             const indexes = new Map<K, number>();
-
             for await (const [key, element] of elements)
             {
                 const index = indexes.get(key) ?? 0;
-
                 yield [key, await iteratee(key, element, index)];
 
                 indexes.set(key, index + 1);
             }
         });
     }
+
+    /**
+     * 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 accoumulator value will be the first element of the iterator.  
+     * The last accumulator value will be the final result of the reduction.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain all the reduced results for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce(async (key, accumulator, value) => accumulator + value);
+     *
+     * console.log(await results.toObject()); // { odd: 4, even: 16 }
+     * ```
+     *
+     * ---
+     *
+     * @param reducer The reducer function to apply to each element of the iterator.
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing the reduced results for each group.
+     */
     public async reduce(reducer: MaybeAsyncKeyedReducer<K, T, T>): Promise<ReducedIterator<K, 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 accoumulator value will be the provided initial value.  
+     * The last accumulator value will be the final result of the reduction.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain all the reduced results for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce(async (key, accumulator, value) => accumulator + value, 0);
+     *
+     * console.log(await results.toObject()); // { odd: 4, even: 16 }
+     * ```
+     *
+     * ---
+     *
+     * @template A The type of the accumulator value which will also be the final result of the reduction.
+     *
+     * @param reducer The reducer function to apply to each element of the iterator.
+     * @param initialValue The initial value for the accumulator.
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing the reduced results for each group.
+     */
+    public async reduce<A extends PropertyKey>(reducer: MaybeAsyncKeyedReducer<K, T, A>, initialValue: MaybePromise<A>)
+        : Promise<ReducedIterator<K, A>>;
+
+    /**
+     * 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 accoumulator value will be the provided initial value by the given function.  
+     * The last accumulator value will be the final result of the reduction.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain all the reduced results for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .reduce(async (key, { value }, currentValue) => ({ value: value + currentValue }), (key) => ({ value: 0 }));
+     *
+     * console.log(await results.toObject()); // { odd: { value: 4 }, even: { value: 16 } }
+     * ```
+     *
+     * ---
+     *
+     * @template A The type of the accumulator value which will also be the final result of the reduction.
+     *
+     * @param reducer The reducer function to apply to each element of the iterator.
+     * @param initialValue The function that provides the initial value for the accumulator.
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing the reduced results for each group.
+     */
     public async reduce<A>(reducer: MaybeAsyncKeyedReducer<K, T, A>, initialValue: (key: K) => MaybePromise<A>)
         : Promise<ReducedIterator<K, A>>;
-    public async reduce<A>(reducer: MaybeAsyncKeyedReducer<K, T, A>, initialValue?: (key: K) => MaybePromise<A>)
-        : Promise<ReducedIterator<K, A>>
+    public async reduce<A>(
+        reducer: MaybeAsyncKeyedReducer<K, T, A>, initialValue?: MaybePromise<A> | ((key: K) => MaybePromise<A>)
+    ): Promise<ReducedIterator<K, A>>
     {
         const values = new Map<K, [number, A]>();
 
@@ -119,7 +557,9 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             else if (initialValue !== undefined)
             {
                 index = 0;
-                accumulator = await initialValue(key);
+
+                if (initialValue instanceof Function) { accumulator = await initialValue(key); }
+                else { accumulator = await initialValue; }
             }
             else
             {
@@ -137,26 +577,94 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
-    public flatMap<V>(iteratee: MaybeAsyncKeyedIteratee<K, T, Iterable<V>>): AggregatedAsyncIterator<K, V>
+    /**
+     * 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 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 SmartAsyncIterator<number>([[-3, -1], 0, 2, 3, 5, [6, 8]])
+     *      .groupBy(async (values) =>
+     *      {
+     *          const value = values instanceof Array ? values[0] : values;
+     *          return value % 2 === 0 ? "even" : "odd";
+     *      })
+     *     .flatMap(async (key, values) => values);
+     *
+     * console.log(await 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 AggregatedAsyncIterator} containing the transformed elements.
+     */
+    public flatMap<V>(iteratee: MaybeAsyncKeyedIteratee<K, T, V | readonly V[]>): AggregatedAsyncIterator<K, V>
     {
         const elements = this._elements;
 
         return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[K, V]>
         {
             const indexes = new Map<K, number>();
-
             for await (const [key, element] of elements)
             {
                 const index = indexes.get(key) ?? 0;
                 const values = await iteratee(key, element, index);
 
-                for await (const value of values) { yield [key, value]; }
+                if (values instanceof Array)
+                {
+                    for (const value of values) { yield [key, value]; }
+                }
+                else { yield [key, values]; }
 
                 indexes.set(key, index + 1);
             }
         });
     }
 
+    /**
+     * Drops a given number of elements from the beginning of each group of the iterator.  
+     * The remaining elements will be included in the new iterator.
+     * See also {@link AggregatedAsyncIterator.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.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .drop(2);
+     *
+     * console.log(await results.toObject()); // { odd: [3, 5], even: [6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @param count The number of elements to drop from the beginning of each group.
+     *
+     * @returns A new {@link AggregatedAsyncIterator} containing the remaining elements.
+     */
     public drop(count: number): AggregatedAsyncIterator<K, T>
     {
         const elements = this._elements;
@@ -164,7 +672,6 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[K, T]>
         {
             const indexes = new Map<K, number>();
-
             for await (const [key, element] of elements)
             {
                 const index = indexes.get(key) ?? 0;
@@ -179,6 +686,36 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             }
         });
     }
+
+    /**
+     * Takes a given number of elements from the beginning of each group of the iterator.  
+     * The elements will be included in the new iterator.
+     * See also {@link AggregatedAsyncIterator.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.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .take(2);
+     *
+     * console.log(await results.toObject()); // { odd: [-3, -1], even: [0, 2] }
+     * ```
+     *
+     * ---
+     *
+     * @param limit The number of elements to take from the beginning of each group.
+     *
+     * @returns A new {@link AggregatedAsyncIterator} containing the taken elements.
+     */
     public take(limit: number): AggregatedAsyncIterator<K, T>
     {
         const elements = this._elements;
@@ -186,7 +723,6 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[K, T]>
         {
             const indexes = new Map<K, number>();
-
             for await (const [key, element] of elements)
             {
                 const index = indexes.get(key) ?? 0;
@@ -199,8 +735,77 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Finds the first element of each group of the iterator that satisfies a given condition.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * Once the first element of one group satisfies the condition,
+     * the result for the respective group will be the element itself.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain the first element that satisfies the condition for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .find(async (key, value) => value > 0);
+     *
+     * console.log(await results.toObject()); // { odd: 3, even: 2 }
+     * ```
+     *
+     * ---
+     *
+     * @param predicate The condition to check for each element of the iterator.
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing
+     * the first element that satisfies the condition for each group.
+     */
     public async find(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): Promise<ReducedIterator<K, T | undefined>>;
-    public async find<S extends T>(predicate: MaybeAsyncKeyedTypeGuardIteratee<K, T, S>)
+
+    /**
+     * Finds the first element of each group of the iterator that satisfies a given condition.  
+     * This method will consume the entire iterator in the process.
+     *
+     * It will iterate over all elements of the iterator checking if they satisfy the condition.  
+     * Once the first element of one group satisfies the condition,
+     * the result for the respective group will be the element itself.
+     *
+     * Eventually, it will return a new {@link ReducedIterator}
+     * object that will contain the first element that satisfies the condition for each group.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const results = new SmartAsyncIterator<number | string>([-3, "-1", 0, "2", "3", 5, 6, "8"])
+     *     .groupBy(async (value) => Number(value) % 2 === 0 ? "even" : "odd")
+     *     .find<number>(async (key, value) => typeof value === "number");
+     *
+     * console.log(await results.toObject()); // { odd: -3, even: 0 }
+     * ```
+     *
+     * ---
+     *
+     * @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 {@link Promise} resolving to a new {@link ReducedIterator} containing
+     * the first element that satisfies the condition for each group.
+     */
+    public async find<S extends T>(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>)
         : Promise<ReducedIterator<K, S | undefined>>;
 
     public async find(predicate: MaybeAsyncKeyedIteratee<K, T, boolean>): Promise<ReducedIterator<K, T | undefined>>
@@ -223,6 +828,63 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Enumerates the elements of the iterator.  
+     * Each element is paired with its index within the group in the 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 SmartAsyncIterator<number>([-3, 0, 2, -1, 3])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .enumerate();
+     *
+     * console.log(results.toObject()); // { odd: [[0, -3], [1, -1], [2, 3]], even: [[0, 0], [1, 2]] }
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link AggregatedAsyncIterator} containing the enumerated elements.
+     */
+    public enumerate(): AggregatedAsyncIterator<K, [number, T]>
+    {
+        return this.map((key, value, index) => [index, value]);
+    }
+
+    /**
+     * Removes all duplicate elements from within each group of the iterator.  
+     * The first occurrence of each element will be included in the new iterator.
+     *
+     * 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 SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 6, -3, -1, 0, 5, 6, 8, 0, 2])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .unique();
+     *
+     * console.log(await results.toObject()); // { odd: [-3, -1, 3, 5], even: [0, 2, 6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link AggregatedAsyncIterator} containing only the unique elements.
+     */
     public unique(): AggregatedAsyncIterator<K, T>
     {
         const elements = this._elements;
@@ -230,11 +892,9 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[K, T]>
         {
             const keys = new Map<K, Set<T>>();
-
             for await (const [key, element] of elements)
             {
                 const values = keys.get(key) ?? new Set<T>();
-
                 if (values.has(element)) { continue; }
 
                 values.add(element);
@@ -245,6 +905,28 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Counts the number of elements within each group of 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 results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .count();
+     *
+     * console.log(await results.toObject()); // { odd: 4, even: 4 }
+     * ```
+     *
+     * ---
+     *
+     * @returns
+     * A {@link Promise} resolving to a new {@link ReducedIterator} containing the number of elements for each group.
+     */
     public async count(): Promise<ReducedIterator<K, number>>
     {
         const counters = new Map<K, number>();
@@ -262,6 +944,32 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Iterates over the elements of the iterator.  
+     * The elements are passed to the given iteratee function along with their key and index within the group.
+     *
+     * This method will consume the entire iterator in the process.  
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const aggregator = new SmartAsyncIterator<number>([-3, 0, 2, -1, 3])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd");
+     *
+     * await aggregator.forEach(async (key, value, index) =>
+     * {
+     *     console.log(`${index}: ${value}`); // "0: -3", "0: 0", "1: 2", "1: -1", "2: 3"
+     * };
+     * ```
+     *
+     * ---
+     *
+     * @param iteratee The function to execute for each element of the iterator.
+     *
+     * @returns A {@link Promise} that will resolve once the iteration is complete.
+     */
     public async forEach(iteratee: MaybeAsyncKeyedIteratee<K, T>): Promise<void>
     {
         const indexes = new Map<K, number>();
@@ -270,12 +978,87 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         {
             const index = indexes.get(key) ?? 0;
 
-            iteratee(key, element, index);
+            await iteratee(key, element, index);
 
             indexes.set(key, index + 1);
         }
     }
 
+    /**
+     * Changes the key of each element on which the iterator is aggregated.  
+     * The new key is determined by the given iteratee function.
+     *
+     * Since the iterator is lazy, the reorganization 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 SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .map(async (key, value, index) => index % 2 === 0 ? value : -value)
+     *     .reorganizeBy(async (key, value) => value >= 0 ? "+" : "-");
+     *
+     * console.log(await results.toObject()); // { "+": [1, 0, 3, 6], "-": [-3, -2, -5, -8] }
+     * ```
+     *
+     * ---
+     *
+     * @template J The type of the new key.
+     *
+     * @param iteratee The function to determine the new key for each element of the iterator.
+     *
+     * @returns A new {@link AggregatedAsyncIterator} containing the elements reorganized by the new keys.
+     */
+    public reorganizeBy<J extends PropertyKey>(iteratee: MaybeAsyncKeyedIteratee<K, T, J>)
+        : AggregatedAsyncIterator<J, T>
+    {
+        const elements = this._elements;
+
+        return new AggregatedAsyncIterator(async function* (): AsyncGenerator<[J, T]>
+        {
+            const indexes = new Map<K, number>();
+            for await (const [key, element] of elements)
+            {
+                const index = indexes.get(key) ?? 0;
+                yield [await iteratee(key, element, index), element];
+
+                indexes.set(key, index + 1);
+            }
+        });
+    }
+
+    /**
+     * An utility method that returns a new {@link SmartAsyncIterator}
+     * 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 SmartAsyncIterator([-3, Symbol(), "A", { }, null, [1 , 2, 3], false])
+     *     .groupBy(async (value) => typeof value)
+     *     .keys();
+     *
+     * console.log(await keys.toArray()); // ["number", "symbol", "string", "object", "boolean"]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartAsyncIterator} containing all the keys of the iterator.
+     */
     public keys(): SmartAsyncIterator<K>
     {
         const elements = this._elements;
@@ -283,7 +1066,6 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         return new SmartAsyncIterator<K>(async function* ()
         {
             const keys = new Set<K>();
-
             for await (const [key] of elements)
             {
                 if (keys.has(key)) { continue; }
@@ -293,10 +1075,65 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
             }
         });
     }
-    public items(): SmartAsyncIterator<[K, T]>
+
+    /**
+     * An utility method that returns a new {@link SmartAsyncIterator}
+     * 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 SmartAsyncIterator<number>([-3, 0, 2, -1, 3])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .entries();
+     *
+     * console.log(await entries.toArray()); // [["odd", -3], ["even", 0], ["even", 2], ["odd", -1], ["odd", 3]]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartAsyncIterator} containing all the entries of the iterator.
+     */
+    public entries(): SmartAsyncIterator<[K, T]>
     {
         return this._elements;
     }
+
+    /**
+     * An utility method that returns a new {@link SmartAsyncIterator}
+     * 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 SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd")
+     *     .values();
+     *
+     * console.log(await values.toArray()); // [-3, -1, 0, 2, 3, 5, 6, 8]
+     * ```
+     *
+     * ---
+     *
+     * @returns A new {@link SmartAsyncIterator} containing all the values of the iterator.
+     */
     public values(): SmartAsyncIterator<T>
     {
         const elements = this._elements;
@@ -307,12 +1144,53 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
         });
     }
 
+    /**
+     * Materializes the iterator into an array of arrays.  
+     * This method will consume the entire iterator in the process.
+     *
+     * If the iterator is infinite, the method will never return.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const aggregator = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd");
+     *
+     * console.log(await aggregator.toArray()); // [[-3, -1, 3, 5], [0, 2, 6, 8]]
+     * ```
+     *
+     * ---
+     *
+     * @returns A {@link Promise} resolving to an {@link Array} containing all the values of the iterator.
+     */
     public async toArray(): Promise<T[][]>
     {
         const map = await this.toMap();
 
         return Array.from(map.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 aggregator = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd");
+     *
+     * console.log(await aggregator.toMap()); // Map(2) { "odd" => [-3, -1, 3, 5], "even" => [0, 2, 6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @returns A {@link Promise} resolving to a {@link Map} containing all the entries of the iterator.
+     */
     public async toMap(): Promise<Map<K, T[]>>
     {
         const groups = new Map<K, T[]>();
@@ -327,6 +1205,27 @@ export default class AggregatedAsyncIterator<K extends PropertyKey, T>
 
         return groups;
     }
+
+    /**
+     * 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 aggregator = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+     *     .groupBy(async (value) => value % 2 === 0 ? "even" : "odd");
+     *
+     * console.log(await aggregator.toObject()); // { odd: [-3, -1, 3, 5], even: [0, 2, 6, 8] }
+     * ```
+     *
+     * ---
+     *
+     * @returns A {@link Promise} resolving to an object containing all the entries of the iterator.
+     */
     public async toObject(): Promise<Record<K, T[]>>
     {
         const groups = { } as Record<K, T[]>;