@byloth/core 2.0.0-rc.8 → 2.0.0

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,17 +2,131 @@ 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.
+     *
+     * ```ts
+     * const publisher = new Publisher();
+     * ```
+     */
     public constructor()
     {
         this._subscribers = new Map();
     }
 
-    public subscribe<K extends keyof T, S extends T[K]>(event: K, subscriber: S): () => void
+    /**
+     * Unsubscribes all the subscribers from all the events.
+     *
+     * ```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.
+     *
+     * ```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.
+     *
+     * ```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 +146,34 @@ export default class Publisher<T extends { [K in keyof T]: Callback<any[], any>
         };
     }
 
-    public publish<K extends keyof T, A extends Parameters<T[K]>, R extends ReturnType<T[K]>>(event: K, ...args: A): R[]
+    /**
+     * Unsubscribes a subscriber from an event.
+     *
+     * ```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 R[];
+        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";

package/src/models/callbacks/switchable-callback.ts

@@ -3,20 +3,83 @@ import { KeyException, NotImplementedException, RuntimeException } from "../exce
 import CallableObject from "./callable-object.js";
 import type { Callback } from "./types.js";
 
+/**
+ * A class representing a callback that can be switched between multiple implementations.
+ *
+ * It can be used to implement different behaviors for the same event handler, allowing
+ * it to respond to different states without incurring any overhead during execution.
+ *
+ * ```ts
+ * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>();
+ *
+ * onPointerMove.register("released", () => { [...] });
+ * onPointerMove.register("pressed", () => { [...] });
+ *
+ * window.addEventListener("pointerdown", () => { onPointerMove.switch("pressed"); });
+ * window.addEventListener("pointermove", onPointerMove);
+ * window.addEventListener("pointerup", () => { onPointerMove.switch("released"); });
+ * ```
+ *
+ * @template T The type signature of the callback. Default is `(...args: any[]) => any`.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export default class SwitchableCallback<T extends Callback<any[], any> = Callback> extends CallableObject<T>
 {
+    /**
+     * The currently selected implementation of the callback.
+     */
     protected _callback: T;
+
+    /**
+     * All the implementations that have been registered for the callback.
+     *
+     * The keys are the names of the implementations they were registered with.  
+     * The values are the implementations themselves.
+     */
     protected _callbacks: Map<string, T>;
 
+    /**
+     * A flag indicating whether the callback is enabled or not.
+     *
+     * This protected property is the only one that can be modified directly by the derived classes.  
+     * If you're looking for the public and readonly property, use
+     * the {@link SwitchableCallback.isEnabled} getter instead.
+     */
     protected _isEnabled: boolean;
+
+    /**
+     * A flag indicating whether the callback is enabled or not.
+     *
+     * It indicates whether the callback is currently able to execute the currently selected implementation.  
+     * If it's disabled, the callback will be invoked without executing anything.
+     */
     public get isEnabled(): boolean { return this._isEnabled; }
 
+    /**
+     * The key that is associated with the currently selected implementation.
+     *
+     * This protected property is the only one that can be modified directly by the derived classes.  
+     * If you're looking for the public and readonly property, use the {@link SwitchableCallback.key} getter instead.
+     */
     protected _key: string;
-    public get key(): string { return this._key; }
 
-    public readonly invoke: (...args: Parameters<T>) => ReturnType<T>;
+    /**
+     * The key that is associated with the currently selected implementation.
+     */
+    public get key(): string { return this._key; }
 
+    /**
+     * The function that will be called by the extended class when the object is invoked as a function.
+     */
+    protected readonly _invoke: (...args: Parameters<T>) => ReturnType<T>;
+
+    /**
+     * Initializes a new instance of the {@link SwitchableCallback} class.
+     *
+     * ```ts
+     * const onPointerMove = new SwitchableCallback<(evt: PointerEvent) => void>();
+     * ```
+     */
     public constructor()
     {
         const _default = () =>
@@ -32,12 +95,24 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
         this._callback = ((_default) as unknown) as T;
         this._callbacks = new Map<string, T>();
 
-        this._isEnabled = false;
+        this._isEnabled = true;
         this._key = "";
 
-        this.invoke = (...args: Parameters<T>): ReturnType<T> => this._callback(...args);
+        this._invoke = (...args: Parameters<T>): ReturnType<T> => this._callback(...args);
     }
 
+    /**
+     * Enables the callback, allowing it to execute the currently selected implementation.
+     *
+     * Also note that:
+     * - If any implementation has been registered yet, a {@link KeyException} will be thrown.  
+     * - If the callback is already enabled, a {@link RuntimeException} will be thrown.
+     *
+     * ```ts
+     * window.addEventListener("pointerdown", () => { onPointerMove.enable(); });
+     * window.addEventListener("pointermove", onPointerMove);
+     * ```
+     */
     public enable(): void
     {
         if (!(this._key))
@@ -55,6 +130,17 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
         this._callback = this._callbacks.get(this._key)!;
         this._isEnabled = true;
     }
+
+    /**
+     * Disables the callback, allowing it to be invoked without executing any implementation.
+     *
+     * If the callback is already disabled, a {@link RuntimeException} will be thrown.
+     *
+     * ```ts
+     * window.addEventListener("pointermove", onPointerMove);
+     * window.addEventListener("pointerup", () => { onPointerMove.disable(); });
+     * ```
+     */
     public disable(): void
     {
         if (!(this._isEnabled))
@@ -67,6 +153,21 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
         this._isEnabled = false;
     }
 
+    /**
+     * Registers a new implementation for the callback.
+     *
+     * Also note that:
+     * - If the callback has no other implementation registered yet, this one will be selected as default.
+     * - If the key has already been used for another implementation, a {@link KeyException} will be thrown.
+     *
+     * ```ts
+     * onPointerMove.register("pressed", () => { [...] });
+     * onPointerMove.register("released", () => { [...] });
+     * ```
+     *
+     * @param key The key that will be associated with the implementation.
+     * @param callback The implementation to register.
+     */
     public register(key: string, callback: T): void
     {
         if (this._callbacks.size === 0)
@@ -81,8 +182,26 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
 
         this._callbacks.set(key, callback);
     }
+
+    /**
+     * Unregisters an implementation for the callback.
+     *
+     * Also note that:
+     * - If the key is the currently selected implementation, a {@link KeyException} will be thrown.
+     * - If the key has no associated implementation yet, a {@link KeyException} will be thrown.
+     *
+     * ```ts
+     * onPointerMove.unregister("released");
+     * ```
+     *
+     * @param key The key that is associated with the implementation to unregister.
+     */
     public unregister(key: string): void
     {
+        if (this._key === key)
+        {
+            throw new KeyException("Unable to unregister the currently selected callback.");
+        }
         if (!(this._callbacks.has(key)))
         {
             throw new KeyException(`The key '${key}' doesn't yet have any associated callback.`);
@@ -91,6 +210,19 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
         this._callbacks.delete(key);
     }
 
+    /**
+     * Switches the callback to the implementation associated with the given key.
+     *
+     * If the key has no associated implementation yet, a {@link KeyException} will be thrown.
+     *
+     * ```ts
+     * window.addEventListener("pointerdown", () => { onPointerMove.switch("pressed"); });
+     * window.addEventListener("pointermove", onPointerMove);
+     * window.addEventListener("pointerup", () => { onPointerMove.switch("released"); });
+     * ```
+     *
+     * @param key The key that is associated with the implementation to switch to.
+     */
     public switch(key: string): void
     {
         if (!(this._callbacks.has(key)))
@@ -99,6 +231,12 @@ export default class SwitchableCallback<T extends Callback<any[], any> = Callbac
         }
 
         this._key = key;
-        this._callback = this._callbacks.get(key)!;
+
+        if (this._isEnabled)
+        {
+            this._callback = this._callbacks.get(key)!;
+        }
     }
+
+    public override readonly [Symbol.toStringTag]: string = "SwitchableCallback";
 }

package/src/models/callbacks/types.ts

@@ -1 +1,17 @@
+/**
+ * A type that represents a generic function.
+ *
+ * It can be used to define the signature of a callback, a event handler or any other function.  
+ * It's simply a shorthand for the `(...args: A) => R` function signature.
+ *
+ * ```ts
+ * const callback: Callback<[PointerEvent]> = (evt: PointerEvent): void => { [...] };
+ * ```
+ *
+ * @template A
+ * The type of the arguments that the function accepts.  
+ * It must be an array of types, even if it's empty. Default is `[]`.
+ *
+ * @template R The return type of the function. Default is `void`.
+ */
 export type Callback<A extends unknown[] = [], R = void> = (...args: A) => R;