@flex-development/when 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+## 1.0.0 (2026-02-18)
+
+### :package: Build
+
+- [[`89747c3`](https://github.com/flex-development/when/commit/89747c317883b749a9f9ef20702c7a0847db291b)] **ts:** fix dts bundle
+
+### :robot: Continuous Integration
+
+- [[`8472f72`](https://github.com/flex-development/when/commit/8472f7299ee70065318b2b925fccb926e62ef46d)] **deps:** Bump actions/cache from 5.0.1 to 5.0.3 ([#2](https://github.com/flex-development/when/issues/2))
+- [[`a490ffe`](https://github.com/flex-development/when/commit/a490ffea18095d99f07edba0608c5f517e1e60db)] **deps:** Bump actions/checkout from 6.0.1 to 6.0.2 ([#4](https://github.com/flex-development/when/issues/4))
+- [[`cebe06a`](https://github.com/flex-development/when/commit/cebe06ae414c0bde9b126574cdf40bf5a6ba9311)] **deps:** Bump actions/setup-node from 6.1.0 to 6.2.0 ([#3](https://github.com/flex-development/when/issues/3))
+- [[`34b0da9`](https://github.com/flex-development/when/commit/34b0da9ab276073eaa2675ca2072af7183fff021)] **deps:** Bump streetsidesoftware/cspell-action from 8.1.2 to 8.2.0 ([#1](https://github.com/flex-development/when/issues/1))
+
+### :pencil: Documentation
+
+- [[`b69462f`](https://github.com/flex-development/when/commit/b69462f9f82ac07ae96920af0f22d57f06567e9f)] use
+- [[`0f9a427`](https://github.com/flex-development/when/commit/0f9a4272e75ef01441e2bf4e5eecc450f0092d2b)] what is this?
+- [[`8391dab`](https://github.com/flex-development/when/commit/8391dabf2049d8eebd9319234ca54e90287e4701)] why not `Promise.resolve`?
+
+### :sparkles: Features
+
+- [[`0bdbc47`](https://github.com/flex-development/when/commit/0bdbc4740d57624a8f5ec7a33289c7ba5e96a5c5)] `when`
+- [[`aa84d47`](https://github.com/flex-development/when/commit/aa84d47f2d16b53826c936443799af42a74959db)] **lib:** `isPromiseLike`
+- [[`4fab731`](https://github.com/flex-development/when/commit/4fab7311e0fd2e0a909d0d1ce74a1ab478968ec8)] **lib:** `isThenable`
+- [[`507ad2b`](https://github.com/flex-development/when/commit/507ad2b3cdc8577b4e8c8b0cf5e2adbc7641a4a6)] **types:** `Awaitable`
+
+### :bug: Fixes
+
+- [[`5ef99bb`](https://github.com/flex-development/when/commit/5ef99bb77f0b35c3670d72ddba4f77a4bb506235)] **pkg:** default export
+- [[`21ec642`](https://github.com/flex-development/when/commit/21ec642d83071e1d965a23dec609c4d1c662dd84)] **pkg:** library exports
+
+### :house_with_garden: Housekeeping
+
+- [[`4cca93d`](https://github.com/flex-development/when/commit/4cca93dda1fbc6dbd863405ecfe88259087c2463)] fix release workflow
+- [[`a5418df`](https://github.com/flex-development/when/commit/a5418dfc0cae7c2ca231e735665d76b625615edc)] initial commit
+
+## 1.0.0 (2026-02-18)
+
+### :package: Build
+
+- [[`89747c3`](https://github.com/flex-development/when/commit/89747c317883b749a9f9ef20702c7a0847db291b)] **ts:** fix dts bundle
+
+### :robot: Continuous Integration
+
+- [[`8472f72`](https://github.com/flex-development/when/commit/8472f7299ee70065318b2b925fccb926e62ef46d)] **deps:** Bump actions/cache from 5.0.1 to 5.0.3 ([#2](https://github.com/flex-development/when/issues/2))
+- [[`a490ffe`](https://github.com/flex-development/when/commit/a490ffea18095d99f07edba0608c5f517e1e60db)] **deps:** Bump actions/checkout from 6.0.1 to 6.0.2 ([#4](https://github.com/flex-development/when/issues/4))
+- [[`cebe06a`](https://github.com/flex-development/when/commit/cebe06ae414c0bde9b126574cdf40bf5a6ba9311)] **deps:** Bump actions/setup-node from 6.1.0 to 6.2.0 ([#3](https://github.com/flex-development/when/issues/3))
+- [[`34b0da9`](https://github.com/flex-development/when/commit/34b0da9ab276073eaa2675ca2072af7183fff021)] **deps:** Bump streetsidesoftware/cspell-action from 8.1.2 to 8.2.0 ([#1](https://github.com/flex-development/when/issues/1))
+
+### :pencil: Documentation
+
+- [[`b69462f`](https://github.com/flex-development/when/commit/b69462f9f82ac07ae96920af0f22d57f06567e9f)] use
+- [[`0f9a427`](https://github.com/flex-development/when/commit/0f9a4272e75ef01441e2bf4e5eecc450f0092d2b)] what is this?
+- [[`8391dab`](https://github.com/flex-development/when/commit/8391dabf2049d8eebd9319234ca54e90287e4701)] why not `Promise.resolve`?
+
+### :sparkles: Features
+
+- [[`0bdbc47`](https://github.com/flex-development/when/commit/0bdbc4740d57624a8f5ec7a33289c7ba5e96a5c5)] `when`
+- [[`aa84d47`](https://github.com/flex-development/when/commit/aa84d47f2d16b53826c936443799af42a74959db)] **lib:** `isPromiseLike`
+- [[`4fab731`](https://github.com/flex-development/when/commit/4fab7311e0fd2e0a909d0d1ce74a1ab478968ec8)] **lib:** `isThenable`
+- [[`507ad2b`](https://github.com/flex-development/when/commit/507ad2b3cdc8577b4e8c8b0cf5e2adbc7641a4a6)] **types:** `Awaitable`
+
+### :bug: Fixes
+
+- [[`5ef99bb`](https://github.com/flex-development/when/commit/5ef99bb77f0b35c3670d72ddba4f77a4bb506235)] **pkg:** default export
+- [[`21ec642`](https://github.com/flex-development/when/commit/21ec642d83071e1d965a23dec609c4d1c662dd84)] **pkg:** library exports
+
+### :house_with_garden: Housekeeping
+
+- [[`a5418df`](https://github.com/flex-development/when/commit/a5418dfc0cae7c2ca231e735665d76b625615edc)] initial commit
+
+
+

package/LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Flex Development, LLC All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,558 @@
+# \:timer\_clock: when
+
+[![github release](https://img.shields.io/github/v/release/flex-development/when.svg?include_prereleases\&sort=semver)](https://github.com/flex-development/when/releases/latest)
+[![npm](https://img.shields.io/npm/v/@flex-development/when.svg)](https://npmjs.com/package/@flex-development/when)
+[![npm downloads](https://img.shields.io/npm/dm/@flex-development/when.svg)](https://www.npmcharts.com/compare/@flex-development/when?interval=30)
+[![install size](https://packagephobia.now.sh/badge?p=@flex-development/when)](https://packagephobia.now.sh/result?p=@flex-development/when)
+[![codecov](https://codecov.io/github/flex-development/when/graph/badge.svg?token=BG38l3Clm1)](https://codecov.io/github/flex-development/when)
+[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)
+[![license](https://img.shields.io/github/license/flex-development/when.svg)](LICENSE.md)
+[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\&logoColor=ffffff)](https://conventionalcommits.org)
+[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\&logoColor=ffffff)](https://typescriptlang.org)
+[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\&logo=vitest\&logoColor=ffffff)](https://vitest.dev)
+[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\&logo=yarn\&logoColor=ffffff)](https://yarnpkg.com)
+
+like `.then`, but for synchronous values *and* thenables.
+
+## Contents
+
+- [What is this?](#what-is-this)
+  - [Why not `Promise.resolve`?](#why-not-promiseresolve)
+- [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)
+  - [Bind `this` context](#bind-this-context)
+  - [Use an options object](#use-an-options-object)
+- [API](#api)
+  - [`isThenable<T>(value)`][isthenable]
+  - [`when<[T][, Next][, Args][, Self]>(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]
+- [Glossary](#glossary)
+- [Project](#project)
+  - [Version](#version)
+  - [Contribute](#contribute)
+
+## What is this?
+
+`when` is a small, but useful package for chaining a callback
+onto an [awaitable][] (a value or a [*thenable*][thenable]).
+
+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.
+
+`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.
+
+### Why not `Promise.resolve`?
+
+`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.
+
+## Install
+
+This package is [ESM only][esm].
+
+In Node.js (version 20+) with [yarn][]:
+
+```sh
+yarn add @flex-development/when
+```
+
+<blockquote>
+  <small>
+    See <a href='https://yarnpkg.com/protocol/git'>Git - Protocols | Yarn</a>
+    &nbsp;for details regarding installing from Git.
+  </small>
+</blockquote>
+
+In Deno with [`esm.sh`][esmsh]:
+
+```ts
+import { when } from 'https://esm.sh/@flex-development/when'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import { when } from 'https://esm.sh/@flex-development/when'
+</script>
+```
+
+## Use
+
+### Chain a synchronous value
+
+```ts
+import { isThenable, when, type Awaitable } from '@flex-development/when'
+import { ok } from 'devlop'
+
+/**
+ * The result.
+ *
+ * @const {Awaitable<number>} result
+ */
+const result: Awaitable<number> = when(0, n => n + 1)
+
+ok(!isThenable(result), 'expected `result` to not be thenable')
+console.dir(result) // 1
+```
+
+### Chain a [*thenable*][thenable]
+
+```ts
+import { isThenable, when, type Awaitable } from '@flex-development/when'
+import { ok } from 'devlop'
+
+/**
+ * The result.
+ *
+ * @const {Awaitable<number>} result
+ */
+const result: Awaitable<number> = when(Promise.resolve(2), n => n + 1)
+
+ok(isThenable(result), 'expected `result` to be thenable')
+console.dir(await result) // 3
+```
+
+### Pass arguments to the chain callback
+
+Arguments are passed first, and the resolved value is passed last.
+
+When the `value` passed to `when` is not [*thenable*][thenable], the resolved value is the same `value`.
+
+```ts
+import when, { type Awaitable } from '@flex-development/when'
+
+/**
+ * The result.
+ *
+ * @const {Awaitable<number>} result
+ */
+const result: Awaitable<number> = when(1, Math.min, null, undefined, 2, 3, 4)
+
+console.dir(result) // 1
+```
+
+### Handle rejections / thrown errors
+
+```ts
+import when, { type Awaitable } from '@flex-development/when'
+
+/**
+ * The thenable value.
+ *
+ * @const {PromiseLike<never>} value
+ */
+const value: PromiseLike<never> = new Promise((resolve, reject) => {
+  return void reject(new Error('nope', { cause: { url: import.meta.url } }))
+})
+
+/**
+ * The result.
+ *
+ * @const {Awaitable<boolean>} result
+ */
+const result: Awaitable<boolean> = when(value, chain, reject)
+
+console.dir(await result) // false
+
+/**
+ * @this {void}
+ *
+ * @return {true}
+ *  The success result
+ */
+function chain(this: void): true {
+  return true
+}
+
+/**
+ * @this {void}
+ *
+ * @param {Error} e
+ *  The error to handle
+ * @return {false}
+ *  The failure result
+ */
+function reject(this: void, e: Error): false {
+  return console.dir(e), false
+}
+```
+
+### Bind `this` context
+
+```ts
+import when, { type Awaitable } from '@flex-development/when'
+
+/**
+ * The `this` context.
+ */
+type Context = { prefix: string }
+
+/**
+ * The result.
+ *
+ * @const {Awaitable<string>} result
+ */
+const result: Awaitable<string> = when(13, id, null, { prefix: 'id:' })
+
+console.log(result) // 'id:13'
+
+/**
+ * @this {Context}
+ *
+ * @param {number | string} num
+ *  The id number
+ * @return {string}
+ *  The id string
+ */
+function id(this: Context, num: number | string): string {
+  return this.prefix + num
+}
+```
+
+### Use an options object
+
+```ts
+import when, { type Awaitable } from '@flex-development/when'
+
+/**
+ * The `this` context.
+ */
+type Context = { errors: Error[] }
+
+/**
+ * The thenable value.
+ *
+ * @const {Promise<number>} value
+ */
+const value: Promise<number> = new Promise(resolve => resolve(3))
+
+/**
+ * The result.
+ *
+ * @const {Awaitable<number | undefined>} result
+ */
+const result: Awaitable<number | undefined> = when(value, {
+  args: [39],
+  chain: divide,
+  context: { errors: [] },
+  reject
+})
+
+console.dir(await result) // 13
+
+/**
+ * @this {void}
+ *
+ * @param {number} dividend
+ *  The number to divide
+ * @param {number} divisor
+ *  The number to divide by
+ * @return {number}
+ *  The quotient
+ */
+function divide(this: void, dividend: number, divisor: number): number {
+  return dividend / divisor
+}
+
+/**
+ * @this {Context}
+ *
+ * @param {Error} e
+ *  The error to handle
+ * @return {undefined}
+ */
+function reject(this: Context, e: Error): undefined {
+  return void this.errors.push(e)
+}
+```
+
+## API
+
+`when` exports the identifiers listed below.
+
+The default export is [`when`][when].
+
+### `isThenable<T>(value)`
+
+Check if `value` looks like a [*thenable*][thenable].
+
+> 👉 **Note**: Also exported as `isPromiseLike`.
+
+#### Type Parameters
+
+- `T` (`any`)
+  — the resolved value
+
+#### Parameters
+
+- `value` (`unknown`)
+  — the thing to check
+
+#### Returns
+
+(`value is PromiseLike<T>`) `true` if `value` is a thenable, `false` otherwise
+
+<!--lint disable-->
+
+### `when<[T][, Next][, Args][, Self]>(value, chain[, reject][, context][, ...args])`
+
+<!--lint enable-->
+
+Chain a callback, calling the function after `value` is resolved, or immediately if `value` is not thenable.
+
+#### Overloads
+
+```ts
+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>
+```
+
+```ts
+function when<
+  T,
+  Next = any,
+  Args extends any[] = any[],
+  Self = unknown
+>(
+  this: void,
+  value: Awaitable<T>,
+  chain: Options<T, Next, Args, Self>
+): Awaitable<Next>
+```
+
+#### Type Parameters
+
+- `T` (`any`)
+  — the previously resolved value
+- `Next` (`any`, optional)
+  — the next resolved value
+  - **default**: `any`
+- `Args` (`readonly any[]`, optional)
+  — the function arguments
+  - **default**: `any[]`
+- `Self` (`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 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
+- `...args` (`Args`)
+  — the arguments to pass to the chain callback
+
+#### Returns
+
+([`Awaitable<Next>`][awaitable]) The next promise or value
+
+## Types
+
+This package is fully typed with [TypeScript][].
+
+### `Awaitable<T>`
+
+A synchronous or [*thenable*][thenable] value (`type`).
+
+```ts
+type Awaitable<T> = PromiseLike<T> | T
+```
+
+#### Type Parameters
+
+- `T` (`any`)
+  — the resolved value
+
+### `Chain<[T][, Next][, Args][, Self]>`
+
+A chain callback (`type`).
+
+```ts
+type Chain<
+  T = any,
+  Next = any,
+  Args extends readonly any[] = any[],
+  Self = unknown
+> = (this: Self, ...params: [...Args, T]) => 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 function arguments
+  - **default**: `any[]`
+- `Self` (`any`, optional)
+  — the `this` context
+  - **default**: `unknown`
+
+#### Parameters
+
+- **`this`** (`Self`)
+- `...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
+
+### `Options<[T][, Next][, Args][, Self]>`
+
+Options for chaining (`interface`).
+
+```ts
+interface Options<
+  T = any,
+  Next = any,
+  Args extends readonly any[] = any[],
+  Self = any
+> { /* ... */ }
+```
+
+#### 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
+  - **default**: `any`
+
+#### Properties
+
+- `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
+
+### `Reject<[Next][, Fail][, Self]>`
+
+The callback to fire when a promise is rejected or an error is thrown from a synchronous function (`type`).
+
+```ts
+type Reject<
+  Next = any,
+  Fail = any,
+  Self = unknown
+> = (this: Self, e: Fail) => Awaitable<Next>
+```
+
+#### Type Parameters
+
+- `Next` (`any`, optional)
+  — the next resolved value
+  - **default**: `any`
+- `Fail` (`any`, optional)
+  — the error to handle
+  - **default**: `any`
+- `Self` (`any`, optional)
+  — the `this` context
+  - **default**: `unknown`
+
+#### Parameters
+
+- **`this`** (`Self`)
+- `e` (`Fail`)
+  — the error
+
+#### Returns
+
+([`Awaitable<Next>`][awaitable]) The next promise or value
+
+## Glossary
+
+### *awaitable*
+
+A synchronous or [*thenable*][thenable] value.
+
+### *thenable*
+
+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.
+
+## Project
+
+### Version
+
+when adheres to [semver][].
+
+### Contribute
+
+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.
+
+[await]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/await
+
+[awaitable]: #awaitablet
+
+[chain]: #chaint-next-args-self
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[isthenable]: #isthenabletvalue
+
+[options]: #optionst-next-args-self
+
+[promise-resolve]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve
+
+[reject]: #rejectnext-fail-self
+
+[semver]: https://semver.org
+
+[thenable]: #thenable
+
+[typescript]: https://www.typescriptlang.org
+
+[when]: #whent-next-args-selfvalue-chain-reject-context-args
+
+[yarn]: https://yarnpkg.com

package/dist/index.d.mts

@@ -0,0 +1,196 @@
+/**
+ * @file Interfaces - Options
+ * @module when/interfaces/Options
+ */
+
+/**
+ * Options for chaining.
+ *
+ * @template {any} [T=any]
+ *  The previously resolved value
+ * @template {any} [Next=any]
+ *  The next resolved value
+ * @template {ReadonlyArray<any>} [Args=any[]]
+ *  The chain function arguments
+ * @template {any} [Self=any]
+ *  The `this` context
+ */
+interface Options<T = any, Next = any, Args extends readonly any[] = any[], Self = any> {
+    /**
+     * The arguments to pass to the {@linkcode chain} callback.
+     */
+    args?: Args | null | undefined;
+    /**
+     * The chain callback.
+     *
+     * @see {@linkcode Chain}
+     */
+    chain: Chain<T, Next, Args, Self>;
+    /**
+     * The `this` context of the {@linkcode chain}
+     * and {@linkcode reject} callbacks.
+     */
+    context?: Self | null | undefined;
+    /**
+     * The callback to fire when a promise is rejected or an error is thrown.
+     *
+     * @see {@linkcode Reject}
+     */
+    reject?: Reject<Next, any, Self> | null | undefined;
+}
+
+/**
+ * @file isThenable
+ * @module when/lib/isThenable
+ */
+/**
+ * Check if `value` looks like a thenable.
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @return {value is PromiseLike<T>}
+ *  `true` if `value` is a thenable, `false` otherwise
+ */
+declare function isThenable<T>(this: void, value: unknown): value is PromiseLike<T>;
+
+/**
+ * @file when
+ * @module when/lib/when
+ */
+
+/**
+ * Chain a callback, calling the function after `value` is resolved,
+ * or immediately if `value` is not thenable.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Chain}
+ * @see {@linkcode Reject}
+ *
+ * @template {any} T
+ *  The previously resolved value
+ * @template {any} [Next=any]
+ *  The next resolved value
+ * @template {ReadonlyArray<any>} [Args=any[]]
+ *  The chain function arguments
+ * @template {any} [Self=any]
+ *  The `this` context
+ *
+ * @this {void}
+ *
+ * @param {Awaitable<T>} value
+ *  The promise or the resolved value
+ * @param {Chain<T, Next, Args, Self>} 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 {Args} args
+ *  The arguments to pass to the chain callback
+ * @return {Awaitable<Next>}
+ *  The next promise or value
+ */
+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>;
+/**
+ * Chain a callback, calling the function after `value` is resolved,
+ * or immediately if `value` is not thenable.
+ *
+ * @see {@linkcode Awaitable}
+ * @see {@linkcode Options}
+ *
+ * @template {any} T
+ *  The previously resolved value
+ * @template {any} [Next=any]
+ *  The next resolved value
+ * @template {ReadonlyArray<any>} [Args=any[]]
+ *  The chain function arguments
+ * @template {any} [Self=unknown]
+ *  The `this` context
+ *
+ * @this {void}
+ *
+ * @param {Awaitable<T>} value
+ *  The promise or the resolved value
+ * @param {Options<T, Next, Args, Self>} chain
+ *  Options for chaining
+ * @return {Awaitable<Next>}
+ *  The next promise or value
+ */
+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>;
+
+/**
+ * @file Type Aliases - Awaitable
+ * @module when/types/Awaitable
+ */
+/**
+ * A synchronous or thenable value.
+ *
+ * @template {any} T
+ *  The resolved value
+ */
+type Awaitable<T> = PromiseLike<T> | T;
+
+/**
+ * @file Type Aliases - Chain
+ * @module when/types/Chain
+ */
+
+/**
+ * A chain callback.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {any} [T=any]
+ *  The previously resolved value
+ * @template {any} [Next=any]
+ *  The next resolved value
+ * @template {ReadonlyArray<any>} [Args=any[]]
+ *  The function arguments
+ * @template {any} [Self=unknown]
+ *  The `this` context
+ *
+ * @this {Self}
+ *
+ * @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
+ */
+type Chain<T = any, Next = any, Args extends readonly any[] = any[], Self = unknown> = (this: Self, ...params: [...Args, T]) => Awaitable<Next>;
+
+/**
+ * @file Type Aliases - Reject
+ * @module when/types/Reject
+ */
+
+/**
+ * The callback to fire when a promise is rejected
+ * or an error is thrown from a synchronous function.
+ *
+ * @see {@linkcode Awaitable}
+ *
+ * @template {any} [Next=any]
+ *  The next resolved value
+ * @template {any} [Fail=any]
+ *  The error to handle
+ * @template {any} [Self=unknown]
+ *  The `this` context
+ *
+ * @this {Self}
+ *
+ * @param {unknown} e
+ *  The error
+ * @return {Awaitable<Next>}
+ *  The next promise or value
+ */
+type Reject<Next = any, Fail = any, Self = unknown> = (this: Self, e: Fail) => Awaitable<Next>;
+
+export { when as default, isThenable as isPromiseLike, isThenable, when };
+export type { Awaitable, Chain, Options, Reject };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+/**
+ * @file Package Entry Point
+ * @module when
+ */
+export * from '#lib/index';
+export { default } from '#lib/when';

package/dist/lib/index.mjs

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

package/dist/lib/is-thenable.mjs

@@ -0,0 +1,25 @@
+/**
+ * @file isThenable
+ * @module when/lib/isThenable
+ */
+/**
+ * Check if `value` looks like a thenable.
+ *
+ * @template {any} T
+ *  The resolved value
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The thing to check
+ * @return {value is PromiseLike<T>}
+ *  `true` if `value` is a thenable, `false` otherwise
+ */
+function isThenable(value) {
+    return (!Array.isArray(value) &&
+        typeof value === 'object' &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+export default isThenable;

package/dist/lib/when.mjs

@@ -0,0 +1,62 @@
+/**
+ * @file when
+ * @module when/lib/when
+ */
+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.
+ *
+ * @see {@linkcode Chain}
+ * @see {@linkcode Options}
+ * @see {@linkcode Reject}
+ *
+ * @this {void}
+ *
+ * @param {unknown} value
+ *  The promise or the resolved value
+ * @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 {unknown} [context]
+ *  The `this` context of the chain and error callbacks
+ * @param {unknown[]} args
+ *  The arguments to pass to the chain callback
+ * @return {unknown}
+ *  The next promise or value
+ */
+function when(value, chain, reject, context, ...args) {
+    if (typeof chain === 'object') {
+        reject = chain.reject;
+        context = chain.context;
+        args = chain.args ?? [];
+        chain = chain.chain;
+    }
+    // no promise, call chain function immediately.
+    if (!isThenable(value)) {
+        try {
+            return chain.call(context, ...args, value);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    }
+    // already have a promise, chain callback.
+    return value.then(resolved => chain.call(context, ...args, resolved), fail);
+    /**
+     * @this {void}
+     *
+     * @param {unknown} e
+     *  The error to handle
+     * @return {unknown}
+     *  The rejection result
+     * @throws {unknown}
+     */
+    function fail(e) {
+        if (typeof reject !== 'function')
+            throw e;
+        return reject.call(context, e);
+    }
+}

package/package.json

@@ -0,0 +1,161 @@
+{
+  "name": "@flex-development/when",
+  "description": "Like .then, but for synchronous values and thenables",
+  "version": "1.0.0",
+  "keywords": [
+    "async",
+    "await",
+    "awaitable",
+    "callback",
+    "chain",
+    "promise",
+    "sync",
+    "synchronous",
+    "then",
+    "thenable",
+    "typescript"
+  ],
+  "license": "BSD-3-Clause",
+  "homepage": "https://github.com/flex-development/when",
+  "repository": "https://github.com/flex-development/when.git",
+  "bugs": "https://github.com/flex-development/when/issues",
+  "author": {
+    "name": "Lexus Drumgold",
+    "url": "https://github.com/unicornware"
+  },
+  "publishConfig": {
+    "access": "public",
+    "diff-dst-prefix": "when",
+    "diff-src-prefix": "when",
+    "directory": "./",
+    "executableFiles": [],
+    "node-options": null,
+    "pack-destination": ".",
+    "parseable": true,
+    "prefer-dedupe": true,
+    "provenance": true,
+    "tag-version-prefix": ""
+  },
+  "type": "module",
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "README.md",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "when": "./src/index.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#fixtures/*": "./__fixtures__/*.mts",
+    "#interfaces/*": {
+      "when": "./src/interfaces/*.mts",
+      "default": "./dist/interfaces/*.d.mts"
+    },
+    "#lib/*": {
+      "when": "./src/lib/*.mts",
+      "default": "./dist/lib/*.mjs"
+    },
+    "#tests/*": "./__tests__/*.mts",
+    "#types/*": {
+      "when": "./src/types/*.mts",
+      "default": "./dist/types/*.d.mts"
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "remarkConfig": {
+    "plugins": [
+      "@flex-development/remark-preset"
+    ]
+  },
+  "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",
+    "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 .",
+    "check:spelling": "cspell lint --color --no-progress --relative $@ \"**\"",
+    "check:types": "tsc -p tsconfig.json",
+    "check:types:attw": "yarn pack && attw package.tgz; yarn clean:pack",
+    "check:types:build": "tsc -p tsconfig.build.json",
+    "check:upgrades": "yarn upgrade-interactive",
+    "clean:build": "trash \"./{dist,*.tgz}\" || exit 0",
+    "clean:modules": "trash ./.yarn/{cache,*.gz} ./node_modules",
+    "clean:pack": "trash \"./*.tgz\"",
+    "clean:test": "trash ./coverage && trash __tests__/reports",
+    "codecov": "yarn test:cov && yarn test:cov:upload",
+    "codecov:validate": "cat .codecov.yml | curl --data-binary @- https://codecov.io/validate",
+    "commitlint": "commitlint -V",
+    "fix:cg": "yarn fix:format && yarn fix:lint",
+    "fix:dedupe": "yarn dedupe --strategy=highest",
+    "fix:format": "dprint fmt",
+    "fix:lint": "yarn check:lint --cache --fix",
+    "_postinstall": "[ -f ./.git ] && [ -f ./node_modules/.bin/husky ] && chmod +x .husky/_/* && husky || exit 0",
+    "postpack": "toggle-scripts +postinstall",
+    "postpublish": "toggle-scripts +prepack",
+    "prepack": "toggle-scripts -postinstall && yarn build",
+    "prepublishOnly": "toggle-scripts -prepack",
+    "release": "bash ./scripts/release.sh",
+    "remark": "remark .",
+    "test": "yarn clean:build; vitest run",
+    "test:cov": "yarn test --coverage",
+    "test:cov:reports": "yarn test:cov --merge-reports --mode=reports",
+    "test:cov:ui": "yarn test:ui --coverage",
+    "test:cov:upload": "./codecov -t $CODECOV_TOKEN -f ./coverage/lcov.info",
+    "test:reports": "yarn test --merge-reports --mode=reports",
+    "test:ui": "cross-env VITEST_UI=1 vitest --ui",
+    "typecheck": "yarn test --typecheck --mode=typecheck",
+    "typecheck:ui": "yarn test:ui --typecheck --mode=typecheck"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.2",
+    "@commitlint/cli": "20.4.1",
+    "@commitlint/types": "20.4.0",
+    "@edge-runtime/vm": "5.0.0",
+    "@flex-development/commitlint-config": "1.0.1",
+    "@flex-development/eslint-config": "1.1.1",
+    "@flex-development/grease": "3.0.0-alpha.9",
+    "@flex-development/pathe": "4.0.2",
+    "@flex-development/remark-preset": "1.0.0",
+    "@flex-development/tutils": "6.0.0-alpha.25",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@tsconfig/strictest": "2.0.8",
+    "@types/concat-stream": "2.0.3",
+    "@types/is-ci": "3.0.4",
+    "@types/node-notifier": "8.0.5",
+    "@types/rollup": "0.54.0",
+    "@vates/toggle-scripts": "1.0.0",
+    "@vitest/coverage-v8": "4.0.18",
+    "@vitest/ui": "4.0.18",
+    "concat-stream": "2.0.0",
+    "cross-env": "10.1.0",
+    "cspell": "9.6.4",
+    "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",
+    "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-plugin-dts": "6.3.0",
+    "sh-syntax": "0.5.8",
+    "trash-cli": "7.2.0",
+    "typescript": "5.9.3",
+    "unified": "11.0.5",
+    "vfile": "6.0.3",
+    "vitest": "4.0.18"
+  },
+  "packageManager": "yarn@4.12.0",
+  "sideEffects": false
+}