mirror of
https://github.com/Foundry376/Mailspring.git
synced 2025-01-01 13:14:16 +08:00
442 lines
16 KiB
HTML
442 lines
16 KiB
HTML
---
|
|
layout: docs
|
|
title: DatabaseStore
|
|
edit_url: "https://github.com/nylas/N1/blob/master/src/flux/stores/database-store.coffee"
|
|
---
|
|
|
|
<h2>Summary</h2>
|
|
|
|
<div class="markdown-from-sourecode">
|
|
<p><p>N1 is built on top of a custom database layer modeled after
|
|
ActiveRecord. For many parts of the application, the database is the source
|
|
of truth. Data is retrieved from the API, written to the database, and changes
|
|
to the database trigger Stores and components to refresh their contents.</p>
|
|
<p>The DatabaseStore is available in every application window and allows you to
|
|
make queries against the local cache. Every change to the local cache is
|
|
broadcast as a change event, and listening to the DatabaseStore keeps the
|
|
rest of the application in sync.</p>
|
|
<h2 id="listening-for-changes">Listening for Changes</h2>
|
|
<p>To listen for changes to the local cache, subscribe to the DatabaseStore and
|
|
inspect the changes that are sent to your listener method.</p>
|
|
<pre><code class="lang-coffeescript"><span class="hljs-variable">@unsubscribe</span> = DatabaseStore.<span class="hljs-function">listen</span>(<span class="hljs-variable">@_onDataChanged</span>, @)
|
|
|
|
...
|
|
|
|
<span class="hljs-attribute">_onDataChanged</span>: (change) ->
|
|
return unless change.objectClass is Message
|
|
return unless <span class="hljs-variable">@_myMessageID</span> in _.map change.objects, (m) -> m.id
|
|
|
|
# Refresh Data
|
|
</code></pre>
|
|
<p>The local cache changes very frequently, and your stores and components should
|
|
carefully choose when to refresh their data. The <code>change</code> object passed to your
|
|
event handler allows you to decide whether to refresh your data and exposes
|
|
the following keys:</p>
|
|
<p><code>objectClass</code>: The <a href='model.html'>Model</a> class that has been changed. If multiple types of models
|
|
were saved to the database, you will receive multiple change events.</p>
|
|
<p><code>objects</code>: An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> of <a href='model.html'>Model</a> instances that were either created, updated or
|
|
deleted from the local cache. If your component or store presents a single object
|
|
or a small collection of objects, you should look to see if any of the objects
|
|
are in your displayed set before refreshing.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Instance Methods</h3>
|
|
|
|
<h4 id=find class="function-name">
|
|
find(<span class="args"><span class="arg">class</span><span class="arg">id</span></span>) <a href="#find" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Creates a new Model Query for retrieving a single model specified by
|
|
the class and id.</p>
|
|
<p>Example:</p>
|
|
<pre><code class="lang-coffee">DatabaseStore.find<span class="hljs-function"><span class="hljs-params">(Thread, <span class="hljs-string">'id-123'</span>)</span>.<span class="hljs-title">then</span> <span class="hljs-params">(thread)</span> -></span>
|
|
<span class="hljs-comment"># thread is a Thread object, or null if no match was found.</span>
|
|
</code></pre>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>class</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The class of the <a href='model.html'>Model</a> you're trying to retrieve.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>id</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string'>String</a> id of the <a href='model.html'>Model</a> you're trying to retrieve</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='modelquery.html'>ModelQuery</a></p>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=findBy class="function-name">
|
|
findBy(<span class="args"><span class="arg">class</span><span class="arg">predicates</span></span>) <a href="#findBy" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Creates a new Model Query for retrieving a single model matching the
|
|
predicates provided.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>class</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The class of the <a href='model.html'>Model</a> you're trying to retrieve.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>predicates</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> of <a href='matcher.html'>matcher</a> objects. The set of predicates the returned model must match.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='modelquery.html'>ModelQuery</a></p>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=findAll class="function-name">
|
|
findAll(<span class="args"><span class="arg">class</span><span class="arg">predicates</span></span>) <a href="#findAll" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Creates a new Model Query for retrieving all models matching the
|
|
predicates provided.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>class</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The class of the <a href='model.html'>Model</a> you're trying to retrieve.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>predicates</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> of <a href='matcher.html'>matcher</a> objects. The set of predicates the returned model must match.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='modelquery.html'>ModelQuery</a></p>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=count class="function-name">
|
|
count(<span class="args"><span class="arg">class</span><span class="arg">predicates</span></span>) <a href="#count" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Creates a new Model Query that returns the <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/number'>Number</a> of models matching
|
|
the predicates provided.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>class</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The class of the <a href='model.html'>Model</a> you're trying to retrieve.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>predicates</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> of <a href='matcher.html'>matcher</a> objects. The set of predicates the returned model must match.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='modelquery.html'>ModelQuery</a></p>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=modelify class="function-name">
|
|
modelify(<span class="args"><span class="arg">class</span><span class="arg"></span></span>) <a href="#modelify" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Modelify converts the provided array of IDs or models (or a mix of
|
|
IDs and models) into an array of models of the <code>klass</code> provided by querying for the missing items.</p>
|
|
<p>Modelify is efficient and uses a single database query. It resolves Immediately
|
|
if no query is necessary.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>class</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>The <a href='model.html'>Model</a> class desired.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em></em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>'arr' An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> with a mix of string model IDs and/or models.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4 id=run class="function-name">
|
|
run(<span class="args"><span class="arg">modelQuery</span></span>) <a href="#run" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Executes a <a href='modelquery.html'>ModelQuery</a> on the local database.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>modelQuery</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>A <a href='modelquery.html'>ModelQuery</a> to execute.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='https://github.com/petkaantonov/bluebird/blob/master/API.md'>Promise</a> that</p>
|
|
<ul>
|
|
<li>resolves with the result of the database query.</li>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=persistModel class="function-name">
|
|
persistModel(<span class="args"><span class="arg">model</span></span>) <a href="#persistModel" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Asynchronously writes <code>model</code> to the cache and triggers a change event.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>model</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>A <a href='model.html'>Model</a> to write to the database.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='https://github.com/petkaantonov/bluebird/blob/master/API.md'>Promise</a> that</p>
|
|
<ul>
|
|
<li>resolves after the database queries are complete and any listening
|
|
database callbacks have finished</li>
|
|
<li>rejects if any databse query fails or one of the triggering
|
|
callbacks failed</li>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=persistModels class="function-name">
|
|
persistModels(<span class="args"><span class="arg">models</span></span>) <a href="#persistModels" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Asynchronously writes <code>models</code> to the cache and triggers a single change
|
|
event. Note: Models must be of the same class to be persisted in a batch operation.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>models</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>An <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/array'>Array</a> of <a href='model.html'>Model</a> objects to write to the database.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='https://github.com/petkaantonov/bluebird/blob/master/API.md'>Promise</a> that</p>
|
|
<ul>
|
|
<li>resolves after the database queries are complete and any listening
|
|
database callbacks have finished</li>
|
|
<li>rejects if any databse query fails or one of the triggering
|
|
callbacks failed</li>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
<h4 id=unpersistModel class="function-name">
|
|
unpersistModel(<span class="args"><span class="arg">model</span></span>) <a href="#unpersistModel" class="link"></a>
|
|
</h4>
|
|
|
|
<div class="function-description markdown-from-sourecode">
|
|
<p><p>Asynchronously removes <code>model</code> from the cache and triggers a change event.</p>
|
|
</p>
|
|
</div>
|
|
|
|
<strong>Parameters</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td style="width:15%;">
|
|
<em>model</em>
|
|
</td>
|
|
<td class="markdown-from-sourecode">
|
|
|
|
<p>A <a href='model.html'>Model</a> to write to the database.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<strong>Returns</strong>
|
|
<table class="arguments">
|
|
<tr>
|
|
<th>Return Values</th>
|
|
</tr>
|
|
<tr><td class="markdown-from-sourecode"><p>Returns a <a href='https://github.com/petkaantonov/bluebird/blob/master/API.md'>Promise</a> that</p>
|
|
<ul>
|
|
<li>resolves after the database queries are complete and any listening
|
|
database callbacks have finished</li>
|
|
<li>rejects if any databse query fails or one of the triggering
|
|
callbacks failed</li>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|