@byloth/core 2.0.0 → 2.0.2

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

@@ -24,6 +24,9 @@ import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardPredicate } from "./typ
  * This is particularly useful when you have group elements and
  * need perform specific operations on the reduced elements.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
  *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -32,6 +35,8 @@ import type { KeyedIteratee, KeyedReducer, KeyedTypeGuardPredicate } from "./typ
  * console.log(results.toObject()); // { odd: 4, even: 4 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to group the elements.
  * @template T The type of the elements in the iterator.
  */
@@ -45,10 +50,15 @@ export default class ReducedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link ReducedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const results = new ReducedIterator<string, number>([["A", 1], ["B", 2], ["C", 4]]);
      * ```
      *
+     * ---
+     *
      * @param iterable A reduced iterable object.
      */
     public constructor(iterable: Iterable<[K, T]>);
@@ -56,6 +66,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link ReducedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const results = new ReducedIterator<string, number>({
      *     _index: 0,
@@ -69,6 +82,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param iterator An reduced iterator object.
      */
     public constructor(iterator: Iterator<[K, T]>);
@@ -76,6 +91,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link ReducedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * import { range, Random } from "@byloth/core";
      *
@@ -88,6 +106,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param generatorFn A generator function that produces the reduced elements.
      */
     public constructor(generatorFn: GeneratorFunction<[K, T]>);
@@ -95,10 +115,15 @@ export default class ReducedIterator<K extends PropertyKey, T>
     /**
      * Initializes a new instance of the {@link ReducedIterator} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const results = new ReducedIterator(reducedValues);
      * ```
      *
+     * ---
+     *
      * @param argument An iterable, iterator or generator function that produces the reduced elements.
      */
     public constructor(argument: Iterable<[K, T]> | Iterator<[K, T]> | GeneratorFunction<[K, T]>);
@@ -120,6 +145,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite and every element satisfies the condition, 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")
@@ -129,6 +157,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results); // true
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns `true` if all elements satisfy the condition, `false` otherwise.
@@ -156,6 +186,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite and no element satisfies the condition, 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")
@@ -165,6 +198,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results); // true
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns `true` if any element satisfies the condition, `false` otherwise.
@@ -192,6 +227,9 @@ export default class ReducedIterator<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")
@@ -201,6 +239,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 4, even: 16 }
      * ```
      *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns A new {@link ReducedIterator} containing only the elements that satisfy the condition.
@@ -220,6 +260,9 @@ export default class ReducedIterator<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) => Number(value) % 2 === 0 ? "even" : "odd")
@@ -229,6 +272,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 4 }
      * ```
      *
+     * ---
+     *
      * @template S
      * The type of the elements that satisfy the condition.  
      * This allows the type-system to infer the correct type of the iterator.
@@ -266,6 +311,9 @@ export default class ReducedIterator<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")
@@ -275,6 +323,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { odd: 8, even: 32 }
      * ```
      *
+     * ---
+     *
      * @template V The type of the elements after the transformation.
      *
      * @param iteratee The transformation function to apply to each element of the iterator.
@@ -308,6 +358,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * - 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 result = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -317,6 +370,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(result); // 20
      * ```
      *
+     * ---
+     *
      * @param reducer The reducer function to apply to the elements of the iterator.
      *
      * @returns The final value after reducing all the elements of the iterator.
@@ -335,6 +390,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const result = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -344,6 +402,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(result); // { value: 20 }
      * ```
      *
+     * ---
+     *
      * @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 the elements of the iterator.
@@ -388,6 +448,9 @@ export default class ReducedIterator<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")
@@ -397,6 +460,8 @@ export default class ReducedIterator<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.
@@ -437,6 +502,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * Only the dropped elements will be consumed in the process.  
      * The rest of the iterator will be consumed once the new iterator is.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -445,7 +513,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * console.log(results.toObject()); // { even: [0, 2, 6, 8] }
      * ```
-     * 
+     *
+     * ---
+     *
      * @param count The number of elements to drop.
      *
      * @returns A new {@link ReducedIterator} containing the remaining elements.
@@ -478,6 +548,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * Only the taken elements will be consumed from the original reduced iterator.  
      * The rest of the original reduced iterator will be available for further consumption.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -489,11 +562,13 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(reduced.toObject()); // { even: [0, 2, 6, 8] }
      * ```
      *
-     * @param count The number of elements to take.
+     * ---
+     *
+     * @param limit The number of elements to take.
      *
      * @returns A new {@link ReducedIterator} containing the taken elements.
      */
-    public take(count: number): ReducedIterator<K, T>
+    public take(limit: number): ReducedIterator<K, T>
     {
         const elements = this._elements.enumerate();
 
@@ -501,7 +576,7 @@ export default class ReducedIterator<K extends PropertyKey, T>
         {
             for (const [index, [key, element]] of elements)
             {
-                if (index >= count) { break; }
+                if (index >= limit) { break; }
                 yield [key, element];
             }
         });
@@ -521,14 +596,20 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * - 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 results = new SmartIterator<number>([-3, -3, -1, 0, 1, 2, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
      *     .reduce((key, accumulator, value) => accumulator + value)
      *     .find((key, value) => value > 0);
-     * 
+     *
      * console.log(results); // 16
-     * 
+     * ```
+     *
+     * ---
+     *
      * @param predicate The condition to check for each element of the iterator.
      *
      * @returns The first element that satisfies the condition, `undefined` otherwise.
@@ -549,13 +630,19 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * - 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 results = new SmartIterator<number | string>(["-3", -3, "-1", 0, 1, 2, "5", 6, 8])
      *     .groupBy((value) => Number(value) % 2 === 0 ? "even" : "odd")
      *     .reduce((key, accumulator, value) => accumulator + value)
      *     .find<number>((key, value) => typeof value === "number");
-     * 
+     *
      * console.log(results); // 16
+     * ```
+     *
+     * ---
      *
      * @template S
      * The type of the elements that satisfy the condition.  
@@ -589,6 +676,9 @@ export default class ReducedIterator<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 ReducedIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -598,6 +688,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // [[0, 4], [1, 16]]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link ReducedIterator} object containing the enumerated elements.
      */
     public enumerate(): ReducedIterator<K, [number, T]>
@@ -616,6 +708,9 @@ export default class ReducedIterator<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 ReducedIterator<number>([-3, -1, 0, 2, 3, 6, -3, -1, 1, 5, 6, 8, 7, 2])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -650,6 +745,9 @@ export default class ReducedIterator<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")
@@ -659,6 +757,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results); // 2
      * ```
      *
+     * ---
+     *
      * @returns The number of elements in the iterator.
      */
     public count(): number
@@ -677,17 +777,22 @@ export default class ReducedIterator<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 reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
      *     .reduce((key, accumulator, value) => accumulator + value);
-     * 
+     *
      * reduced.forEach((key, value, index) =>
      * {
      *     console.log(`#${index} - ${key}: ${value}`); // "#0 - odd: 4", "#1 - even: 16"
      * });
      * ```
      *
+     * ---
+     *
      * @param iteratee The function to apply to each element of the reduced iterator.
      */
     public forEach(iteratee: KeyedIteratee<K, T>): void
@@ -709,6 +814,9 @@ export default class ReducedIterator<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")
@@ -718,6 +826,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(results.toObject()); // { positive: 4, negative: -12 }
      * ```
      *
+     * ---
+     *
      * @template J The type of the new keys used to group the elements.
      *
      * @param iteratee The function to determine the new key of each element of the iterator.
@@ -748,6 +858,9 @@ export default class ReducedIterator<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<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -757,6 +870,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(keys.toArray()); // ["odd", "even"]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing all the keys of the iterator.
      */
     public keys(): SmartIterator<K>
@@ -784,6 +899,9 @@ export default class ReducedIterator<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, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -793,6 +911,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(entries.toArray()); // [["odd", 4], ["even", 16]]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing all the entries of the iterator.
      */
     public entries(): SmartIterator<[K, T]>
@@ -811,6 +931,9 @@ export default class ReducedIterator<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")
@@ -820,6 +943,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(values.toArray()); // [4, 16]
      * ```
      *
+     * ---
+     *
      * @returns A new {@link SmartIterator} containing all the values of the iterator.
      */
     public values(): SmartIterator<T>
@@ -841,6 +966,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -849,6 +977,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(reduced.toArray()); // [4, 16]
      * ```
      *
+     * ---
+     *
      * @returns The {@link Array} containing all elements of the iterator.
      */
     public toArray(): T[]
@@ -862,6 +992,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -870,6 +1003,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(reduced.toMap()); // Map(2) { "odd" => 4, "even" => 16 }
      * ```
      *
+     * ---
+     *
      * @returns The {@link Map} containing all elements of the iterator.
      */
     public toMap(): Map<K, T>
@@ -883,6 +1018,9 @@ export default class ReducedIterator<K extends PropertyKey, T>
      *
      * If the iterator is infinite, the method will never return.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const reduced = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
      *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
@@ -891,6 +1029,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * console.log(reduced.toObject()); // { odd: 4, even: 16 }
      * ```
      *
+     * ---
+     *
      * @returns The {@link Object} containing all elements of the iterator.
      */
     public toObject(): Record<K, T>

package/src/models/aggregators/types.ts

@@ -5,6 +5,9 @@ import type { MaybePromise } from "../promises/types.js";
  * with the addition of a `key` parameter, compared to the JavaScript's standard ones.  
  * It can be used to transform the elements of an aggregated iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: KeyedIteratee<string, number, string> = (key: string, value: number) => `${value}`;
  * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
@@ -14,6 +17,8 @@ import type { MaybePromise } from "../promises/types.js";
  * console.log(results.toObject()); // { odd: ["-3", "-1", "3", "5"], even: ["0", "2", "6", "8"] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
@@ -25,6 +30,9 @@ export type KeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value:
  * function with the addition of a `key` parameter.  
  * It can be used to transform the elements of an aggregated iterable asynchronously.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: AsyncKeyedIteratee<string, number, string> = async (key: string, value: number) => `${value}`;
  * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
@@ -34,6 +42,8 @@ export type KeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value:
  * console.log(await results.toObject()); // { odd: ["-3", "-1", "3", "5"], even: ["0", "2", "6", "8"] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
@@ -45,6 +55,9 @@ export type AsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, va
  * with the addition of a `key` parameter that can be either synchronous or asynchronous.  
  * It can be used to transform the elements of an aggregated iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: AsyncKeyedIteratee<string, number, string> = [async] (key: string, value: number) => `${value}`;
  * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
@@ -54,6 +67,8 @@ export type AsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, va
  * console.log(await results.toObject()); // { odd: ["-3", "-1", "3", "5"], even: ["0", "2", "6", "8"] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
@@ -69,6 +84,9 @@ export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> =
  * It can be used to filter the elements of an aggregated iterable
  * while allowing the type-system to infer them correctly.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const predicate: KeyedTypeGuardPredicate<string, number | string, string> =
  *     (key: string, value: number | string): value is string => typeof value === "string";
@@ -80,6 +98,8 @@ export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> =
  * console.log(results.toObject()); // { odd: ["0", "5", "8"], even: [] }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template R
@@ -100,6 +120,9 @@ export type KeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
  * An utility type that represents a reducer-like function.  
  * It can be used to reduce the elements of an aggregated iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: KeyedReducer<string, number, number> =
  *     (key: string, accumulator: number, value: number) => accumulator + value;
@@ -111,6 +134,8 @@ export type KeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
  * console.log(results.toObject()); // { odd: 4, even: 16 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
@@ -121,6 +146,9 @@ export type KeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A,
  * An utility type that represents an asynchronous reducer-like function.  
  * It can be used to reduce the elements of an aggregated iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: AsyncKeyedReducer<string, number, number> =
  *     async (key: string, accumulator: number, value: number) => accumulator + value;
@@ -132,6 +160,8 @@ export type KeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A,
  * console.log(await results.toObject()); // { odd: 4, even: 16 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
@@ -143,6 +173,9 @@ export type AsyncKeyedReducer<K extends PropertyKey, T, A> =
  * An utility type that represents a reducer-like function that can be either synchronous or asynchronous.  
  * It can be used to reduce the elements of an aggregated iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: MaybeAsyncKeyedReducer<string, number, number> =
  *     [async] (key: string, accumulator: number, value: number) => accumulator + value;
@@ -154,6 +187,8 @@ export type AsyncKeyedReducer<K extends PropertyKey, T, A> =
  * console.log(await results.toObject()); // { odd: 4, even: 16 }
  * ```
  *
+ * ---
+ *
  * @template K The type of the key used to aggregate elements in the iterable.
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.

package/src/models/callbacks/callable-object.ts

@@ -8,6 +8,9 @@ const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R =
 /**
  * An abstract class that can be used to implement callable objects.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * class ActivableCallback extends CallableObject<(evt: PointerEvent) => void>
  * {
@@ -25,6 +28,8 @@ const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R =
  * window.addEventListener("pointerup", () => { callback.enabled = false; });
  * ```
  *
+ * ---
+ *
  * @template T
  * The type signature of the callback function.  
  * It must be a function. Default is `(...args: any[]) => any`.
@@ -49,6 +54,8 @@ export default abstract class CallableObject<T extends Callback<any[], any> = ()
      * The method that will be called when the object is invoked.  
      * It must be implemented by the derived classes.
      *
+     * ---
+     *
      * @param args The arguments that have been passed to the object.
      *
      * @returns The return value of the method.