@byloth/core 2.0.0 → 2.0.1

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

@@ -51,10 +51,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 +67,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 +83,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 +100,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 +109,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 +126,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 +135,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 +145,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 +154,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 +164,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 +173,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 +261,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 +271,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 +306,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 +316,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 +351,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 +361,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 +382,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 +392,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 +436,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 +446,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 +487,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 +497,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 +517,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 +527,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 +574,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 +584,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 +631,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 +641,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 +687,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 +698,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 +739,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 +749,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 +772,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 +782,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 +822,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 +835,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 +855,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 +865,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 +895,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 +905,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 +929,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 +940,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 +967,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 +984,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 +1001,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 +1022,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 +1042,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 +1072,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 +1097,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 +1107,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 +1131,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 +1144,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[]>