@byloth/core 2.0.0 → 2.0.1

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

@@ -43,10 +43,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 +59,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 +77,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param iterator The iterator to aggregate.
      */
     public constructor(iterator: Iterator<[K, T]>);
@@ -76,6 +86,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 +101,8 @@ export default class AggregatedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param generatorFn The generator function to aggregate.
      */
     public constructor(generatorFn: GeneratorFunction<[K, T]>);
@@ -95,10 +110,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 +140,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 +151,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 +189,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 +200,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 +238,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 +249,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 +270,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 +281,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 +324,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 +335,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 +374,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 +385,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 +407,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 +418,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 +443,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 +454,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 +510,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 +525,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 +568,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 +579,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 +619,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 +630,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 +666,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 +677,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 +697,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 +708,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 +752,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 +763,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 +783,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 +794,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 +824,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 +835,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 +863,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 +876,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 +903,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 +915,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 +951,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 +962,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 +995,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 +1006,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 +1026,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 +1037,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 +1057,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 +1067,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 +1084,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 +1094,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 +1119,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 +1129,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[]>