feat: when

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

.dictionary.txt

@@ -10,6 +10,7 @@ jchen
 kaisugi
 nvmrc
 shfmt
+succ
 unstub
 vates
 vitest

.github/infrastructure.yml

@@ -178,7 +178,7 @@ repository:
   automated_security_fixes: true
   default_branch: main
   delete_branch_on_merge: true
-  description: ⛓️ chain a callback onto a value or promise
+  description: .then for values and thenables
   has_issues: true
   has_projects: true
   has_wiki: false
@@ -192,6 +192,8 @@ repository:
     - awaitable
     - chain
     - promise
+    - then
+    - thenable
   visibility: public
   vulnerability_alerts: true
   web_commit_signoff_required: true

README.md

@@ -12,16 +12,21 @@
 [![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)
 
-chain a callback onto a value or promise
+like `.then`, but for values *and* thenables.
 
 ## Contents
 
 - [What is this?](#what-is-this)
 - [Install](#install)
 - [Use](#use)
 - [API](#api)
+  - [`isPromiseLike<T>(value)`][ispromiselike]
+  - [`when<[T][, Next][, Args][, Self]>(value, chain[, reject][, context][, ...args])`][when]
 - [Types](#types)
-  - [`Awaitable<T>`](#awaitablet)
+  - [`Awaitable<T>`][awaitable]
+  - [`Chain<[T][, Next][, Args][, Self]>`][chain]
+  - [`Options<[T][, Next][, Args][, Self]>`][options]
+  - [`Reject<[Next][, Fail][, Self]>`][reject]
 - [Project](#project)
   - [Version](#version)
   - [Contribute](#contribute)
@@ -69,7 +74,7 @@ In browsers with [`esm.sh`][esmsh]:
 
 `when` exports the identifiers listed below.
 
-The default export is `when`.
+The default export is [`when`][when].
 
 ### `isPromiseLike<T>(value)`
 
@@ -89,6 +94,76 @@ Check if `value` looks like a promise.
 
 (`value is PromiseLike<T>`) `true` if `value` is `PromiseLike` object, `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 a promise.
+
+#### 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][].
@@ -106,6 +181,118 @@ type Awaitable<T> = PromiseLike<T> | T
 - `T` (`any`)
   — the 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
+
 ## Project
 
 ### Version
@@ -119,12 +306,24 @@ 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.
 
+[awaitable]: #awaitablet
+
+[chain]: #chaint-next-args-self
+
 [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
 [esmsh]: https://esm.sh
 
+[ispromiselike]: #ispromiseliketvalue
+
+[options]: #optionst-next-args-self
+
+[reject]: #rejectnext-fail-self
+
 [semver]: https://semver.org
 
 [typescript]: https://www.typescriptlang.org
 
+[when]: #whent-next-args-selfvalue-chain-reject-context-args
+
 [yarn]: https://yarnpkg.com

eslint.config.mjs

@@ -19,6 +19,18 @@ const config = [
     rules: {
       'unicorn/no-thenable': 0
     }
+  },
+  {
+    files: ['src/lib/when.mts'],
+    rules: {
+      'promise/prefer-await-to-then': 0
+    }
+  },
+  {
+    files: ['src/types/chain.mts'],
+    rules: {
+      'jsdoc/valid-types': 0
+    }
   }
 ]
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flex-development/when",
-  "description": "Chain a callback onto a value or promise",
+  "description": "Like .then, but for values and thenables",
   "version": "0.0.0",
   "keywords": [
     "async",
@@ -10,6 +10,8 @@
     "chain",
     "promise",
     "sync",
+    "then",
+    "thenable",
     "typescript"
   ],
   "license": "BSD-3-Clause",

src/interfaces/__tests__/options.spec-d.mts

@@ -0,0 +1,40 @@
+/**
+ * @file Type Tests - Options
+ * @module when/types/tests/unit-d/Options
+ */
+
+import type TestSubject from '#interfaces/options'
+import type { Nilable } from '@flex-development/tutils'
+import type { Chain, Reject } from '@flex-development/when'
+
+describe('unit-d:interfaces/Options', () => {
+  type T = URL | string
+  type Next = string
+  type Args = [T]
+  type Self = undefined
+  type Subject = TestSubject<T, Next, Args, Self>
+
+  it('should match [args?: Args | null | undefined]', () => {
+    expectTypeOf<Subject>()
+      .toHaveProperty('args')
+      .toEqualTypeOf<Nilable<Args>>()
+  })
+
+  it('should match [chain: Chain<T, Next, Args, Self>]', () => {
+    expectTypeOf<Subject>()
+      .toHaveProperty('chain')
+      .toEqualTypeOf<Chain<T, Next, Args, Self>>()
+  })
+
+  it('should match [context?: Self | null | undefined]', () => {
+    expectTypeOf<Subject>()
+      .toHaveProperty('context')
+      .toEqualTypeOf<Nilable<Self>>()
+  })
+
+  it('should match [reject?: Reject<Next, any, Self> | null | undefined]', () => {
+    expectTypeOf<Subject>()
+      .toHaveProperty('reject')
+      .toEqualTypeOf<Nilable<Reject<Next, any, Self>>>()
+  })
+})

src/interfaces/index.mts

@@ -3,4 +3,4 @@
  * @module when/interfaces
  */
 
-export type {}
+export type { default as Options } from '#interfaces/options'