Mailspring/packages/nylas-mail/docs/classes/Task.html
2017-02-16 13:15:10 -08:00

1817 lines
49 KiB
HTML

<!DOCTYPE HTML>
<html lang="" >
<head>
<meta charset="UTF-8">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Task · Nylas Mail Plugin SDK</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content="">
<meta name="generator" content="GitBook 3.2.2">
<link rel="stylesheet" href="../gitbook/style.css">
<link rel="stylesheet" href="../gitbook/gitbook-plugin-search/search.css">
<link rel="stylesheet" href="../gitbook/gitbook-plugin-anchors/plugin.css">
<link rel="stylesheet" href="../gitbook/gitbook-plugin-highlight/website.css">
<link rel="stylesheet" href="../styles/website.css">
<meta name="HandheldFriendly" content="true"/>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="../gitbook/images/apple-touch-icon-precomposed-152.png">
<link rel="shortcut icon" href="../gitbook/images/favicon.ico" type="image/x-icon">
<link rel="next" href="TaskQueueStatusStore.html" />
<link rel="prev" href="StyleManager.html" />
<link rel="shortcut icon" href='../img/favicon.png' type="image/x-icon">
</head>
<body>
<div class="book">
<div class="book-summary">
<div id="book-search-input" role="search">
<input type="text" placeholder="Type to search" />
</div>
<nav role="navigation">
<ul class="summary">
<li class="chapter " data-level="1.1" >
<span>
Nylas Mail SDK Guides
</span>
</li>
<li class="chapter " data-level="1.2" data-path="../">
<a href="../">
Introduction
</a>
</li>
<li class="chapter " data-level="1.3" data-path="../guides/GettingStarted.html">
<a href="../guides/GettingStarted.html">
Getting Started
</a>
</li>
<li class="chapter " data-level="1.4" data-path="../guides/GettingStarted-2.html">
<a href="../guides/GettingStarted-2.html">
Getting Started Part 2
</a>
</li>
<li class="chapter " data-level="1.5" data-path="../guides/PackageOverview.html">
<a href="../guides/PackageOverview.html">
Building a Package
</a>
</li>
<li class="chapter " data-level="1.6" data-path="../guides/InterfaceConcepts.html">
<a href="../guides/InterfaceConcepts.html">
Interface Concepts
</a>
</li>
<li class="chapter " data-level="1.7" data-path="../guides/React.html">
<a href="../guides/React.html">
UI Components
</a>
</li>
<li class="chapter " data-level="1.8" data-path="../guides/Architecture.html">
<a href="../guides/Architecture.html">
Application Architecture
</a>
</li>
<li class="chapter " data-level="1.9" data-path="../guides/Debugging.html">
<a href="../guides/Debugging.html">
Debugging Nylas Mail
</a>
</li>
<li class="chapter " data-level="1.10" data-path="../guides/Database.html">
<a href="../guides/Database.html">
Accessing the Database
</a>
</li>
<li class="chapter " data-level="1.11" data-path="../guides/ComposerExtensions.html">
<a href="../guides/ComposerExtensions.html">
Extending the Composer
</a>
</li>
<li class="chapter " data-level="1.12" data-path="../guides/WritingSpecs.html">
<a href="../guides/WritingSpecs.html">
Writing Tests
</a>
</li>
<li class="chapter " data-level="1.13" data-path="../guides/IntegrationTesting.html">
<a href="../guides/IntegrationTesting.html">
Integration Testing
</a>
</li>
<li class="chapter " data-level="1.14" data-path="../guides/Windows.html">
<a href="../guides/Windows.html">
Developing on Windows
</a>
</li>
<li class="chapter " data-level="1.15" data-path="../guides/FAQ.html">
<a href="../guides/FAQ.html">
FAQ
</a>
</li>
<li class="header">Full Class Reference</li>
<li class="chapter " data-level="2.1" >
<span>
General
</span>
<ul class="articles">
<li class="chapter " data-level="2.1.1" data-path="Actions.html">
<a href="Actions.html">
Actions
</a>
</li>
<li class="chapter " data-level="2.1.2" data-path="BufferedProcess.html">
<a href="BufferedProcess.html">
BufferedProcess
</a>
</li>
<li class="chapter " data-level="2.1.3" data-path="ChangeFolderTask.html">
<a href="ChangeFolderTask.html">
ChangeFolderTask
</a>
</li>
<li class="chapter " data-level="2.1.4" data-path="ChangeLabelsTask.html">
<a href="ChangeLabelsTask.html">
ChangeLabelsTask
</a>
</li>
<li class="chapter " data-level="2.1.5" data-path="ChangeMailTask.html">
<a href="ChangeMailTask.html">
ChangeMailTask
</a>
</li>
<li class="chapter " data-level="2.1.6" data-path="Color.html">
<a href="Color.html">
Color
</a>
</li>
<li class="chapter " data-level="2.1.7" data-path="Config.html">
<a href="Config.html">
Config
</a>
</li>
<li class="chapter " data-level="2.1.8" data-path="Contenteditable.html">
<a href="Contenteditable.html">
Contenteditable
</a>
</li>
<li class="chapter " data-level="2.1.9" data-path="KeyCommandsRegion.html">
<a href="KeyCommandsRegion.html">
KeyCommandsRegion
</a>
</li>
<li class="chapter " data-level="2.1.10" data-path="NylasEnvConstructor.html">
<a href="NylasEnvConstructor.html">
NylasEnvConstructor
</a>
</li>
<li class="chapter " data-level="2.1.11" data-path="QueryResultSet.html">
<a href="QueryResultSet.html">
QueryResultSet
</a>
</li>
<li class="chapter " data-level="2.1.12" data-path="QuerySubscriptionPool.html">
<a href="QuerySubscriptionPool.html">
QuerySubscriptionPool
</a>
</li>
<li class="chapter " data-level="2.1.13" data-path="StyleManager.html">
<a href="StyleManager.html">
StyleManager
</a>
</li>
<li class="chapter active" data-level="2.1.14" data-path="Task.html">
<a href="Task.html">
Task
</a>
</li>
<li class="chapter " data-level="2.1.15" data-path="TaskQueueStatusStore.html">
<a href="TaskQueueStatusStore.html">
TaskQueueStatusStore
</a>
</li>
<li class="chapter " data-level="2.1.16" data-path="ThemeManager.html">
<a href="ThemeManager.html">
ThemeManager
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.2" >
<span>
Component Kit
</span>
<ul class="articles">
<li class="chapter " data-level="2.2.1" data-path="EventedIFrame.html">
<a href="EventedIFrame.html">
EventedIFrame
</a>
</li>
<li class="chapter " data-level="2.2.2" data-path="Flexbox.html">
<a href="Flexbox.html">
Flexbox
</a>
</li>
<li class="chapter " data-level="2.2.3" data-path="InjectedComponent.html">
<a href="InjectedComponent.html">
InjectedComponent
</a>
</li>
<li class="chapter " data-level="2.2.4" data-path="InjectedComponentSet.html">
<a href="InjectedComponentSet.html">
InjectedComponentSet
</a>
</li>
<li class="chapter " data-level="2.2.5" data-path="Menu.html">
<a href="Menu.html">
Menu
</a>
</li>
<li class="chapter " data-level="2.2.6" data-path="MenuItem.html">
<a href="MenuItem.html">
MenuItem
</a>
</li>
<li class="chapter " data-level="2.2.7" data-path="MenuNameEmailItem.html">
<a href="MenuNameEmailItem.html">
MenuNameEmailItem
</a>
</li>
<li class="chapter " data-level="2.2.8" data-path="MultiselectActionBar.html">
<a href="MultiselectActionBar.html">
MultiselectActionBar
</a>
</li>
<li class="chapter " data-level="2.2.9" data-path="MultiselectList.html">
<a href="MultiselectList.html">
MultiselectList
</a>
</li>
<li class="chapter " data-level="2.2.10" data-path="ResizableRegion.html">
<a href="ResizableRegion.html">
ResizableRegion
</a>
</li>
<li class="chapter " data-level="2.2.11" data-path="RetinaImg.html">
<a href="RetinaImg.html">
RetinaImg
</a>
</li>
<li class="chapter " data-level="2.2.12" data-path="Spinner.html">
<a href="Spinner.html">
Spinner
</a>
</li>
<li class="chapter " data-level="2.2.13" data-path="UnsafeComponent.html">
<a href="UnsafeComponent.html">
UnsafeComponent
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.3" >
<span>
Extensions
</span>
<ul class="articles">
<li class="chapter " data-level="2.3.1" data-path="ComposerExtension.html">
<a href="ComposerExtension.html">
ComposerExtension
</a>
</li>
<li class="chapter " data-level="2.3.2" data-path="ContenteditableExtension.html">
<a href="ContenteditableExtension.html">
ContenteditableExtension
</a>
</li>
<li class="chapter " data-level="2.3.3" data-path="DraftStoreExtension.html">
<a href="DraftStoreExtension.html">
DraftStoreExtension
</a>
</li>
<li class="chapter " data-level="2.3.4" data-path="MessageStoreExtension.html">
<a href="MessageStoreExtension.html">
MessageStoreExtension
</a>
</li>
<li class="chapter " data-level="2.3.5" data-path="MessageViewExtension.html">
<a href="MessageViewExtension.html">
MessageViewExtension
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.4" >
<span>
Models
</span>
<ul class="articles">
<li class="chapter " data-level="2.4.1" data-path="Contact.html">
<a href="Contact.html">
Contact
</a>
</li>
<li class="chapter " data-level="2.4.2" data-path="Message.html">
<a href="Message.html">
Message
</a>
</li>
<li class="chapter " data-level="2.4.3" data-path="Model.html">
<a href="Model.html">
Model
</a>
</li>
<li class="chapter " data-level="2.4.4" data-path="Thread.html">
<a href="Thread.html">
Thread
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.5" >
<span>
Stores
</span>
<ul class="articles">
<li class="chapter " data-level="2.5.1" data-path="AccountStore.html">
<a href="AccountStore.html">
AccountStore
</a>
</li>
<li class="chapter " data-level="2.5.2" data-path="ComponentRegistry.html">
<a href="ComponentRegistry.html">
ComponentRegistry
</a>
</li>
<li class="chapter " data-level="2.5.3" data-path="ContactStore.html">
<a href="ContactStore.html">
ContactStore
</a>
</li>
<li class="chapter " data-level="2.5.4" data-path="FocusedContentStore.html">
<a href="FocusedContentStore.html">
FocusedContentStore
</a>
</li>
<li class="chapter " data-level="2.5.5" data-path="TaskQueue.html">
<a href="TaskQueue.html">
TaskQueue
</a>
</li>
<li class="chapter " data-level="2.5.6" data-path="WorkspaceStore.html">
<a href="WorkspaceStore.html">
WorkspaceStore
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.6" >
<span>
Database
</span>
<ul class="articles">
<li class="chapter " data-level="2.6.1" data-path="Attribute.html">
<a href="Attribute.html">
Attribute
</a>
</li>
<li class="chapter " data-level="2.6.2" data-path="AttributeBoolean.html">
<a href="AttributeBoolean.html">
AttributeBoolean
</a>
</li>
<li class="chapter " data-level="2.6.3" data-path="AttributeCollection.html">
<a href="AttributeCollection.html">
AttributeCollection
</a>
</li>
<li class="chapter " data-level="2.6.4" data-path="AttributeDateTime.html">
<a href="AttributeDateTime.html">
AttributeDateTime
</a>
</li>
<li class="chapter " data-level="2.6.5" data-path="AttributeJoinedData.html">
<a href="AttributeJoinedData.html">
AttributeJoinedData
</a>
</li>
<li class="chapter " data-level="2.6.6" data-path="AttributeNumber.html">
<a href="AttributeNumber.html">
AttributeNumber
</a>
</li>
<li class="chapter " data-level="2.6.7" data-path="AttributeObject.html">
<a href="AttributeObject.html">
AttributeObject
</a>
</li>
<li class="chapter " data-level="2.6.8" data-path="AttributeServerId.html">
<a href="AttributeServerId.html">
AttributeServerId
</a>
</li>
<li class="chapter " data-level="2.6.9" data-path="AttributeString.html">
<a href="AttributeString.html">
AttributeString
</a>
</li>
<li class="chapter " data-level="2.6.10" data-path="DatabaseStore.html">
<a href="DatabaseStore.html">
DatabaseStore
</a>
</li>
<li class="chapter " data-level="2.6.11" data-path="Matcher.html">
<a href="Matcher.html">
Matcher
</a>
</li>
<li class="chapter " data-level="2.6.12" data-path="ModelQuery.html">
<a href="ModelQuery.html">
ModelQuery
</a>
</li>
<li class="chapter " data-level="2.6.13" data-path="SortOrder.html">
<a href="SortOrder.html">
SortOrder
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.7" >
<span>
Drafts
</span>
<ul class="articles">
<li class="chapter " data-level="2.7.1" data-path="DraftChangeSet.html">
<a href="DraftChangeSet.html">
DraftChangeSet
</a>
</li>
<li class="chapter " data-level="2.7.2" data-path="DraftEditingSession.html">
<a href="DraftEditingSession.html">
DraftEditingSession
</a>
</li>
<li class="chapter " data-level="2.7.3" data-path="DraftStore.html">
<a href="DraftStore.html">
DraftStore
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.8" >
<span>
NylasEnv
</span>
<ul class="articles">
<li class="chapter " data-level="2.8.1" data-path="PackageManager.html">
<a href="PackageManager.html">
PackageManager
</a>
</li>
</ul>
</li>
<li class="chapter " data-level="2.9" >
<span>
Atom
</span>
</li>
<li class="divider"></li>
<li>
<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
Published with GitBook
</a>
</li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<!-- Title -->
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i>
<a href=".." >Task</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<div id="book-search-results">
<div class="search-noresults">
<section class="normal markdown-section">
<h1 id="task"><a name="task" class="plugin-anchor" href="#task"><i class="fa fa-link" aria-hidden="true"></i></a>Task</h1>
<h2 id="summary"><a name="summary" class="plugin-anchor" href="#summary"><i class="fa fa-link" aria-hidden="true"></i></a>Summary</h2>
<p>Tasks are a robust way to handle any mutating changes that need
to interface with a remote API.</p>
<p>Tasks help you handle and encapsulate optimistic updates, rollbacks,
undo/redo, API responses, API errors, queuing, and multi-step
dependencies.</p>
<p>They are especially useful in offline mode. Users may have taken tons of
actions that we&apos;ve queued up to process when they come back online.</p>
<p>Tasks represent individual changes to the datastore that alter the local
cache and need to be synced back to the server.</p>
<p>To create your own task, subclass Task and implement the following
required methods:</p>
<ul>
<li><a href="Task.html#performLocal">Task::performLocal</a></li>
<li><a href="Task.html#performRemote">Task::performRemote</a></li>
</ul>
<p>See their usage in the documentation below.</p>
<h2 id="task-dependencies"><a name="task-dependencies" class="plugin-anchor" href="#task-dependencies"><i class="fa fa-link" aria-hidden="true"></i></a>Task Dependencies</h2>
<p>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:</p>
<ul>
<li><a href="Task.html#isDependentOnTask">Task::isDependentOnTask</a></li>
<li><a href="Task.html#onDependentTaskError">Task::onDependentTaskError</a></li>
<li><a href="Task.html#shouldDequeueOtherTask">Task::shouldDequeueOtherTask</a></li>
</ul>
<h2 id="undo--redo"><a name="undo--redo" class="plugin-anchor" href="#undo--redo"><i class="fa fa-link" aria-hidden="true"></i></a>Undo / Redo</h2>
<p>The Task system also supports undo/redo handling. Your subclass must
implement the following methods to enable this:</p>
<ul>
<li><a href="Task.html#isUndo">Task::isUndo</a></li>
<li><a href="Task.html#canBeUndone">Task::canBeUndone</a></li>
<li><a href="Task.html#createUndoTask">Task::createUndoTask</a></li>
<li><a href="Task.html#createIdenticalTask">Task::createIdenticalTask</a></li>
</ul>
<h2 id="offline-considerations"><a name="offline-considerations" class="plugin-anchor" href="#offline-considerations"><i class="fa fa-link" aria-hidden="true"></i></a>Offline Considerations</h2>
<p>All tasks should gracefully handle the case when there is no network
connection.</p>
<p>if we&apos;re offline the common behavior is for a task to:</p>
<ol>
<li>Perform its local change</li>
<li>Attempt the remote request, which will fail</li>
<li>Have <code>performRemote</code> resolve a <code>Task.Status.Retry</code></li>
<li>Sit queued up waiting to be retried</li>
</ol>
<p>Remember that a user may be offline for hours and perform thousands of
tasks in the meantime. It&apos;s important that your tasks implement
<code>shouldDequeueOtherTask</code> and <code>isDependentOnTask</code> to make sure ordering
always remains correct.</p>
<h2 id="serialization-and-window-considerations"><a name="serialization-and-window-considerations" class="plugin-anchor" href="#serialization-and-window-considerations"><i class="fa fa-link" aria-hidden="true"></i></a>Serialization and Window Considerations</h2>
<p>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&apos;t lose any pending tasks if (a user is offline for a while)
and quits and relaunches the application.</p>
<p>All instance variables you create must be able to be serialized to a
JSON string and re-inflated. Notably, <strong><code>function</code> objects will not be
properly re-inflated</strong>.</p>
<p>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 <a href="Utils.html#deserializeRegisteredObject">Utils::deserializeRegisteredObject</a>. if (you create)
your own custom classes, they must be registered once per window via
<a href="TaskRegistry.html#register">TaskRegistry::register</a></p>
<h2 id="example-task"><a name="example-task" class="plugin-anchor" href="#example-task"><i class="fa fa-link" aria-hidden="true"></i></a>Example Task</h2>
<p><strong>Task Definition</strong>:</p>
<pre><code class="lang-js"><span class="hljs-keyword">import</span> _ <span class="hljs-keyword">from</span> <span class="hljs-string">&apos;underscore&apos;</span>
<span class="hljs-keyword">import</span> request <span class="hljs-keyword">from</span> <span class="hljs-string">&apos;request&apos;</span>
<span class="hljs-keyword">import</span> {Task, DatabaseStore} <span class="hljs-keyword">from</span> <span class="hljs-string">&apos;nylas-exports&apos;</span>
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">UpdateTodoTask</span> <span class="hljs-keyword">extends</span> <span class="hljs-title">Task</span> </span>{
<span class="hljs-keyword">constructor</span>(existingTodo, newData) {
<span class="hljs-keyword">super</span>()
<span class="hljs-keyword">this</span>.existingTodo = existingTodo;
<span class="hljs-keyword">this</span>.newData = newData;
}
performLocal() {
<span class="hljs-keyword">this</span>.updatedTodo = _.extend(_.clone(<span class="hljs-keyword">this</span>.existingTodo), <span class="hljs-keyword">this</span>.newData);
<span class="hljs-keyword">return</span> DatabaseStore.inTransaction((t) =&gt; t.persistModel(<span class="hljs-keyword">this</span>.updatedTodo));
}
performRemote() {
<span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Promise</span> (resolve, reject) =&gt; {
<span class="hljs-keyword">const</span> options = {url: <span class="hljs-string">&quot;https://myapi.co&quot;</span>, method: <span class="hljs-string">&apos;PUT&apos;</span>, json: <span class="hljs-keyword">this</span>.newData}
request(options, (error, response, body) =&gt; {
<span class="hljs-keyword">if</span> (error) {
resolve(Task.Status.Failed);
}
resolve(Task.Status.Success);
});
};
};
}
</code></pre>
<p><strong>Task Usage</strong>:</p>
<pre><code class="lang-coffee">import {Actions} from <span class="hljs-string">&apos;nylas-exports&apos;</span>;
import UpdateTodoTask from <span class="hljs-string">&apos;./update-todo-task&apos;</span>;
someMethod() {
...
const task = <span class="hljs-keyword">new</span> UpdateTodoTask(existingTodo, {name: <span class="hljs-string">&quot;Test&quot;</span>});
Actions.queueTask(task);
...
}
</code></pre>
<p>This example <code>UpdateTodoTask</code> does not handle undo/redo, nor does it
rollback the changes if (there&apos;s an API error. See examples in)
<a href="Task.html#performLocal">Task::performLocal</a> for ideas on how to handle this.</p>
<ul>
</ul>
<h3 id="instance-methods"><a name="instance-methods" class="plugin-anchor" href="#instance-methods"><i class="fa fa-link" aria-hidden="true"></i></a>Instance Methods</h3>
<h4 id="constructor" class="function-name"><a name="constructor" class="plugin-anchor" href="#constructor"><i class="fa fa-link" aria-hidden="true"></i></a>
constructor(<span class="args"></span>) <a href="#constructor" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>Override the constructor to pass initial args to your Task and
initialize instance variables.
**IMPORTANT:** if (you override the constructor, be sure to call)
`super`.
On construction, all Tasks instances are given a unique `id`.</p>
</div>
<h4 id="performRemote" class="function-name"><a name="performRemote" class="plugin-anchor" href="#performRemote"><i class="fa fa-link" aria-hidden="true"></i></a>
performRemote(<span class="args"><span class="arg">Task.Status.Success</span><span class="arg">Task.Status.Retry</span><span class="arg">Task.Status.Continue</span><span class="arg">Task.Status.Failed</span></span>) <a href="#performRemote" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>**Required** | Put the actual API request code here.
You must return a {Promise} that resolves to one of the following
status constants:
The resolved status will determine what the {TaskQueue} does with this
task when it is finished.
This is where you should put your actual API code. You can use the
node `request` library to easily hit APIs, or use the {NylasAPI} class
to talk to the [Nylas Platform API](https://nylas.com/cloud/docs/).
Here is a more detailed explanation of Task Statuses:
### Task.Status.Success
Resolve to `Task.Status.Success` when the task successfully completes.
Once done, the task will be dequeued and logged as a success.
### Task.Status.Retry
if (you resolve `Task.Status.Retry`, the task will remain on the queue)
and tried again later. Any other task dependent on the current one
will also continue waiting.
`Task.Status.Retry` is useful if (it looks like we&apos;re offline, or you)
get an API error code that indicates temporary failure.
### Task.Status.Continue
Resolving `Task.Status.Continue` will silently dequeue the task, allow
dependent tasks through, but not mark it as successfully resolved.
This is useful if (you get permanent API errors, but don&apos;t really care)
if (the task failed.)
### Task.Status.Failed
if (you catch a permanent API error code (like a 500), or something)
else goes wrong then resolve to `Task.Status.Failed`.
Resolving `Task.Status.Failed` will dequeue this task, and **dequeue
all dependent tasks**.
You can optionally return the error object itself for debugging
purposes by resolving an array of the form: `[Task.Status.Failed,
errorObject]`
You should not `throw` exceptions. Catch all cases yourself and
determine which `Task.Status` to resolve to. if (due to programmer)
error an exception is thrown, our {TaskQueue} will catch it, log it,
and deal with the task as if (it resolved `Task.Status.Failed`.)</p>
</div>
<p><strong>Parameters</strong></p>
<table class="arguments">
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td style="width:15%;">
<em>Task.Status.Success</em>
</td>
<td class="markdown-from-sourecode">
</td>
</tr>
<tr>
<td style="width:15%;">
<em>Task.Status.Retry</em>
</td>
<td class="markdown-from-sourecode">
</td>
</tr>
<tr>
<td style="width:15%;">
<em>Task.Status.Continue</em>
</td>
<td class="markdown-from-sourecode">
</td>
</tr>
<tr>
<td style="width:15%;">
<em>Task.Status.Failed</em>
</td>
<td class="markdown-from-sourecode">
</td>
</tr>
</table>
<p><strong>Returns</strong></p>
<table class="arguments">
<tr>
<th>Return Values</th>
</tr>
<tr><td class="markdown-from-sourecode">Returns a {Promise} that resolves to a valid `Task.Status` type.</td></tr>
</table>
<h4 id="isDependentOnTask" class="function-name"><a name="isDependentOnTask" class="plugin-anchor" href="#isDependentOnTask"><i class="fa fa-link" aria-hidden="true"></i></a>
isDependentOnTask(<span class="args"><span class="arg">other</span></span>) <a href="#isDependentOnTask" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>determines which other tasks this one is dependent on.
Any task that passes the truth test will be considered a &quot;dependency&quot;.
if a &quot;dependency&quot; has a `Task.Status.Failed`, then all downstream
tasks will get dequeued recursively for any of the downstream tasks that
return true for `shouldBeDequeuedOnDependencyFailure`
A task will also never be run at the same time as one of its
dependencies.</p>
</div>
<strong>Parameters</strong>
<table class="arguments">
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td style="width:15%;">
<em>other</em>
</td>
<td class="markdown-from-sourecode">
An instance of a {Task} you must test to see if (it&apos;s a) dependency of this one.
</td>
</tr>
</table>
<p><strong>Returns</strong></p>
<table class="arguments">
<tr>
<th>Return Values</th>
</tr>
<tr><td class="markdown-from-sourecode">Returns `true` (is dependent on) or `false` (is not dependent on)</td></tr>
</table>
<h4 id="shouldDequeueOtherTask" class="function-name"><a name="shouldDequeueOtherTask" class="plugin-anchor" href="#shouldDequeueOtherTask"><i class="fa fa-link" aria-hidden="true"></i></a>
shouldDequeueOtherTask(<span class="args"><span class="arg">other</span></span>) <a href="#shouldDequeueOtherTask" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>determines which other tasks this one should dequeue when
it is first queued.
Any task that passes the truth test will be considered &quot;obsolete&quot; and
dequeued immediately.
This is particularly useful in offline mode. Users may queue up tons
of tasks but when we come back online to process them, we only want to
process the latest one.</p>
</div>
<strong>Parameters</strong>
<table class="arguments">
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td style="width:15%;">
<em>other</em>
</td>
<td class="markdown-from-sourecode">
An instance of a {Task} you must test to see if (it&apos;s now) obsolete.
</td>
</tr>
</table>
<p><strong>Returns</strong></p>
<p><table class="arguments">
<tr>
<th>Return Values</th>
</tr>
<tr><td class="markdown-from-sourecode">Returns `true` (should dequeue) or `false` (should not dequeue)</td></tr>
</table></p>
<h4 id="shouldBeDequeuedOnDependencyFailure" class="function-name"><a name="shouldBeDequeuedOnDependencyFailure" class="plugin-anchor" href="#shouldBeDequeuedOnDependencyFailure"><i class="fa fa-link" aria-hidden="true"></i></a>
shouldBeDequeuedOnDependencyFailure(<span class="args"></span>) <a href="#shouldBeDequeuedOnDependencyFailure" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>determines if the current task should be dequeued if one of the
tasks it depends on fails.</p>
</div>
<p><strong>Returns</strong></p>
<p><table class="arguments">
<tr>
<th>Return Values</th>
</tr>
<tr><td class="markdown-from-sourecode">Returns `true` (should dequeue) or `false` (should not dequeue)</td></tr>
</table></p>
<h4 id="isUndo" class="function-name"><a name="isUndo" class="plugin-anchor" href="#isUndo"><i class="fa fa-link" aria-hidden="true"></i></a>
isUndo(<span class="args"></span>) <a href="#isUndo" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>It&apos;s up to you to determine how you want to indicate whether
or not you have an instance of an &quot;Undo Task&quot;. We commonly use a
simple instance variable boolean flag.</p>
</div>
<p><strong>Returns</strong></p>
<p><table class="arguments">
<tr>
<th>Return Values</th>
</tr>
<tr><td class="markdown-from-sourecode">Returns `true` (is an Undo Task) or `false` (is not an Undo Task)</td></tr>
</table></p>
<h4 id="canBeUndone" class="function-name"><a name="canBeUndone" class="plugin-anchor" href="#canBeUndone"><i class="fa fa-link" aria-hidden="true"></i></a>
canBeUndone(<span class="args"></span>) <a href="#canBeUndone" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>Determines whether or not this task can be undone via the
{UndoRedoStore}</p>
</div>
<p><strong>Returns</strong></p>
<p><table class="arguments">
<tr>
<th>Return Values</th>
</tr>
<tr><td class="markdown-from-sourecode">Returns `true` (can be undone) or `false` (can&apos;t be undone)</td></tr>
</table></p>
<h4 id="createUndoTask" class="function-name"><a name="createUndoTask" class="plugin-anchor" href="#createUndoTask"><i class="fa fa-link" aria-hidden="true"></i></a>
createUndoTask(<span class="args"></span>) <a href="#createUndoTask" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>Return from `createIdenticalTask` and set a flag so your
`performLocal` and `performRemote` methods know that this is an undo
task.</p>
</div>
<h4 id="createIdenticalTask" class="function-name"><a name="createIdenticalTask" class="plugin-anchor" href="#createIdenticalTask"><i class="fa fa-link" aria-hidden="true"></i></a>
createIdenticalTask(<span class="args"></span>) <a href="#createIdenticalTask" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>Return a deep-cloned task to be used for an undo task</p>
</div>
<h4 id="cancel" class="function-name"><a name="cancel" class="plugin-anchor" href="#cancel"><i class="fa fa-link" aria-hidden="true"></i></a>
cancel(<span class="args"></span>) <a href="#cancel" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>code to run if (someone tries to dequeue your task while it is)
in flight.</p>
</div>
<h4 id="label" class="function-name"><a name="label" class="plugin-anchor" href="#label"><i class="fa fa-link" aria-hidden="true"></i></a>
label(<span class="args"></span>) <a href="#label" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>(optional) A string displayed to users when your task is run.
When tasks are run, we automatically display a notification to users
of the form &quot;label (numberOfImpactedItems)&quot;. if (this does not a return)
a string, no notification is displayed</p>
</div>
<h4 id="numberOfImpactedItems" class="function-name"><a name="numberOfImpactedItems" class="plugin-anchor" href="#numberOfImpactedItems"><i class="fa fa-link" aria-hidden="true"></i></a>
numberOfImpactedItems(<span class="args"></span>) <a href="#numberOfImpactedItems" class="link"></a>
</h4>
<div class="function-description markdown-from-sourecode">
<p>A string displayed to users indicating how many items your
task affected.</p>
</div>
</section>
</div>
<div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
</div>
</div>
</div>
<a href="StyleManager.html" class="navigation navigation-prev " aria-label="Previous page: StyleManager">
<i class="fa fa-angle-left"></i>
</a>
<a href="TaskQueueStatusStore.html" class="navigation navigation-next " aria-label="Next page: TaskQueueStatusStore">
<i class="fa fa-angle-right"></i>
</a>
</div>
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Task","level":"2.1.14","depth":2,"next":{"title":"TaskQueueStatusStore","level":"2.1.15","depth":2,"path":"classes/TaskQueueStatusStore.md","ref":"classes/TaskQueueStatusStore.md","articles":[]},"previous":{"title":"StyleManager","level":"2.1.13","depth":2,"path":"classes/StyleManager.md","ref":"classes/StyleManager.md","articles":[]},"dir":"ltr"},"config":{"plugins":["search","lunr","-fontsettings","-sharing","anchors","github","editlink","favicon"],"root":"./docs_src","styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"editlink":{"label":"Edit This Page","multilingual":false,"base":"https://github.com/nylas/nylas-mail-docs/tree/master"},"github":{"url":"https://github.com/nylas/nylas-mail-docs"},"favicon":{"shortcut":"/img/favicon.png"},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"anchors":{},"highlight":{},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Nylas Mail Plugin SDK","links":{"sharing":{"facebook":false,"twitter":false}},"gitbook":"3.2.2"},"file":{"path":"classes/Task.md","mtime":"2017-01-30T10:28:19.000Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2017-01-30T10:28:53.038Z"},"basePath":"..","book":{"language":""}});
});
</script>
</div>
<script src="../gitbook/gitbook.js"></script>
<script src="../gitbook/theme.js"></script>
<script src="../gitbook/gitbook-plugin-search/search-engine.js"></script>
<script src="../gitbook/gitbook-plugin-search/search.js"></script>
<script src="../gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
<script src="../gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
<script src="../gitbook/gitbook-plugin-github/plugin.js"></script>
<script src="../gitbook/gitbook-plugin-editlink/plugin.js"></script>
</body>
</html>