@byloth/core 2.0.0 → 2.0.2

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

@@ -17,6 +17,9 @@ import type { GeneratorFunction, Iteratee, TypeGuardPredicate, Reducer, Iterator
  * This allows to chain multiple transformations without
  * the need to iterate over the elements multiple times.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const result = new SmartIterator<number>(["-5", "-4", "-3", "-2", "-1", "0", "1", "2", "3", "4", "5"])
  *     .map(Number)
@@ -28,6 +31,8 @@ import type { GeneratorFunction, Iteratee, TypeGuardPredicate, Reducer, Iterator
  * console.log(result); // 31
  * ```
  *
+ * ---
+ *
  * @template T The type of elements in the iterator.
  * @template R The type of the final result of the iterator. Default is `void`.
  * @template N The type of the argument required by the `next` method. Default is `undefined`.
@@ -42,10 +47,15 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     /**
      * Initializes a new instance of the {@link SmartIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<string>(["A", "B", "C"]);
      * ```
      *
+     * ---
+     *
      * @param iterable The iterable object to wrap.
      */
     public constructor(iterable: Iterable<T, R, N>);
@@ -53,6 +63,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     /**
      * Initializes a new instance of the {@link SmartIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number, void, number>({
      *     _sum: 0, _count: 0,
@@ -67,6 +80,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * })
      * ```
      *
+     * ---
+     *
      * @param iterator The iterator object to wrap.
      */
     public constructor(iterator: Iterator<T, R, N>);
@@ -74,6 +89,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     /**
      * Initializes a new instance of the {@link SmartIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>(function* ()
      * {
@@ -81,6 +99,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * });
      * ```
      *
+     * ---
+     *
      * @param generatorFn The generator function to wrap.
      */
     public constructor(generatorFn: GeneratorFunction<T, R, N>);
@@ -88,10 +108,15 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
     /**
      * Initializes a new instance of the {@link SmartIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator(values);
      * ```
      *
+     * ---
+     *
      * @param argument The iterable, iterator or generator function to wrap.
      */
     public constructor(argument: IteratorLike<T, R, N> | GeneratorFunction<T, R, N>);
@@ -124,6 +149,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * If the iterator is infinite and every element satisfies the condition, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.every((value) => value < 0);
@@ -131,6 +159,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // false
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns `true` if all elements satisfy the condition, `false` otherwise.
@@ -163,6 +193,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * If the iterator is infinite and no element satisfies the condition, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.some((value) => value < 0);
@@ -170,6 +203,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // true
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns `true` if any element satisfies the condition, `false` otherwise.
@@ -202,6 +237,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.filter((value) => value < 0);
@@ -209,6 +247,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [-2, -1]
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns A new {@link SmartIterator} containing only the elements that satisfy the condition.
@@ -228,6 +268,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number | string>([-2, "-1", "0", 1, "2"]);
      * const result = iterator.filter<number>((value) => typeof value === "number");
@@ -235,6 +278,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [-2, 1]
      * ```
      *
+     * ---
+     *
      * @template S
      * The type of the elements that satisfy the condition.  
      * This allows the type-system to infer the correct type of the new iterator.
@@ -277,6 +322,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.map((value) => Math.abs(value));
@@ -284,6 +332,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [2, 1, 0, 1, 2]
      * ```
      *
+     * ---
+     *
      * @template V The type of the elements after the transformation.
      *
      * @param iteratee The transformation function to apply to each element of the iterator.
@@ -323,6 +373,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * - If an empty iterator is provided, a {@link ValueException} will be thrown.
      * - If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
      * const result = iterator.reduce((acc, value) => acc + value);
@@ -330,6 +383,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // 15
      * ```
      *
+     * ---
+     *
      * @param reducer The reducer function to apply to each element of the iterator.
      *
      * @returns The final result of the reduction.
@@ -348,6 +403,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
      * const result = iterator.reduce((acc, value) => acc + value, 10);
@@ -355,6 +413,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // 25
      * ```
      *
+     * ---
+     *
      * @template A The type of the accumulator value which will also be the type of the final result of the reduction.
      *
      * @param reducer The reducer function to apply to each element of the iterator.
@@ -400,6 +460,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number[]>([[-2, -1], 0, 1, 2, [3, 4, 5]]);
      * const result = iterator.flatMap((value) => value);
@@ -407,6 +470,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [-2, -1, 0, 1, 2, 3, 4, 5]
      * ```
      *
+     * ---
+     *
      * @template V The type of the elements after the transformation.
      *
      * @param iteratee The transformation function to apply to each element of the iterator.
@@ -452,6 +517,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * Only the dropped elements will be consumed in the process.  
      * The rest of the iterator will be consumed only once the new one is.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.drop(3);
@@ -459,6 +527,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [1, 2]
      * ```
      *
+     * ---
+     *
      * @param count The number of elements to drop.
      *
      * @returns A new {@link SmartIterator} containing the remaining elements.
@@ -503,6 +573,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * Only the taken elements will be consumed from the original iterator.  
      * The rest of the original iterator will be available for further consumption.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.take(3);
@@ -511,6 +584,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(iterator.toArray()); // [1, 2]
      * ```
      *
+     * ---
+     *
      * @param limit The number of elements to take.
      *
      * @returns A new {@link SmartIterator} containing the taken elements.
@@ -550,6 +625,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * - If no element satisfies the condition, `undefined` will be returned once the entire iterator is consumed.
      * - If the iterator is infinite and no element satisfies the condition, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.find((value) => value > 0);
@@ -557,6 +635,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // 1
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns The first element that satisfies the condition, `undefined` otherwise.
@@ -577,6 +657,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * - If no element satisfies the condition, `undefined` will be returned once the entire iterator is consumed.
      * - If the iterator is infinite and no element satisfies the condition, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number | string>([-2, "-1", "0", 1, "2"]);
      * const result = iterator.find<number>((value) => typeof value === "number");
@@ -584,6 +667,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // -2
      * ```
      *
+     * ---
+     *
      * @template S
      * The type of the element that satisfies the condition.  
      * This allows the type-system to infer the correct type of the result.
@@ -621,6 +706,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<string>(["A", "M", "N", "Z"]);
      * const result = iterator.enumerate();
@@ -628,6 +716,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [[0, "A"], [1, "M"], [2, "N"], [3, "Z"]]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing the enumerated elements.
      */
     public enumerate(): SmartIterator<[number, T], R>
@@ -646,6 +736,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([1, 1, 2, 3, 2, 3, 4, 5, 5, 4]);
      * const result = iterator.unique();
@@ -653,6 +746,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toArray()); // [1, 2, 3, 4, 5]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing only the unique elements.
      */
     public unique(): SmartIterator<T, R>
@@ -680,6 +775,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
      * const result = iterator.count();
@@ -687,6 +785,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // 5
      * ```
      *
+     * ---
+     *
      * @returns The number of elements in the iterator.
      */
     public count(): number
@@ -709,6 +809,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This method will consume the entire iterator in the process.  
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>(["A", "M", "N", "Z"]);
      * iterator.forEach((value, index) =>
@@ -717,6 +820,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * }
      * ```
      *
+     * ---
+     *
      * @param iteratee The function to apply to each element of the iterator.
      */
     public forEach(iteratee: Iteratee<T>): void
@@ -740,6 +845,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * Once the iterator is done, the method will return an object with the `done` property set to `true`.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5]);
      *
@@ -754,6 +862,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // { done: true, value: undefined }
      * ```
      *
+     * ---
+     *
      * @param values The value to pass to the next element, if required.
      *
      * @returns The result of the iteration, containing the value of the operation.
@@ -768,6 +878,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * free the resources and perform any cleanup operation.  
      * It may also be used to signal the end or to compute a specific final result of the iteration process.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>({
      *     _index: 0,
@@ -786,6 +899,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * }
      * ```
      *
+     * ---
+     *
      * @param value The final value of the iterator.
      *
      * @returns The result of the iterator.
@@ -802,6 +917,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * free the resources and perform any cleanup operation.  
      * It may also be used to signal that an error occurred during the iteration process or to handle it.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>({
      *     _index: 0,
@@ -829,6 +947,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * }
      * ```
      *
+     * ---
+     *
      * @param error The error to throw into the iterator.
      *
      * @returns The final result of the iterator.
@@ -852,6 +972,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * This means that the original iterator won't be consumed until the
      * the new one is and that consuming one of them will consume the other as well.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator<number>([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
      * const result = iterator.groupBy<string>((value) => value % 2 === 0 ? "even" : "odd");
@@ -859,6 +982,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result.toObject()); // { odd: [1, 3, 5, 7, 9], even: [2, 4, 6, 8, 10] }
      * ```
      *
+     * ---
+     *
      * @template K The type of the keys used to group the elements.
      *
      * @param iteratee The key function to apply to each element of the iterator.
@@ -881,6 +1006,9 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartIterator(function* ()
      * {
@@ -891,6 +1019,8 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      * console.log(result); // [0, 1, 2, 3, 4]
      * ```
      *
+     * ---
+     *
      * @returns The {@link Array} containing all elements of the iterator.
      */
     public toArray(): T[]