@flex-development/when 1.0.0 → 3.0.0

package/dist/index.d.mts

@@ -1,3 +1,85 @@
+/**
+ * @file Interfaces - PromiseLike
+ * @module when/interfaces/PromiseLike
+ */
+declare global {
+    interface PromiseLike<T> {
+        /**
+         * Attach callbacks for resolution and/or rejection.
+         *
+         * @template {any} [S=T]
+         *  The next resolved value on success
+         * @template {any} [F=never]
+         *  The next resolved value on failure
+         *
+         * @this {unknown}
+         *
+         * @param {((value: T) => PromiseLike<S> | S) | null | undefined} [succ]
+         *  The callback to execute when the thenable is resolved
+         * @param {((reason: any) => F | PromiseLike<F>) | null | undefined} [fail]
+         *  The callback to execute when the thenable is rejected
+         * @return {PromiseLike<F | S>}
+         *  The next promise-like object
+         */
+        then<S = T, F = never>(succ?: ((value: T) => PromiseLike<S> | S) | null | undefined, fail?: ((reason: any) => F | PromiseLike<F>) | null | undefined): PromiseLike<F | S>;
+    }
+}
+
+/**
+ * @file Interfaces - Catchable
+ * @module when/interfaces/Catchable
+ */
+
+/**
+ * A thenable that can be caught.
+ *
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} [T=any]
+ *  The resolved value
+ *
+ * @extends {Thenable<T>}
+ */
+interface Catchable<T = any> extends Thenable<T> {
+    /**
+     * Attach a callback only to be invoked on rejection.
+     *
+     * @see {@linkcode Catch}
+     *
+     * @override
+     */
+    catch: Catch<T>;
+}
+
+/**
+ * @file Interfaces - Finalizable
+ * @module when/interfaces/Finalizable
+ */
+
+/**
+ * A thenable that can be finalized.
+ *
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} [T=any]
+ *  The resolved value
+ *
+ * @extends {Thenable<T>}
+ */
+interface Finalizable<T = any> extends Thenable<T> {
+    /**
+     * Attach a callback only to be invoked
+     * on settlement (fulfillment or rejection).
+     *
+     * > 👉 **Note**: The resolved value cannot be modified from the callback.
+     *
+     * @see {@linkcode Finally}
+     *
+     * @override
+     */
+    finally: Finally<T>;
+}
+
 /**
  * @file Interfaces - Options
  * @module when/interfaces/Options
@@ -10,12 +92,16 @@
  *  The previously resolved value
  * @template {any} [Next=any]
  *  The next resolved value
+ * @template {any} [Failure=Next]
+ *  The next resolved value on failure
  * @template {ReadonlyArray<any>} [Args=any[]]
  *  The chain function arguments
- * @template {any} [Self=any]
+ * @template {any} [Error=any]
+ *  The error to possibly handle
+ * @template {any} [This=any]
  *  The `this` context
  */
-interface Options<T = any, Next = any, Args extends readonly any[] = any[], Self = any> {
+interface Options<T = any, Next = any, Failure = Next, Args extends readonly any[] = any[], Error = any, This = any> {
     /**
      * The arguments to pass to the {@linkcode chain} callback.
      */
@@ -23,28 +109,201 @@ interface Options<T = any, Next = any, Args extends readonly any[] = any[], Self
     /**
      * The chain callback.
      *
+     * > 👉 **Note**: For thenables, this callback is passed to `then` as
+     * > the `onfulfilled` parameter.
+     *
      * @see {@linkcode Chain}
+     * @see {@linkcode PromiseLike.then}
      */
-    chain: Chain<T, Next, Args, Self>;
+    chain: Chain<T, Next, Args, This>;
     /**
-     * The `this` context of the {@linkcode chain}
-     * and {@linkcode reject} callbacks.
+     * The `this` context of the {@linkcode chain} and {@linkcode fail} callbacks.
+     */
+    context?: This | null | undefined;
+    /**
+     * The callback to fire when a failure occurs.
+     *
+     * Failures include:
+     *
+     * - Rejections of the input thenable
+     * - Rejections returned from {@linkcode chain}
+     * - Synchronous errors thrown in {@linkcode chain}
+     *
+     * If no `fail` handler is provided, failures are re-thrown or re-propagated.
+     *
+     * > 👉 **Note**: For thenables, this callback is passed to `then` as
+     * > the `onrejected` parameter, and if implemented, to `catch` as well
+     * > to prevent unhandled rejections.
+     *
+     * @see {@linkcode Fail}
+     * @see {@linkcode Promise.catch}
+     * @see {@linkcode PromiseLike.then}
+     *
+     * @since 2.0.0
      */
-    context?: Self | null | undefined;
+    fail?: Fail<Failure, Error, This> | null | undefined;
     /**
-     * The callback to fire when a promise is rejected or an error is thrown.
+     * The callback to invoke after chaining completes, whether the operation
+     * succeeds or fails.
+     *
+     * It runs exactly once after {@linkcode chain} and {@linkcode fail}, cannot
+     * affect the resolved value, and does not intercept errors.
      *
-     * @see {@linkcode Reject}
+     * @see {@linkcode Finish}
+     *
+     * @since 3.0.0
      */
-    reject?: Reject<Next, any, Self> | null | undefined;
+    finish?: Finish<This> | null | undefined;
 }
 
+/**
+ * @file Interfaces - Thenable
+ * @module when/interfaces/Thenable
+ */
+
+/**
+ * The completion of an asynchronous operation, and the minimal structural
+ * contract required by `when` to treat a value as asynchronous.
+ *
+ * Unlike {@linkcode PromiseLike}, this interface allows maybe-callable `catch`
+ * and `finally` methods, which when present, are used by `when` to ensure
+ * failures are handled and post-processing hooks are executed without forcing
+ * promise allocation.
+ *
+ * Maybe-callable methods are named so because they are not required,
+ * and may be a method implementation, `null`, or `undefined`.
+ *
+ * @template {any} [T=any]
+ *  The resolved value
+ */
+interface Thenable<T = any> {
+    /**
+     * Attach a callback only to be invoked on rejection.
+     *
+     * @see {@linkcode Catch}
+     */
+    catch?: Catch<T> | null | undefined;
+    /**
+     * Attach a callback only to be invoked
+     * on settlement (fulfillment or rejection).
+     *
+     * > 👉 **Note**: The resolved value cannot be modified from the callback.
+     *
+     * @see {@linkcode Finally}
+     */
+    finally?: Finally<T> | null | undefined;
+    /**
+     * Attach callbacks to be invoked on resolution (fulfillment)
+     * and/or rejection.
+     *
+     * @see {@linkcode Then}
+     */
+    then: Then<T>;
+}
+
+/**
+ * @file isCatchable
+ * @module when/lib/isCatchable
+ */
+
+/**
+ * Check if `value` looks like a `Thenable` that can be caught.
+ *
+ * @see {@linkcode Catchable}
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @return {value is Catchable<T>}
+ *  `true` if `value` is a thenable with a `catch` method, `false` otherwise
+ */
+declare function isCatchable<T>(this: void, value: unknown): value is Catchable<T>;
+
+/**
+ * @file isFinalizable
+ * @module when/lib/isFinalizable
+ */
+
+/**
+ * Check if `value` looks like a thenable that can be finalized.
+ *
+ * @see {@linkcode Finalizable}
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @return {value is Finalizable<T>}
+ *  `true` if `value` is a thenable with a `finally` method, `false` otherwise
+ */
+declare function isFinalizable<T>(this: void, value: unknown): value is Finalizable<T>;
+
+/**
+ * @file isPromise
+ * @module when/lib/isPromise
+ */
+/**
+ * Check if `value` looks like a {@linkcode Promise}.
+ *
+ * > 👉 **Note**: This function intentionally performs structural checks
+ * > instead of brand checks.
+ * > It does not rely on `instanceof Promise` or constructors, making it
+ * > compatible with cross-realm promises and custom thenables.
+ *
+ * @see {@linkcode isThenable}
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @param {boolean | null | undefined} [finalizable=true]
+ *  Whether a `finally` method is required.\
+ *  When `false`, only `then` and `catch` are checked
+ * @return {value is Promise<T>}
+ *  `true` if `value` is a thenable with a `catch` method,
+ *  and `finally` method (if requested), `false` otherwise
+ */
+declare function isPromise<T>(this: void, value: unknown, finalizable?: boolean | null | undefined): value is Promise<T>;
+
+/**
+ * @file isPromiseLike
+ * @module when/lib/isPromiseLike
+ */
+/**
+ * Check if `value` looks like a {@linkcode PromiseLike} structure.
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @return {value is PromiseLike<T>}
+ *  `true` if `value` is an object or function with a `then` method,
+ *  `false` otherwise
+ */
+declare function isPromiseLike<T>(this: void, value: unknown): value is PromiseLike<T>;
+
 /**
  * @file isThenable
  * @module when/lib/isThenable
  */
+
 /**
- * Check if `value` looks like a thenable.
+ * Check if `value` looks like a {@linkcode Thenable}.
+ *
+ * @see {@linkcode Thenable}
  *
  * @template {any} T
  *  The resolved value
@@ -53,10 +312,11 @@ interface Options<T = any, Next = any, Args extends readonly any[] = any[], Self
  *
  * @param {unknown} value
  *  The thing to check
- * @return {value is PromiseLike<T>}
- *  `true` if `value` is a thenable, `false` otherwise
+ * @return {value is Thenable<T>}
+ *  `true` if `value` is an object or function with a `then` method,
+ *  and maybe-callable methods `catch` and/or `finally`, `false` otherwise
  */
-declare function isThenable<T>(this: void, value: unknown): value is PromiseLike<T>;
+declare function isThenable<T>(this: void, value: unknown): value is Thenable<T>;
 
 /**
  * @file when
@@ -65,11 +325,11 @@ declare function isThenable<T>(this: void, value: unknown): value is PromiseLike
 
 /**
  * Chain a callback, calling the function after `value` is resolved,
- * or immediately if `value` is not thenable.
+ * or immediately if `value` is not a thenable.
  *
  * @see {@linkcode Awaitable}
  * @see {@linkcode Chain}
- * @see {@linkcode Reject}
+ * @see {@linkcode Fail}
  *
  * @template {any} T
  *  The previously resolved value
@@ -77,28 +337,69 @@ declare function isThenable<T>(this: void, value: unknown): value is PromiseLike
  *  The next resolved value
  * @template {ReadonlyArray<any>} [Args=any[]]
  *  The chain function arguments
- * @template {any} [Self=any]
+ * @template {any} [This=any]
  *  The `this` context
+ * @template {Awaitable<Next>} [Result=Awaitable<Next>]
+ *  The next awaitable
  *
  * @this {void}
  *
  * @param {Awaitable<T>} value
- *  The promise or the resolved value
- * @param {Chain<T, Next, Args, Self>} chain
+ *  The current awaitable
+ * @param {Chain<T, Next, Args, This>} chain
  *  The chain callback
- * @param {Reject<Next, any, Self>} [reject]
- *  The callback to fire when a promise is rejected or an error is thrown
- * @param {Self | null | undefined} [context]
- *  The `this` context of the chain and error callbacks
+ * @param {null | undefined} [fail]
+ *  The callback to fire when a failure occurs
+ * @param {This | null | undefined} [context]
+ *  The `this` context of the chain and `fail` callbacks
  * @param {Args} args
  *  The arguments to pass to the chain callback
- * @return {Awaitable<Next>}
- *  The next promise or value
+ * @return {Result}
+ *  The next awaitable
+ */
+declare function when<T, Next = any, Args extends any[] = any[], This = unknown, Result extends Awaitable<Next> = Awaitable<Next>>(this: void, value: Awaitable<T>, chain: Chain<T, Next, Args, This>, fail?: null | undefined, context?: This | null | undefined, ...args: Args): Result;
+/**
+ * Chain a callback, calling the function after `value` is resolved,
+ * or immediately if `value` is not a thenable.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Chain}
+ * @see {@linkcode Fail}
+ *
+ * @template {any} T
+ *  The previously resolved value
+ * @template {any} [Next=any]
+ *  The next resolved value
+ * @template {any} [Failure=Next]
+ *  The next resolved value on failure
+ * @template {ReadonlyArray<any>} [Args=any[]]
+ *  The chain function arguments
+ * @template {any} [Error=any]
+ *  The error to possibly handle
+ * @template {any} [This=any]
+ *  The `this` context
+ * @template {Awaitable<Failure | Next>} [Result=Awaitable<Failure | Next>]
+ *  The next awaitable
+ *
+ * @this {void}
+ *
+ * @param {Awaitable<T>} value
+ *  The current awaitable
+ * @param {Chain<T, Next, Args, This>} chain
+ *  The chain callback
+ * @param {Fail<Failure, Error, This> | null | undefined} [fail]
+ *  The callback to fire when a failure occurs
+ * @param {This | null | undefined} [context]
+ *  The `this` context of the chain and `fail` callbacks
+ * @param {Args} args
+ *  The arguments to pass to the chain callback
+ * @return {Result}
+ *  The next awaitable
  */
-declare function when<T, Next = any, Args extends any[] = any[], Self = unknown>(this: void, value: Awaitable<T>, chain: Chain<T, Next, Args, Self>, reject?: Reject<Next, any, Self> | null | undefined, context?: Self | null | undefined, ...args: Args): Awaitable<Next>;
+declare function when<T, Next = any, Failure = Next, Args extends any[] = any[], Error = any, This = unknown, Result extends Awaitable<Failure | Next> = Awaitable<Failure | Next>>(this: void, value: Awaitable<T>, chain: Chain<T, Next, Args, This>, fail?: Fail<Failure, Error, This> | null | undefined, context?: This | null | undefined, ...args: Args): Result;
 /**
  * Chain a callback, calling the function after `value` is resolved,
- * or immediately if `value` is not thenable.
+ * or immediately if `value` is not a thenable.
  *
  * @see {@linkcode Awaitable}
  * @see {@linkcode Options}
@@ -107,33 +408,69 @@ declare function when<T, Next = any, Args extends any[] = any[], Self = unknown>
  *  The previously resolved value
  * @template {any} [Next=any]
  *  The next resolved value
+ * @template {any} [Failure=Next]
+ *  The next resolved value on failure
  * @template {ReadonlyArray<any>} [Args=any[]]
  *  The chain function arguments
- * @template {any} [Self=unknown]
+ * @template {any} [Error=any]
+ *  The error to possibly handle
+ * @template {any} [This=unknown]
  *  The `this` context
+ * @template {Awaitable<Failure | Next>} [Result=Awaitable<Failure | Next>]
+ *  The next awaitable
  *
  * @this {void}
  *
  * @param {Awaitable<T>} value
- *  The promise or the resolved value
- * @param {Options<T, Next, Args, Self>} chain
+ *  The current awaitable
+ * @param {Options<T, Next, Failure, Args, Error, This>} chain
  *  Options for chaining
- * @return {Awaitable<Next>}
- *  The next promise or value
+ * @return {Result}
+ *  The next awaitable
  */
-declare function when<T, Next = any, Args extends any[] = any[], Self = unknown>(this: void, value: Awaitable<T>, chain: Options<T, Next, Args, Self>): Awaitable<Next>;
+declare function when<T, Next = any, Failure = Next, Args extends any[] = any[], Error = any, This = unknown, Result extends Awaitable<Failure | Next> = Awaitable<Failure | Next>>(this: void, value: Awaitable<T>, chain: Options<T, Next, Failure, Args, Error, This>): Result;
 
 /**
  * @file Type Aliases - Awaitable
  * @module when/types/Awaitable
  */
+
 /**
  * A synchronous or thenable value.
  *
+ * @see {@linkcode Thenable}
+ *
  * @template {any} T
  *  The resolved value
  */
-type Awaitable<T> = PromiseLike<T> | T;
+type Awaitable<T> = Thenable<T> | T;
+
+/**
+ * @file Type Aliases - Catch
+ * @module when/types/Catch
+ */
+
+/**
+ * Attach a callback only for the rejection of a `Thenable`.
+ *
+ * @see {@linkcode OnRejected}
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} [T=unknown]
+ *  The resolved value
+ * @template {any} [Reason=any]
+ *  The reason for the rejection
+ * @template {any} [Next=never]
+ *  The next resolved value
+ *
+ * @this {any}
+ *
+ * @param {OnRejected<Next, Reason> | null | undefined} [onrejected]
+ *  The callback to execute when the thenable is rejected
+ * @return {Thenable<Next | T>}
+ *  The next thenable
+ */
+type Catch<T = unknown, Reason = any> = <Next = never>(this: any, onrejected?: OnRejected<Next, Reason> | null | undefined) => Thenable<Next | T>;
 
 /**
  * @file Type Aliases - Chain
@@ -151,46 +488,184 @@ type Awaitable<T> = PromiseLike<T> | T;
  *  The next resolved value
  * @template {ReadonlyArray<any>} [Args=any[]]
  *  The function arguments
- * @template {any} [Self=unknown]
+ * @template {any} [This=unknown]
  *  The `this` context
  *
- * @this {Self}
+ * @this {This}
  *
  * @param {[...Args, T]} params
  *  The function parameters, with the last being the previously resolved value.\
  *  In cases where a promise is not being resolved,
  *  this is the same `value` passed to `when`
  * @return {Awaitable<Next>}
- *  The next promise or value
+ *  The next awaitable
  */
-type Chain<T = any, Next = any, Args extends readonly any[] = any[], Self = unknown> = (this: Self, ...params: [...Args, T]) => Awaitable<Next>;
+type Chain<T = any, Next = any, Args extends readonly any[] = any[], This = unknown> = (this: This, ...params: [...Args, T]) => Awaitable<Next>;
 
 /**
- * @file Type Aliases - Reject
- * @module when/types/Reject
+ * @file Type Aliases - Fail
+ * @module when/types/Fail
  */
 
 /**
- * The callback to fire when a promise is rejected
- * or an error is thrown from a synchronous function.
+ * The callback to fire when a failure occurs.
  *
  * @see {@linkcode Awaitable}
  *
  * @template {any} [Next=any]
  *  The next resolved value
- * @template {any} [Fail=any]
- *  The error to handle
- * @template {any} [Self=unknown]
+ * @template {any} [Reason=any]
+ *  The reason for the failure
+ * @template {any} [This=unknown]
  *  The `this` context
  *
- * @this {Self}
+ * @this {This}
  *
- * @param {unknown} e
- *  The error
+ * @param {Reason} reason
+ *  The reason for the failure
  * @return {Awaitable<Next>}
- *  The next promise or value
+ *  The next awaitable
+ */
+type Fail<Next = any, Reason = any, This = unknown> = (this: This, reason: Reason) => Awaitable<Next>;
+
+/**
+ * @file Type Aliases - Finally
+ * @module when/types/Finally
+ */
+
+/**
+ * Attach a callback that is invoked only when a `Thenable`
+ * is settled (fulfilled or rejected).
+ *
+ * > 👉 **Note**: The resolved value cannot be modified from the callback.
+ *
+ * @see {@linkcode OnFinally}
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} [T=unknown]
+ *  The resolved value
+ *
+ * @this {any}
+ *
+ * @param {OnFinally | null | undefined} [onfinally]
+ *  The callback to execute when the thenable is settled
+ * @return {Thenable<T>}
+ *  The next thenable
+ */
+type Finally<T = unknown> = (this: any, onfinally?: OnFinally | null | undefined) => Thenable<T>;
+
+/**
+ * @file Type Aliases - Finish
+ * @module when/types/Finish
+ */
+/**
+ * A post-processing hook invoked exactly once after an awaitable settles,
+ * regardless of success or failure.
+ *
+ * The resolved value cannot be modified from the hook,
+ * and any error is re-thrown after execution.
+ *
+ * @template {any} [This=unknown]
+ *  The `this` context
+ *
+ * @this {This}
+ *
+ * @return {undefined | void}
+ */
+type Finish<This = unknown> = (this: This) => undefined | void;
+
+/**
+ * @file Type Aliases - OnFinally
+ * @module when/types/OnFinally
+ */
+/**
+ * The callback to execute when a `Thenable` is settled (fulfilled or rejected).
+ *
+ * @this {unknown}
+ *
+ * @return {undefined | void}
+ */
+type OnFinally = (this: unknown) => undefined | void;
+
+/**
+ * @file Type Aliases - OnFulfilled
+ * @module when/types/OnFulfilled
+ */
+
+/**
+ * The callback to execute when a `Thenable` is resolved.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {any} T
+ *  The resolved value
+ * @template {any} [Next=T]
+ *  The next resolved value
+ *
+ * @this {unknown}
+ *
+ * @param {T} value
+ *  The resolved value
+ * @return {Awaitable<Next>}
+ *  The next awaitable
+ */
+type OnFulfilled<T, Next = T> = (this: unknown, value: T) => Awaitable<Next>;
+
+/**
+ * @file Type Aliases - OnRejected
+ * @module when/types/OnRejected
+ */
+
+/**
+ * The callback to execute when a `Thenable` is rejected.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {any} Next
+ *  The next resolved value
+ * @template {any} [Reason=any]
+ *  The reason for the rejection
+ *
+ * @this {unknown}
+ *
+ * @param {Reason} reason
+ *  The reason for the rejection
+ * @return {Awaitable<Next>}
+ *  The next awaitable
+ */
+type OnRejected<Next, Reason = any> = (this: unknown, reason: Reason) => Awaitable<Next>;
+
+/**
+ * @file Type Aliases - Then
+ * @module when/types/Then
+ */
+
+/**
+ * Attach callbacks for the resolution and/or rejection of a `Thenable`.
+ *
+ * @see {@linkcode OnFulfilled}
+ * @see {@linkcode OnRejected}
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} [T=unknown]
+ *  The previously resolved value
+ * @template {any} [Reason=any]
+ *  The reason for a rejection
+ * @template {any} [Succ=T]
+ *  The next resolved value on success
+ * @template {any} [Fail=never]
+ *  The next resolved value on failure
+ *
+ * @this {any}
+ *
+ * @param {OnFulfilled<T, Succ> | null | undefined} [onfulfilled]
+ *  The callback to execute when the thenable is resolved
+ * @param {OnRejected<Fail, Reason> | null | undefined} [onrejected]
+ *  The callback to execute when the thenable is rejected
+ * @return {Thenable<Fail | Succ>}
+ *  The next thenable
  */
-type Reject<Next = any, Fail = any, Self = unknown> = (this: Self, e: Fail) => Awaitable<Next>;
+type Then<T = unknown, Reason = any> = <Succ = T, Fail = never>(this: any, onfulfilled?: OnFulfilled<T, Succ> | null | undefined, onrejected?: OnRejected<Fail, Reason> | null | undefined) => Thenable<Fail | Succ>;
 
-export { when as default, isThenable as isPromiseLike, isThenable, when };
-export type { Awaitable, Chain, Options, Reject };
+export { when as default, isCatchable, isFinalizable, isPromise, isPromiseLike, isThenable, when };
+export type { Awaitable, Catch, Catchable, Chain, Fail, Finalizable, Finally, Finish, OnFinally, OnFulfilled, OnRejected, Options, Then, Thenable };