package @rimbu/task/ops

The @rimbu/task/ops entry exposes the composable operations and modifiers that work with core Task values from @rimbu/task, such as all, race, withTimeout, withRetry, chain, and helpers for supervision and error handling. Import from this entry when you want to build higher‑level task pipelines or apply reusable behaviours like timeouts, retries, argument binding and result mapping.

Functions

all

Executes multiple Tasks concurrently and waits for all to complete. Returns an array of results corresponding to each Task.

Definition

export declare function all<RS extends any[], A extends readonly any[] = []>(tasks: {
  [K in keyof RS]: Task<RS[K], {
    [AK in keyof A]?: A[AK];
  }>;
}, options?: {
  maxBranch?: number | undefined;
}): Task<RS, A>;

Type parameters

Name	Description
RS
A

Parameters

Name	Type	Description
tasks	{   [K in keyof RS]: Task<RS[K], {     [AK in keyof A]?: A[AK];   }>; }
options	{   maxBranch?: number | undefined; }

allSettled

Executes multiple Tasks concurrently and waits for all to settle (either resolve or reject). Returns an array of PromiseSettledResult objects corresponding to each Task.

Definition

export declare function allSettled<RS extends any[], A extends readonly any[] = []>(tasks: {
  [K in keyof RS]: Task<RS[K], {
    [AK in keyof A]?: A[AK];
  }>;
}, options?: {
  maxBranch?: number | undefined;
}): Task<{
  [K in keyof RS]: PromiseSettledResult<RS[K]>;
}, A>;

Type parameters

Name	Description
RS
A

Parameters

Name	Type	Description
tasks	{   [K in keyof RS]: Task<RS[K], {     [AK in keyof A]?: A[AK];   }>; }
options	{   maxBranch?: number | undefined; }

any

Executes multiple Tasks concurrently and returns the result of the first Task to successfully complete. If all Tasks fail, an AggregateError is thrown. All other Tasks are cancelled once one completes successfully.

Definition

export declare function any<R, A extends readonly any[] = []>(tasks: Task<R, {
  [AK in keyof A]?: A[AK];
}>[], options?: {
  maxBranch?: number | undefined;
}): Task<R, A>;

Type parameters

Name	Description
R
A

Parameters

Name	Type	Description
tasks	Task<R, {   [AK in keyof A]?: A[AK]; }>[]
options	{   maxBranch?: number | undefined; }

catchAll

Catches all errors thrown by a Task and allows for handling them with a provided Task. If no handling Task is provided, errors are caught and undefined is returned. Note that CancellationError is not caught and will always be re-thrown.

Definition

export declare function catchAll<R = undefined>(onError?: Task<R> | undefined): Task.Modifier<R>;

Type parameters

Name	Description
R

Parameters

Name	Type	Description
onError	Task<R> | undefined

catchError

Catches errors thrown by a Task and allows for handling them with a provided function. If the handling function returns a Task, it will be executed; otherwise, the original error is re-thrown. Note that CancellationError is not caught and will always be re-thrown.

Definition

export declare function catchError<R = never>(onError?: ((error: any) => Task<R> |undefined)| undefined): Task.Modifier<R>;

Type parameters

Name	Description
R

Parameters

Name	Type	Description
onError	((error: any) => Task<R> |undefined)| undefined

chain

Chains multiple Tasks together, executing them sequentially. The output of each Task is passed as the input to the next Task.

Definition

export declare function chain<RS extends any[], A extends any[]>(tasks: Task.Chain<RS, A>): Task<Last<RS>, A>;

Type parameters

Name	Description
RS
A

Parameters

Name	Type	Description
tasks	Task.Chain<RS, A>

clog

A Task that logs its direct arguments to the console.

Definition

clog: (...args: Parameters<(typeof console)['log']>) => Task<void>

Parameters

Name	Type	Description
args	Parameters<(typeof console)['log']>

clogArgs

A Task that logs its Task arguments to the console.

Definition

clogArgs: <A extends readonly any[] = []>(_context: Task.Context, ...args: A) => Task.Result<A>

Type parameters

Name	Description
A

Parameters

Name	Type	Description
_context	Task.Context
args	A

combined

Combines multiple Task modifiers into a single modifier. If no modifiers are provided, returns an identity modifier. Modifiers are applied in the order they are provided.

Definition

export declare function combined(...modifiers: Task.Modifier[]): Task.Modifier;

Parameters

Name	Type	Description
modifiers	Task.Modifier[]

delay

Creates a Task that delays execution for a specified number of milliseconds.

Definition

export declare function delay(ms: number): Task<void, any[]>;

Parameters

Name	Type	Description
ms	number

effect

Creates a Task that applies a side-effect function when executed. The side-effect function receives the same arguments as the Task.

Definition

export declare function effect<R, A extends readonly any[] = []>(fn: (...args: A) => R): (...args: A) => Task<R>;

Type parameters

Name	Description
R
A

Parameters

Name	Type	Description
fn	(...args: A) => R

joinAll

undocumented

Definition

export declare function joinAll<R extends readonly any[]>(jobs: {
  [K in keyof R]: Task.Job<R[K]>;
}): Promise<R>;

Type parameters

Name	Description
R

Parameters

Name	Type	Description
jobs	{   [K in keyof R]: Task.Job<R[K]>; }

mapOutput

Maps the output of a Task using a provided function. The mapping function receives the output of the Task as its arguments.

Definition

export declare function mapOutput<RO, RI extends [any]>(fn: (...input: RI) => RO): Task<RO, RI>;

Type parameters

Name	Description
RO
RI

Parameters

Name	Type	Description
fn	(...input: RI) => RO

mapOutputArr

Maps the output of a Task that returns an array using a provided function. The mapping function receives the elements of the output array as its arguments.

Definition

export declare function mapOutputArr<RO, RI extends readonly any[]>(fn: (...input: RI) => RO): Task<RO, [RI]>;

Type parameters

Name	Description
RO
RI

Parameters

Name	Type	Description
fn	(...input: RI) => RO

race

Executes multiple Tasks concurrently and returns the result of the first Task to complete. All other Tasks are cancelled once one completes.

Definition

export declare function race<R, A extends readonly any[] = []>(tasks: Task<R, {
  [AK in keyof A]?: A[AK];
}>[], options?: {
  maxBranch?: number | undefined;
}): Task<R, A>;

Type parameters

Name	Description
R
A

Parameters

Name	Type	Description
tasks	Task<R, {   [AK in keyof A]?: A[AK]; }>[]
options	{   maxBranch?: number | undefined; }

repeat

Repeats a Task a specified number of times.

Definition

export declare function repeat(times: number): <A extends readonly any[] = []>(task: Task<unknown, [...A, number]>) => Task<void, A>;

Parameters

Name	Type	Description
times	number

taskify

Converts a function that takes an AbortSignal in one of its arguments into a Task. The Task will automatically handle cancellation using the Task's context signal.

Definition

export declare function taskify<R, A extends readonly any[], N extends number, S extends string = 'signal'>(fn: (...args: A) => R, signalArgIndex: N, signalPropName?: S): A[N] extends {
  [N in S]?: AbortSignal | undefined;
} |null| undefined ? Task<R, A> : never;

Type parameters

Name	Description
R
A
N
S

Parameters

Name	Type	Description
fn	(...args: A) => R	The function to convert, which must take an AbortSignal in one of its arguments.
signalArgIndex	N
signalPropName	S

example

import { taskify } from '@rimbu/task/ops';
import { readFile } from 'fs/promises';
const readFileTask = taskify(readFile, 1);
const job = Task.launch(readFileTask, ['path/to/file', { encoding: 'utf-8' }]);
job.cancel();
await job.join({ recover: () => {} }); // recovers from error or cancellation

throwError

A Task that throws an error created by the provided function when executed.

Definition

throwError: (createError: () => any) => Task<never>

Parameters

Name	Type	Description
createError	() => any

throwErrorClass

A Task that throws an error of the specified class when executed.

Definition

throwErrorClass: (ErrorClass: new () => any) => Task<never>

Parameters

Name	Type	Description
ErrorClass	new () => any

withArgs

Binds specific arguments to a Task, returning a new Task that requires no arguments.

Definition

export declare function withArgs<R, A extends readonly any[]>(task: Task<R, A>, ...args: A): Task<R>;

Type parameters

Name	Description
R
A

Parameters

Name	Type	Description
task	Task<R, A>	The original Task to bind arguments to.
args	A

withRetry

Retries a Task a specified number of times with optional delays between attempts. If the Task fails after all attempts, a RetryExhaustedError is thrown.

Definition

export declare function withRetry(times?: number | undefined, delayMsArray?: number[]): Task.Modifier;

Parameters

Name	Type	Description
times	number | undefined	The maximum number of retry attempts. If undefined, retries indefinitely.
delayMsArray	number[]

withTimeout

Applies a timeout to a Task. If the Task does not complete within the specified time, it will be cancelled and a TimeoutError will be thrown.

Definition

export declare function withTimeout(ms: number): Task.Modifier;

Parameters

Name	Type	Description
ms	number

Constants

Name	Description
cancelAllChildren	A Task that cancels all child contexts of the current context when executed. This is useful for stopping all ongoing child tasks.
cancelContext	A Task that cancels the current context when executed.
cancelParent	A Task that cancels the parent context of the current context when executed. If there is no parent context, it throws a CancellationError.
runSingleCancelNew	undocumented
runSingleCancelPrevious	undocumented