@flex-development/when 2.0.0 → 3.0.0

package/dist/lib/is-thenable.mjs

@@ -2,9 +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,
- * i.e. a {@linkcode PromiseLike} object.
+ * Check if `value` looks like a {@linkcode Thenable}.
+ *
+ * @see {@linkcode Thenable}
  *
  * @template {any} T
  *  The resolved value
@@ -13,15 +16,34 @@
  *
  * @param {unknown} value
  *  The thing to check
- * @return {value is PromiseLike<T>}
+ * @return {value is Thenable<T>}
  *  `true` if `value` is an object or function with a `then` method,
- *  `false` otherwise
+ *  and maybe-callable methods `catch` and/or `finally`, `false` otherwise
  */
 function isThenable(value) {
-    if (!value)
+    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;
-    if (typeof value !== 'function' && typeof value !== 'object')
+    // cannot be a thenable, invalid `finally` property.
+    if (!maybeCallable(value['finally']))
         return false;
-    return 'then' in value && typeof value.then === 'function';
+    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,7 +2,8 @@
  * @file when
  * @module when/lib/when
  */
-import isPromise from '#lib/is-promise';
+import isCatchable from '#lib/is-catchable';
+import isFinalizable from '#lib/is-finalizable';
 import isThenable from '#lib/is-thenable';
 export default when;
 /**
@@ -29,40 +30,90 @@ export default when;
  *  The next awaitable
  */
 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') {
         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 {
-            // try attaching "global" rejection handler with `catch`.
-            return katch(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 failure(e);
+            return finalize(katch(failure(e)));
         }
     }
-    // already have a promise, chain the chain callback.
+    // 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`.
-    return katch(value);
+    // 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
-     * @throws {unknown}
+     *  The rejection result or never, may throw `e`
      */
     function failure(e) {
         if (typeof fail !== 'function')
-            throw e;
+            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`.
      *
@@ -74,8 +125,21 @@ function when(value, chain, fail, context, ...args) {
      *  The `value`
      */
     function katch(value) {
-        if (isPromise(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 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';

package/dist/testing/lib/create-thenable.mjs

@@ -0,0 +1,350 @@
+/**
+ * @file createThenable
+ * @module when/testing/lib/createThenable
+ */
+import isThenable from '#lib/is-thenable';
+export default 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
+ */
+function createThenable(executor, options) {
+    /**
+     * Whether the thenable has been settled.
+     *
+     * @var {boolean} settled
+     */
+    let settled = false;
+    /**
+     * The settled state.
+     *
+     * @var {State<T, Reason> | undefined} state
+     */
+    let state;
+    try {
+        executor(ok, nok);
+    }
+    catch (e) {
+        nok(e);
+    }
+    //  executor neither resolved nor rejected, treat as `ok(undefined)`.
+    if (!state)
+        ok(undefined);
+    return wrapState(state);
+    /**
+     * Adopt an awaitable into a {@linkcode Thenable}.
+     *
+     * If `x` is a thenable, the returned thenable follows its settlement.
+     * Otherwise, the returned thenable is immediately resolved with `x`.
+     *
+     * @template {any} X
+     *  The resolved value
+     *
+     * @this {void}
+     *
+     * @param {Awaitable<X>} x
+     *  The awaitable to adopt
+     * @return {Thenable<X>}
+     *  A thenable representing the adopted awaitable
+     */
+    function adopt(x) {
+        if (isThenable(x)) {
+            // wrap foreign thenable so `then` still returns a thenable.
+            return addMethods({
+                /**
+                 * @template {any} [Next=X]
+                 *  The next resolved value on success
+                 * @template {any} [Failure=never]
+                 *  The next resolved value on failure
+                 *
+                 * @this {void}
+                 *
+                 * @param {OnFulfilled<X, Next> | null | undefined} [onfulfilled]
+                 *  The callback to execute when the thenable is resolved
+                 * @param {OnRejected<Failure, Reason> | null | undefined} [onrejected]
+                 *  The callback to execute when the thenable is rejected
+                 * @return {Thenable<Failure | Next>}
+                 *  The next thenable
+                 */
+                then(onfulfilled, onrejected) {
+                    return adopt(x.then(
+                    /**
+                     * @this {void}
+                     *
+                     * @param {X} value
+                     *  The resolved value
+                     * @return {Awaitable<Next>}
+                     *  The next awaitable
+                     */
+                    function succ(value) {
+                        return resolve(value, onfulfilled);
+                    }, 
+                    /**
+                     * @this {void}
+                     *
+                     * @param {unknown} e
+                     *  The reason for the rejection
+                     * @return {Awaitable<Failure>}
+                     *  The next awaitable
+                     */
+                    function fail(e) {
+                        return reject(e, onrejected);
+                    }));
+                }
+            });
+        }
+        return wrapState({ ok: true, value: x });
+    }
+    /**
+     * Add requested methods to a `thenable`.
+     *
+     * @template {any} U
+     *  The resolved value
+     *
+     * @this {void}
+     *
+     * @param {Thenable<U>} thenable
+     *  The current thenable
+     * @return {Thenable<U>}
+     *  The `thenable`
+     */
+    function addMethods(thenable) {
+        if (!options) {
+            thenable.catch = katch;
+            thenable.finally = finalize;
+            return thenable;
+        }
+        if (options.catch) {
+            thenable.catch = katch;
+        }
+        else if ('catch' in options && options.catch !== false) {
+            thenable.catch = options.catch;
+        }
+        if (options.finally) {
+            thenable.finally = finalize;
+        }
+        else if ('finally' in options && options.finally !== false) {
+            thenable.finally = options.finally;
+        }
+        return thenable;
+    }
+    /**
+     * Attach a callback that is invoked only when `this` thenable is settled.
+     *
+     * @template {any} U
+     *  The resolved value
+     *
+     * @this {Thenable<U>}
+     *
+     * @param {OnFinally | null | undefined} [onfinally]
+     *  The callback to execute when the thenable is settled
+     * @return {Thenable<U>}
+     *  The next thenable
+     */
+    function finalize(onfinally) {
+        return typeof onfinally === 'function' ? this.then(succ, fail) : this;
+        /**
+         * @this {void}
+         *
+         * @param {unknown} reason
+         *  The reason for the rejection
+         * @return {never}
+         *  Never; throws `reason`
+         * @throws {unknown}
+         */
+        function fail(reason) {
+            void onfinally();
+            throw reason;
+        }
+        /**
+         * @this {void}
+         *
+         * @param {U} value
+         *  The resolved value
+         * @return {U}
+         *  The resolved `value`
+         */
+        function succ(value) {
+            return void onfinally(), value;
+        }
+    }
+    /**
+     * Attach a callback only for the rejection of `this` thenable.
+     *
+     * @template {any} U
+     *  The resolved value
+     * @template {any} [Failure=never]
+     *  The resolved value on failure
+     *
+     * @this {Thenable<U>}
+     *
+     * @param {OnRejected<Failure, Reason> | null | undefined} [onrejected]
+     *  The callback to execute when the thenable is rejected
+     * @return {Thenable<Failure | U>}
+     *  The next thenable
+     */
+    function katch(onrejected) {
+        return this.then(null, onrejected);
+    }
+    /**
+     * Reject the thenable.
+     *
+     * @this {void}
+     *
+     * @param {Reason} reason
+     *  The reason for the rejection
+     * @return {undefined}
+     */
+    function nok(reason) {
+        return void (settled || (settled = true, state = { ok: false, reason }));
+    }
+    /**
+     * Resolve the thenable.
+     *
+     * @this {void}
+     *
+     * @param {Awaitable<T>} value
+     *  The awaitable
+     * @return {undefined}
+     */
+    function ok(value) {
+        return void (settled || (settled = true, state = { ok: true, value }));
+    }
+    /**
+     * Handle a rejection.
+     *
+     * @template {any} T
+     *  The next resolved value
+     *
+     * @this {void}
+     *
+     * @param {unknown} reason
+     *  The reason for the rejection
+     * @param {OnRejected<T, Reason> | null | undefined} [onrejected]
+     *  The callback to execute when the thenable is rejected
+     * @return {Awaitable<T>}
+     *  The next awaitable
+     */
+    function reject(reason, onrejected) {
+        if (typeof onrejected === 'function')
+            return onrejected(reason);
+        return wrapState({ ok: false, reason: reason });
+    }
+    /**
+     * Handle a resolved `value`.
+     *
+     * @template {any} T
+     *  The resolved value
+     * @template {any} Next
+     *  The next resolved value
+     * @this {void}
+     *
+     * @param {T} value
+     *  The resolved value
+     * @return {Awaitable<Next>}
+     *  The next awaitable
+     */
+    function resolve(value, onfulfilled) {
+        if (typeof onfulfilled === 'function')
+            return onfulfilled(value);
+        return value;
+    }
+    /**
+     * Wrap a settled state into a {@linkcode Thenable}.
+     *
+     * @template {any} S
+     *  The resolved value
+     *
+     * @this {void}
+     *
+     * @param {State} s
+     *  The settled state
+     * @return {Thenable<S>}
+     *  A thenable representing the settled state
+     */
+    function wrapState(s) {
+        return addMethods({
+            /**
+             * @template {any} [Next=S]
+             *  The next resolved value on success
+             * @template {any} [Failure=never]
+             *  The next resolved value on failure
+             *
+             * @this {void}
+             *
+             * @param {OnFulfilled<S, Next> | null | undefined} [onfulfilled]
+             *  The callback to execute when the thenable is resolved
+             * @param {OnRejected<Failure, Reason> | null | undefined} [onrejected]
+             *  The callback to execute when the thenable is rejected
+             * @return {Thenable<Failure | Next>}
+             *  The next thenable
+             */
+            then(onfulfilled, onrejected) {
+                try {
+                    if (s.ok) {
+                        if (isThenable(s.value))
+                            return adopt(s.value).then(succ, fail);
+                        return adopt(succ(s.value));
+                        /**
+                         * @this {void}
+                         *
+                         * @param {S} value
+                         *  The resolved value
+                         * @return {Awaitable<Next>}
+                         *  The next awaitable
+                         */
+                        function succ(value) {
+                            return resolve(value, onfulfilled);
+                        }
+                    }
+                    // rejected.
+                    if (typeof onrejected === 'function')
+                        return adopt(fail(s.reason));
+                    return wrapState({ ok: false, reason: s.reason });
+                }
+                catch (e) {
+                    return wrapState({ ok: false, reason: e });
+                }
+                /**
+                 * @this {void}
+                 *
+                 * @param {unknown} e
+                 *  The reason for the rejection
+                 * @return {Awaitable<Failure>}
+                 *  The next awaitable
+                 */
+                function fail(e) {
+                    return reject(e, onrejected);
+                }
+            }
+        });
+    }
+}

package/dist/testing/lib/index.mjs

@@ -0,0 +1,5 @@
+/**
+ * @file Entry Point - Library
+ * @module when/testing/lib
+ */
+export { default as createThenable } from '#testing/lib/create-thenable';