@byloth/core 2.0.0 → 2.0.2

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

@@ -26,6 +26,9 @@ import type {
  * This allows to chain multiple transformations without
  * the need to iterate over the elements multiple times.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const result = new SmartAsyncIterator<number>(["-5", "-4", "-3", "-2", "-1", "0", "1", "2", "3", "4", "5"])
  *     .map((value) => Number(value))
@@ -37,6 +40,8 @@ import type {
  * console.log(await 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 passed to the `next` method. Default is `undefined`.
@@ -51,10 +56,15 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<string>(["A", "B", "C"]);
      * ```
      *
+     * ---
+     *
      * @param iterable The iterable object to wrap.
      */
     public constructor(iterable: Iterable<T>);
@@ -62,10 +72,15 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>([1, 2, 3, 4, 5]);
      * ```
      *
+     * ---
+     *
      * @param iterable The asynchronous iterable object to wrap.
      */
     public constructor(iterable: AsyncIterable<T>);
@@ -73,6 +88,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number, void, number>({
      *     _sum: 0, _count: 0,
@@ -87,6 +105,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * })
      * ```
      *
+     * ---
+     *
      * @param iterator The iterator object to wrap.
      */
     public constructor(iterator: Iterator<T, R, N>);
@@ -94,6 +114,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number, void, number>({
      *     _sum: 0, _count: 0,
@@ -108,6 +131,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * })
      * ```
      *
+     * ---
+     *
      * @param iterator The asynchronous iterator object to wrap.
      */
     public constructor(iterator: AsyncIterator<T, R, N>);
@@ -115,6 +140,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>(function* ()
      * {
@@ -122,6 +150,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * });
      * ```
      *
+     * ---
+     *
      * @param generatorFn The generator function to wrap.
      */
     public constructor(generatorFn: GeneratorFunction<T, R, N>);
@@ -129,6 +159,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>(async function* ()
      * {
@@ -136,6 +169,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * });
      * ```
      *
+     * ---
+     *
      * @param generatorFn The asynchronous generator function to wrap.
      */
     public constructor(generatorFn: AsyncGeneratorFunction<T, R, N>);
@@ -143,10 +178,15 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
     /**
      * Initializes a new instance of the {@link SmartAsyncIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator(values);
      * ```
      *
+     * ---
+     *
      * @param argument The synchronous or asynchronous iterable, iterator or generator function to wrap.
      */
     public constructor(argument: MaybeAsyncIteratorLike<T, R, N> | MaybeAsyncGeneratorFunction<T, R, N>);
@@ -226,6 +266,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * If the iterator is infinite and every element satisfies the condition, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = await iterator.every(async (value) => value < 0);
@@ -233,6 +276,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // false
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns
@@ -266,6 +311,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * If the iterator is infinite and no element satisfies the condition, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = await iterator.some(async (value) => value > 0);
@@ -273,6 +321,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // true
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns
@@ -306,6 +356,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.filter(async (value) => value < 0);
@@ -313,6 +366,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await result.toArray()); // [-2, -1]
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns A new {@link SmartAsyncIterator} containing only the elements that satisfy the condition.
@@ -332,6 +387,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number | string>([-2, "-1", "0", 1, "2"]);
      * const result = iterator.filter<number>(async (value) => typeof value === "number");
@@ -339,6 +397,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await 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.
@@ -381,6 +441,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.map(async (value) => Math.abs(value));
@@ -388,6 +451,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await 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.
@@ -427,6 +492,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * - 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 SmartAsyncIterator<number>([1, 2, 3, 4, 5]);
      * const result = await iterator.reduce(async (acc, value) => acc + value);
@@ -434,6 +502,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // 15
      * ```
      *
+     * ---
+     *
      * @param reducer The reducer function to apply to each element of the iterator.
      *
      * @returns A {@link Promise} that will resolve to the final result of the reduction.
@@ -452,6 +522,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>([1, 2, 3, 4, 5]);
      * const result = await iterator.reduce(async (acc, value) => acc + value, 10);
@@ -459,6 +532,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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.
@@ -504,6 +579,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number[]>([[-2, -1], 0, 1, 2, [3, 4, 5]]);
      * const result = iterator.flatMap(async (value) => value);
@@ -511,6 +589,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await 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.
@@ -556,6 +636,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.drop(3);
@@ -563,6 +646,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await result.toArray()); // [1, 2]
      * ```
      *
+     * ---
+     *
      * @param count The number of elements to drop.
      *
      * @returns A new {@link SmartAsyncIterator} containing the remaining elements.
@@ -607,6 +692,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = iterator.take(3);
@@ -615,6 +703,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await iterator.toArray()); // [1, 2]
      * ```
      *
+     * ---
+     *
      * @param limit The number of elements to take.
      *
      * @returns A new {@link SmartAsyncIterator} containing the taken elements.
@@ -654,6 +744,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * - 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 SmartAsyncIterator<number>([-2, -1, 0, 1, 2]);
      * const result = await iterator.find(async (value) => value > 0);
@@ -661,6 +754,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // 1
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns
@@ -682,6 +777,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * - 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 SmartAsyncIterator<number | string>([-2, "-1", "0", 1, "2"]);
      * const result = await iterator.find<number>(async (value) => typeof value === "number");
@@ -689,6 +787,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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.
@@ -727,6 +827,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<string>(["A", "M", "N", "Z"]);
      * const result = iterator.enumerate();
@@ -737,6 +840,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * }
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartAsyncIterator} containing the enumerated elements.
      */
     public enumerate(): SmartAsyncIterator<[number, T], R>
@@ -755,6 +860,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>([1, 1, 2, 3, 2, 3, 4, 5, 5, 4]);
      * const result = iterator.unique();
@@ -762,6 +870,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await result.toArray()); // [1, 2, 3, 4, 5]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartAsyncIterator} containing only the unique elements.
      */
     public unique(): SmartAsyncIterator<T, R>
@@ -790,6 +900,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>([1, 2, 3, 4, 5]);
      * const result = await iterator.count();
@@ -797,6 +910,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // 5
      * ```
      *
+     * ---
+     *
      * @returns A {@link Promise} that will resolve to the number of elements in the iterator.
      */
     public async count(): Promise<number>
@@ -819,6 +934,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>(["A", "M", "N", "Z"]);
      * await iterator.forEach(async (value, index) =>
@@ -827,6 +945,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * }
      * ```
      *
+     * ---
+     *
      * @param iteratee The function to apply to each element of the iterator.
      *
      * @returns A {@link Promise} that will resolve once the iteration is complete.
@@ -852,6 +972,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * Once the iterator is done, the method will return an object with the `done` property set to `true`.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator<number>([1, 2, 3, 4, 5]);
      *
@@ -866,6 +989,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // { done: true, value: undefined }
      * ```
      *
+     * ---
+     *
      * @param values The value to pass to the next element, if required.
      *
      * @returns
@@ -881,6 +1006,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>({
      *     _index: 0,
@@ -899,6 +1027,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * }
      * ```
      *
+     * ---
+     *
      * @param value The final value of the iterator.
      *
      * @returns A {@link Promise} that will resolve to the final result of the iterator.
@@ -917,6 +1047,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>({
      *     _index: 0,
@@ -944,6 +1077,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * }
      * ```
      *
+     * ---
+     *
      * @param error The error to throw into the iterator.
      *
      * @returns A {@link Promise} that will resolve to the final result of the iterator.
@@ -967,6 +1102,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * 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 SmartAsyncIterator<number>([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
      * const result = iterator.groupBy<string>(async (value) => value % 2 === 0 ? "even" : "odd");
@@ -974,6 +1112,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(await 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.
@@ -996,6 +1136,9 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const iterator = new SmartAsyncIterator(async function* ()
      * {
@@ -1006,6 +1149,8 @@ export default class SmartAsyncIterator<T, R = void, N = undefined> implements A
      * console.log(result); // [0, 1, 2, 3, 4]
      * ```
      *
+     * ---
+     *
      * @returns A {@link Promise} that will resolve to an array containing all elements of the iterator.
      */
     public toArray(): Promise<T[]>