Task

Task

new Task(getFuture)

Creates a Task from a function that returns a Future.

Parameters:
Name Type Description
getFuture function

A function which returns a Future

Methods

run(onSuccessopt, onErroropt, onCancelopt) → {Future}

Starts executing the Task. No side effect will take place until this method is invoked. Returns a Future representing the outcome of the Task.

A started task can be cancelled by invoking Future#cancel on the returned Future. Cancelling a Task will cancel the the currently executing step and will skip all subsequent steps.

Parameters:
Name Type Attributes Description
onSuccess function <optional>

callback invoked if the Task has succeded

onError function <optional>

callback invoked if the Task has aborted. If not provided an Exception will be thrown

onCancel function <optional>

callback invoked if the Task was cancelled

Returns:
Type:
Future

orElse(task) → {Task}

Run a race between the 2 proivded Tasks. Returns a new Task that will

  • resolve with the value of the first resolved input Task
  • reject with the error of the first rejected input Task. The other Task will be cancelled.
  • If the 2 input Tasks are cancelled, the Task wil be cancelled with reason of the last cancelled Task.
Parameters:
Name Type Description
task Task

a Task that this task will be raced against

Returns:
Type:
Task

then(onSuccessopt, onErroropt, onCancelopt) → {Task}

Chains a callback that will run after this Task completes. Each of the 3 chained callbacks can return another Task to execute further actions. returning a non Task value from a callback has the same effect as returning Task.resolve(value).

Note that unlike Task#run, this method doesn't start the execution of the Task. All it does is to construct a new Task that, when started, will run in sequence the two tasks (this Task and the one returned by the invoked callback).

The current Task will invoke the appropriate callback corresponding to the type of its outcome (success, error or cancellation). Each callback is optional. In case the corresponding callback was not provided, the final outcome will be the same as the first Task.

Cancelling the result Task will cancel the current step in the chain and skip the execution of the Tasks in the subsequent step(s).

This method returns a new Task that will complete with the same outcome as the second Task returned from the appropriate callback.

Parameters:
Name Type Attributes Description
onSuccess function <optional>

callback invoked if the Task has succeded

onError function <optional>

callback invoked if the Task has aborted. If

onCancel function <optional>

callback invoked if the Task was cancelled

Returns:
Type:
Task

log(prefix) → {Future}

a helper method to debug Tasks. It will log the outcome of the Task in the console. All log messages will be prefixed withe provided string.

This method returns a Future that represent the outcome of the Task.

Parameters:
Name Type Description
prefix string

used to prefix logged messages

Returns:
Type:
Future

(static) of(value) → {Task}

Returns a Task that will always resolve with the provided value

Parameters:
Name Type Description
value *
Returns:
Type:
Task

(static) resolve()

Same as Task.of

(static) reject(error) → {Task}

Returns a Task that will always reject with the provided value

Parameters:
Name Type Description
error *
Returns:
Type:
Task

(static) cancel(reason) → {Task}

Returns a Task that will always be cancelled with the provided value

Parameters:
Name Type Description
reason *
Returns:
Type:
Task

(static) from(executor) → {Task}

Creates a Task that, when started, will get its outcome using the provided executor function.

Each time the Task is started using Task.run, the executor function will be invoked with 3 callbacks: resolve, reject and cancel. The executor function must invoke the appropriate callback to notify the Task's outcome.

Task's executors are invoked synchrously (immediately).

Parameters:
Name Type Description
executor executor
Returns:
Type:
Task

(static) join() → {Task}

Creates a Task that will be complete with the same outcome as the provided Future.

Note that cancelling the execution of the returned task will not cancel the original Future.

Returns:
Type:
Task

(static) empty() → {Task}

Returns a Task that does nothing. An empty task doesn't have an outcome.

In particular an empty task has the following properties (≅ means the 2 tasks
behave in similar ways)

emptyTask.orElse(anotherTask)         ≅ anotherTask
anotherTask.orElse(emptyTask)         ≅ anotherTask
emptyTask.then(_ => anotherTask)      ≅ emptyTask
anotherTask.then(_ => emptyTask)      ≅ emptyTask
Task.zipw(f, emptyTask, anotherTask)  ≅ emptyTask
Task.zipw(f, anotherTask, emptyTask)  ≅ emptyTask
Returns:
Type:
Task

(static) race2()

Same as task1.orElse(task2)

(static) race(tasks) → {Task}

Runs a race between all the provided Tasks. This is the same as

task1.orElse(task2)......orElse(taskN)

The Task will resolve/reject with the first resolved/rejected Task. In either case the other Tasks are automatically cancelled. If all the Tasks are cancelled, the result Task will be cancelled with the last cancellation's result.

Cancelling the result Task will cancel all other Tasks.

Parameters:
Name Type Description
tasks Array.<Task>
Returns:
Type:
Task

(static) zipw(f, task1, task2) → {Task}

Combine the resolved outcomes of 2 input Tasks using the provided function.

If one of the input Tasks is rejected/cancelled, then the result Task will be rejected/cancelled a well. The other Task will also be automatically cancelled.

Cancelling the result Task will cancel the 2 input Tasks (if still pending)

Parameters:
Name Type Description
f function

Used to combine the resolved values of the 2 tasks

task1 Task
task2 Task
Returns:
Type:
Task

(static) all(tasks) → {Task}

Returns a Task that will resolve with Array of all values if all input tasks are resolved. If any input Task is rejected/cancelled, the result Task will also be rejected/cancelled. In either case all Tasks that are still pending will be automatically cancelled.

Cancelling the result Task will cancel all input Tasks (if pending)

Parameters:
Name Type Description
tasks Array.<Task>
Returns:
Type:
Task

(static) traverse(f, values) → {Task}

Transform the input values into Tasks using the provided function and returns that combines the values of all created Tasks using Task.all

Parameters:
Name Type Description
f function

A function that takes a value and returns a Task

values Array.<object>

An array of values

Returns:
Type:
Task

(static) detect(p, tasks)

Pass the input Tasks trough an async predicate (a function that returns a Task of a Boolean). The result Task will resolve with the first value that pass the async test.

Parameters:
Name Type Description
p function

A function that takes a value and returnd Task of a Boolean

tasks Array.<Task>

(static) apply(f, tasks, ctx)

Returns a Task that will applies the provided function to the resolved values of the input Tasks. The Task will be rejected/cancelled if any of the input Tasks is rejected/cancelled and the other Tasks will be cancelled if still pending.

Parameters:
Name Type Description
f function
tasks Array.<Task>
ctx object

If provided, will be used as a this for the function

(static) lift()

Transforms a function that acts on plain values to a function that acts on Tasks. This is the same as Task.apply.bind(undefined, f)