@byloth/core 2.0.0-rc.9 → 2.0.1

package/src/models/aggregators/types.ts

@@ -1,19 +1,162 @@
-/* eslint-disable max-len */
-
 import type { MaybePromise } from "../promises/types.js";
 
+/**
+ * An utility type that represents an {@link https://en.wikipedia.org/wiki/Iteratee|iteratee}-like function
+ * 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.
+ *
+ * ```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])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .map(iteratee);
+ *
+ * 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`.
+ */
 export type KeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => R;
+
+/**
+ * An utility type that represents an asynchronous {@link https://en.wikipedia.org/wiki/Iteratee|iteratee}-like
+ * function with the addition of a `key` parameter.  
+ * It can be used to transform the elements of an aggregated iterable asynchronously.
+ *
+ * ```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])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .map(iteratee);
+ *
+ * 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`.
+ */
 export type AsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => Promise<R>;
-export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> = (key: K, value: T, index: number) => MaybePromise<R>;
 
-export type KeyedTypeGuardIteratee<K extends PropertyKey, T, R extends T> = (key: K, value: T, index: number) => value is R;
+/**
+ * An utility type that represents an {@link https://en.wikipedia.org/wiki/Iteratee|iteratee}-like function
+ * 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.
+ *
+ * ```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])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .map(iteratee);
+ *
+ * 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`.
+ */
+export type MaybeAsyncKeyedIteratee<K extends PropertyKey, T, R = void> =
+    (key: K, value: T, index: number) => MaybePromise<R>;
 
-// @ts-expect-error - This is an asyncronous type guard keyed-iteratee that guarantees the return value is a promise.
-export type AsyncKeyedTypeGuardIteratee<K extends PropertyKey, T, R extends T> = (key: K, value: T, index: number) => value is Promise<R>;
+/**
+ * An utility type that represents a {@link https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)|predicate}-like
+ * function with the addition of a `key` parameter, compared to the JavaScript's standard ones,
+ * which act as a
+ * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates|type guard}.  
+ * It can be used to filter the elements of an aggregated iterable
+ * while allowing the type-system to infer them correctly.
+ *
+ * ```ts
+ * const predicate: KeyedTypeGuardPredicate<string, number | string, string> =
+ *     (key: string, value: number | string): value is string => typeof value === "string";
+ *
+ * const results = new SmartIterator<number | string>([-3, -1, "0", 2, 3, "5", 6, "8"])
+ *     .groupBy((value) => Number(value) % 2 === 0 ? "even" : "odd")
+ *     .filter(predicate);
+ *
+ * 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
+ * The type of the return value of the predicate.  
+ * It must be a subtype of `T`. Default is `T`.
+ */
+export type KeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
+    (key: K, value: T, index: number) => value is R;
 
-// @ts-expect-error - This may be an asyncronous type guard keyed-iteratee that guarantees the return value may be a promise.
-export type MaybeAsyncKeyedTypeGuardIteratee<K extends PropertyKey, T, R extends T> = (key: K, value: T, index: number) => value is MaybePromise<R>;
+// These types need this Issue to be solved: https://github.com/microsoft/TypeScript/issues/37681
+//
+// export type AsyncKeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
+//     (key: K, value: T, index: number) => value is Promise<R>;
+// export type MaybeAsyncKeyedTypeGuardPredicate<K extends PropertyKey, T, R extends T> =
+//     (key: K, value: T, index: number) => value is MaybePromise<R>;
 
+/**
+ * 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.
+ *
+ * ```ts
+ * const sum: KeyedReducer<string, number, number> =
+ *     (key: string, accumulator: number, value: number) => accumulator + value;
+ *
+ * const results = new SmartIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .reduce(sum);
+ *
+ * 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.
+ */
 export type KeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => A;
-export type AsyncKeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => Promise<A>;
-export type MaybeAsyncKeyedReducer<K extends PropertyKey, T, A> = (key: K, accumulator: A, value: T, index: number) => MaybePromise<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.
+ *
+ * ```ts
+ * const sum: AsyncKeyedReducer<string, number, number> =
+ *     async (key: string, accumulator: number, value: number) => accumulator + value;
+ *
+ * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .reduce(sum);
+ *
+ * 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.
+ */
+export type AsyncKeyedReducer<K extends PropertyKey, T, A> =
+    (key: K, accumulator: A, value: T, index: number) => Promise<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.
+ *
+ * ```ts
+ * const sum: MaybeAsyncKeyedReducer<string, number, number> =
+ *     [async] (key: string, accumulator: number, value: number) => accumulator + value;
+ *
+ * const results = new SmartAsyncIterator<number>([-3, -1, 0, 2, 3, 5, 6, 8])
+ *     .groupBy((value) => value % 2 === 0 ? "even" : "odd")
+ *     .reduce(sum);
+ *
+ * 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.
+ */
+export type MaybeAsyncKeyedReducer<K extends PropertyKey, T, A> =
+    (key: K, accumulator: A, value: T, index: number) => MaybePromise<A>;

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

@@ -2,16 +2,42 @@
 
 import type { Callback } from "./types.js";
 
-export const SmartFunction = (Function as unknown) as
-    new<T extends Callback<any[], any> = () => void>(...args: string[]) =>
-        (...args: Parameters<T>) => ReturnType<T>;
+const SmartFunction = (Function as unknown) as new<A extends unknown[] = [], R = void>(...args: string[])
+    => (...args: A) => R;
 
+/**
+ * An abstract class that can be used to implement callable objects.
+ *
+ * ```ts
+ * class ActivableCallback extends CallableObject<(evt: PointerEvent) => void>
+ * {
+ *     public enabled = false;
+ *     protected _invoke(): void
+ *     {
+ *         if (this.enabled) { [...] }
+ *     }
+ * }
+ *
+ * const callback = new ActivableCallback();
+ *
+ * window.addEventListener("pointerdown", () => { callback.enabled = true; });
+ * window.addEventListener("pointermove", callback);
+ * 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`.
+ */
 export default abstract class CallableObject<T extends Callback<any[], any> = () => void>
-    extends SmartFunction<T>
+    extends SmartFunction<Parameters<T>, ReturnType<T>>
 {
+    /**
+     * Initializes a new instance of the {@link CallableObject} class.
+     */
     public constructor()
     {
-        super(`return this.invoke(...arguments);`);
+        super(`return this._invoke(...arguments);`);
 
         const self = this.bind(this);
         Object.setPrototypeOf(this, self);
@@ -19,5 +45,15 @@ export default abstract class CallableObject<T extends Callback<any[], any> = ()
         return self as this;
     }
 
-    public abstract invoke(...args: Parameters<T>): ReturnType<T>;
+    /**
+     * 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.
+     */
+    protected abstract _invoke(...args: Parameters<T>): ReturnType<T>;
+
+    public readonly [Symbol.toStringTag]: string = "CallableObject";
 }

package/src/models/callbacks/index.ts

@@ -1,5 +1,5 @@
-import CallableObject, { SmartFunction } from "./callable-object.js";
+import CallableObject from "./callable-object.js";
 import Publisher from "./publisher.js";
 import SwitchableCallback from "./switchable-callback.js";
 
-export { CallableObject, Publisher, SmartFunction, SwitchableCallback };
+export { CallableObject, Publisher, SwitchableCallback };

package/src/models/callbacks/publisher.ts

@@ -2,16 +2,146 @@ import { ReferenceException } from "../exceptions/index.js";
 
 import type { Callback } from "./types.js";
 
+/**
+ * A class implementing the
+ * {@link https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern|Publish-subscribe} pattern.
+ *
+ * It can be used to create a simple event system where objects can subscribe
+ * to events and receive notifications when the events are published.  
+ * It's a simple and efficient way to decouple the objects and make them communicate with each other.
+ *
+ * Using generics, it's also possible to define the type of the events and the callbacks that can be subscribed to them.
+ *
+ * ```ts
+ * interface EventsMap
+ * {
+ *     "player:spawn": (evt: SpawnEvent) => void;
+ *     "player:move": ({ x, y }: Point) => void;
+ *     "player:death": () => void;
+ * }
+ *
+ * const publisher = new Publisher<EventsMap>();
+ *
+ * let unsubscribe: () => void;
+ * publisher.subscribe("player:death", unsubscribe);
+ * publisher.subscribe("player:spawn", (evt) =>
+ * {
+ *     unsubscribe = publisher.subscribe("player:move", ({ x, y }) => { [...] });
+ * });
+ * ```
+ *
+ * @template T
+ * A map containing the names of the emittable events and the
+ * related callback signatures that can be subscribed to them.  
+ * Default is `Record<string, () => void>`.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default class Publisher<T extends { [K in keyof T]: Callback<any[], any> } = Record<string, Callback>>
 {
+    /**
+     * A map containing all the subscribers for each event.
+     *
+     * The keys are the names of the events they are subscribed to.  
+     * The values are the arrays of the subscribers themselves.
+     */
     protected _subscribers: Map<keyof T, Callback<unknown[], unknown>[]>;
 
+    /**
+     * Initializes a new instance of the {@link Publisher} class.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const publisher = new Publisher();
+     * ```
+     */
     public constructor()
     {
         this._subscribers = new Map();
     }
 
+    /**
+     * Unsubscribes all the subscribers from all the events.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("player:spawn", (evt) => { [...] });
+     * publisher.subscribe("player:move", (coords) => { [...] });
+     * publisher.subscribe("player:move", () => { [...] });
+     * publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * publisher.subscribe("player:death", () => { [...] });
+     *
+     * // All these subscribers are working fine...
+     *
+     * publisher.clear();
+     *
+     * // ... but now they're all gone!
+     * ```
+     */
+    public clear(): void
+    {
+        this._subscribers.clear();
+    }
+
+    /**
+     * Publishes an event to all the subscribers.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * publisher.subscribe("player:move", (coords) => { [...] });
+     * publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * publisher.subscribe("player:move", (evt) => { [...] });
+     *
+     * 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.
+     * @param args The arguments to pass to the subscribers.
+     *
+     * @returns An array containing the return values of all the subscribers.
+     */
+    public publish<K extends keyof T>(event: K, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
+    {
+        const subscribers = this._subscribers.get(event);
+        if (!(subscribers)) { return []; }
+
+        return subscribers.slice()
+            .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+    }
+
+    /**
+     * Subscribes a new subscriber to an event.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * let unsubscribe: () => void;
+     * publisher.subscribe("player:death", unsubscribe);
+     * publisher.subscribe("player:spawn", (evt) =>
+     * {
+     *     unsubscribe = publisher.subscribe("player:move", ({ x, y }) => { [...] });
+     * });
+     * ```
+     *
+     * ---
+     *
+     * @template K The key of the map containing the callback signature to subscribe.
+     *
+     * @param event The name of the event to subscribe to.
+     * @param subscriber The subscriber to add to the event.
+     *
+     * @returns A function that can be used to unsubscribe the subscriber.
+     */
     public subscribe<K extends keyof T>(event: K, subscriber: T[K]): () => void
     {
         if (!(this._subscribers.has(event))) { this._subscribers.set(event, []); }
@@ -32,13 +162,39 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
         };
     }
 
-    public publish<K extends keyof T>(event: K, ...args: Parameters<T[K]>): ReturnType<T[K]>[]
+    /**
+     * Unsubscribes a subscriber from an event.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const onPlayerMove = ({ x, y }: Point) => { [...] };
+     *
+     * publisher.subscribe("player:spawn", (evt) => publisher.subscribe("player:move", onPlayerMove));
+     * 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.
+     * @param subscriber The subscriber to remove from the event.
+     */
+    public unsubscribe<K extends keyof T>(event: K, subscriber: T[K]): void
     {
         const subscribers = this._subscribers.get(event);
-        if (!(subscribers)) { return []; }
+        if (!(subscribers)) { return; }
 
-        return subscribers.slice()
-            .map((subscriber) => subscriber(...args)) as ReturnType<T[K]>[];
+        const index = subscribers.indexOf(subscriber);
+        if (index < 0)
+        {
+            throw new ReferenceException("Unable to unsubscribe the required subscriber. " +
+                "The subscription was already unsubscribed or was never subscribed.");
+        }
+
+        subscribers.splice(index, 1);
     }
 
     public readonly [Symbol.toStringTag]: string = "Publisher";