Summary
Nylas Mail 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.
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.
Listening for Changes
To listen for changes to the local cache, subscribe to the DatabaseStore and inspect the changes that are sent to your listener method.
@unsubscribe = DatabaseStore.listen(@_onDataChanged, @)
...
_onDataChanged: (change) ->
return unless change.objectClass is Message
return unless @_myMessageID in _.map change.objects, (m) -> m.id
# Refresh Data
The local cache changes very frequently, and your stores and components should
carefully choose when to refresh their data. The change object passed to your
event handler allows you to decide whether to refresh your data and exposes
the following keys:
objectClass: The Model class that has been changed. If multiple types of models
were saved to the database, you will receive multiple change events.
objects: An Array of Model 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.
Instance Methods
find(classid)
Creates a new Model Query for retrieving a single model specified by the class and id.
Example:
DatabaseStore.find(Thread, 'id-123').then (thread) ->
# thread is a Thread object, or null if no match was found.
| Argument | Description |
|---|---|
| class |
The class of the Model you're trying to retrieve. |
| id |
| Return Values |
|---|
Returns a ModelQuery |
findBy(classpredicates)
Creates a new Model Query for retrieving a single model matching the predicates provided.
| Argument | Description |
|---|---|
| class |
The class of the Model you're trying to retrieve. |
| predicates |
An Array of matcher objects. The set of predicates the returned model must match. |
| Return Values |
|---|
Returns a ModelQuery |
findAll(classpredicates)
Creates a new Model Query for retrieving all models matching the predicates provided.
| Argument | Description |
|---|---|
| class |
The class of the Model you're trying to retrieve. |
| predicates |
An Array of matcher objects. The set of predicates the returned model must match. |
| Return Values |
|---|
Returns a ModelQuery |
count(classpredicates)
Creates a new Model Query that returns the Number of models matching the predicates provided.
| Argument | Description |
|---|---|
| class |
The class of the Model you're trying to retrieve. |
| predicates |
An Array of matcher objects. The set of predicates the returned model must match. |
| Return Values |
|---|
Returns a ModelQuery |
modelify(class)
Modelify converts the provided array of IDs or models (or a mix of
IDs and models) into an array of models of the klass provided by querying for the missing items.
Modelify is efficient and uses a single database query. It resolves Immediately if no query is necessary.
| Argument | Description |
|---|---|
| class |
The Model class desired. |
|
'arr' An Array with a mix of string model IDs and/or models. |
run(modelQuery)
Executes a ModelQuery on the local database.
| Argument | Description |
|---|---|
| modelQuery |
A ModelQuery to execute. |
| Return Values |
|---|
Returns a Promise that
|
persistModel(model)
Asynchronously writes model to the cache and triggers a change event.
| Argument | Description |
|---|---|
| model |
A Model to write to the database. |
| Return Values |
|---|
Returns a Promise that
|
persistModels(models)
Asynchronously writes models to the cache and triggers a single change
event. Note: Models must be of the same class to be persisted in a batch operation.
| Argument | Description |
|---|---|
| models |
| Return Values |
|---|
Returns a Promise that
|
unpersistModel(model)
Asynchronously removes model from the cache and triggers a change event.
| Argument | Description |
|---|---|
| model |
A Model to write to the database. |
| Return Values |
|---|
Returns a Promise that
|