ReadonlyexpectThe next step must fail. A throw, a rejection and next(err) all satisfy
it, and the error becomes the value for the following step. Successful
completion fails the run. The value is typed unknown, because a rejection
value can be anything.
ReadonlykeepThe next step passes its input through, whatever it returns. Use it for assertions that should not consume the value.
Add a step that waits for async work, whether it is already running or the function starts it.
A function is called with the previous value when the sequence reaches
it, and what it returns is handled exactly as a value passed here would be.
A Promise, or any thenable, is awaited. An array resolves element-wise,
like Promise.all, keeping its tuple positions.
This is separate from .step() because an array's intention cannot be
known: [p1, p2] may be work to wait for, or may be a value the next step
wants to hold on to and race or inspect itself. That is just as true of an
array a function returns, so .step() passes an array on untouched in
either form, and .asyncStep() is how you ask for it to be resolved.
The function form is also what defers the work. .asyncStep([f(), g()])
starts both before the chain runs, while .asyncStep(() => [f(), g()])
starts them when the step is reached.
Wait for a signal passed by value rather than by name.
The signal still has to be declared in config.signals, since that is what
makes it an obligation; this form only avoids restating its name as a
string. Prefer it wherever the name is not type-checked, such as a plain
.js spec, because a typo there is otherwise caught only at runtime.
Add a step that finishes by calling an error-first callback rather than by returning.
How many parameters the function declares decides what it receives. One is the callback alone, which is the usual shape for adapting a callback API. Two are the previous value and the callback. This mirrors the positional API, where a single callback-named parameter also receives only the callback.
The function's return value is ignored, so a Promise it happens to return is not a second completion path.
Two overloads rather than one flexible signature: a union of signatures
with differing arity, or a conditional type in parameter position, stops
TypeScript contextually typing the lambda and its parameters silently
become any.
Require an instance of any listed class, plus optional message/code checks; infer its type.
Optionalmatcher: ErrorMatcherOptionalcode: ErrorCodeLike expectError, and also require an exact message or an instance of
the supplied class. A class narrows the next step's input to its instance type.
Message and class requirements compose. When code is given, require the
top-level error code to equal it too.
Add a step. It receives the previous step's value, and the value it finishes with goes on to the next step.
A step that returns nothing finishes with undefined. Use .keep.step to
assert on the value and pass it through instead.
A returned Promise is awaited. A returned array is passed on exactly as it is, even when it holds promises; asyncStep is what resolves those.
An ordinary step's output is inferred from what it returns. A
callbackStep's output cannot be inferred, because it only appears in the
callback's parameter position, so it defaults to unknown. Pass it
explicitly, as .callbackStep<string>(...), only where a later step needs
the value's type.
Add a step that is a value rather than a function.
A Promise, or any thenable, is adopted: the run waits for it and its
settled value goes on to the next step. Any other value, an array
included, is passed straight on. So .expectError.step(save(bad)) reads
as well as wrapping it in an arrow, and .step(41) seeds a chain.
An array is deliberately not resolved here; see asyncStep.
Everything except a function is detected from the value itself. A bare function is the one ambiguous case, since nothing distinguishes a step that returns a value from one that wants a callback, which is why callbackStep is a separate method rather than a detected shape.
A value passed this way is already running, unlike a function, which the runner does not call until the sequence reaches it.
Declared after the function form so a lambda is still contextually typed against that signature.
An ordered sequence of steps. Immutable and thenable.