Class: AsyncWhat

Map over iterable/collection results asynchronously.

Attach a fallback to handle missing results or matching errors.

This method extends the primary async function with recovery logic:

• If the primary function resolves to undefined, the fallback f is awaited and returned.
• If the primary function rejects, the error is tested against the optional matcher.
  • If it matches, the fallback f is awaited and returned.
  • If it does not match, the error is re-thrown.
• When the fallback is invoked due to an error, the error object is appended as the last argument to f.

Error matching is delegated to Errors.matches, which supports:

• number: compares against err.statusCode
• string: compares against error class name, or substring match for thrown strings
• RegExp: tested against the error message or thrown string
• Function: custom predicate (err) => boolean

Non-functions (constants or Promises) are automatically lifted into async functions returning that constant or awaited value.

Filter inputs by an asynchronous predicate.

Throws an error if the predicate returns falsy.

Apply multiple functions and return all results.

Dynamically adapts this AsyncWhat instance for different use cases depending on the arguments provided.

Overload modes:

1. Path-expanding mode (no arguments):

   • self()
     Converts this AsyncWhat: item -> items to an AsyncWhat: path -> paths by expanding path across the results of this(path.last).

2. Context-mapping / nominal mode (string or string[] as first arg):

   • self(name) → extracts ctx[name] and passes it as input.
   • self(nameIn, nameOut) → maps ctx[nameIn] to input and stores result in ctx[nameOut].
   • self([name1, name2, ...]) → extracts multiple properties from context.
   • self([name1, name2, ...], nameOut) → stores result in ctx[nameOut].

3. Timeout mode (single number):

   • self(timeoutMs)
     Wraps this AsyncWhat so that it fails if it does not complete within timeoutMs ms.

4. Argument-binding mode (two args: number, value):

   • self(index, value)
     Injects value into the argument list at position index.

5. Retry mode (numeric first arg with ≥3 args):

   • self(nAttempts, baseDelay, factor, maxDelay)
     Retries this AsyncWhat with exponential backoff.
     The produced AsyncWhat has a .stopped property which can be set to true to cancel retries.

Sequentially apply a list of async functions, stopping if undefined.

Asynchronous conditional in event-driven mode.

Returns an AsyncWhat that wraps the current AsyncWhat (this) and either starts or stops it based on the given event and predicate.

Behavior:

• start = true: the underlying AsyncWhat is only executed when the predicate evaluates truthy upon the occurrence of the event.
• start = false: the underlying AsyncWhat is immediately invoked (so it can run and be stopped) and will be stopped when the predicate evaluates truthy upon the event.

Rejects with TimeoutError if no matching event occurs within the specified timeout.

The returned AsyncWhat proxies the .stopped property of the underlying AsyncWhat.

Example: infinite cyclic execution with start/stop triggers

const cyclic = doSomething.self(Infinity, 100, 1);

const bounded = cyclic .when( isStart,
emitter, event, undefined, true // start cyclic execution when event occurs ) .when( isStop,
emitter, event, undefined, false // stop cyclic execution when event occurs );

bounded();

Keep only results passing an async or sync predicate.

Both the wrapped function f and the predicate p can be synchronous or asynchronous.

• If p resolves truthy, returns the value.
• If p resolves falsy, returns undefined or throws error.
• If either f or p rejects, that rejection is propagated.

Wrap a function, value, or another AsyncWhat into an AsyncWhat.

• If f is already an AsyncWhat, it is returned unchanged.
• If f is not a function, it is treated as a constant value.
• Otherwise, f is wrapped into an async function.

Static version of each.

Static version of if.

Wraps a function with an asynchronous predicate. Throws the specified error if the predicate fails.

Create an AsyncWhat that matches specific argument values.

Retries a function multiple times with exponential backoff, wrapped as an AsyncWhat.

The function f(ctx) may be synchronous or asynchronous. If it throws, rejects, or returns undefined, the next attempt is scheduled after an exponentially increasing delay:

delay = min(baseDelay * factor ** attemptIndex, maxDelay)

Retries are scheduled via setTimeout, ensuring stack safety even for infinite retries. Only the last error is kept in memory.

The returned AsyncWhat exposes a .stopped property: set it to true to cancel further retries. When stopped, the promise rejects with the last encountered error, or with "Retry stopped by user" if no error occurred.

Retype a function so that it behaves like the given instance.

Static version of when.

Waits for an event on an emitter. Each time the event fires, evaluates predicate(...eventArgs, emitter). If truthy:

• removes the listener
• sets f.stopped = !start
  • if start = true, allows the underlying AsyncWhat f to run
  • if start = false, stops f after it was immediately invoked
• resolves with f(...eventArgs, emitter) only if starting; resolves immediately if stopping

If start = false, the underlying AsyncWhat f is called immediately so it exists and can later be stopped.

If no matching event occurs within timeoutMs, the listener is removed and a TimeoutError is thrown.

Works with both Node.js EventEmitter (on/off) and DOM EventTarget (addEventListener/removeEventListener).

The returned AsyncWhat exposes a .stopped property, which proxies f.stopped.

Static version of which.

Wraps a function or AsyncWhat with a predicate. Returns undefined or throws error if the predicate fails.

Runs an async function with a timeout.

Wraps fn(ctx) in a Promise.race against a timeout. Returns an AsyncWhat that resolves if fn completes before the timeout, or rejects with the provided error (default TimeoutError).