Task

Index

Constructor

• create
• error
• ok
• reject
• resolve

Type

• hasInstance

Other

• ErrorOf
• ValueOf
• all
• allSettled
• andRun
• andThen
• any
• from
• ignore
• map
• mapError
• mapResult
• orElse
• run
• tryCall

Constructor

create

• create<Value, Error>(sideEffect: (resolver: { canceler: TaskCanceler; run: <V, E>(task: TaskLike<V, E>) => Awaitable<Result<V, E>> }) => Awaitable<Result<Value, Error>>): Task<Value, Error>

• Task constructor

  @example

  const getTime = Task(() => Task.ok(Date.now()));
  const fetchTask = (url: string) => Task(() => fetch(url).then(Task.ok, Task.error));
  const delay = (ms: number) => Task(() => new Promise(resolve => { setTimeout(() => resolve(Task.ok()); }), ms));

  ---

  Type parameters

  • Value
  • Error = never

error

• error(): Result<never, void>
• error<E>(resultError: E): Result<never, E>

• Create a new Error object

  @example

  Error();// { _: 'Error', ok: false, value: undefined }
  Error(new globalThis.Error('my message'));// { _: 'Error', ok: false, error: Error}

ok

• ok(): Result<void, never>
• ok<V>(resultValue: V): Result<V, never>

• Create a new Ok object

  @example

  Ok();// { _: 'Ok', ok: true, value: undefined }
  Ok('value');// { _: 'Ok', ok: true, value: 'value'}

reject

• reject<Value>(): Task<Value, void>
• reject<Value, Error>(errorValue: Error): Task<Value, Error>

• Constructor that always returns a failed Task that rejects void.

  @example

  const task = Task.reject();
  const result = Task.run(task);// Result.Error()

  ---

  Type parameters

  • Value = never

resolve

• resolve<Error>(): Task<void, Error>
• resolve<Value, Error>(value: Value): Task<Value, Error>

• Constructor that always returns a successful Task that resolves void.

  @example

  const task = Task.resolve();
  const result = Task.run(task);// Result.Ok()

  ---

  Type parameters

  • Error = never

Type

hasInstance

• hasInstance(anyValue: unknown): anyValue is TaskLike<unknown, unknown>

• Return true if anyValue is a valid Task

  @example

  Task.hasInstance(Task.resolve(...)); // true
  Task.hasInstance({}); // false

Other

ErrorOf

ErrorOf<T>: T extends Task<any, infer Error> ? Error : never

Extracts error type of task T

---

Type parameters

• T

ValueOf

ValueOf<T>: T extends Task<infer V, any> ? V : never

Extracts value type of task T

---

Type parameters

• T

all

• all<T>(tasks: [...T[]]): Task<{ [ K in keyof T ]: Task.ValueOf<T[K]> }, Task.ErrorOf<T[keyof T]>>
• all<Value, Error>(tasks: Iterable<TaskLike<Value, Error>, any, any>): Task<ReadonlyArray<Value>, Error>

• Resolves with the array of all task values, or reject with the first error

  @example

  const success = Task.all([
    Task.resolve(1),
    Task.resolve(2),
  ]);
  const successResult = Task.run(success);// Result.Ok([1, 2])
  
  const failure = Task.all([
    Task.resolve(1),
    Task.reject('error'),
  ]);
  const failureResult = Task.run(failure);// Result.Error('error')

  ---

  Type parameters

  • T: readonly TaskLike<any, any>[]

allSettled

• allSettled<T>(tasks: [...T[]]): Task<{ [ K in keyof T ]: Result<Task.ValueOf<T[K]>, Task.ErrorOf<T[K]>> }, never>
• allSettled<Value, Error>(tasks: Iterable<TaskLike<Value, Error>, any, any>): Task<ReadonlyArray<Result<Value, Error>>, never>

• Resolves an array of all task results

  @example

  const task = Task.allSettled([
    Task.reject(1),
    Task.resolve(2),
  ]);
  const taskResults = Task.run(task);// [Result.Error(1), Result.Ok(2)]

  ---

  Type parameters

  • T: TaskLike<any, any>[]

andRun

• andRun<ValueFrom, ErrorFrom, ErrorTo>(self: TaskLike<ValueFrom, ErrorFrom>, fn: (value: ValueFrom) => TaskLike<any, ErrorTo>): Task<ValueFrom, ErrorFrom | ErrorTo>

• Similar to andThen but the task keep task resolved value

  @example

  const success = Task.resolve('foo');
  Task.andRun(success, (value) => Console.log('result=', value));// console.log('result=foo'); then resolves 'foo'
  Task.andRun(success, (value) => Task.reject(`SomeError`));// Task.reject('SomeError')
  
  const failure = Task.reject('PreviousError');
  Task.andRun(failure, (value) => Task.resolve(`never_used`));// Task.reject('PreviousError')

  ---

  Type parameters

  • ValueFrom
  • ErrorFrom
  • ErrorTo

andThen

• andThen<ValueFrom, ErrorFrom, ValueTo, ErrorTo>(self: TaskLike<ValueFrom, ErrorFrom>, fn: (value: ValueFrom) => TaskLike<ValueTo, ErrorTo>): Task<ValueTo, ErrorFrom | ErrorTo>

• Calls fn if the task is successful, otherwise returns the failed task untouched. This function can be used for control flow based on Task values.

  @example

  const success = Task.resolve('foo');
  Task.andThen(success, (value) => Task.resolve(`${value}_then`));// Task.resolve('foo_then')
  
  const failure = Task.reject('PreviousError');
  Task.andThen(failure, (value) => Task.resolve(`never_used`));// Task.reject('PreviousError')

  ---

  Type parameters

  • ValueFrom
  • ErrorFrom
  • ValueTo
  • ErrorTo

any

• any<T>(tasks: [...T[]]): Task<Task.ValueOf<T[keyof T]>, AggregateError<{ [ K in keyof T ]: Task.ErrorOf<T[K]> }>>
• any<Value, Error>(tasks: Iterable<TaskLike<Value, Error>, any, any>): Task<Value, AggregateError<Error[]>>

• Resolves with the first value, or reject with an aggregated error

  @example

  const success = Task.any([
    Task.reject(1),
    Task.resolve(2),
  ]);
  const successResult = Task.run(success);// Result.Ok(2)
  
  const failure = Task.any([
    Task.reject('error1'),
    Task.reject('error2'),
  ]);
  const failureResult = Task.run(failure);// Result.Error(AggregateError({ errors: ['error1', 'error2']}))

  ---

  Type parameters

  • T: TaskLike<any, any>[]

from

• from<Value, Error>(taskLike: TaskLike<Value, Error> | TaskFunction<Value, Error>): Task<Value, Error>

• Create a Task from a Symbol.run function or a TaskLike

  @example

  const task = Task.from(({ resolve }) => resolve('hello'));// from a callback
  const task = Task.from({ [Symbol.run]: ({ resolve }) => resolve('hello') });// from a TaskLike

  ---

  Type parameters

  • Value
  • Error

ignore

• ignore<Error>(self: Task<unknown, Error>): Task<void, Error>

• Ignores value of task

  @example

  const task = Task.resolve('foo');
  Task.ignore(task);// Task.resolve()

  ---

  Type parameters

  • Error

map

• map<ValueFrom, ErrorFrom, ValueTo>(self: TaskLike<ValueFrom, ErrorFrom>, fn: (value: ValueFrom) => ValueTo): Task<ValueTo, ErrorFrom>

• Maps a Task<Value, Error> to Task<NewValue, Error> by applying a function to a success value, leaving a failure untouched. This function can be used to compose the results of two functions.

  @example

  const task = Task.resolve('foo');
  Task.map(task, (value) => `${value}_bar`));// Task.resolve('foo_bar')

  ---

  Type parameters

  • ValueFrom
  • ErrorFrom
  • ValueTo

mapError

• mapError<ValueFrom, ErrorFrom, ErrorTo>(self: TaskLike<ValueFrom, ErrorFrom>, fn: (error: ErrorFrom) => ErrorTo): Task<ValueFrom, ErrorTo>

• Maps a Task<Value, ErrorFrom> to Task<Value, ErrorTo> by applying a function to a contained failure error, leaving a success value untouched. This function can be used to pass through a successful result while handling an error.

  @example

  const task = Task.reject('error');
  Task.mapError(task, (value) => `${value}_bar`));// Task.reject('error_bar')

  ---

  Type parameters

  • ValueFrom
  • ErrorFrom
  • ErrorTo

mapResult

• mapResult<ValueFrom, ErrorFrom, ValueTo, ErrorTo>(self: TaskLike<ValueFrom, ErrorFrom>, mapFn: (result: Result<ValueFrom, ErrorFrom>) => Result<ValueTo, ErrorTo>): Task<ValueTo, ErrorTo>

• Maps a Task<ValueFrom, ErrorFrom> to Task<ValueTo, ErrorTo> by applying a function to the result of the task.

  @example

  const task = Task.reject('error');
  const handledTask = Task.mapResult(task, (result) =>
     Result.isOk(result) ? result : Result.Ok('handled_value') )
  ); // Task.resolve('handled_value')

  ---

  Type parameters

  • ValueFrom
  • ErrorFrom
  • ValueTo
  • ErrorTo

orElse

• orElse<ValueFrom, ErrorFrom, ValueTo, ErrorTo>(self: TaskLike<ValueFrom, ErrorFrom>, fn: (error: ErrorFrom) => TaskLike<ValueTo, ErrorTo>): Task<ValueFrom | ValueTo, ErrorTo>

• Calls fn if the task is failed, otherwise returns the successful task untouched. This function can be used for control flow based on Task values.

  @example

  const success = Task.resolve('foo');
  Task.orElse(success, (value) => Task.resolve(`never_used`));// Task.resolve('foo')
  
  const failure = Task.reject('PreviousError');
  Task.orElse(failure, (error) => Task.reject(`${value}_caught`));// Task.reject('PreviousError_caught')

  ---

  Type parameters

  • ValueFrom
  • ErrorFrom
  • ValueTo
  • ErrorTo

run

• run<Value, Error>(self: TaskLike<Value, Error>, canceler?: TaskCanceler): Awaitable<Result<Value, Error>>

• Run task and return the result or a promise of the result

  ⚠ Impure function that may throw an error, it should be used on the edge of the program.

  @example

  const getMessage = Task.resolve('Hello World!');
  const messageResult = Task.run(getMessage);// Result.Ok('Hello World!')

  ---

  Type parameters

  • Value
  • Error

tryCall

• tryCall<Value, Error>(sideEffect: () => Awaitable<Value>, onError?: (error: unknown) => Awaitable<Error>): Task<Value, Error>

• Creates a new Task that resolves sideEffect(). When an exception is thrown then it rejects onError([thrown error]).

  @example

  const class ResponseError extends Error {}
  const fetch = Task.tryCall(
   () => fetch('my/url'), // Task will resolve Ok(fetch('my/url'))
   (error) => new ResponseError(), // Task will reject Error(new ResponseError())
  );// Task<Response, ResponseError>
  
  const randomNumber = Task.tryCall(async () => Math.random());// Task<number, never>

  ---

  Type parameters

  • Value
  • Error = never