@byloth/core 2.0.0 → 2.0.1

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

@@ -45,10 +45,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 +61,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 +77,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param iterator An reduced iterator object.
      */
     public constructor(iterator: Iterator<[K, T]>);
@@ -76,6 +86,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 +101,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 +110,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 +140,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 +152,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 +181,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 +193,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 +222,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 +234,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 +255,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 +267,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 +306,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 +318,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 +353,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 +365,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 +385,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 +397,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 +443,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 +455,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 +497,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")
@@ -478,6 +541,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 +555,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 +569,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,6 +589,9 @@ 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")
@@ -549,6 +620,9 @@ 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")
@@ -589,6 +663,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 +675,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 +695,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 +732,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 +744,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,6 +764,9 @@ 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")
@@ -688,6 +778,8 @@ export default class ReducedIterator<K extends PropertyKey, T>
      * });
      * ```
      *
+     * ---
+     *
      * @param iteratee The function to apply to each element of the reduced iterator.
      */
     public forEach(iteratee: KeyedIteratee<K, T>): void
@@ -709,6 +801,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 +813,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 +845,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 +857,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 +886,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 +898,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 +918,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 +930,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 +953,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 +964,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 +979,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 +990,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 +1005,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 +1016,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/callbacks/publisher.ts

@@ -49,6 +49,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Initializes a new instance of the {@link Publisher} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const publisher = new Publisher();
      * ```
@@ -61,6 +64,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Unsubscribes all the subscribers from all the events.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * publisher.subscribe("player:spawn", (evt) => { [...] });
      * publisher.subscribe("player:move", (coords) => { [...] });
@@ -83,6 +89,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Publishes an event to all the subscribers.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * publisher.subscribe("player:move", (coords) => { [...] });
      * publisher.subscribe("player:move", ({ x, y }) => { [...] });
@@ -91,6 +100,8 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * publisher.publish("player:move", { x: 10, y: 20 });
      * ```
      *
+     * ---
+     *
      * @template K The key of the map containing the callback signature to publish.
      *
      * @param event The name of the event to publish.
@@ -110,6 +121,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Subscribes a new subscriber to an event.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * let unsubscribe: () => void;
      * publisher.subscribe("player:death", unsubscribe);
@@ -119,6 +133,8 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * });
      * ```
      *
+     * ---
+     *
      * @template K The key of the map containing the callback signature to subscribe.
      *
      * @param event The name of the event to subscribe to.
@@ -149,6 +165,9 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
     /**
      * Unsubscribes a subscriber from an event.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const onPlayerMove = ({ x, y }: Point) => { [...] };
      *
@@ -156,6 +175,8 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
      * publisher.subscribe("player:death", () => publisher.unsubscribe("player:move", onPlayerMove));
      * ```
      *
+     * ---
+     *
      * @template K The key of the map containing the callback signature to unsubscribe.
      *
      * @param event The name of the event to unsubscribe from.