@byloth/core 2.0.1 → 2.1.0

package/src/models/iterators/types.ts

@@ -3,6 +3,9 @@ import type { MaybePromise } from "../promises/types.js";
 /**
  * An union type that represents an iterable object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iterable: MaybeAsyncIterable<number> = [...];
  * for await (const value of iterable)
@@ -11,6 +14,8 @@ import type { MaybePromise } from "../promises/types.js";
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  */
 export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> | AsyncIterable<T, R, N>;
@@ -18,6 +23,9 @@ export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> |
 /**
  * An union type that represents an iterator object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iterator: MaybeAsyncIterator<number> = { ... };
  * for await (const value of iterator)
@@ -26,6 +34,8 @@ export type MaybeAsyncIterable<T, R = void, N = undefined> = Iterable<T, R, N> |
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterator.
  */
 export type MaybeAsyncIterator<T, R = void, N = undefined> = Iterator<T, R, N> | AsyncIterator<T, R, N>;
@@ -33,6 +43,9 @@ export type MaybeAsyncIterator<T, R = void, N = undefined> = Iterator<T, R, N> |
 /**
  * An union type that represents a generator object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const generator: MaybeAsyncGenerator<number> = [async] function*() { ... };
  * for await (const value of generator)
@@ -46,6 +59,9 @@ export type MaybeAsyncGenerator<T, R = void, N = undefined> = Generator<T, R, N>
  * An utility type that represents a function that returns a generator object.  
  * It differs from the native `GeneratorFunction` type by allowing to specify the types of the returned generator.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const generatorFn: GeneratorFunction<number> = function*() { ... };
  * const generator: Generator<number> = generatorFn();
@@ -56,6 +72,8 @@ export type MaybeAsyncGenerator<T, R = void, N = undefined> = Generator<T, R, N>
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements generated by the generator.
  * @template R The type of the return value of the generator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -66,6 +84,9 @@ export type GeneratorFunction<T, R = void, N = undefined> = () => Generator<T, R
  * An utility type that represents a function that returns an asynchronous generator object.  
  * It differs from the native `AsyncGeneratorFunction` type by allowing to specify the types of the returned generator.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const asyncGeneratorFn: AsyncGeneratorFunction<number> = async function*() { ... };
  * const generator: AsyncGenerator<number> = asyncGeneratorFn();
@@ -75,6 +96,8 @@ export type GeneratorFunction<T, R = void, N = undefined> = () => Generator<T, R
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements generated by the generator.
  * @template R The type of the return value of the generator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -85,6 +108,9 @@ export type AsyncGeneratorFunction<T, R = void, N = undefined> = () => AsyncGene
  * An utility type that represents a function that returns a
  * generator object that can be either synchronous or asynchronous.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const generatorFn: MaybeAsyncGeneratorFunction<number> = [async] function*() { ... };
  * const generator: MaybeAsyncGenerator<number> = generatorFn();
@@ -94,6 +120,8 @@ export type AsyncGeneratorFunction<T, R = void, N = undefined> = () => AsyncGene
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements generated by the generator.
  * @template R The type of the return value of the generator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -105,13 +133,18 @@ export type MaybeAsyncGeneratorFunction<T, R = void, N = undefined> = () => Mayb
  * {@link https://en.wikipedia.org/wiki/Iteratee|iteratee} function.  
  * It can be used to transform the elements of an iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: Iteratee<number, string> = (value: number) => `${value}`;
  * const values: string[] = [1, 2, 3, 4, 5].map(iteratee);
- * 
+ *
  * console.log(values); // ["1", "2", "3", "4", "5"]
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
  */
@@ -121,6 +154,9 @@ export type Iteratee<T, R = void> = (value: T, index: number) => R;
  * An utility type that represents an asynchronous {@link https://en.wikipedia.org/wiki/Iteratee|iteratee} function.  
  * It can be used to transform the elements of an iterable asynchronously.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: AsyncIteratee<number, string> = async (value: number) => `${value}`;
  * const values: Promise<string>[] = [1, 2, 3, 4, 5].map(iteratee);
@@ -130,6 +166,8 @@ export type Iteratee<T, R = void> = (value: T, index: number) => R;
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
  */
@@ -140,6 +178,9 @@ export type AsyncIteratee<T, R = void> = (value: T, index: number) => Promise<R>
  * function that can be either synchronous or asynchronous.  
  * It can be used to transform the elements of an iterable.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: MaybeAsyncIteratee<number, string> = [async] (value: number) => `${value}`;
  * const values: Promise<string>[] = [1, 2, 3, 4, 5].map(iteratee);
@@ -149,6 +190,8 @@ export type AsyncIteratee<T, R = void> = (value: T, index: number) => Promise<R>
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iteratee. Default is `void`.
  */
@@ -161,6 +204,9 @@ export type MaybeAsyncIteratee<T, R = void> = (value: T, index: number) => Maybe
  * It can be used to ensure the type of the elements of an iterable
  * while allowing the type-system to infer them correctly.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const iteratee: TypeGuardPredicate<number | string, string> = (value): value is string => typeof value === "string";
  * const values: string[] = [1, "2", 3, "4", 5].filter(iteratee);
@@ -170,6 +216,8 @@ export type MaybeAsyncIteratee<T, R = void> = (value: T, index: number) => Maybe
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R
  * The type of the elements that pass the type guard.  
@@ -186,6 +234,9 @@ export type TypeGuardPredicate<T, R extends T> = (value: T, index: number) => va
  * An utility type that represents a reducer function.  
  * It can be used to reduce the elements of an iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: Reducer<number, number> = (accumulator, value) => accumulator + value;
  * const total: number = [1, 2, 3, 4, 5].reduce(sum);
@@ -193,6 +244,8 @@ export type TypeGuardPredicate<T, R extends T> = (value: T, index: number) => va
  * console.log(total); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
  */
@@ -202,6 +255,9 @@ export type Reducer<T, A> = (accumulator: A, value: T, index: number) => A;
  * An utility type that represents an asynchronous reducer function.  
  * It can be used to reduce the elements of an iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: AsyncReducer<number, number> = async (accumulator, value) => accumulator + value;
  * const result = await new SmartAsyncIterator<number>([1, 2, 3, 4, 5]).reduce(sum);
@@ -209,6 +265,8 @@ export type Reducer<T, A> = (accumulator: A, value: T, index: number) => A;
  * console.log(result); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
  */
@@ -218,6 +276,9 @@ export type AsyncReducer<T, A> = (accumulator: A, value: T, index: number) => Pr
  * An utility type that represents a reducer function that can be either synchronous or asynchronous.  
  * It can be used to reduce the elements of an iterable into a single value.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const sum: MaybeAsyncReducer<number, number> = [async] (accumulator, value) => accumulator + value;
  * const result = await new SmartAsyncIterator<number>([1, 2, 3, 4, 5]).reduce(sum);
@@ -225,6 +286,8 @@ export type AsyncReducer<T, A> = (accumulator: A, value: T, index: number) => Pr
  * console.log(result); // 15
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template A The type of the accumulator.
  */
@@ -234,6 +297,9 @@ export type MaybeAsyncReducer<T, A> = (accumulator: A, value: T, index: number)
  * An union type that represents either an iterable or an iterator object.  
  * More in general, it represents an object that can be looped over in one way or another.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements: IteratorLike<number> = { ... };
  * const iterator: SmartIterator<number> = new SmartIterator(elements);
@@ -243,6 +309,8 @@ export type MaybeAsyncReducer<T, A> = (accumulator: A, value: T, index: number)
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iterator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -253,6 +321,9 @@ export type IteratorLike<T, R = void, N = undefined> = Iterable<T, R, N> | Itera
  * An union type that represents either an iterable or an iterator object that can be asynchronous.  
  * More in general, it represents an object that can be looped over in one way or another.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements: AsyncIteratorLike<number> = { ... };
  * const iterator: SmartAsyncIterator<number> = new SmartAsyncIterator(elements);
@@ -262,6 +333,8 @@ export type IteratorLike<T, R = void, N = undefined> = Iterable<T, R, N> | Itera
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iterator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.
@@ -273,6 +346,9 @@ export type AsyncIteratorLike<T, R = void, N = undefined> = AsyncIterable<T, R,
  * object that can be either synchronous or asynchronous.  
  * More in general, it represents an object that can be looped over in one way or another.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const elements: MaybeAsyncIteratorLike<number> = { ... };
  * const iterator: SmartAsyncIterator<number> = new SmartAsyncIterator(elements);
@@ -282,6 +358,8 @@ export type AsyncIteratorLike<T, R = void, N = undefined> = AsyncIterable<T, R,
  * }
  * ```
  *
+ * ---
+ *
  * @template T The type of the elements in the iterable.
  * @template R The type of the return value of the iterator. Default is `void`.
  * @template N The type of the `next` method argument. Default is `undefined`.

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

@@ -4,12 +4,15 @@ import { EnvironmentException } from "../exceptions/index.js";
 import type { JSONValue } from "./types.js";
 
 /**
- * A wrapper around the `Storage` API to better store and easily retrieve
+ * A wrapper around the {@link Storage} API to better store and easily retrieve
  * typed JSON values using the classical key-value pair storage system.
  *
  * It allows to handle either the volatile {@link sessionStorage} or the persistent
  * {@link localStorage} at the same time, depending on what's your required use case.
  *
+ * ---
+ *
+ * @example
  * ```ts
  * const jsonStorage = new JSONStorage();
  *

package/src/models/json/types.ts

@@ -6,7 +6,7 @@ export type JSONArray = JSONValue[];
 /**
  * A type that represents a JSON object.
  */
-export interface JSONObject { [key: string]: JSONValue }
+export type JSONObject<T extends object = object> = { [K in keyof T]: JSONValue };
 
 /**
  * A type that represents all the possible values of a JSON value.

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.  

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>

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>

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();
  *

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);
  *
@@ -119,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.
      *

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) =>
  * {

package/src/models/types.ts

@@ -9,6 +9,7 @@ export type {
 
 } from "./aggregators/types.js";
 
+export type { MapViewEventsMap, ReadonlyMapView, SetViewEventsMap, ReadonlySetView } from "./collections/types.js";
 export type {
     GeneratorFunction,
     AsyncGeneratorFunction,
@@ -26,13 +27,7 @@ export type {
 
 } from "./iterators/types.js";
 
-export type {
-    JSONArray,
-    JSONObject,
-    JSONValue
-
-} from "./json/types.js";
-
+export type { JSONArray, JSONObject, JSONValue } from "./json/types.js";
 export type {
     MaybePromise,
     FulfilledHandler,
@@ -43,4 +38,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>

package/src/utils/curve.ts

@@ -1,7 +1,7 @@
 import { SmartIterator, ValueException } from "../models/index.js";
 
 /**
- * A utility class that provides a set of methods to generate sequences of numbers following specific curves.  
+ * An utility class that provides a set of methods to generate sequences of numbers following specific curves.  
  * It can be used to generate sequences of values that can be
  * used in animations, transitions and other different scenarios.
  *