@flex-development/when 1.0.0 → 3.0.0

package/dist/lib/index.mjs

@@ -2,5 +2,9 @@
  * @file Entry Point - Library
  * @module when/lib
  */
-export { default as isPromiseLike, default as isThenable } from '#lib/is-thenable';
+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 } 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

@@ -0,0 +1,37 @@
+/**
+ * @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 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
+ */
+function isPromise(value, finalizable) {
+    if (!(isThenable(value) && isCatchable(value)))
+        return false;
+    return finalizable ?? true ? isFinalizable(value) : true;
+}
+export default isPromise;

package/dist/lib/is-thenable.mjs

@@ -2,8 +2,12 @@
  * @file isThenable
  * @module when/lib/isThenable
  */
+import hasThen from '#lib/is-promise-like';
+export default 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
@@ -12,14 +16,34 @@
  *
  * @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
  */
 function isThenable(value) {
-    return (!Array.isArray(value) &&
-        typeof value === 'object' &&
-        value !== null &&
-        'then' in value &&
-        typeof value.then === 'function');
+    if (!hasThen(value))
+        return false; // no `then` method, cannot be a thenable.
+    // a thenable without a `catch` or `finally` method.
+    if (!('catch' in value) && !('finally' in value))
+        return true;
+    // cannot be a thenable, invalid `catch` property.
+    if (!maybeCallable(value['catch']))
+        return false;
+    // cannot be a thenable, invalid `finally` property.
+    if (!maybeCallable(value['finally']))
+        return false;
+    return true; // thenable.
+}
+/**
+ * @internal
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @return {((...args: any[]) => any) | null | undefined}
+ *  `true` if `value` is a function, `null`, or `undefined`, `false` otherwise
+ */
+function maybeCallable(value) {
+    return value == null || typeof value === 'function';
 }
-export default isThenable;

package/dist/lib/when.mjs

@@ -2,61 +2,144 @@
  * @file when
  * @module when/lib/when
  */
+import isCatchable from '#lib/is-catchable';
+import isFinalizable from '#lib/is-finalizable';
 import isThenable from '#lib/is-thenable';
 export default when;
 /**
  * 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 Chain}
  * @see {@linkcode Options}
- * @see {@linkcode Reject}
+ * @see {@linkcode Fail}
  *
  * @this {void}
  *
  * @param {unknown} value
- *  The promise or the resolved value
+ *  The current awaitable
  * @param {Chain<any, unknown> | Options} chain
  *  The chain callback or options for chaining
- * @param {Reject | null | undefined} [reject]
- *  The callback to fire when a promise is rejected or an error is thrown
+ * @param {Fail | null | undefined} [fail]
+ *  The callback to fire when a failure occurs
  * @param {unknown} [context]
- *  The `this` context of the chain and error callbacks
+ *  The `this` context of the chain and `fail` callbacks
  * @param {unknown[]} args
  *  The arguments to pass to the chain callback
  * @return {unknown}
- *  The next promise or value
+ *  The next awaitable
  */
-function when(value, chain, reject, context, ...args) {
+function when(value, chain, fail, context, ...args) {
+    /**
+     * The post-processing hook.
+     *
+     * @var {Finish | null | undefined}
+     */
+    let finish;
+    /**
+     * Whether the post-processing hook ran.
+     *
+     * @var {boolean}
+     */
+    let finished = false;
     if (typeof chain === 'object') {
-        reject = chain.reject;
+        fail = chain.fail;
+        finish = chain.finish;
         context = chain.context;
         args = chain.args ?? [];
         chain = chain.chain;
     }
-    // no promise, call chain function immediately.
+    // no thenable, call chain function immediately.
     if (!isThenable(value)) {
         try {
-            return chain.call(context, ...args, value);
+            // try attaching "global" rejection handler with `catch`,
+            // then try running `finish`, or attaching it with `finally`.
+            return finalize(katch(chain.call(context, ...args, value)));
         }
         catch (e) {
-            return fail(e);
+            return finalize(katch(failure(e)));
         }
     }
-    // already have a promise, chain callback.
-    return value.then(resolved => chain.call(context, ...args, resolved), fail);
+    // already have a thenable, chain the chain callback.
+    value = value.then(res => chain.call(context, ...args, res), failure);
+    // try attaching "global" rejection handler with `catch`,
+    // then try running `finish`, or attaching it with `finally`.
+    return finalize(katch(value));
     /**
      * @this {void}
      *
      * @param {unknown} e
      *  The error to handle
      * @return {unknown}
-     *  The rejection result
+     *  The rejection result or never, may throw `e`
+     */
+    function failure(e) {
+        if (typeof fail !== 'function')
+            return thrower(e);
+        return fail.call(context, e);
+    }
+    /**
+     * @this {void}
+     *
+     * @return {undefined}
+     */
+    function fin() {
+        return void (finished || (finished = true, finish?.call(context)));
+    }
+    /**
+     * @this {void}
+     *
+     * @param {unknown} value
+     *  The awaitable
+     * @return {unknown}
+     *  The `value`
+     */
+    function finalize(value) {
+        if (typeof finish === 'function') {
+            if (isFinalizable(value))
+                return value.finally(fin);
+            if (isThenable(value))
+                return value.then(identity, thrower);
+        }
+        return identity(value);
+        /**
+         * @this {void}
+         *
+         * @param {unknown} value
+         *  The resolved value
+         * @return {unknown}
+         *  The `value`
+         */
+        function identity(value) {
+            return fin(), value;
+        }
+    }
+    /**
+     * Try attaching a rejection handler with `catch`.
+     *
+     * @this {void}
+     *
+     * @param {unknown} value
+     *  The awaitable
+     * @return {unknown}
+     *  The `value`
+     */
+    function katch(value) {
+        if (isCatchable(value))
+            value = value.catch(failure);
+        return value;
+    }
+    /**
+     * @this {void}
+     *
+     * @param {unknown} e
+     *  The error to throw
+     * @return {never}
+     *  Never; throws `e`
      * @throws {unknown}
      */
-    function fail(e) {
-        if (typeof reject !== 'function')
-            throw e;
-        return reject.call(context, e);
+    function thrower(e) {
+        void fin();
+        throw e;
     }
 }

package/dist/testing/index.d.mts

@@ -0,0 +1,149 @@
+import type { Thenable, Awaitable } from '@flex-development/when';
+
+/**
+ * @file Interfaces - CreateThenableOptions
+ * @module when/testing/interfaces/CreateThenableOptions
+ */
+/**
+ * Options for creating a thenable.
+ */
+interface CreateThenableOptions {
+    /**
+     * Control whether returned thenables implement a `catch` method.
+     *
+     * When an options object is omitted, `null`, or `undefined`,
+     * the method will be implemented.
+     *
+     * When an options object is provided, `catch` is only implemented
+     * if `options.catch` is `true`.
+     *
+     * If `options.catch` is `null` or `undefined`, the thenable's `catch`
+     * property will have the same value.\
+     * Pass `false` to disable the method implementation.
+     */
+    catch?: boolean | null | undefined;
+    /**
+     * Control whether returned thenables implement a `finally` method.
+     *
+     * When an options object is omitted, `null`, or `undefined`,
+     * the method will be implemented.
+     *
+     * When an options object is provided, `finally` is only implemented
+     * if `options.finally` is `true`.
+     *
+     * If `options.finally` is `null` or `undefined`, the thenable's `finally`
+     * property will have the same value.\
+     * Pass `false` to disable the method implementation.
+     */
+    finally?: boolean | null | undefined;
+}
+
+/**
+ * @file createThenable
+ * @module when/testing/lib/createThenable
+ */
+
+/**
+ * Create a thenable.
+ *
+ * The returned object conforms to {@linkcode Thenable} and ensures `then`
+ * always returns another {@linkcode Thenable}, even when adopting a foreign
+ * thenable.
+ *
+ * When `options` is omitted, `null`, or `undefined`, the returned thenable is
+ * *modern* (a thenable with `then`, `catch`, and `finally` methods).
+ * Pass an options object (e.g. `{}`) to start from a *bare* (`then` method
+ * only) thenable and selectively enable methods.
+ *
+ * @see {@linkcode CreateThenableOptions}
+ * @see {@linkcode Executor}
+ * @see {@linkcode Thenable}
+ *
+ * @template {any} T
+ *  The resolved value
+ * @template {any} [Reason=Error]
+ *  The reason for a rejection
+ * @template {Thenable<T>} [Result=Thenable<T>]
+ *  The thenable
+ *
+ * @this {void}
+ *
+ * @param {Executor<T, Reason>} executor
+ *  The initialization callback
+ * @param {CreateThenableOptions | null | undefined} [options]
+ *  Options for creating a thenable
+ * @return {Result}
+ *  The thenable
+ */
+declare function createThenable<T, Reason = Error, Result extends Thenable<T> = Thenable<T>>(this: void, executor: Executor<T, Reason>, options?: CreateThenableOptions | null | undefined): Result;
+
+/**
+ * @file Type Aliases - Executor
+ * @module when/testing/types/Executor
+ */
+
+/**
+ * The callback used to initialize a thenable.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Resolve}
+ * @see {@linkcode Reject}
+ *
+ * @template {any} [T=any]
+ *  The resolved value
+ * @template {any} [Reason=Error]
+ *  The reason for a rejection
+ *
+ * @this {void}
+ *
+ * @param {Resolve<T>} resolve
+ *  The callback used to resolve the thenable with a value
+ *  or the result of another awaitable
+ * @param {Reject<Reason>} reject
+ *  The callback used to reject the thenable with a provided reason or error
+ * @return {undefined | void}
+ */
+type Executor<T = any, Reason = Error> = (this: void, resolve: Resolve<T>, reject: Reject<Reason>) => undefined | void;
+
+/**
+ * @file Type Aliases - Reject
+ * @module when/testing/types/Reject
+ */
+/**
+ * The callback used to reject a thenable with a provided reason or error.
+ *
+ * @template {any} [Reason=Error]
+ *  The reason for the rejection
+ *
+ * @this {void}
+ *
+ * @param {Reason} reason
+ *  The reason for the rejection
+ * @return {undefined}
+ */
+type Reject<Reason = Error> = (this: void, reason: Reason) => undefined;
+
+/**
+ * @file Type Aliases - Resolve
+ * @module when/testing/types/Resolve
+ */
+
+/**
+ * The callback used to resolve a thenable with a value
+ * or the result of another awaitable.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {any} [T=any]
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {Awaitable<T>} value
+ *  The awaitable
+ * @return {undefined}
+ */
+type Resolve<T = any> = (this: void, value: Awaitable<T>) => undefined;
+
+export { createThenable };
+export type { CreateThenableOptions, Executor, Reject, Resolve };

package/dist/testing/index.mjs

@@ -0,0 +1,5 @@
+/**
+ * @file Package Entry Point
+ * @module when/testing
+ */
+export * from '#testing/lib/index';