@flex-development/when 1.0.0 → 3.0.0

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';

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "@flex-development/when",
-  "description": "Like .then, but for synchronous values and thenables",
-  "version": "1.0.0",
+  "description": "Chain callbacks on synchronous values or thenables without forcing Promise.resolve or microtasks.",
+  "version": "3.0.0",
   "keywords": [
     "async",
     "await",
     "awaitable",
     "callback",
     "chain",
+    "esm",
+    "functional",
+    "hooks",
+    "microtask",
+    "pipeline",
     "promise",
+    "promise-like",
     "sync",
     "synchronous",
     "then",
     "thenable",
-    "typescript"
+    "typescript",
+    "utility"
   ],
   "license": "BSD-3-Clause",
   "homepage": "https://github.com/flex-development/when",
@@ -48,7 +55,11 @@
       "when": "./src/index.mts",
       "default": "./dist/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./testing": {
+      "when": "./src/testing/index.mts",
+      "default": "./dist/testing/index.mjs"
+    }
   },
   "imports": {
     "#fixtures/*": "./__fixtures__/*.mts",
@@ -60,6 +71,10 @@
       "when": "./src/lib/*.mts",
       "default": "./dist/lib/*.mjs"
     },
+    "#testing/*": {
+      "when": "./src/testing/*.mts",
+      "default": "./dist/testing/*.mjs"
+    },
     "#tests/*": "./__tests__/*.mts",
     "#types/*": {
       "when": "./src/types/*.mts",
@@ -75,7 +90,7 @@
   },
   "scripts": {
     "build": "yarn clean:build && tsc -p tsconfig.build.json --noEmit false && yarn bundle:dts",
-    "bundle:dts": "rollup --config=rollup.config.mts && trash dist/{interfaces,types} && trash dist/{internal,lib}/*.d.mts",
+    "bundle:dts": "rollup --config=rollup.config.mts && trash dist/**/{interfaces,types} && trash dist/**/lib/*.d.mts",
     "check:ci": "yarn dedupe --check && yarn check:format && yarn check:lint && yarn check:spelling && yarn typecheck && yarn check:types && yarn test:cov && yarn pack && yarn check:types:build && attw package.tgz && yarn clean:pack",
     "check:format": "dprint check --incremental=false",
     "check:lint": "eslint --exit-on-fatal-error --max-warnings 0 .",
@@ -114,9 +129,10 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.2",
-    "@commitlint/cli": "20.4.1",
+    "@commitlint/cli": "20.4.2",
     "@commitlint/types": "20.4.0",
     "@edge-runtime/vm": "5.0.0",
+    "@faker-js/faker": "10.3.0",
     "@flex-development/commitlint-config": "1.0.1",
     "@flex-development/eslint-config": "1.1.1",
     "@flex-development/grease": "3.0.0-alpha.9",
@@ -134,20 +150,20 @@
     "@vitest/ui": "4.0.18",
     "concat-stream": "2.0.0",
     "cross-env": "10.1.0",
-    "cspell": "9.6.4",
+    "cspell": "9.7.0",
     "devlop": "1.1.0",
     "dprint": "0.51.1",
     "editorconfig": "3.0.1",
     "eslint": "9.39.2",
     "growl": "1.10.5",
-    "happy-dom": "20.6.2",
+    "happy-dom": "20.7.0",
     "husky": "9.1.7",
     "is-ci": "4.1.0",
     "node-notifier": "10.0.1",
     "pkg-size": "2.4.0",
     "remark": "15.0.1",
     "remark-cli": "12.0.1",
-    "rollup": "4.57.1",
+    "rollup": "4.59.0",
     "rollup-plugin-dts": "6.3.0",
     "sh-syntax": "0.5.8",
     "trash-cli": "7.2.0",