@byloth/core 2.0.0 → 2.0.2

package/src/models/promises/deferred-promise.ts

@@ -12,6 +12,9 @@ import SmartPromise from "./smart-promise.js";
  * This is a change in the approach to promises: instead of defining how the promise will be resolved (or rejected),  
  * you define how to handle the resolution (or rejection) when it occurs.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const promise = new DeferredPromise<string, string[]>((value: string) => value.split(" "));
  *
@@ -19,6 +22,8 @@ import SmartPromise from "./smart-promise.js";
  * promise.resolve("Hello, World!");
  * ```
  *
+ * ---
+ *
  * @template T The type of value the promise expects to initially be resolved with. Default is `void`.
  * @template F
  * The type of value returned by the `onFulfilled` callback.  
@@ -58,10 +63,15 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
     /**
      * Initializes a new instance of the {@link DeferredPromise} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new DeferredPromise<string, string[]>((value: string) => value.split(" "));
      * ```
      *
+     * ---
+     *
      * @param onFulfilled The callback to execute once the promise is fulfilled.
      * @param onRejected The callback to execute once the promise is rejected.
      */
@@ -88,6 +98,9 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
     /**
      * Watches another promise and resolves or rejects this promise when the other one is settled.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new Promise<string>((resolve) => setTimeout(() => resolve("Hello, World!"), 1_000));
      * const deferred = new DeferredPromise<string, string[]>((value: string) => value.split(" "));
@@ -96,6 +109,8 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
      * deferred.watch(promise);
      * ```
      *
+     * ---
+     *
      * @param otherPromise The promise to watch.
      *
      * @returns The current instance of the {@link DeferredPromise} class.

package/src/models/promises/smart-promise.ts

@@ -7,6 +7,9 @@ import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types
  * The state can be either `pending`, `fulfilled` or `rejected` and is accessible through
  * the {@link SmartPromise.isPending}, {@link SmartPromise.isFulfilled} & {@link SmartPromise.isRejected} properties.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const promise = new SmartPromise<string>((resolve, reject) =>
  * {
@@ -22,6 +25,8 @@ import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types
  * console.log(promise.isFulfilled); // true
  * ```
  *
+ * ---
+ *
  * @template T The type of value the promise will eventually resolve to. Default is `void`.
  */
 export default class SmartPromise<T = void> implements Promise<T>
@@ -29,6 +34,9 @@ export default class SmartPromise<T = void> implements Promise<T>
     /**
      * Wraps a new {@link SmartPromise} object around an existing native {@link Promise} object.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const request = fetch("https://api.example.com/data");
      * const smartRequest = SmartPromise.FromPromise(request);
@@ -40,6 +48,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * console.log(smartRequest.isFulfilled); // true
      * ```
      *
+     * ---
+     *
      * @param promise The promise to wrap.
      *
      * @returns A new {@link SmartPromise} object that wraps the provided promise.
@@ -105,6 +115,9 @@ export default class SmartPromise<T = void> implements Promise<T>
     /**
      * Initializes a new instance of the {@link SmartPromise} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise<string>((resolve, reject) =>
      * {
@@ -112,6 +125,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * });
      * ```
      *
+     * ---
+     *
      * @param executor
      * The function responsible for eventually resolving or rejecting the promise.  
      * Similarly to the native {@link Promise} object, it's immediately executed after the promise is created.
@@ -144,6 +159,9 @@ export default class SmartPromise<T = void> implements Promise<T>
     /**
      * Creates a new {@link Promise} identical to the one wrapped by this instance, with a different reference.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise<string>((resolve, reject) =>
      * {
@@ -153,6 +171,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * console.log(await promise.then()); // "Hello, World!"
      * ```
      *
+     * ---
+     *
      * @returns A new {@link Promise} identical to the original one.
      */
     public then(onFulfilled?: null): Promise<T>;
@@ -163,6 +183,9 @@ export default class SmartPromise<T = void> implements Promise<T>
      * The previous result of the promise is passed as the argument to the callback.  
      * The callback's return value is considered the new promise's result instead.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise<string>((resolve, reject) =>
      * {
@@ -172,6 +195,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * promise.then((result) => console.log(result)); // "Hello, World!"
      * ```
      *
+     * ---
+     *
      * @template F The type of value the new promise will eventually resolve to. Default is `T`.
      *
      * @param onFulfilled The callback to execute once the promise is fulfilled.
@@ -193,6 +218,9 @@ export default class SmartPromise<T = void> implements Promise<T>
      * The rejection callback's return value is considered the new promise's result.
      * - If the rejection callback throws an error, the new promise is rejected with that error.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
@@ -203,6 +231,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * promise.then(() => console.log("OK!"), () => console.log("KO!")); // "OK!" or "KO!"
      * ```
      *
+     * ---
+     *
      * @template F The type of value the new promise will eventually resolve to. Default is `T`.
      * @template R The type of value the new promise will eventually resolve to. Default is `never`.
      *
@@ -223,6 +253,9 @@ export default class SmartPromise<T = void> implements Promise<T>
     /**
      * Creates a new {@link Promise} identical to the one wrapped by this instance, with a different reference.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
@@ -232,6 +265,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * promise.catch(); // Uncaught Error: An unknown error occurred.
      * ```
      *
+     * ---
+     *
      * @returns A new {@link Promise} identical to the original one.
      */
     public catch(onRejected?: null): Promise<T>;
@@ -245,6 +280,9 @@ export default class SmartPromise<T = void> implements Promise<T>
      * The callback's return value is considered the new promise's result.
      * - If the callback throws an error, the new promise is rejected with that error.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
@@ -254,6 +292,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      * promise.catch((reason) => console.error(reason)); // "Error: An unknown error occurred."
      * ```
      *
+     * ---
+     *
      * @template R The type of value the new promise will eventually resolve to. Default is `T`.
      *
      * @param onRejected The callback to execute once the promise is rejected.
@@ -269,6 +309,9 @@ export default class SmartPromise<T = void> implements Promise<T>
     /**
      * Attaches a callback that executes right after the promise is settled, regardless of the outcome.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new SmartPromise((resolve, reject) =>
      * {
@@ -283,6 +326,8 @@ export default class SmartPromise<T = void> implements Promise<T>
      *     .finally(() => console.log("Done!")); // Always logs "Done!".
      * ```
      *
+     * ---
+     *
      * @param onFinally The callback to execute when once promise is settled.
      *
      * @returns A new {@link Promise} that executes the callback once the promise is settled.

package/src/models/promises/timed-promise.ts

@@ -9,6 +9,9 @@ import type { MaybePromise, PromiseExecutor } from "./types.js";
  *
  * If the operation takes longer than the specified time, the promise is rejected with a {@link TimeoutException}.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const promise = new TimedPromise<string>((resolve, reject) =>
  * {
@@ -21,6 +24,8 @@ import type { MaybePromise, PromiseExecutor } from "./types.js";
  *     .catch((error) => console.error(error)); // TimeoutException: The operation has timed out.
  * ```
  *
+ * ---
+ *
  * @template T The type of value the promise will eventually resolve to. Default is `void`.
  */
 export default class TimedPromise<T = void> extends SmartPromise<T>
@@ -28,6 +33,9 @@ export default class TimedPromise<T = void> extends SmartPromise<T>
     /**
      * Initializes a new instance of the {@link TimedPromise} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const promise = new TimedPromise<string>((resolve, reject) =>
      * {
@@ -36,6 +44,8 @@ export default class TimedPromise<T = void> extends SmartPromise<T>
      * }, 5_000);
      * ```
      *
+     * ---
+     *
      * @param executor
      * The function responsible for eventually resolving or rejecting the promise.  
      * Similarly to the native {@link Promise} object, it's immediately executed after the promise is created.

package/src/models/promises/types.ts

@@ -2,6 +2,9 @@
  * An union type that represents a value that can be either a value or a promise of that value.  
  * This is useful when you want to handle both synchronous and asynchronous values in the same way.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * async function splitWords(value: MaybePromise<string>): Promise<string[]>
  * {
@@ -9,6 +12,8 @@
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the value.
  */
 export type MaybePromise<T> = T | PromiseLike<T>;
@@ -17,6 +22,9 @@ export type MaybePromise<T> = T | PromiseLike<T>;
  * An utility type that represents the callback that is executed when a promise is fulfilled.  
  * It's compatible with the `onFulfilled` parameter of the `then` method of the native {@link Promise} object.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const onFulfilled: FulfilledHandler<string, string[]> = (value) => value.split(" ");
  *
@@ -24,6 +32,8 @@ export type MaybePromise<T> = T | PromiseLike<T>;
  *     .then(onFulfilled);
  * ```
  *
+ * ---
+ *
  * @template T The type of value accepted by the function. Default is `void`.
  * @template R The type of value returned by the function. Default is `T`.
  */
@@ -33,6 +43,9 @@ export type FulfilledHandler<T = void, R = T> = (value: T) => MaybePromise<R>;
  * An utility type that represents the callback that is executed when a promise is rejected.  
  * It's compatible with the `onRejected` parameter of the `then`/`catch` methods of the native {@link Promise} object.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const onRejected: RejectedHandler<unknown, string> = (reason) => String(reason);
  *
@@ -40,6 +53,8 @@ export type FulfilledHandler<T = void, R = T> = (value: T) => MaybePromise<R>;
  *     .catch(onRejected);
  * ```
  *
+ * ---
+ *
  * @template E The type of value accepted by the function. Default is `unknown`.
  * @template R The type of value returned by the function. Default is `never`.
  */
@@ -49,12 +64,17 @@ export type RejectedHandler<E = unknown, R = never> = (reason: E) => MaybePromis
  * An utility type that represents a function that can be used to resolve a promise.  
  * It's compatible with the `resolve` parameter of the native {@link Promise} executor.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * let _resolve: PromiseResolver<string> = (result) => console.log(result);
  *
  * await new Promise<string>((resolve) => { _resolve = resolve; });
  * ```
  *
+ * ---
+ *
  * @template T The type of the value accepted by the function. Default is `void`.
  */
 export type PromiseResolver<T = void> = (result: MaybePromise<T>) => void;
@@ -63,12 +83,17 @@ export type PromiseResolver<T = void> = (result: MaybePromise<T>) => void;
  * An utility type that represents a function that can be used to reject a promise.  
  * It's compatible with the `reject` parameter of the native {@link Promise} executor.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * let _reject: PromiseRejecter<string> = (reason) => console.error(reason);
  *
  * await new Promise<string>((_, reject) => { _reject = reject; });
  * ```
  *
+ * ---
+ *
  * @template E The type of the value accepted by the function. Default is `unknown`.
  */
 export type PromiseRejecter<E = unknown> = (reason?: MaybePromise<E>) => void;
@@ -77,6 +102,9 @@ export type PromiseRejecter<E = unknown> = (reason?: MaybePromise<E>) => void;
  * An utility type that represents the function that will be executed by the promise.  
  * It's compatible with the `executor` parameter of the native {@link Promise} object.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const executor: PromiseExecutor<string> = (resolve, reject) =>
  * {
@@ -86,6 +114,8 @@ export type PromiseRejecter<E = unknown> = (reason?: MaybePromise<E>) => void;
  * await new Promise<string>(executor);
  * ```
  *
+ * ---
+ *
  * @template T The type of value accepted by the `resolve` function. Default is `void`.
  * @template E The type of value accepted by the `reject` function. Default is `unknown`.
  */

package/src/models/timers/clock.ts

@@ -22,6 +22,9 @@ interface ClockEventMap
  * It can be started, stopped and, when running, it ticks at a specific frame rate.  
  * It's possible to subscribe to these events to receive notifications when they occur.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const clock = new Clock();
  *
@@ -42,10 +45,15 @@ export default class Clock extends GameLoop
     /**
      * Initializes a new instance of the {@link Clock} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const clock = new Clock();
      * ```
      *
+     * ---
+     *
      * @param msIfNotBrowser
      * The interval in milliseconds at which the clock will tick if the environment is not a browser.  
      * `TimeUnit.Second` by default.
@@ -62,11 +70,16 @@ export default class Clock extends GameLoop
      *
      * If the clock is already running, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * clock.onStart(() => { [...] }); // This callback will be executed.
      * clock.start();
      * ```
      *
+     * ---
+     *
      * @param elapsedTime The elapsed time to set as default when the clock starts. Default is `0`.
      */
     public override start(elapsedTime = 0): void
@@ -85,6 +98,9 @@ export default class Clock extends GameLoop
      *
      * If the clock hasn't yet started, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * clock.onStop(() => { [...] }); // This callback will be executed.
      * clock.stop();
@@ -105,11 +121,16 @@ export default class Clock extends GameLoop
     /**
      * Subscribes to the `tick` event of the clock.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * clock.onTick((elapsedTime) => { [...] }); // This callback will be executed.
      * clock.start();
      * ```
      *
+     * ---
+     *
      * @param callback The callback that will be executed when the clock ticks.
      * @param tickStep
      * The minimum time in milliseconds that must pass from the previous execution of the callback to the next one.

package/src/models/timers/countdown.ts

@@ -24,6 +24,9 @@ interface CountdownEventMap
  * It can be started, stopped, when running it ticks at a specific frame rate and it expires when the time's up.  
  * It's possible to subscribe to these events to receive notifications when they occur.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const countdown = new Countdown(10_000);
  *
@@ -75,10 +78,15 @@ export default class Countdown extends GameLoop
     /**
      * Initializes a new instance of the {@link Countdown} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const countdown = new Countdown(10_000);
      * ```
      *
+     * ---
+     *
      * @param duration
      * The total duration of the countdown in milliseconds.
      *
@@ -114,6 +122,8 @@ export default class Countdown extends GameLoop
      * The internal method actually responsible for stopping the
      * countdown and resolving or rejecting the {@link Countdown._deferrer} promise.
      *
+     * ---
+     *
      * @param reason
      * The reason why the countdown has stopped.
      *
@@ -140,11 +150,16 @@ export default class Countdown extends GameLoop
      *
      * If the countdown is already running, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * countdown.onStart(() => { [...] }); // This callback will be executed.
      * countdown.start();
      * ```
      *
+     * ---
+     *
      * @param remainingTime
      * The remaining time to set as default when the countdown starts.  
      * Default is the {@link Countdown.duration} itself.
@@ -169,11 +184,16 @@ export default class Countdown extends GameLoop
      *
      * If the countdown hasn't yet started, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * countdown.onStop(() => { [...] }); // This callback will be executed.
      * countdown.stop();
      * ```
      *
+     * ---
+     *
      * @param reason
      * The reason why the countdown has stopped.
      *
@@ -194,11 +214,16 @@ export default class Countdown extends GameLoop
     /**
      * Subscribes to the `expire` event of the countdown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * countdown.onExpire(() => { [...] }); // This callback will be executed once the countdown has expired.
      * countdown.start();
      * ```
      *
+     * ---
+     *
      * @param callback The callback that will be executed when the countdown expires.
      *
      * @returns A function that can be used to unsubscribe from the event.
@@ -211,11 +236,16 @@ export default class Countdown extends GameLoop
     /**
      * Subscribes to the `tick` event of the countdown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * countdown.onTick((remainingTime) => { [...] }); // This callback will be executed.
      * countdown.start();
      * ```
      *
+     * ---
+     *
      * @param callback The callback that will be executed when the countdown ticks.
      * @param tickStep
      * The minimum time in milliseconds that must pass from the previous execution of the callback to the next one.

package/src/models/timers/game-loop.ts

@@ -27,6 +27,9 @@ interface GameLoopEventMap
  * elapsed time since the start of the game loop.  
  * It's also possible to subscribe to the `start` & `stop` events to receive notifications when they occur.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const loop = new GameLoop((elapsedTime: number) =>
  * {
@@ -116,10 +119,15 @@ export default class GameLoop
     /**
      * Initializes a new instance of the {@link GameLoop} class.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const loop = new GameLoop((elapsedTime: number) => { [...] });
      * ```
      *
+     * ---
+     *
      * @param callback The function that will be executed at each iteration of the game loop.
      * @param msIfNotBrowser
      * The interval in milliseconds that will be used if the current environment isn't a browser. Default is `40`.
@@ -164,11 +172,16 @@ export default class GameLoop
      *
      * If the game loop is already running, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * loop.onStart(() => { [...] }); // This callback will be executed.
      * loop.start();
      * ```
      *
+     * ---
+     *
      * @param elapsedTime The elapsed time to set as default when the game loop starts. Default is `0`.
      */
     public start(elapsedTime = 0): void
@@ -187,6 +200,9 @@ export default class GameLoop
      *
      * If the game loop hasn't yet started, a {@link RuntimeException} will be thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * loop.onStop(() => { [...] }); // This callback will be executed.
      * loop.stop();
@@ -210,10 +226,15 @@ export default class GameLoop
     /**
      * Subscribes to the `start` event of the game loop.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * loop.onStart(() => { console.log("The game loop has started."); });
      * ```
      *
+     * ---
+     *
      * @param callback The function that will be executed when the game loop starts.
      *
      * @returns A function that can be used to unsubscribe from the event.
@@ -226,10 +247,15 @@ export default class GameLoop
     /**
      * Subscribes to the `stop` event of the game loop.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * loop.onStop(() => { console.log("The game loop has stopped."); });
      * ```
      *
+     * ---
+     *
      * @param callback The function that will be executed when the game loop stops.
      *
      * @returns A function that can be used to unsubscribe from the event.

package/src/models/types.ts

@@ -43,4 +43,4 @@ export type {
 
 } from "./promises/types.js";
 
-export type { Callback } from "./callbacks/types.js";
+export type { Callback, CallbackMap } from "./callbacks/types.js";

package/src/utils/async.ts

@@ -2,12 +2,17 @@
  * Returns a promise that resolves after a certain number of milliseconds.  
  * It can be used to pause or delay the execution of an asynchronous function.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * doSomething();
  * await delay(1_000);
  * doSomethingElse();
  * ```
  *
+ * ---
+ *
  * @param milliseconds The number of milliseconds to wait before resolving the promise.
  *
  * @returns A {@link Promise} that resolves after the specified number of milliseconds.
@@ -21,6 +26,9 @@ export function delay(milliseconds: number): Promise<void>
  * Returns a promise that resolves on the next animation frame.  
  * It can be used to synchronize operations with the browser's rendering cycle.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const $el = document.querySelector(".element");
  *
@@ -29,6 +37,8 @@ export function delay(milliseconds: number): Promise<void>
  * $el.style.opacity = "1";
  * ```
  *
+ * ---
+ *
  * @returns A {@link Promise} that resolves on the next animation frame.
  */
 export function nextAnimationFrame(): Promise<void>
@@ -40,6 +50,9 @@ export function nextAnimationFrame(): Promise<void>
  * Returns a promise that resolves on the next microtask.  
  * It can be used to yield to the event loop in long-running operations to prevent blocking the main thread.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * for (let i = 0; i < 100_000_000; i += 1)
  * {
@@ -49,6 +62,8 @@ export function nextAnimationFrame(): Promise<void>
  * }
  * ```
  *
+ * ---
+ *
  * @returns A {@link Promise} that resolves on the next microtask.
  */
 export function yieldToEventLoop(): Promise<void>