@byloth/core 2.0.0 → 2.0.1

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

@@ -42,10 +42,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 +58,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 +75,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 +84,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 +94,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 +103,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 +144,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 +154,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 +188,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 +198,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 +232,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 +242,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 +263,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 +273,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 +317,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 +327,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 +368,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 +378,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 +398,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 +408,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 +455,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 +465,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 +512,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 +522,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 +568,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 +579,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 +620,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 +630,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 +652,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 +662,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 +701,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 +711,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 +731,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 +741,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 +770,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 +780,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 +804,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 +815,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 +840,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 +857,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 +873,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 +894,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 +912,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 +942,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 +967,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 +977,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 +1001,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 +1014,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[]