Task

Summary

Tasks are a robust way to handle any mutating changes that need to interface with a remote API.

Tasks help you handle and encapsulate optimistic updates, rollbacks, undo/redo, API responses, API errors, queuing, and multi-step dependencies.

They are especially useful in offline mode. Users may have taken tons of actions that we've queued up to process when they come back online.

Tasks represent individual changes to the datastore that alter the local cache and need to be synced back to the server.

To create your own task, subclass Task and implement the following required methods:

• Task::performLocal
• Task::performRemote

See their usage in the documentation below.

Task Dependencies

The Task system handles dependencies between multiple queued tasks. For example, the {SendDraftTask} has a dependency on the {SyncbackDraftTask} (aka saving) succeeding. To establish dependencies between tasks, your subclass may implement one or more of the following methods:

• Task::isDependentOnTask
• Task::onDependentTaskError
• Task::shouldDequeueOtherTask

Undo / Redo

The Task system also supports undo/redo handling. Your subclass must implement the following methods to enable this:

• Task::isUndo
• Task::canBeUndone
• Task::createUndoTask
• Task::createIdenticalTask

Offline Considerations

All tasks should gracefully handle the case when there is no network connection.

if we're offline the common behavior is for a task to:

1. Perform its local change
2. Attempt the remote request, which will fail
3. Have performRemote resolve a Task.Status.Retry
4. Sit queued up waiting to be retried

Remember that a user may be offline for hours and perform thousands of tasks in the meantime. It's important that your tasks implement shouldDequeueOtherTask and isDependentOnTask to make sure ordering always remains correct.

Serialization and Window Considerations

The whole {TaskQueue} and all of its Tasks are serialized and stored in the Database. This allows the {TaskQueue} to work across windows and ensures we don't lose any pending tasks if (a user is offline for a while) and quits and relaunches the application.

All instance variables you create must be able to be serialized to a JSON string and re-inflated. Notably, function objects will not be properly re-inflated.

if (you have instance variables that are instances of core {Model}) classes or {Task} classes, they will be automatically re-inflated to the correct class via Utils::deserializeRegisteredObject. if (you create) your own custom classes, they must be registered once per window via TaskRegistry::register

Example Task

Task Definition:

import _ from 'underscore'
import request from 'request'
import {Task, DatabaseStore} from 'nylas-exports'

class UpdateTodoTask extends Task {
constructor(existingTodo, newData) {
super()
this.existingTodo = existingTodo;
this.newData = newData;
}

performLocal() {
this.updatedTodo = _.extend(_.clone(this.existingTodo), this.newData);
return DatabaseStore.inTransaction((t) => t.persistModel(this.updatedTodo));
}

performRemote() {
return new Promise (resolve, reject) => {
const options = {url: "https://myapi.co", method: 'PUT', json: this.newData}
request(options, (error, response, body) => {
if (error) {
resolve(Task.Status.Failed);
}
resolve(Task.Status.Success);
});
};
};
}

Task Usage:

import {Actions} from 'nylas-exports';
import UpdateTodoTask from './update-todo-task';

someMethod() {
...
const task = new UpdateTodoTask(existingTodo, {name: "Test"});
Actions.queueTask(task);
...
}

This example UpdateTodoTask does not handle undo/redo, nor does it rollback the changes if (there's an API error. See examples in) Task::performLocal for ideas on how to handle this.

Instance Methods

constructor()

performRemote(Task.Status.SuccessTask.Status.RetryTask.Status.ContinueTask.Status.Failed)

Parameters

Returns

isDependentOnTask(other)

Returns

shouldDequeueOtherTask(other)

Returns

shouldBeDequeuedOnDependencyFailure()

Returns

isUndo()

Returns

canBeUndone()

Returns

createUndoTask()

createIdenticalTask()

cancel()

label()

numberOfImpactedItems()