@byloth/core 2.0.0 → 2.0.2

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

@@ -22,6 +22,9 @@ import type { KeyedIteratee, KeyedTypeGuardPredicate, KeyedReducer } from "./typ
  * This is particularly useful when you need to group elements and
  * then perform specific operations on the groups themselves.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
  *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -30,6 +33,8 @@ import type { KeyedIteratee, KeyedTypeGuardPredicate, KeyedReducer } from "./typ
  * console.log(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.
  */
@@ -43,10 +48,15 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link AggregatedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new AggregatedIterator<string, number>([["A", 1], ["B", 2], ["A", 3], ["C", 4], ["B", 5]]);
      * ```
      *
+     * ---
+     *
      * @param iterable The iterable to aggregate.
      */
     public constructor(iterable: Iterable<[K, T]>);
@@ -54,6 +64,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link AggregatedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * import { Random } from "@byloth/core";
      *
@@ -69,6 +82,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param iterator The iterator to aggregate.
      */
     public constructor(iterator: Iterator<[K, T]>);
@@ -76,6 +91,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link AggregatedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * import { range, Random } from "@byloth/core";
      *
@@ -88,6 +106,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param generatorFn The generator function to aggregate.
      */
     public constructor(generatorFn: GeneratorFunction<[K, T]>);
@@ -95,10 +115,15 @@ export default class AggregatedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link AggregatedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new AggregatedIterator(keyedValues);
      * ```
      *
+     * ---
+     *
      * @param argument The iterable, iterator or generator function to aggregate.
      */
     public constructor(argument: IteratorLike<[K, T]> | GeneratorFunction<[K, T]>);
@@ -120,6 +145,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -128,6 +156,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: false, even: true }
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns A new {@link ReducedIterator} containing the boolean results for each group.
@@ -164,6 +194,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-5, -4, -3, -2, -1, 0])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -172,6 +205,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: false, even: true }
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns A {@link ReducedIterator} containing the boolean results for each group.
@@ -208,6 +243,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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")
@@ -216,6 +254,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(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 AggregatedIterator} containing only the elements that satisfy the condition.
@@ -235,6 +275,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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) => value % 2 === 0 ? "even" : "odd")
@@ -243,6 +286,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(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.
@@ -284,6 +329,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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")
@@ -292,6 +340,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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.
@@ -329,6 +379,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -337,6 +390,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 4, even: 16 }
      * ```
      *
+     * ---
+     *
      * @param reducer The reducer function to apply to each element of the iterator.
      *
      * @returns A new {@link ReducedIterator} containing the reduced results for each group.
@@ -357,6 +412,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -365,6 +423,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 4, even: 16 }
      * ```
      *
+     * ---
+     *
      * @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.
@@ -388,6 +448,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -396,6 +459,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: { value: 4 }, even: { value: 16 } }
      * ```
      *
+     * ---
+     *
      * @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.
@@ -450,6 +515,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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((values) =>
@@ -462,6 +530,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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.
@@ -503,6 +573,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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")
@@ -511,6 +584,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(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 AggregatedIterator} containing the remaining elements.
@@ -549,6 +624,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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")
@@ -557,7 +635,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: [-3, -1], even: [0, 2] }
      * ```
      *
-     * @param count The number of elements to take from the beginning of each group.
+     * ---
+     *
+     * @param limit The number of elements to take from the beginning of each group.
      *
      * @returns A new {@link AggregatedIterator} containing the taken elements.
      */
@@ -591,6 +671,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -599,6 +682,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 3, even: 2 }
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns A new {@link ReducedIterator} containing the first element that satisfies the condition for each group.
@@ -617,6 +702,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number | string>([-3, "-1", 0, "2", "3", 5, 6, "8"])
      *     .groupBy((value) => Number(value) % 2 === 0 ? "even" : "odd")
@@ -625,6 +713,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(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.
@@ -667,6 +757,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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, 0, 2, -1, 3])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -675,6 +768,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: [[0, -3], [1, -1], [2, 3]], even: [[0, 0], [1, 2]] }
      * ```
      *
+     * ---
+     *
      * @returns A new {@link AggregatedIterator} containing the enumerated elements.
      */
     public enumerate(): AggregatedIterator<K, [number, T]>
@@ -693,6 +788,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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, 6, -3, -1, 0, 5, 6, 8, 0, 2])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -701,6 +799,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: [-3, -1, 3, 5], even: [0, 2, 6, 8] }
      * ```
      *
+     * ---
+     *
      * @returns A new {@link AggregatedIterator} containing only the unique elements.
      */
     public unique(): AggregatedIterator<K, T>
@@ -729,6 +829,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      *
      * 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")
@@ -737,6 +840,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 4, even: 4 }
      * ```
      *
+     * ---
+     *
      * @returns A new {@link ReducedIterator} containing the number of elements for each group.
      */
     public count(): ReducedIterator<K, number>
@@ -763,6 +868,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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 SmartIterator<number>([-3, 0, 2, -1, 3])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd");
@@ -773,6 +881,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * };
      * ```
      *
+     * ---
+     *
      * @param iteratee The function to execute for each element of the iterator.
      */
     public forEach(iteratee: KeyedIteratee<K, T>): void
@@ -798,6 +908,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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")
@@ -807,6 +920,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(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.
@@ -841,6 +956,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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([-3, Symbol(), "A", { }, null, [1 , 2, 3], false])
      *     .groupBy((value) => typeof value)
@@ -849,6 +967,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(keys.toArray()); // ["number", "symbol", "string", "object", "boolean"]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing all the keys of the iterator.
      */
     public keys(): SmartIterator<K>
@@ -880,6 +1000,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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, 0, 2, -1, 3])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -888,6 +1011,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(entries.toArray()); // [["odd", -3], ["even", 0], ["even", 2], ["odd", -1], ["odd", 3]]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing all the entries of the iterator.
      */
     public entries(): SmartIterator<[K, T]>
@@ -906,6 +1031,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * 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")
@@ -914,6 +1042,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(values.toArray()); // [-3, -1, 0, 2, 3, 5, 6, 8]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing all the values of the iterator.
      */
     public values(): SmartIterator<T>
@@ -932,6 +1062,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const aggregator = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd");
@@ -939,6 +1072,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(aggregator.toArray()); // [[-3, -1, 3, 5], [0, 2, 6, 8]]
      * ```
      *
+     * ---
+     *
      * @returns An {@link Array} of arrays containing the elements of the iterator.
      */
     public toArray(): T[][]
@@ -954,6 +1089,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const aggregator = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd");
@@ -961,6 +1099,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(aggregator.toMap()); // Map(2) { "odd" => [-3, -1, 3, 5], "even" => [0, 2, 6, 8] }
      * ```
      *
+     * ---
+     *
      * @returns A {@link Map} containing the elements of the iterator.
      */
     public toMap(): Map<K, T[]>
@@ -984,6 +1124,9 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const aggregator = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd");
@@ -991,6 +1134,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * console.log(aggregator.toObject()); // { odd: [-3, -1, 3, 5], even: [0, 2, 6, 8] }
      * ```
      *
+     * ---
+     *
      * @returns An {@link Object} containing the elements of the iterator.
      */
     public toObject(): Record<K, T[]>