DatabaseStore
Summary
Mailspring 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.
this.unsubscribe = DatabaseStore.listen(this._onDataChanged, this.)
...
_onDataChanged: (change) ->
return unless change.objectClass is Message
return unless this._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()
Creates a new Model Query for retrieving a single model specified by the class and id. * \`class\` The class of the {Model} you're trying to retrieve. * \`id\` The {String} id of the {Model} you're trying to retrieve Example: ```coffee DatabaseStore.find(Thread, 'id-123').then (thread) -> // thread is a Thread object, or null if no match was found. ```
Returns
| Return Values |
|---|
| Returns a {Query} |
findBy()
Creates a new Model Query for retrieving a single model matching the predicates provided. * \`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 {Query} |
findAll()
Creates a new Model Query for retrieving all models matching the predicates provided. * \`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 {Query} |
count()
Creates a new Model Query that returns the {Number} of models matching the predicates provided. * \`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 {Query} |
modelify()
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. * \`class\` The {Model} class desired. * 'arr' An {Array} with a mix of string model IDs and/or models.
run()
Executes a {Query} on the local database. * \`modelQuery\` A {Query} to execute.
| Return Values |
|---|
| Returns a {Promise} that * resolves with the result of the database query. |
inTransaction()
Opens a new database transaction for writing changes. DatabaseStore.inTransacion makes the following guarantees: * No other calls to \`inTransaction\` will run until the promise has finished. * No other process will be able to write to sqlite while the provided function is running. `BEGIN IMMEDIATE TRANSACTION` semantics are: * No other connection will be able to write any changes. * Other connections can read from the database, but they will not see pending changes.
| Return Values |
|---|
| this.param fn {function} callback that will be executed inside a database transaction |
| Returns a {Promise} that resolves when the transaction has successfully completed. |