@flex-development/when 2.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
@@ -60,8 +142,109 @@ interface Options<T = any, Next = any, Failure = Next, Args extends readonly any
      * @since 2.0.0
      */
     fail?: Fail<Failure, Error, This> | null | undefined;
+    /**
+     * 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 Finish}
+     *
+     * @since 3.0.0
+     */
+    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
@@ -69,8 +252,8 @@ interface Options<T = any, Next = any, Failure = Next, Args extends readonly any
 /**
  * Check if `value` looks like a {@linkcode Promise}.
  *
- * > 👉 **Note**: This function intentionally performs a structural check
- * > instead of a brand check.
+ * > 👉 **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.
  *
@@ -83,18 +266,21 @@ interface Options<T = any, Next = any, Failure = Next, Args extends readonly any
  *
  * @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, `false` otherwise
+ *  `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): value is Promise<T>;
+declare function isPromise<T>(this: void, value: unknown, finalizable?: boolean | null | undefined): value is Promise<T>;
 
 /**
- * @file isThenable
- * @module when/lib/isThenable
+ * @file isPromiseLike
+ * @module when/lib/isPromiseLike
  */
 /**
- * Check if `value` looks like a thenable,
- * i.e. a {@linkcode PromiseLike} object.
+ * Check if `value` looks like a {@linkcode PromiseLike} structure.
  *
  * @template {any} T
  *  The resolved value
@@ -107,7 +293,30 @@ declare function isPromise<T>(this: void, value: unknown): value is Promise<T>;
  *  `true` if `value` is an object or function with a `then` method,
  *  `false` otherwise
  */
-declare function isThenable<T>(this: void, value: unknown): value is PromiseLike<T>;
+declare function isPromiseLike<T>(this: void, value: unknown): value is PromiseLike<T>;
+
+/**
+ * @file isThenable
+ * @module when/lib/isThenable
+ */
+
+/**
+ * Check if `value` looks like a {@linkcode Thenable}.
+ *
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @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 Thenable<T>;
 
 /**
  * @file when
@@ -130,6 +339,8 @@ declare function isThenable<T>(this: void, value: unknown): value is PromiseLike
  *  The chain function arguments
  * @template {any} [This=any]
  *  The `this` context
+ * @template {Awaitable<Next>} [Result=Awaitable<Next>]
+ *  The next awaitable
  *
  * @this {void}
  *
@@ -143,10 +354,10 @@ declare function isThenable<T>(this: void, value: unknown): value is PromiseLike
  *  The `this` context of the chain and `fail` callbacks
  * @param {Args} args
  *  The arguments to pass to the chain callback
- * @return {Awaitable<Next>}
+ * @return {Result}
  *  The next awaitable
  */
-declare function when<T, Next = any, Args extends any[] = any[], This = unknown>(this: void, value: Awaitable<T>, chain: Chain<T, Next, Args, This>, fail?: null | undefined, context?: This | null | undefined, ...args: Args): Awaitable<Next>;
+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.
@@ -167,6 +378,8 @@ declare function when<T, Next = any, Args extends any[] = any[], This = unknown>
  *  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}
  *
@@ -180,10 +393,10 @@ declare function when<T, Next = any, Args extends any[] = any[], This = unknown>
  *  The `this` context of the chain and `fail` callbacks
  * @param {Args} args
  *  The arguments to pass to the chain callback
- * @return {Awaitable<Failure | Next>}
+ * @return {Result}
  *  The next awaitable
  */
-declare function when<T, Next = any, Failure = Next, Args extends any[] = any[], Error = any, This = unknown>(this: void, value: Awaitable<T>, chain: Chain<T, Next, Args, This>, fail?: Fail<Failure, Error, This> | null | undefined, context?: This | null | undefined, ...args: Args): Awaitable<Failure | 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 a thenable.
@@ -203,6 +416,8 @@ declare function when<T, Next = any, Failure = Next, Args extends any[] = 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}
  *
@@ -210,22 +425,52 @@ declare function when<T, Next = any, Failure = Next, Args extends any[] = any[],
  *  The current awaitable
  * @param {Options<T, Next, Failure, Args, Error, This>} chain
  *  Options for chaining
- * @return {Awaitable<Failure | Next>}
+ * @return {Result}
  *  The next awaitable
  */
-declare function when<T, Next = any, Failure = Next, Args extends any[] = any[], Error = any, This = unknown>(this: void, value: Awaitable<T>, chain: Options<T, Next, Failure, Args, Error, This>): Awaitable<Failure | 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
@@ -269,19 +514,158 @@ type Chain<T = any, Next = any, Args extends readonly any[] = any[], This = unkn
  *
  * @template {any} [Next=any]
  *  The next resolved value
- * @template {any} [Error=any]
- *  The error to handle
+ * @template {any} [Reason=any]
+ *  The reason for the failure
+ * @template {any} [This=unknown]
+ *  The `this` context
+ *
+ * @this {This}
+ *
+ * @param {Reason} reason
+ *  The reason for the failure
+ * @return {Awaitable<Next>}
+ *  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}
  *
- * @param {unknown} e
- *  The error
+ * @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 Fail<Next = any, Error = any, This = unknown> = (this: This, e: Error) => Awaitable<Next>;
+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 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, isPromise, isThenable as isPromiseLike, isThenable, when };
-export type { Awaitable, Chain, Fail, Options };
+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 };

package/dist/lib/index.mjs

@@ -2,6 +2,9 @@
  * @file Entry Point - Library
  * @module when/lib
  */
+export { default as isCatchable } from '#lib/is-catchable';
+export { default as isFinalizable } from '#lib/is-finalizable';
 export { default as isPromise } from '#lib/is-promise';
-export { default as isPromiseLike, default as isThenable } from '#lib/is-thenable';
+export { default as isPromiseLike } from '#lib/is-promise-like';
+export { default as isThenable } from '#lib/is-thenable';
 export { default as when } from '#lib/when';

package/dist/lib/is-catchable.mjs

@@ -0,0 +1,24 @@
+/**
+ * @file isCatchable
+ * @module when/lib/isCatchable
+ */
+import isThenable from '#lib/is-thenable';
+/**
+ * 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
+ */
+function isCatchable(value) {
+    return isThenable(value) && typeof value.catch === 'function';
+}
+export default isCatchable;

package/dist/lib/is-finalizable.mjs

@@ -0,0 +1,24 @@
+/**
+ * @file isFinalizable
+ * @module when/lib/isFinalizable
+ */
+import isThenable from '#lib/is-thenable';
+/**
+ * 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
+ */
+function isFinalizable(value) {
+    return isThenable(value) && typeof value.finally === 'function';
+}
+export default isFinalizable;

package/dist/lib/is-promise-like.mjs

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+function isPromiseLike(value) {
+    if (typeof value !== 'function' && typeof value !== 'object')
+        return false;
+    return !!value && 'then' in value && typeof value.then === 'function';
+}
+export default isPromiseLike;

package/dist/lib/is-promise.mjs

@@ -2,12 +2,14 @@
  * @file isPromise
  * @module when/lib/isPromise
  */
+import isCatchable from '#lib/is-catchable';
+import isFinalizable from '#lib/is-finalizable';
 import isThenable from '#lib/is-thenable';
 /**
  * Check if `value` looks like a {@linkcode Promise}.
  *
- * > 👉 **Note**: This function intentionally performs a structural check
- * > instead of a brand check.
+ * > 👉 **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.
  *
@@ -20,12 +22,16 @@ import isThenable from '#lib/is-thenable';
  *
  * @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, `false` otherwise
+ *  `true` if `value` is a thenable with a `catch` method,
+ *  and `finally` method (if requested), `false` otherwise
  */
-function isPromise(value) {
-    if (!isThenable(value))
+function isPromise(value, finalizable) {
+    if (!(isThenable(value) && isCatchable(value)))
         return false;
-    return 'catch' in value && typeof value.catch === 'function';
+    return finalizable ?? true ? isFinalizable(value) : true;
 }
 export default isPromise;