@flex-development/when 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [2.0.0](https://github.com/flex-development/when/compare/1.0.0...2.0.0) (2026-02-19)
+
+### ⚠ BREAKING CHANGES
+
+- `catch` support
+
+### :package: Build
+
+- [[`dd93b19`](https://github.com/flex-development/when/commit/dd93b19904b21760b5ae86a48fe7b7127adbcf95)] **deps-dev:** Bump @commitlint/cli from 20.4.1 to 20.4.2 in the commitlint group ([#9](https://github.com/flex-development/when/issues/9))
+- [[`9229069`](https://github.com/flex-development/when/commit/9229069b28f05bf3394c29d85ec3261c6246959b)] **deps-dev:** Bump happy-dom from 20.6.2 to 20.6.3 ([#10](https://github.com/flex-development/when/issues/10))
+
+### :sparkles: Features
+
+- [[`8d8f17f`](https://github.com/flex-development/when/commit/8d8f17f847ac90d5633d87c554229bbd42d9a1cf)] `catch` support
+- [[`003be0f`](https://github.com/flex-development/when/commit/003be0f34d1e626b0ee6ea940d73f0babd12df78)] **lib:** `isPromise`
+
 ## 1.0.0 (2026-02-18)
 
 ### :package: Build
@@ -71,3 +87,4 @@
 
 
 
+

package/README.md

@@ -17,44 +17,72 @@ like `.then`, but for synchronous values *and* thenables.
 ## Contents
 
 - [What is this?](#what-is-this)
+- [When should I use this?](#when-should-i-use-this)
   - [Why not `Promise.resolve`?](#why-not-promiseresolve)
+  - [Design guarantees](#design-guarantees)
 - [Install](#install)
 - [Use](#use)
   - [Chain a synchronous value](#chain-a-synchronous-value)
   - [Chain a *thenable*](#chain-a-thenable)
   - [Pass arguments to the chain callback](#pass-arguments-to-the-chain-callback)
-  - [Handle rejections / thrown errors](#handle-rejections--thrown-errors)
+  - [Handle failures](#handle-failures)
   - [Bind `this` context](#bind-this-context)
   - [Use an options object](#use-an-options-object)
 - [API](#api)
+  - [`isPromise<T>(value)`][ispromise]
   - [`isThenable<T>(value)`][isthenable]
-  - [`when<[T][, Next][, Args][, Self]>(value, chain[, reject][, context][, ...args])`][when]
+  - [`when<T[, Next][, Failure][, Args][, Error][, This]>(value, chain[, reject][, context][, ...args])`][when]
 - [Types](#types)
   - [`Awaitable<T>`][awaitable]
-  - [`Chain<[T][, Next][, Args][, Self]>`][chain]
-  - [`Options<[T][, Next][, Args][, Self]>`][options]
-  - [`Reject<[Next][, Fail][, Self]>`][reject]
+  - [`Chain<[T][, Next][, Args][, This]>`][chain]
+  - [`Fail<[Next][, Error][, This]>`][fail]
+  - [`Options<[T][, Next][, Failure][, Args][, Error][, This]>`][options]
 - [Glossary](#glossary)
 - [Project](#project)
   - [Version](#version)
   - [Contribute](#contribute)
+  - [Sponsor](#sponsor)
 
 ## What is this?
 
-`when` is a small, but useful package for chaining a callback
-onto an [awaitable][] (a value or a [*thenable*][thenable]).
+`when` is a tiny primitive for chaining callbacks
+onto [awaitables][awaitable] (synchronous or [*thenable*][thenable] values).
 
-For thenable values, `.then` is used to invoke the callback after resolution.
-Otherwise, the callback is called immediately.
-This makes it easy to write one code path that supports both synchronous and asynchronous values.
+For thenable values, `then` is used to invoke the callback after resolution. Otherwise, the callback fires immediately.
+This makes it easy to write one code path that supports both synchronous values and promises.
 
-`when` is especially useful in libraries supporting awaitable APIs or libraries that accept user-provided hooks,
-loaders, or resolvers that may or may not return promises.
+## When should I use this?
 
-### Why not `Promise.resolve`?
+`when` is especially useful in libraries implementing awaitable APIs.
 
-`when` preserves synchronous values when possible, thus avoiding microtask scheduling and needless promise-allocation
-for these values, as well as making it a great choice for libraries offering API flexibility.
+It provides [`Promise.then`][promise-then] semantics without forcing [`Promise.resolve`][promise-resolve],
+preserving synchronous execution whenever possible.
+
+Typical use cases include plugin systems, hook pipelines, module resolvers, data loaders, and file system adapters where
+users may return both synchronous or asynchronous values.
+
+If you're only dealing with promises and thenables, consider using native `async/await` or `Promise` chaining instead.
+
+### Why not [`Promise.resolve`][promise-resolve]?
+
+`when` preserves synchronous operations whenever possible,
+avoiding unnecessary promise allocation and microtask scheduling.
+
+```ts
+Promise.resolve(value).then(fn) // always a promise
+```
+
+```ts
+when(value, fn) // only a promise if `value` is a thenable, or `fn` returns one
+```
+
+### Design guarantees
+
+- Synchronous values remain synchronous
+- [*Thenable*s][thenable] are chained without wrapping in [`Promise.resolve`][promise-resolve]
+- No additional microtasks are scheduled for non-thenables
+- Failures propagate unless a `fail` handler is provided
+- Returned thenables are preserved without additional wrapping
 
 ## Install
 
@@ -125,7 +153,7 @@ console.dir(await result) // 3
 
 ### Pass arguments to the chain callback
 
-Arguments are passed first, and the resolved value is passed last.
+When arguments are provided, they are passed to the `chain` callback first, followed by the resolved value.
 
 When the `value` passed to `when` is not [*thenable*][thenable], the resolved value is the same `value`.
 
@@ -137,12 +165,23 @@ import when, { type Awaitable } from '@flex-development/when'
  *
  * @const {Awaitable<number>} result
  */
-const result: Awaitable<number> = when(1, Math.min, null, undefined, 2, 3, 4)
+const result: Awaitable<number> = when(
+  1, // last argument passed to `Math.min`
+  Math.min, // `chain`
+  null, // `fail`
+  undefined, // `context`
+  2, // first argument passed to `Math.min`
+  3, // second argument passed to `Math.min`
+  4 // third argument passed to `Math.min`
+)
 
 console.dir(result) // 1
 ```
 
-### Handle rejections / thrown errors
+### Handle failures
+
+For [*thenable*s][thenable], the `fail` callback is passed to `then` as the `onrejected` parameter,
+and if implemented, to `catch` as well to prevent unhandled rejections.
 
 ```ts
 import when, { type Awaitable } from '@flex-development/when'
@@ -161,7 +200,7 @@ const value: PromiseLike<never> = new Promise((resolve, reject) => {
  *
  * @const {Awaitable<boolean>} result
  */
-const result: Awaitable<boolean> = when(value, chain, reject)
+const result: Awaitable<boolean> = when(value, chain, fail)
 
 console.dir(await result) // false
 
@@ -183,7 +222,7 @@ function chain(this: void): true {
  * @return {false}
  *  The failure result
  */
-function reject(this: void, e: Error): false {
+function fail(this: void, e: Error): false {
   return console.dir(e), false
 }
 ```
@@ -246,7 +285,7 @@ const result: Awaitable<number | undefined> = when(value, {
   args: [39],
   chain: divide,
   context: { errors: [] },
-  reject
+  fail
 })
 
 console.dir(await result) // 13
@@ -272,7 +311,7 @@ function divide(this: void, dividend: number, divisor: number): number {
  *  The error to handle
  * @return {undefined}
  */
-function reject(this: Context, e: Error): undefined {
+function fail(this: Context, e: Error): undefined {
   return void this.errors.push(e)
 }
 ```
@@ -283,9 +322,31 @@ function reject(this: Context, e: Error): undefined {
 
 The default export is [`when`][when].
 
+### `isPromise<T>(value)`
+
+Check if `value` looks like a `Promise`.
+
+> 👉 **Note**: This function intentionally performs a structural check instead of a brand check.
+> It does not rely on `instanceof Promise` or constructors, making it compatible with cross-realm promises
+> and custom thenables.
+
+#### Type Parameters
+
+- `T` (`any`)
+  — the resolved value
+
+#### Parameters
+
+- `value` (`unknown`)
+  — the thing to check
+
+#### Returns
+
+(`value is Promise<T>`) `true` if `value` is a [*thenable*][thenable] with a `catch` method, `false` otherwise
+
 ### `isThenable<T>(value)`
 
-Check if `value` looks like a [*thenable*][thenable].
+Check if `value` looks like a [*thenable*][thenable], i.e. a `PromiseLike` object.
 
 > 👉 **Note**: Also exported as `isPromiseLike`.
 
@@ -301,15 +362,16 @@ Check if `value` looks like a [*thenable*][thenable].
 
 #### Returns
 
-(`value is PromiseLike<T>`) `true` if `value` is a thenable, `false` otherwise
+(`value is PromiseLike<T>`) `true` if `value` is an object or function with a `then` method, `false` otherwise
 
 <!--lint disable-->
 
-### `when<[T][, Next][, Args][, Self]>(value, chain[, reject][, context][, ...args])`
+### `when<T[, Next][, Failure][, Args][, Error][, This]>(value, chain[, fail][, context][, ...args])`
 
 <!--lint enable-->
 
-Chain a callback, calling the function after `value` is resolved, or immediately if `value` is not thenable.
+Chain a callback, calling the function after `value` is resolved,
+or immediately if `value` is not a [*thenable*][thenable].
 
 #### Overloads
 
@@ -318,13 +380,13 @@ function when<
   T,
   Next = any,
   Args extends any[] = any[],
-  Self = unknown
+  This = unknown
 >(
   this: void,
   value: Awaitable<T>,
-  chain: Chain<T, Next, Args, Self>,
-  reject?: Reject<Next, any, Self> | null | undefined,
-  context?: Self | null | undefined,
+  chain: Chain<T, Next, Args, This>,
+  fail?: null | undefined,
+  context?: This | null | undefined,
   ...args: Args
 ): Awaitable<Next>
 ```
@@ -333,13 +395,33 @@ function when<
 function when<
   T,
   Next = any,
+  Failure = Next,
   Args extends any[] = any[],
-  Self = unknown
+  Error = any,
+  This = unknown
 >(
   this: void,
   value: Awaitable<T>,
-  chain: Options<T, Next, Args, Self>
-): Awaitable<Next>
+  chain: Chain<T, Next, Args, This>,
+  fail?: Fail<Failure, Error, This> | null | undefined,
+  context?: This | null | undefined,
+  ...args: Args
+): Awaitable<Failure | Next>
+```
+
+```ts
+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>
 ```
 
 #### Type Parameters
@@ -349,29 +431,41 @@ function when<
 - `Next` (`any`, optional)
   — the next resolved value
   - **default**: `any`
+- `Failure` (`any`, optional)
+  — the next resolved value on failure
+  - **default**: `Next`
 - `Args` (`readonly any[]`, optional)
-  — the function arguments
+  — the chain function arguments
   - **default**: `any[]`
-- `Self` (`any`, optional)
+- `Error` (`any`, optional)
+  — the error to possibly handle
+  - **default**: `any`
+- `This` (`any`, optional)
   — the `this` context
   - **default**: `unknown`
 
 #### Parameters
 
 - `value` ([`Awaitable<T>`][awaitable])
-  — the promise or the resolved value
-- `chain` ([`Chain<T, Next, Args, Self>`][chain] | [`Options<T, Next, Args, Self>`][options])
+  — the current [*awaitable*][awaitable-term]
+- `chain` ([`Chain<T, Next, Args, This>`][chain] | [`Options<T, Next, Failure, Args, Error, This>`][options])
   — the chain callback or options for chaining
-- `reject` ([`Reject<Next, any, Self>`][reject] | `null` | `undefined`)
-  — the callback to fire when a promise is rejected or an error is thrown
-- `context` (`Self` | `null` | `undefined`)
-  — the `this` context of the chain and error callbacks
+- `fail` ([`Fail<Failure, Error, This>`][fail] | `null` | `undefined`)
+  — the callback to fire when a failure occurs. failures include:
+  - rejections of the input [*thenable*][thenable]
+  - rejections returned from `chain`
+  - synchronous errors thrown in `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.
+- `context` (`This` | `null` | `undefined`)
+  — the `this` context of the chain and `fail` callbacks
 - `...args` (`Args`)
   — the arguments to pass to the chain callback
 
 #### Returns
 
-([`Awaitable<Next>`][awaitable]) The next promise or value
+([`Awaitable<Failure | Next>`][awaitable] | [`Awaitable<Next>`][awaitable]) The next [*awaitable*][awaitable-term]
 
 ## Types
 
@@ -390,7 +484,7 @@ type Awaitable<T> = PromiseLike<T> | T
 - `T` (`any`)
   — the resolved value
 
-### `Chain<[T][, Next][, Args][, Self]>`
+### `Chain<[T][, Next][, Args][, This]>`
 
 A chain callback (`type`).
 
@@ -399,8 +493,8 @@ type Chain<
   T = any,
   Next = any,
   Args extends readonly any[] = any[],
-  Self = unknown
-> = (this: Self, ...params: [...Args, T]) => Awaitable<Next>
+  This = unknown
+> = (this: This, ...params: [...Args, T]) => Awaitable<Next>
 ```
 
 #### Type Parameters
@@ -414,93 +508,107 @@ type Chain<
 - `Args` (`readonly any[]`, optional)
   — the function arguments
   - **default**: `any[]`
-- `Self` (`any`, optional)
+- `This` (`any`, optional)
   — the `this` context
   - **default**: `unknown`
 
 #### Parameters
 
-- **`this`** (`Self`)
+- **`this`** (`This`)
 - `...params` (`[...Args, T]`)
   — 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`
 
 #### Returns
 
-([`Awaitable<Next>`][awaitable]) The next promise or value
+([`Awaitable<Next>`][awaitable]) The next [*awaitable*][awaitable-term]
 
-### `Options<[T][, Next][, Args][, Self]>`
+### `Fail<[Next][, Error][, This]>`
 
-Options for chaining (`interface`).
+The callback to fire when a failure occurs (`type`).
 
 ```ts
-interface Options<
-  T = any,
+type Fail<
   Next = any,
-  Args extends readonly any[] = any[],
-  Self = any
-> { /* ... */ }
+  Error = any,
+  This = unknown
+> = (this: This, e: Error) => Awaitable<Next>
 ```
 
 #### Type Parameters
 
-- `T` (`any`, optional)
-  — the previously resolved value
-  - **default**: `any`
 - `Next` (`any`, optional)
   — the next resolved value
   - **default**: `any`
-- `Args` (`readonly any[]`, optional)
-  — the chain function arguments
-  - **default**: `any[]`
-- `Self` (`any`, optional)
-  — the `this` context
+- `Error` (`any`, optional)
+  — the error to handle
   - **default**: `any`
+- `This` (`any`, optional)
+  — the `this` context
+  - **default**: `unknown`
 
-#### Properties
+#### Parameters
 
-- `args?` (`Args` | `null` | `undefined`)
-  — the arguments to pass to the `chain` callback
-- `chain` ([`Chain<T, Next, Args, Self>`][chain])
-  — the chain callback
-- `context?` (`Self` | `null` | `undefined`)
-  — the `this` context of the `chain` and `reject` callbacks
-- `reject?` ([`Reject<Next, any, Self>`][reject] | `null` | `undefined`)
-  — the callback to fire when a promise is rejected or an error is thrown
+- **`this`** (`This`)
+- `e` (`Error`)
+  — the error
+
+#### Returns
+
+([`Awaitable<Next>`][awaitable]) The next [*awaitable*][awaitable-term]
 
-### `Reject<[Next][, Fail][, Self]>`
+### `Options<[T][, Next][, Failure][, Args][, Error][, This]>`
 
-The callback to fire when a promise is rejected or an error is thrown from a synchronous function (`type`).
+Options for chaining (`interface`).
 
 ```ts
-type Reject<
+interface Options<
+  T = any,
   Next = any,
-  Fail = any,
-  Self = unknown
-> = (this: Self, e: Fail) => Awaitable<Next>
+  Failure = Next,
+  Args extends readonly any[] = any[],
+  Error = any,
+  This = any
+> { /* ... */ }
 ```
 
 #### Type Parameters
 
+- `T` (`any`, optional)
+  — the previously resolved value
+  - **default**: `any`
 - `Next` (`any`, optional)
   — the next resolved value
   - **default**: `any`
-- `Fail` (`any`, optional)
-  — the error to handle
+- `Failure` (`any`, optional)
+  — the next resolved value on failure
+  - **default**: `Next`
+- `Args` (`readonly any[]`, optional)
+  — the chain function arguments
+  - **default**: `any[]`
+- `Error` (`any`, optional)
+  — the error to possibly handle
   - **default**: `any`
-- `Self` (`any`, optional)
+- `This` (`any`, optional)
   — the `this` context
-  - **default**: `unknown`
-
-#### Parameters
-
-- **`this`** (`Self`)
-- `e` (`Fail`)
-  — the error
+  - **default**: `any`
 
-#### Returns
+#### Properties
 
-([`Awaitable<Next>`][awaitable]) The next promise or value
+- `args?` (`Args` | `null` | `undefined`)
+  — the arguments to pass to the `chain` callback
+- `chain` ([`Chain<T, Next, Args, This>`][chain])
+  — the chain callback
+- `context?` (`This` | `null` | `undefined`)
+  — the `this` context of the `chain` and `fail` callbacks
+- `fail?` ([`Fail<Next, Error, This>`][fail] | `null` | `undefined`)
+  — the callback to fire when a failure occurs. failures include:
+  - rejections of the input [*thenable*][thenable]
+  - rejections returned from `chain`
+  - synchronous errors thrown in `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.
 
 ## Glossary
 
@@ -510,11 +618,14 @@ A synchronous or [*thenable*][thenable] value.
 
 ### *thenable*
 
-An object or function with a `.then` method.
+An object or function with a `then` method.
 
 JavaScript engines use duck-typing for promises.
-Structures with a `.then` method will be treated as promise-like objects, and work with built-in mechanisms
-like [`Promise.resolve`][promise-resolve] and the [`await` keyword][await] like native promises.
+Arrays, functions, and objects with a `then` method will be treated as promise-like objects, and work with built-in
+mechanisms like [`Promise.resolve`][promise-resolve] and the [`await` keyword][await] like native promises.
+
+Some thenables also implement a `catch` method (like native promises).
+When available, `when` uses it to ensure rejections are handled.
 
 ## Project
 
@@ -529,23 +640,36 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md).
 This project has a [code of conduct](./CODE_OF_CONDUCT.md).
 By interacting with this repository, organization, or community you agree to abide by its terms.
 
+### Sponsor
+
+This package is intentionally small — and intentionally maintained.
+
+Small primitives power larger systems.
+Support long-term stability by sponsoring Flex Development.
+
 [await]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/await
 
+[awaitable-term]: #awaitable
+
 [awaitable]: #awaitablet
 
-[chain]: #chaint-next-args-self
+[chain]: #chaint-next-args-this
 
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
 [esmsh]: https://esm.sh
 
+[fail]: #failnext-error-this
+
+[ispromise]: #ispromisetvalue
+
 [isthenable]: #isthenabletvalue
 
-[options]: #optionst-next-args-self
+[options]: #optionst-next-failure-args-error-this
 
 [promise-resolve]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve
 
-[reject]: #rejectnext-fail-self
+[promise-then]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/then
 
 [semver]: https://semver.org
 
@@ -553,6 +677,6 @@ By interacting with this repository, organization, or community you agree to abi
 
 [typescript]: https://www.typescriptlang.org
 
-[when]: #whent-next-args-selfvalue-chain-reject-context-args
+[when]: #whent-next-failure-args-error-thisvalue-chain-fail-context-args
 
 [yarn]: https://yarnpkg.com

package/dist/index.d.mts

@@ -10,12 +10,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 +27,74 @@ 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?: Self | null | undefined;
+    context?: This | null | undefined;
     /**
-     * The callback to fire when a promise is rejected or an error is thrown.
+     * 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}
      *
-     * @see {@linkcode Reject}
+     * @since 2.0.0
      */
-    reject?: Reject<Next, any, Self> | null | undefined;
+    fail?: Fail<Failure, Error, This> | null | undefined;
 }
 
+/**
+ * @file isPromise
+ * @module when/lib/isPromise
+ */
+/**
+ * Check if `value` looks like a {@linkcode Promise}.
+ *
+ * > 👉 **Note**: This function intentionally performs a structural check
+ * > instead of a brand check.
+ * > 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
+ * @return {value is Promise<T>}
+ *  `true` if `value` is a thenable with a `catch` method, `false` otherwise
+ */
+declare function isPromise<T>(this: void, value: unknown): value is Promise<T>;
+
 /**
  * @file isThenable
  * @module when/lib/isThenable
  */
 /**
- * Check if `value` looks like a thenable.
+ * Check if `value` looks like a thenable,
+ * i.e. a {@linkcode PromiseLike} object.
  *
  * @template {any} T
  *  The resolved value
@@ -54,7 +104,8 @@ 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
+ *  `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>;
 
@@ -65,11 +116,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 +128,65 @@ 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
  *
  * @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
+ *  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, 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>;
 /**
  * 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 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
+ *
+ * @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 {Awaitable<Failure | Next>}
+ *  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>;
+/**
+ * Chain a callback, calling the function after `value` is resolved,
+ * or immediately if `value` is not a thenable.
  *
  * @see {@linkcode Awaitable}
  * @see {@linkcode Options}
@@ -107,21 +195,25 @@ 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
  *
  * @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 {Awaitable<Failure | Next>}
+ *  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>(this: void, value: Awaitable<T>, chain: Options<T, Next, Failure, Args, Error, This>): Awaitable<Failure | Next>;
 
 /**
  * @file Type Aliases - Awaitable
@@ -151,46 +243,45 @@ 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]
+ * @template {any} [Error=any]
  *  The error to handle
- * @template {any} [Self=unknown]
+ * @template {any} [This=unknown]
  *  The `this` context
  *
- * @this {Self}
+ * @this {This}
  *
  * @param {unknown} e
  *  The error
  * @return {Awaitable<Next>}
- *  The next promise or value
+ *  The next awaitable
  */
-type Reject<Next = any, Fail = any, Self = unknown> = (this: Self, e: Fail) => Awaitable<Next>;
+type Fail<Next = any, Error = any, This = unknown> = (this: This, e: Error) => Awaitable<Next>;
 
-export { when as default, isThenable as isPromiseLike, isThenable, when };
-export type { Awaitable, Chain, Options, Reject };
+export { when as default, isPromise, isThenable as isPromiseLike, isThenable, when };
+export type { Awaitable, Chain, Fail, Options };

package/dist/lib/index.mjs

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

package/dist/lib/is-promise.mjs

@@ -0,0 +1,31 @@
+/**
+ * @file isPromise
+ * @module when/lib/isPromise
+ */
+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.
+ * > 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
+ * @return {value is Promise<T>}
+ *  `true` if `value` is a thenable with a `catch` method, `false` otherwise
+ */
+function isPromise(value) {
+    if (!isThenable(value))
+        return false;
+    return 'catch' in value && typeof value.catch === 'function';
+}
+export default isPromise;

package/dist/lib/is-thenable.mjs

@@ -3,7 +3,8 @@
  * @module when/lib/isThenable
  */
 /**
- * Check if `value` looks like a thenable.
+ * Check if `value` looks like a thenable,
+ * i.e. a {@linkcode PromiseLike} object.
  *
  * @template {any} T
  *  The resolved value
@@ -13,13 +14,14 @@
  * @param {unknown} value
  *  The thing to check
  * @return {value is PromiseLike<T>}
- *  `true` if `value` is a thenable, `false` otherwise
+ *  `true` if `value` is an object or function with a `then` method,
+ *  `false` otherwise
  */
 function isThenable(value) {
-    return (!Array.isArray(value) &&
-        typeof value === 'object' &&
-        value !== null &&
-        'then' in value &&
-        typeof value.then === 'function');
+    if (!value)
+        return false;
+    if (typeof value !== 'function' && typeof value !== 'object')
+        return false;
+    return 'then' in value && typeof value.then === 'function';
 }
 export default isThenable;

package/dist/lib/when.mjs

@@ -2,34 +2,35 @@
  * @file when
  * @module when/lib/when
  */
+import isPromise from '#lib/is-promise';
 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) {
     if (typeof chain === 'object') {
-        reject = chain.reject;
+        fail = chain.fail;
         context = chain.context;
         args = chain.args ?? [];
         chain = chain.chain;
@@ -37,14 +38,17 @@ function when(value, chain, reject, context, ...args) {
     // no promise, call chain function immediately.
     if (!isThenable(value)) {
         try {
-            return chain.call(context, ...args, value);
+            // try attaching "global" rejection handler with `catch`.
+            return katch(chain.call(context, ...args, value));
         }
         catch (e) {
-            return fail(e);
+            return failure(e);
         }
     }
-    // already have a promise, chain callback.
-    return value.then(resolved => chain.call(context, ...args, resolved), fail);
+    // already have a promise, chain the chain callback.
+    value = value.then(res => chain.call(context, ...args, res), failure);
+    // try attaching "global" rejection handler with `catch`.
+    return katch(value);
     /**
      * @this {void}
      *
@@ -54,9 +58,24 @@ function when(value, chain, reject, context, ...args) {
      *  The rejection result
      * @throws {unknown}
      */
-    function fail(e) {
-        if (typeof reject !== 'function')
+    function failure(e) {
+        if (typeof fail !== 'function')
             throw e;
-        return reject.call(context, e);
+        return fail.call(context, e);
+    }
+    /**
+     * Try attaching a rejection handler with `catch`.
+     *
+     * @this {void}
+     *
+     * @param {unknown} value
+     *  The awaitable
+     * @return {unknown}
+     *  The `value`
+     */
+    function katch(value) {
+        if (isPromise(value))
+            value = value.catch(failure);
+        return value;
     }
 }

package/package.json

@@ -1,19 +1,27 @@
 {
   "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": "2.0.0",
   "keywords": [
+    "async",
     "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",
@@ -114,7 +122,7 @@
   },
   "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",
     "@flex-development/commitlint-config": "1.0.1",
@@ -140,7 +148,7 @@
     "editorconfig": "3.0.1",
     "eslint": "9.39.2",
     "growl": "1.10.5",
-    "happy-dom": "20.6.2",
+    "happy-dom": "20.6.3",
     "husky": "9.1.7",
     "is-ci": "4.1.0",
     "node-notifier": "10.0.1",