@byloth/core 2.0.0-rc.9 → 2.0.0

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

@@ -2,11 +2,69 @@ import type { PromiseResolver, PromiseRejecter, FulfilledHandler, RejectedHandle
 
 import SmartPromise from "./smart-promise.js";
 
+/**
+ * A class representing a {@link SmartPromise} that can be resolved or rejected from the "outside".  
+ * The `resolve` and `reject` methods are exposed to allow the promise to be settled from another context.
+ *
+ * It's particularly useful in scenarios where the promise is created and needs to be awaited in one place,  
+ * while being resolved or rejected in another (e.g. an event handler for an user interaction).
+ *
+ * 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.
+ *
+ * ```ts
+ * const promise = new DeferredPromise<string, string[]>((value: string) => value.split(" "));
+ *
+ * promise.then((result) => console.log(result)); // ["Hello,", "World!"]
+ * 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.  
+ * This will be the actual type of value the promise will eventually resolve to. Default is `T`.
+ * @template R
+ * The type of value possibly returned by the `onRejected` callback.  
+ * This will be coupled with the type of value the promise will eventually resolve to, if provided. Default is `never`.
+ */
 export default class DeferredPromise<T = void, F = T, R = never> extends SmartPromise<F | R>
 {
+    /**
+     * The exposed function that allows to resolve the promise.
+     *
+     * 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 DeferredPromise.resolve} getter instead.
+     */
     protected _resolve: PromiseResolver<T>;
+
+    /**
+     * The exposed function that allows to reject the promise.
+     */
+    public get resolve(): PromiseResolver<T> { return this._resolve; }
+
+    /**
+     * The exposed function that allows to reject the promise.
+     *
+     * 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 DeferredPromise.reject} getter instead.
+     */
     protected _reject: PromiseRejecter;
 
+    /**
+     * The exposed function that allows to reject the promise.
+     */
+    public get reject(): PromiseRejecter { return this._reject; }
+
+    /**
+     * Initializes a new instance of the {@link DeferredPromise} class.
+     *
+     * ```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.
+     */
     public constructor(onFulfilled?: FulfilledHandler<T, F> | null, onRejected?: RejectedHandler<unknown, R> | null)
     {
         let _resolve: PromiseResolver<T>;
@@ -21,15 +79,27 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
             _reject = reject;
         });
 
-        this._promise.then(onFulfilled as FulfilledHandler<F | R>, onRejected);
+        this._promise = this._promise.then(onFulfilled as FulfilledHandler<F | R>, onRejected);
 
         this._resolve = _resolve!;
         this._reject = _reject!;
     }
 
-    public get resolve(): PromiseResolver<T> { return this._resolve; }
-    public get reject(): PromiseRejecter { return this._reject; }
-
+    /**
+     * Watches another promise and resolves or rejects this promise when the other one is settled.
+     *
+     * ```ts
+     * const promise = new Promise<string>((resolve) => setTimeout(() => resolve("Hello, World!"), 1_000));
+     * const deferred = new DeferredPromise<string, string[]>((value: string) => value.split(" "));
+     *
+     * deferred.then((result) => console.log(result)); // ["Hello,", "World!"]
+     * deferred.watch(promise);
+     * ```
+     *
+     * @param otherPromise The promise to watch.
+     *
+     * @returns The current instance of the {@link DeferredPromise} class.
+     */
     public watch(otherPromise: PromiseLike<T>): this
     {
         otherPromise.then(this.resolve, this.reject);
@@ -37,5 +107,5 @@ export default class DeferredPromise<T = void, F = T, R = never> extends SmartPr
         return this;
     }
 
-    public readonly [Symbol.toStringTag]: string = "DeferredPromise";
+    public override readonly [Symbol.toStringTag]: string = "DeferredPromise";
 }

package/src/models/promises/index.ts

@@ -1,7 +1,5 @@
 import DeferredPromise from "./deferred-promise.js";
-import LongRunningTask from "./long-running-task.js";
 import SmartPromise from "./smart-promise.js";
-import Thenable from "./thenable.js";
 import TimedPromise from "./timed-promise.js";
 
-export { DeferredPromise, LongRunningTask, SmartPromise, Thenable, TimedPromise };
+export { DeferredPromise, SmartPromise, TimedPromise };

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

@@ -1,18 +1,121 @@
 import type { FulfilledHandler, PromiseExecutor, RejectedHandler } from "./types.js";
 
+/**
+ * A wrapper class representing an enhanced version of the native {@link Promise} object.
+ *
+ * It provides additional properties to check the state of the promise itself.  
+ * The state can be either `pending`, `fulfilled` or `rejected` and is accessible through
+ * the {@link SmartPromise.isPending}, {@link SmartPromise.isFulfilled} & {@link SmartPromise.isRejected} properties.
+ *
+ * ```ts
+ * const promise = new SmartPromise<string>((resolve, reject) =>
+ * {
+ *     setTimeout(() => resolve("Hello, World!"), 1_000);
+ * });
+ *
+ * console.log(promise.isPending); // true
+ * console.log(promise.isFulfilled); // false
+ *
+ * console.log(await promise); // "Hello, World!"
+ *
+ * console.log(promise.isPending); // false
+ * 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>
 {
+    /**
+     * Wraps a new {@link SmartPromise} object around an existing native {@link Promise} object.
+     *
+     * ```ts
+     * const request = fetch("https://api.example.com/data");
+     * const smartRequest = SmartPromise.FromPromise(request);
+     *
+     * console.log(request.isPending); // Throws an error: `isPending` is not a property of `Promise`.
+     * console.log(smartRequest.isPending); // true
+     *
+     * const response = await request;
+     * console.log(smartRequest.isFulfilled); // true
+     * ```
+     *
+     * @param promise The promise to wrap.
+     *
+     * @returns A new {@link SmartPromise} object that wraps the provided promise.
+     */
     public static FromPromise<T>(promise: Promise<T>): SmartPromise<T>
     {
         return new SmartPromise((resolve, reject) => promise.then(resolve, reject));
     }
 
+    /**
+     * A flag indicating whether the promise is still pending or not.
+     *
+     * The 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 SmartPromise.isPending} getter instead.
+     */
     protected _isPending: boolean;
+
+    /**
+     * A flag indicating whether the promise is still pending or not.
+     */
+    public get isPending(): boolean
+    {
+        return this._isPending;
+    }
+
+    /**
+     * A flag indicating whether the promise has been fulfilled or not.
+     *
+     * The 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 SmartPromise.isFulfilled} getter instead.
+     */
     protected _isFulfilled: boolean;
+
+    /**
+     * A flag indicating whether the promise has been fulfilled or not.
+     */
+    public get isFulfilled(): boolean
+    {
+        return this._isFulfilled;
+    }
+
+    /**
+     * A flag indicating whether the promise has been rejected or not.
+     *
+     * The 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 SmartPromise.isRejected} getter instead.
+     */
     protected _isRejected: boolean;
 
+    /**
+     * A flag indicating whether the promise has been rejected or not.
+     */
+    public get isRejected(): boolean
+    {
+        return this._isRejected;
+    }
+
+    /**
+     * The native {@link Promise} object wrapped by this instance.
+     */
     protected _promise: Promise<T>;
 
+    /**
+     * Initializes a new instance of the {@link SmartPromise} class.
+     *
+     * ```ts
+     * const promise = new SmartPromise<string>((resolve, reject) =>
+     * {
+     *     setTimeout(() => resolve("Hello, World!"), 1_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.
+     */
     public constructor(executor: PromiseExecutor<T>)
     {
         this._isPending = true;
@@ -38,12 +141,76 @@ export default class SmartPromise<T = void> implements Promise<T>
             .then(_onFulfilled, _onRejected);
     }
 
-    public get isPending(): boolean { return this._isPending; }
-    public get isFulfilled(): boolean { return this._isFulfilled; }
-    public get isRejected(): boolean { return this._isRejected; }
-
+    /**
+     * Creates a new {@link Promise} identical to the one wrapped by this instance, with a different reference.
+     *
+     * ```ts
+     * const promise = new SmartPromise<string>((resolve, reject) =>
+     * {
+     *     setTimeout(() => resolve("Hello, World!"), 1_000);
+     * });
+     *
+     * console.log(await promise.then()); // "Hello, World!"
+     * ```
+     *
+     * @returns A new {@link Promise} identical to the original one.
+     */
     public then(onFulfilled?: null): Promise<T>;
+
+    /**
+     * Attaches a callback that executes right after the promise is fulfilled.
+     *
+     * 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.
+     *
+     * ```ts
+     * const promise = new SmartPromise<string>((resolve, reject) =>
+     * {
+     *     setTimeout(() => resolve("Hello, World!"), 1_000);
+     * });
+     *
+     * 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.
+     *
+     * @returns A new {@link Promise} resolved with the return value of the callback.
+     */
     public then<F = T>(onFulfilled: FulfilledHandler<T, F>, onRejected?: null): Promise<F>;
+
+    /**
+     * Attaches callbacks that executes right after the promise is fulfilled or rejected.
+     *
+     * The previous result of the promise is passed as the argument to the fulfillment callback.  
+     * The fulfillment callback's return value is considered the new promise's result instead.
+     *
+     * If an error is thrown during execution, the rejection callback is then executed instead.
+     *
+     * Also note that:
+     * - If the rejection callback runs properly, the error is considered handled.  
+     * 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.
+     *
+     * ```ts
+     * const promise = new SmartPromise((resolve, reject) =>
+     * {
+     *     setTimeout(resolve, Math.random() * 1_000);
+     *     setTimeout(reject, Math.random() * 1_000);
+     * });
+     *
+     * 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`.
+     *
+     * @param onFulfilled The callback to execute once the promise is fulfilled.
+     * @param onRejected The callback to execute once the promise is rejected.
+     *
+     * @returns A new {@link Promise} resolved or rejected based on the callbacks.
+     */
     public then<F = T, R = never>(onFulfilled: FulfilledHandler<T, F>, onRejected: RejectedHandler<unknown, R>)
         : Promise<F | R>;
     public then<F = T, R = never>(
@@ -53,12 +220,73 @@ export default class SmartPromise<T = void> implements Promise<T>
         return this._promise.then(onFulfilled, onRejected);
     }
 
+    /**
+     * Creates a new {@link Promise} identical to the one wrapped by this instance, with a different reference.
+     *
+     * ```ts
+     * const promise = new SmartPromise((resolve, reject) =>
+     * {
+     *     setTimeout(() => reject(new Error("An unknown error occurred.")), 1_000);
+     * });
+     *
+     * promise.catch(); // Uncaught Error: An unknown error occurred.
+     * ```
+     *
+     * @returns A new {@link Promise} identical to the original one.
+     */
     public catch(onRejected?: null): Promise<T>;
+
+    /**
+     * Attaches a callback to handle the potential rejection of the promise.  
+     * If it happens, the callback is then executed.
+     *
+     * Also note that:
+     * - If the callback runs properly, the error is considered handled.  
+     * 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.
+     *
+     * ```ts
+     * const promise = new SmartPromise((resolve, reject) =>
+     * {
+     *     setTimeout(() => reject(new Error("An unknown error occurred.")), 1_000);
+     * });
+     *
+     * 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.
+     *
+     * @returns A new {@link Promise} able to catch and handle the potential error.
+     */
     public catch<R = never>(onRejected: RejectedHandler<unknown, R>): Promise<T | R>;
     public catch<R = never>(onRejected?: RejectedHandler<unknown, R> | null): Promise<T | R>
     {
         return this._promise.catch(onRejected);
     }
+
+    /**
+     * Attaches a callback that executes right after the promise is settled, regardless of the outcome.
+     *
+     * ```ts
+     * const promise = new SmartPromise((resolve, reject) =>
+     * {
+     *     setTimeout(resolve, Math.random() * 1_000);
+     *     setTimeout(reject, Math.random() * 1_000);
+     * });
+     *
+     *
+     * promise
+     *     .then(() => console.log("OK!")) // Logs "OK!" if the promise is fulfilled.
+     *     .catch(() => console.log("KO!")) // Logs "KO!" if the promise is rejected.
+     *     .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.
+     */
     public finally(onFinally?: (() => void) | null): Promise<T>
     {
         return this._promise.finally(onFinally);

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

@@ -3,8 +3,45 @@ import { TimeoutException } from "../exceptions/index.js";
 import SmartPromise from "./smart-promise.js";
 import type { MaybePromise, PromiseExecutor } from "./types.js";
 
+/**
+ * A class representing a {@link SmartPromise} that rejects automatically after a given time.  
+ * It's useful for operations that must be completed within a certain time frame.
+ *
+ * If the operation takes longer than the specified time, the promise is rejected with a {@link TimeoutException}.
+ *
+ * ```ts
+ * const promise = new TimedPromise<string>((resolve, reject) =>
+ * {
+ *     setTimeout(() => resolve("Hello, World!"), Math.random() * 10_000);
+ *
+ * }, 5_000);
+ *
+ * promise
+ *     .then((result) => console.log(result))  // "Hello, World!"
+ *     .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>
 {
+    /**
+     * Initializes a new instance of the {@link TimedPromise} class.
+     *
+     * ```ts
+     * const promise = new TimedPromise<string>((resolve, reject) =>
+     * {
+     *    setTimeout(() => resolve("Hello, World!"), Math.random() * 10_000);
+     *
+     * }, 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.
+     *
+     * @param timeout The maximum time in milliseconds that the operation can take before timing out.
+     */
     public constructor(executor: PromiseExecutor<T>, timeout?: number)
     {
         super((resolve, reject) =>
@@ -27,5 +64,5 @@ export default class TimedPromise<T = void> extends SmartPromise<T>
         });
     }
 
-    public readonly [Symbol.toStringTag]: string = "TimedPromise";
+    public override readonly [Symbol.toStringTag]: string = "TimedPromise";
 }

package/src/models/promises/types.ts

@@ -1,10 +1,92 @@
-export type { LongRunningTaskOptions } from "./long-running-task.js";
-
+/**
+ * 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.
+ *
+ * ```ts
+ * async function splitWords(value: MaybePromise<string>): Promise<string[]>
+ * {
+ *     return (await value).split(" ");
+ * }
+ * ```
+ *
+ * @template T The type of the value.
+ */
 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.
+ *
+ * ```ts
+ * const onFulfilled: FulfilledHandler<string, string[]> = (value) => value.split(" ");
+ *
+ * await new Promise<string>((resolve) => resolve("Hello, World!"))
+ *     .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`.
+ */
 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.
+ *
+ * ```ts
+ * const onRejected: RejectedHandler<unknown, string> = (reason) => String(reason);
+ *
+ * await new Promise<string>((_, reject) => reject(new Error("An error occurred.")))
+ *     .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`.
+ */
 export type RejectedHandler<E = unknown, R = never> = (reason: E) => MaybePromise<R>;
 
+/**
+ * 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.
+ *
+ * ```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;
+
+/**
+ * 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.
+ *
+ * ```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;
+
+/**
+ * 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.
+ *
+ * ```ts
+ * const executor: PromiseExecutor<string> = (resolve, reject) =>
+ * {
+ *     setTimeout(() => resolve("Hello, World!"), 1_000);
+ * };
+ *
+ * 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`.
+ */
 export type PromiseExecutor<T = void, E = unknown> = (resolve: PromiseResolver<T>, reject: PromiseRejecter<E>) => void;