@byloth/core 2.0.0 → 2.0.1

package/src/models/json/json-storage.ts

@@ -42,10 +42,15 @@ export default class JSONStorage
      * Initializes a new instance of the {@link JSONStorage} class.  
      * It cannot be instantiated outside of a browser environment or an {@link EnvironmentException} is thrown.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const jsonStorage = new JSONStorage();
      * ```
      *
+     * ---
+     *
      * @param preferPersistence
      * Whether to prefer the {@link localStorage} over the {@link sessionStorage} when calling an ambivalent method.  
      * If omitted, it defaults to `true` to prefer the persistent storage.
@@ -106,10 +111,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.get<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -121,10 +131,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.get<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -140,10 +155,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.get<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -166,10 +186,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.recall<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -181,10 +206,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.recall<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -197,10 +227,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.recall<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -218,10 +253,15 @@ export default class JSONStorage
      * Retrieves the value with the specified key looking first in the volatile
      * {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.retrieve<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -234,10 +274,15 @@ export default class JSONStorage
      * Retrieves the value with the specified key looking first in the volatile
      * {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.retrieve<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -251,10 +296,15 @@ export default class JSONStorage
      * Retrieves the value with the specified key looking first in the volatile
      * {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.retrieve<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -271,10 +321,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.read<TValue>("key");
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -286,10 +341,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.read<TValue>("key", defaultValue);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -302,10 +362,15 @@ export default class JSONStorage
     /**
      * Retrieves the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * const value: TValue = jsonStorage.read<TValue>("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to retrieve.
      *
      * @param key The key of the value to retrieve.
@@ -322,6 +387,9 @@ export default class JSONStorage
     /**
      * Checks whether the value with the specified key exists within the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.has("key"))
      * {
@@ -329,6 +397,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      * @param persistent
      * Whether to prefer the persistent {@link localStorage} over the volatile {@link sessionStorage}.  
@@ -346,6 +416,9 @@ export default class JSONStorage
     /**
      * Checks whether the value with the specified key exists within the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.knows("key"))
      * {
@@ -353,6 +426,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      *
      * @returns `true` if the key exists, `false` otherwise.
@@ -366,6 +441,9 @@ export default class JSONStorage
      * Checks whether the value with the specified key exists looking first in the
      * volatile {@link sessionStorage} and then, if not found, in the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.find("key"))
      * {
@@ -373,6 +451,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      *
      * @returns `true` if the key exists, `false` otherwise.
@@ -385,6 +465,9 @@ export default class JSONStorage
     /**
      * Checks whether the value with the specified key exists within the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * if (jsonStorage.exists("key"))
      * {
@@ -392,6 +475,8 @@ export default class JSONStorage
      * }
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to check.
      *
      * @returns `true` if the key exists, `false` otherwise.
@@ -405,12 +490,17 @@ export default class JSONStorage
      * Sets the value with the specified key in the default storage.  
      * If the value is `undefined` or omitted, the key is removed from the storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.set("key");
      * jsonStorage.set("key", value);
      * jsonStorage.set("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to set.
      *
      * @param key The key of the value to set.
@@ -430,12 +520,17 @@ export default class JSONStorage
      * Sets the value with the specified key in the volatile {@link sessionStorage}.  
      * If the value is `undefined` or omitted, the key is removed from the storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.remember("key");
      * jsonStorage.remember("key", value);
      * jsonStorage.remember("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to set.
      *
      * @param key The key of the value to set.
@@ -450,12 +545,17 @@ export default class JSONStorage
      * Sets the value with the specified key in the persistent {@link localStorage}.  
      * If the value is `undefined` or omitted, the key is removed from the storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.write("key");
      * jsonStorage.write("key", value);
      * jsonStorage.write("key", obj?.value);
      * ```
      *
+     * ---
+     *
      * @template T The type of the value to set.
      *
      * @param key The key of the value to set.
@@ -469,10 +569,15 @@ export default class JSONStorage
     /**
      * Removes the value with the specified key from the default storage.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.delete("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      * @param persistent
      * Whether to prefer the persistent {@link localStorage} over the volatile {@link sessionStorage}.  
@@ -488,10 +593,15 @@ export default class JSONStorage
     /**
      * Removes the value with the specified key from the volatile {@link sessionStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.forget("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      */
     public forget(key: string): void
@@ -502,10 +612,15 @@ export default class JSONStorage
     /**
      * Removes the value with the specified key from the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.erase("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      */
     public erase(key: string): void
@@ -517,10 +632,15 @@ export default class JSONStorage
      * Removes the value with the specified key from both the
      * volatile {@link sessionStorage} and the persistent {@link localStorage}.
      *
+     * ---
+     *
+     * @example
      * ```ts
      * jsonStorage.clear("key");
      * ```
      *
+     * ---
+     *
      * @param key The key of the value to remove.
      */
     public clear(key: string): void

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

@@ -58,10 +58,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 +93,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 +104,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

@@ -29,6 +29,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 +43,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 +110,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 +120,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 +154,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 +166,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 +178,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 +190,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 +213,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 +226,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 +248,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 +260,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 +275,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 +287,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 +304,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 +321,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

@@ -28,6 +28,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 +39,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/timers/clock.ts

@@ -42,10 +42,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 +67,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 +95,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 +118,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.