### new Cursor(db, query, [execFn], [hasCallback])
<p>Create a new cursor for this collection</p>
<p>Create a new cursor for this collection</p>
**Params**
| Param | Type | Default | Description |
- db [<code>Datastore</code>](#Datastore) - <p>The datastore this cursor is bound to</p>
| --- | --- | --- | --- |
- query [<code>query</code>](#query) - <p>The query this cursor will operate on</p>
| db | [<code>Datastore</code>](#Datastore) | | <p>The datastore this cursor is bound to</p> |
- [execFn] [<code>execFnWithoutCallback</code>](#Cursor..execFnWithoutCallback) | [<code>execFnWithCallback</code>](#Cursor..execFnWithCallback) - <p>Handler to be executed after cursor has found the results and before the callback passed to find/findOne/update/remove</p>
| query | [<code>query</code>](#query) | | <p>The query this cursor will operate on</p> |
- [hasCallback] <code>boolean</code><code> = true</code> - <p>If false, specifies that the <code>execFn</code> is of type [execFnWithoutCallback](#Cursor..execFnWithoutCallback) rather than [execFnWithCallback](#Cursor..execFnWithCallback).</p>
| [execFn] | [<code>execFn</code>](#Cursor..execFn) \| [<code>execFnAsync</code>](#Cursor..execFnAsync) | | <p>Handler to be executed after cursor has found the results and before the callback passed to find/findOne/update/remove</p> |
| [async] | <code>boolean</code> | <code>false</code> | <p>If true, specifies that the <code>execFn</code> is of type [execFnAsync](#Cursor..execFnAsync) rather than [execFn](#Cursor..execFn).</p> |
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Params**
| Param | Type |
- limit <code>Number</code>
| --- | --- |
| limit | <code>Number</code> |
<aname="Cursor+skip"></a>
<aname="Cursor+skip"></a>
@ -54,10 +72,9 @@
<p>Skip a number of results</p>
<p>Skip a number of results</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Params**
| Param | Type |
- skip <code>Number</code>
| --- | --- |
| skip | <code>Number</code> |
<aname="Cursor+sort"></a>
<aname="Cursor+sort"></a>
@ -65,10 +82,9 @@
<p>Sort results of the query</p>
<p>Sort results of the query</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Params**
| Param | Type | Description |
- sortQuery <code>Object.<string, number></code> - <p>sortQuery is { field: order }, field can use the dot-notation, order is 1 for ascending and -1 for descending</p>
| --- | --- | --- |
| sortQuery | <code>Object.<string, number></code> | <p>sortQuery is { field: order }, field can use the dot-notation, order is 1 for ascending and -1 for descending</p> |
<aname="Cursor+projection"></a>
<aname="Cursor+projection"></a>
@ -76,21 +92,22 @@
<p>Add the use of a projection</p>
<p>Add the use of a projection</p>
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Kind**: instance method of [<code>Cursor</code>](#Cursor)
**Params**
| Param | Type | Description |
- projection <code>Object.<string, number></code> - <p>MongoDB-style projection. {} means take all fields. Then it's { key1: 1, key2: 1 } to take only key1 and key2
| --- | --- | --- |
{ key1: 0, key2: 0 } to omit only key1 and key2. Except _id, you can't mix takes and omits.</p>
| projection | <code>Object.<string, number></code> | <p>MongoDB-style projection. {} means take all fields. Then it's { key1: 1, key2: 1 } to take only key1 and key2 { key1: 0, key2: 0 } to omit only key1 and key2. Except _id, you can't mix takes and omits.</p> |
<p>Does not have a callback, may return a Promise.</p>
### Cursor~execFnAsync ⇒ <code>Promise</code>
**Kind**: inner typedef of [<code>Cursor</code>](#Cursor)
**Kind**: inner typedef of [<code>Cursor</code>](#Cursor)
**Params**
| Param | Type |
- res [<code>?Array.<document></code>](#document) | [<code>document</code>](#document)
| --- | --- |
| res | [<code>?Array.<document></code>](#document) \| [<code>document</code>](#document) |
<aname="Cursor..execCallback"></a>
<aname="Cursor..execCallback"></a>
### Cursor~execCallback : <code>function</code>
### Cursor~execCallback : <code>function</code>
**Kind**: inner typedef of [<code>Cursor</code>](#Cursor)
**Kind**: inner typedef of [<code>Cursor</code>](#Cursor)
**Params**
| Param | Type | Description |
- err <code>Error</code>
| --- | --- | --- |
- res [<code>Array.<document></code>](#document) | <code>\*</code> - <p>If an execFn was given to the Cursor, then the type of this parameter is the one returned by the execFn.</p>
| err | <code>Error</code> | |
| res | [<code>Array.<document></code>](#document) \| <code>\*</code> | <p>If an execFn was given to the Cursor, then the type of this parameter is the one returned by the execFn.</p> |
@ -51,21 +60,76 @@ function fetches the data from datafile and prepares the database. <strong>Don't
datastore, no command (insert, find, update, remove) will be executed before <code>loadDatabase</code> is called, so make sure
datastore, no command (insert, find, update, remove) will be executed before <code>loadDatabase</code> is called, so make sure
to call it yourself or use the <code>autoload</code> option.</p>
to call it yourself or use the <code>autoload</code> option.</p>
**Params**
- options <code>object</code> | <code>string</code> - <p>Can be an object or a string. If options is a string, the behavior is the same as in
v0.6: it will be interpreted as <code>options.filename</code>. <strong>Giving a string is deprecated, and will be removed in the
next major version.</strong></p>
- [.filename] <code>string</code><code> = null</code> - <p>Path to the file where the data is persisted. If left blank, the datastore is
automatically considered in-memory only. It cannot end with a <code>~</code> which is used in the temporary files NeDB uses to
perform crash-safe writes.</p>
- [.inMemoryOnly] <code>boolean</code><code> = false</code> - <p>If set to true, no data will be written in storage.</p>
- [.timestampData] <code>boolean</code><code> = false</code> - <p>If set to true, createdAt and updatedAt will be created and
populated automatically (if not specified by user)</p>
- [.autoload] <code>boolean</code><code> = false</code> - <p>If used, the database will automatically be loaded from the datafile
upon creation (you don't need to call <code>loadDatabase</code>). Any command issued before load is finished is buffered and
will be executed when load is done. When autoloading is done, you can either use the <code>onload</code> callback, or you can
use <code>this.autoloadPromise</code> which resolves (or rejects) when autloading is done.</p>
- [.onload] <code>function</code> - <p>If you use autoloading, this is the handler called after the <code>loadDatabase</code>. It
takes one <code>error</code> argument. If you use autoloading without specifying this handler, and an error happens during
load, an error will be thrown.</p>
- [.beforeDeserialization] <code>function</code> - <p>Hook you can use to transform data after it was serialized and
before it is written to disk. Can be used for example to encrypt data before writing database to disk. This
function takes a string as parameter (one line of an NeDB data file) and outputs the transformed string, <strong>which
must absolutely not contain a <code>\n</code> character</strong> (or data will be lost).</p>
- [.afterSerialization] <code>function</code> - <p>Inverse of <code>afterSerialization</code>. Make sure to include both and not
just one, or you risk data loss. For the same reason, make sure both functions are inverses of one another. Some
failsafe mechanisms are in place to prevent data loss if you misuse the serialization hooks: NeDB checks that never
one is declared without the other, and checks that they are reverse of one another by testing on random strings of
various lengths. In addition, if too much data is detected as corrupt, NeDB will refuse to start as it could mean
you're not using the deserialization hook corresponding to the serialization hook used before.</p>
- [.corruptAlertThreshold] <code>number</code><code> = 0.1</code> - <p>Between 0 and 1, defaults to 10%. NeDB will refuse to start
if more than this percentage of the datafile is corrupt. 0 means you don't tolerate any corruption, 1 means you
don't care.</p>
- [.compareStrings] [<code>compareStrings</code>](#compareStrings) - <p>If specified, it overrides default string comparison which is not
well adapted to non-US characters in particular accented letters. Native <code>localCompare</code> will most of the time be
the right choice.</p>
- [.nodeWebkitAppName] <code>string</code> - <p><strong>Deprecated:</strong> if you are using NeDB from whithin a Node Webkit app,
specify its name (the same one you use in the <code>package.json</code>) in this field and the <code>filename</code> will be relative to
the directory Node Webkit uses to store the rest of the application's data (local storage etc.). It works on Linux,
OS X and Windows. Now that you can use <code>require('nw.gui').App.dataPath</code> in Node Webkit to get the path to the data
directory for your application, you should not use this option anymore and it will be removed.</p>
<aname="Datastore+inMemoryOnly"></a>
### datastore.inMemoryOnly : <code>boolean</code>
<p>Determines if the <code>Datastore</code> keeps data in-memory, or if it saves it in storage. Is not read after
instanciation.</p>
| Param | Type | Default | Description |
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
| --- | --- | --- | --- |
**Access**: protected
| options | <code>object</code> \| <code>string</code> | | <p>Can be an object or a string. If options is a string, the behavior is the same as in v0.6: it will be interpreted as <code>options.filename</code>. <strong>Giving a string is deprecated, and will be removed in the next major version.</strong></p> |
<aname="Datastore+autoload"></a>
| [options.filename] | <code>string</code> | <code>null</code> | <p>Path to the file where the data is persisted. If left blank, the datastore is automatically considered in-memory only. It cannot end with a <code>~</code> which is used in the temporary files NeDB uses to perform crash-safe writes.</p> |
| [options.inMemoryOnly] | <code>boolean</code> | <code>false</code> | <p>If set to true, no data will be written in storage.</p> |
### datastore.autoload : <code>boolean</code>
| [options.timestampData] | <code>boolean</code> | <code>false</code> | <p>If set to true, createdAt and updatedAt will be created and populated automatically (if not specified by user)</p> |
<p>Determines if the <code>Datastore</code> should autoload the database upon instantiation. Is not read after instanciation.</p>
| [options.autoload] | <code>boolean</code> | <code>false</code> | <p>If used, the database will automatically be loaded from the datafile upon creation (you don't need to call <code>loadDatabase</code>). Any command issued before load is finished is buffered and will be executed when load is done. When autoloading is done, you can either use the <code>onload</code> callback, or you can use <code>this.autoloadPromise</code> which resolves (or rejects) when autloading is done.</p> |
| [options.onload] | <code>function</code> | | <p>If you use autoloading, this is the handler called after the <code>loadDatabase</code>. It takes one <code>error</code> argument. If you use autoloading without specifying this handler, and an error happens during load, an error will be thrown.</p> |
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
| [options.beforeDeserialization] | <code>function</code> | | <p>Hook you can use to transform data after it was serialized and before it is written to disk. Can be used for example to encrypt data before writing database to disk. This function takes a string as parameter (one line of an NeDB data file) and outputs the transformed string, <strong>which must absolutely not contain a <code>\n</code> character</strong> (or data will be lost).</p> |
**Access**: protected
| [options.afterSerialization] | <code>function</code> | | <p>Inverse of <code>afterSerialization</code>. Make sure to include both and not just one, or you risk data loss. For the same reason, make sure both functions are inverses of one another. Some failsafe mechanisms are in place to prevent data loss if you misuse the serialization hooks: NeDB checks that never one is declared without the other, and checks that they are reverse of one another by testing on random strings of various lengths. In addition, if too much data is detected as corrupt, NeDB will refuse to start as it could mean you're not using the deserialization hook corresponding to the serialization hook used before.</p> |
<aname="Datastore+timestampData"></a>
| [options.corruptAlertThreshold] | <code>number</code> | <code>0.1</code> | <p>Between 0 and 1, defaults to 10%. NeDB will refuse to start if more than this percentage of the datafile is corrupt. 0 means you don't tolerate any corruption, 1 means you don't care.</p> |
| [options.compareStrings] | [<code>compareStrings</code>](#compareStrings) | | <p>If specified, it overrides default string comparison which is not well adapted to non-US characters in particular accented letters. Native <code>localCompare</code> will most of the time be the right choice.</p> |
| [options.nodeWebkitAppName] | <code>string</code> | | <p><strong>Deprecated:</strong> if you are using NeDB from whithin a Node Webkit app, specify its name (the same one you use in the <code>package.json</code>) in this field and the <code>filename</code> will be relative to the directory Node Webkit uses to store the rest of the application's data (local storage etc.). It works on Linux, OS X and Windows. Now that you can use <code>require('nw.gui').App.dataPath</code> in Node Webkit to get the path to the data directory for your application, you should not use this option anymore and it will be removed.</p> |
<p>Determines if the <code>Datastore</code> should add <code>createdAt</code> and <code>updatedAt</code> fields automatically if not set by the user.</p>
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
**Access**: protected
<aname="Datastore+filename"></a>
### datastore.filename : <code>string</code>
<p>If null, it means <code>inMemoryOnly</code> is <code>true</code>. The <code>filename</code> is the name given to the storage module. Is not read
after instanciation.</p>
**Kind**: instance property of [<code>Datastore</code>](#Datastore)
Previous versions said explicitly the callback was optional, it is now recommended setting one.</p>
Previous versions said explicitly the callback was optional, it is now recommended setting one.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Params**
| Param | Type | Default | Description |
- options <code>object</code>
| --- | --- | --- | --- |
- .fieldName <code>string</code> - <p>Name of the field to index. Use the dot notation to index a field in a nested document.</p>
| options | <code>object</code> | | |
- [.unique] <code>boolean</code><code> = false</code> - <p>Enforce field uniqueness. Note that a unique index will raise an error if you try to index two documents for which the field is not defined.</p>
| options.fieldName | <code>string</code> | | <p>Name of the field to index. Use the dot notation to index a field in a nested document.</p> |
- [.sparse] <code>boolean</code><code> = false</code> - <p>don't index documents for which the field is not defined. Use this option along with "unique" if you want to accept multiple documents for which it is not defined.</p>
| [options.unique] | <code>boolean</code> | <code>false</code> | <p>Enforce field uniqueness. Note that a unique index will raise an error if you try to index two documents for which the field is not defined.</p> |
- [.expireAfterSeconds] <code>number</code> - <p>if set, the created index is a TTL (time to live) index, that will automatically remove documents when the system date becomes larger than the date on the indexed field plus <code>expireAfterSeconds</code>. Documents where the indexed field is not specified or not a <code>Date</code> object are ignored</p>
| [options.sparse] | <code>boolean</code> | <code>false</code> | <p>don't index documents for which the field is not defined. Use this option along with "unique" if you want to accept multiple documents for which it is not defined.</p> |
| [options.expireAfterSeconds] | <code>number</code> | | <p>if set, the created index is a TTL (time to live) index, that will automatically remove documents when the system date becomes larger than the date on the indexed field plus <code>expireAfterSeconds</code>. Documents where the indexed field is not specified or not a <code>Date</code> object are ignored</p> |
<p>Ensure an index is kept for this field. Same parameters as lib/indexes
<p>Async version of [ensureIndex](#Datastore+ensureIndex).</p>
This function acts synchronously on the indexes, however the persistence of the indexes is deferred with the
executor.
Previous versions said explicitly the callback was optional, it is now recommended setting one.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**See**: Datastore#ensureIndex
**Params**
| Param | Type | Default | Description |
- options <code>object</code>
| --- | --- | --- | --- |
- .fieldName <code>string</code> - <p>Name of the field to index. Use the dot notation to index a field in a nested document.</p>
| options | <code>object</code> | | |
- [.unique] <code>boolean</code><code> = false</code> - <p>Enforce field uniqueness. Note that a unique index will raise an error if you try to index two documents for which the field is not defined.</p>
| options.fieldName | <code>string</code> | | <p>Name of the field to index. Use the dot notation to index a field in a nested document.</p> |
- [.sparse] <code>boolean</code><code> = false</code> - <p>Don't index documents for which the field is not defined. Use this option along with "unique" if you want to accept multiple documents for which it is not defined.</p>
| [options.unique] | <code>boolean</code> | <code>false</code> | <p>Enforce field uniqueness. Note that a unique index will raise an error if you try to index two documents for which the field is not defined.</p> |
- [.expireAfterSeconds] <code>number</code> - <p>If set, the created index is a TTL (time to live) index, that will automatically remove documents when the system date becomes larger than the date on the indexed field plus <code>expireAfterSeconds</code>. Documents where the indexed field is not specified or not a <code>Date</code> object are ignored</p>
| [options.sparse] | <code>boolean</code> | <code>false</code> | <p>Don't index documents for which the field is not defined. Use this option along with "unique" if you want to accept multiple documents for which it is not defined.</p> |
| [options.expireAfterSeconds] | <code>number</code> | | <p>If set, the created index is a TTL (time to live) index, that will automatically remove documents when the system date becomes larger than the date on the indexed field plus <code>expireAfterSeconds</code>. Documents where the indexed field is not specified or not a <code>Date</code> object are ignored</p> |
<aname="Datastore+removeIndex"></a>
<aname="Datastore+removeIndex"></a>
@ -160,84 +249,131 @@ Previous versions said explicitly the callback was optional, it is now recommend
Previous versions said explicitly the callback was optional, it is now recommended setting one.</p>
Previous versions said explicitly the callback was optional, it is now recommended setting one.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Params**
| Param | Type | Description |
- fieldName <code>string</code> - <p>Field name of the index to remove. Use the dot notation to remove an index referring to a
| --- | --- | --- |
field in a nested document.</p>
| fieldName | <code>string</code> | <p>Field name of the index to remove. Use the dot notation to remove an index referring to a field in a nested document.</p> |
<p>Async version of [removeIndex](#Datastore+removeIndex).</p>
Previous versions said explicitly the callback was optional, it is now recommended setting one.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**See**: Datastore#removeIndex
**Params**
- fieldName <code>string</code> - <p>Field name of the index to remove. Use the dot notation to remove an index referring to a
field in a nested document.</p>
<aname="Datastore+addToIndexes"></a>
### datastore.addToIndexes(doc)
<p>Add one or several document(s) to all indexes.</p>
<p>This is an internal function.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Access**: protected
**Params**
| Param | Type | Description |
- doc [<code>document</code>](#document)
| --- | --- | --- |
| fieldName | <code>string</code> | <p>Field name of the index to remove. Use the dot notation to remove an index referring to a field in a nested document.</p> |
<aname="Datastore+removeFromIndexes"></a>
<aname="Datastore+removeFromIndexes"></a>
### datastore.removeFromIndexes(doc)
### datastore.removeFromIndexes(doc)
<p>Remove one or several document(s) from all indexes</p>
<p>Remove one or several document(s) from all indexes.</p>
<p>This is an internal function.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Access**: protected
**Params**
| Param | Type |
- doc [<code>document</code>](#document)
| --- | --- |
| doc | [<code>document</code>](#document) |
<aname="Datastore+updateIndexes"></a>
<aname="Datastore+updateIndexes"></a>
### datastore.updateIndexes(oldDoc, [newDoc])
### datastore.updateIndexes(oldDoc, [newDoc])
<p>Update one or several documents in all indexes
<p>Update one or several documents in all indexes.</p>
To update multiple documents, oldDoc must be an array of { oldDoc, newDoc } pairs
<p>To update multiple documents, oldDoc must be an array of { oldDoc, newDoc } pairs.</p>
If one update violates a constraint, all changes are rolled back</p>
<p>If one update violates a constraint, all changes are rolled back.</p>
<p>This is an internal function.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Params**
- oldDoc [<code>document</code>](#document) | <code>Array.<{oldDoc: document, newDoc: document}></code> - <p>Document to update, or an <code>Array</code> of
<code>{oldDoc, newDoc}</code> pairs.</p>
- [newDoc] [<code>document</code>](#document) - <p>Document to replace the oldDoc with. If the first argument is an <code>Array</code> of
<code>{oldDoc, newDoc}</code> pairs, this second argument is ignored.</p>
<p>Return the list of candidates for a given query
Crude implementation for now, we return the candidates given by the first usable index if any
We try the following query types, in this order: basic match, $in match, comparison match
One way to make it better would be to enable the use of multiple indexes if the first usable index
returns too much data. I may do it in the future.</p>
<p>Returned candidates will be scanned to find and remove all expired documents</p>
<p>This is an internal function.</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Access**: protected
**Params**
| Param | Type | Description |
- query [<code>query</code>](#query)
| --- | --- | --- |
- [dontExpireStaleDocs] <code>boolean</code> | <code>function</code><code> = false</code> - <p>If true don't remove stale docs. Useful for the remove
| oldDoc | [<code>document</code>](#document) \| <code>Array.<{oldDoc: document, newDoc: document}></code> | <p>Document to update, or an <code>Array</code> of <code>{oldDoc, newDoc}</code> pairs.</p> |
function which shouldn't be impacted by expirations. If argument is not given, it is used as the callback.</p>
| [newDoc] | [<code>document</code>](#document) | <p>Document to replace the oldDoc with. If the first argument is an <code>Array</code> of <code>{oldDoc, newDoc}</code> pairs, this second argument is ignored.</p> |
- [callback] [<code>countCallback</code>](#Datastore..countCallback) - <p>If given, the function will return undefined, otherwise it will return the Cursor.</p>
| [callback] | [<code>countCallback</code>](#Datastore..countCallback) | <p>If given, the function will return undefined, otherwise it will return the Cursor.</p> |
- [projection] [<code>projection</code>](#projection) | [<code>MultipleDocumentsCallback</code>](#MultipleDocumentsCallback) <code> = {}</code> - <p>MongoDB-style projection. If not given, will be
| [projection] | [<code>projection</code>](#projection) \| [<code>MultipleDocumentsCallback</code>](#MultipleDocumentsCallback) | <code>{}</code> | <p>MongoDB-style projection. If not given, will be interpreted as the callback.</p> |
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Params**
| Param | Type | Default | Description |
- query [<code>query</code>](#query) - <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code></p>
| --- | --- | --- | --- |
- update [<code>document</code>](#document) | <code>\*</code> - <p>specifies how the documents should be modified. It is either a new document or a
| query | [<code>query</code>](#query) | | <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code></p> |
set of modifiers (you cannot use both together, it doesn't make sense!):</p>
| update | [<code>document</code>](#document) \| <code>update</code> | | <p>specifies how the documents should be modified. It is either a new document or a set of modifiers (you cannot use both together, it doesn't make sense!):</p><ul><li>A new document will replace the matched docs</li><li>The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs. Available field modifiers are <code>$set</code> to change a field's value, <code>$unset</code> to delete a field, <code>$inc</code> to increment a field's value and <code>$min</code>/<code>$max</code> to change field's value, only if provided value is less/greater than current value. To work on arrays, you have <code>$push</code>, <code>$pop</code>, <code>$addToSet</code>, <code>$pull</code>, and the special <code>$each</code> and <code>$slice</code>.</li></ul> |
<li>The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs.
| [options.upsert] | <code>boolean</code> | <code>false</code> | <p>If true, can insert a new document corresponding to the <code>update</code> rules if your <code>query</code> doesn't match anything. If your <code>update</code> is a simple object with no modifiers, it is the inserted document. In the other case, the <code>query</code> is stripped from all operator recursively, and the <code>update</code> is applied to it.</p> |
Available field modifiers are <code>$set</code> to change a field's value, <code>$unset</code> to delete a field, <code>$inc</code> to increment a
| [options.returnUpdatedDocs] | <code>boolean</code> | <code>false</code> | <p>(not Mongo-DB compatible) If true and update is not an upsert, will return the array of documents matched by the find query and updated. Updated documents will be returned even if the update did not actually modify them.</p> |
field's value and <code>$min</code>/<code>$max</code> to change field's value, only if provided value is less/greater than current
value. To work on arrays, you have <code>$push</code>, <code>$pop</code>, <code>$addToSet</code>, <code>$pull</code>, and the special <code>$each</code> and <code>$slice</code>.</li>
<p>Async version of [update](#Datastore+update).</p>
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**Kind**: instance method of [<code>Datastore</code>](#Datastore)
**See**: Datastore#update
**Params**
| Param | Type | Default | Description |
- query [<code>query</code>](#query) - <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code></p>
| --- | --- | --- | --- |
- update [<code>document</code>](#document) | <code>\*</code> - <p>specifies how the documents should be modified. It is either a new document or a
| query | [<code>query</code>](#query) | | <p>is the same kind of finding query you use with <code>find</code> and <code>findOne</code></p> |
set of modifiers (you cannot use both together, it doesn't make sense!):</p>
| update | [<code>document</code>](#document) \| <code>update</code> | | <p>specifies how the documents should be modified. It is either a new document or a set of modifiers (you cannot use both together, it doesn't make sense!):</p><ul><li>A new document will replace the matched docs</li><li>The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs. Available field modifiers are <code>$set</code> to change a field's value, <code>$unset</code> to delete a field, <code>$inc</code> to increment a field's value and <code>$min</code>/<code>$max</code> to change field's value, only if provided value is less/greater than current value. To work on arrays, you have <code>$push</code>, <code>$pop</code>, <code>$addToSet</code>, <code>$pull</code>, and the special <code>$each</code> and <code>$slice</code>.</li></ul> |
<li>The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs.
| [options.upsert] | <code>boolean</code> | <code>false</code> | <p>If true, can insert a new document corresponding to the <code>update</code> rules if your <code>query</code> doesn't match anything. If your <code>update</code> is a simple object with no modifiers, it is the inserted document. In the other case, the <code>query</code> is stripped from all operator recursively, and the <code>update</code> is applied to it.</p> |
Available field modifiers are <code>$set</code> to change a field's value, <code>$unset</code> to delete a field, <code>$inc</code> to increment a
| [options.returnUpdatedDocs] | <code>boolean</code> | <code>false</code> | <p>(not Mongo-DB compatible) If true and update is not an upsert, will return the array of documents matched by the find query and updated. Updated documents will be returned even if the update did not actually modify them.</p> |
field's value and <code>$min</code>/<code>$max</code> to change field's value, only if provided value is less/greater than current
value. To work on arrays, you have <code>$push</code>, <code>$pop</code>, <code>$addToSet</code>, <code>$pull</code>, and the special <code>$each</code> and <code>$slice</code>.</li>
**Kind**: instance property of [<code>Executor</code>](#Executor)
**Access**: protected
<aname="Executor+_triggerBuffer"></a>
### executor.\_triggerBuffer()
<p>Method to trigger the buffer processing.</p>
<p>Do not be use directly, use <code>this.processBuffer</code> instead.</p>
**Kind**: instance method of [<code>Executor</code>](#Executor)
**Access**: protected
<aname="Executor+push"></a>
<aname="Executor+push"></a>
### executor.push(task, [forceQueuing])
### executor.push(task, [forceQueuing])
@ -57,27 +24,29 @@ Has an option for a buffer that can be triggered afterwards.</p>
If not, buffer task for later processing</p>
If not, buffer task for later processing</p>
**Kind**: instance method of [<code>Executor</code>](#Executor)
**Kind**: instance method of [<code>Executor</code>](#Executor)
**Params**
| Param | Type | Default | Description |
- task <code>Object</code>
| --- | --- | --- | --- |
- .this <code>Object</code> - <p>Object to use as this</p>
| task | <code>Object</code> | | |
- .fn <code>function</code> - <p>Function to execute</p>
| task.this | <code>Object</code> | | <p>Object to use as this</p> |
- .arguments <code>Array</code> - <p>Array of arguments, IMPORTANT: only the last argument may be a function
| task.fn | <code>function</code> | | <p>Function to execute</p> |
(the callback) and the last argument cannot be false/undefined/null</p>
| task.arguments | <code>Array</code> | | <p>Array of arguments, IMPORTANT: only the last argument may be a function (the callback) and the last argument cannot be false/undefined/null</p> |
- [forceQueuing] <code>Boolean</code><code> = false</code> - <p>Optional (defaults to false) force executor to queue task even if it is not ready</p>
| [forceQueuing] | <code>Boolean</code> | <code>false</code> | <p>Optional (defaults to false) force executor to queue task even if it is not ready</p> |
All methods on an index guarantee that either the whole operation was successful and the index changed
All methods on an index guarantee that either the whole operation was successful and the index changed
or the operation was unsuccessful and an error is thrown while the index is unchanged</p>
or the operation was unsuccessful and an error is thrown while the index is unchanged</p>
**Params**
| Param | Type | Default | Description |
- options <code>object</code>
| --- | --- | --- | --- |
- .fieldName <code>string</code> - <p>On which field should the index apply (can use dot notation to index on sub fields)</p>
| options | <code>object</code> | | |
- [.unique] <code>boolean</code><code> = false</code> - <p>Enforces a unique constraint</p>
| options.fieldName | <code>string</code> | | <p>On which field should the index apply (can use dot notation to index on sub fields)</p> |
- [.sparse] <code>boolean</code><code> = false</code> - <p>Allows a sparse index (we can have documents for which fieldName is <code>undefined</code>)</p>
| [options.sparse] | <code>boolean</code> | <code>false</code> | <p>Allows a sparse index (we can have documents for which fieldName is <code>undefined</code>)</p> |
<aname="Index+fieldName"></a>
<aname="Index+fieldName"></a>
@ -73,10 +72,10 @@ or the operation was unsuccessful and an error is thrown while the index is unch
<p>Reset an index</p>
<p>Reset an index</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- [newData] [<code>document</code>](#document) | [<code>?Array.<document></code>](#document) - <p>Data to initialize the index with. If an error is thrown during
| --- | --- | --- |
insertion, the index is not modified.</p>
| [newData] | [<code>document</code>](#document) \| [<code>?Array.<document></code>](#document) | <p>Data to initialize the index with. If an error is thrown during insertion, the index is not modified.</p> |
<aname="Index+insert"></a>
<aname="Index+insert"></a>
@ -86,10 +85,9 @@ If an array is passed, we insert all its elements (if one insertion fails the in
O(log(n))</p>
O(log(n))</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- doc [<code>document</code>](#document) | [<code>Array.<document></code>](#document) - <p>The document, or array of documents, to insert.</p>
| --- | --- | --- |
| doc | [<code>document</code>](#document) \| [<code>Array.<document></code>](#document) | <p>The document, or array of documents, to insert.</p> |
<aname="Index+remove"></a>
<aname="Index+remove"></a>
@ -100,10 +98,9 @@ The remove operation is safe with regards to the 'unique' constraint
O(log(n))</p>
O(log(n))</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- doc [<code>Array.<document></code>](#document) | [<code>document</code>](#document) - <p>The document, or Array of documents, to remove.</p>
| --- | --- | --- |
| doc | [<code>Array.<document></code>](#document) \| [<code>document</code>](#document) | <p>The document, or Array of documents, to remove.</p> |
<aname="Index+update"></a>
<aname="Index+update"></a>
@ -113,11 +110,12 @@ If a constraint is violated, changes are rolled back and an error thrown
Naive implementation, still in O(log(n))</p>
Naive implementation, still in O(log(n))</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- oldDoc [<code>document</code>](#document) | <code>Array.<{oldDoc: document, newDoc: document}></code> - <p>Document to update, or an <code>Array</code> of
| --- | --- | --- |
<code>{oldDoc, newDoc}</code> pairs.</p>
| oldDoc | [<code>document</code>](#document) \| <code>Array.<{oldDoc: document, newDoc: document}></code> | <p>Document to update, or an <code>Array</code> of<code>{oldDoc, newDoc}</code> pairs.</p> |
- [newDoc] [<code>document</code>](#document) - <p>Document to replace the oldDoc with. If the first argument is an <code>Array</code> of
| [newDoc] | [<code>document</code>](#document) | <p>Document to replace the oldDoc with. If the first argument is an <code>Array</code> of <code>{oldDoc, newDoc}</code> pairs, this second argument is ignored.</p> |
<code>{oldDoc, newDoc}</code> pairs, this second argument is ignored.</p>
<aname="Index+revertUpdate"></a>
<aname="Index+revertUpdate"></a>
@ -125,11 +123,10 @@ Naive implementation, still in O(log(n))</p>
<p>Revert an update</p>
<p>Revert an update</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- oldDoc [<code>document</code>](#document) | <code>Array.<{oldDoc: document, newDoc: document}></code> - <p>Document to revert to, or an <code>Array</code> of <code>{oldDoc, newDoc}</code> pairs.</p>
| --- | --- | --- |
- [newDoc] [<code>document</code>](#document) - <p>Document to revert from. If the first argument is an Array of {oldDoc, newDoc}, this second argument is ignored.</p>
| oldDoc | [<code>document</code>](#document) \| <code>Array.<{oldDoc: document, newDoc: document}></code> | <p>Document to revert to, or an <code>Array</code> of <code>{oldDoc, newDoc}</code> pairs.</p> |
| [newDoc] | [<code>document</code>](#document) | <p>Document to revert from. If the first argument is an Array of {oldDoc, newDoc}, this second argument is ignored.</p> |
<aname="Index+getMatching"></a>
<aname="Index+getMatching"></a>
@ -137,10 +134,9 @@ Naive implementation, still in O(log(n))</p>
<p>Get all documents in index whose key match value (if it is a Thing) or one of the elements of value (if it is an array of Things)</p>
<p>Get all documents in index whose key match value (if it is a Thing) or one of the elements of value (if it is an array of Things)</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- value <code>Array.<\*></code> | <code>\*</code> - <p>Value to match the key against</p>
| --- | --- | --- |
| value | <code>Array.<\*></code> \| <code>\*</code> | <p>Value to match the key against</p> |
<aname="Index+getBetweenBounds"></a>
<aname="Index+getBetweenBounds"></a>
@ -149,14 +145,13 @@ Naive implementation, still in O(log(n))</p>
Documents are sorted by key</p>
Documents are sorted by key</p>
**Kind**: instance method of [<code>Index</code>](#Index)
**Kind**: instance method of [<code>Index</code>](#Index)
**Params**
| Param | Type | Description |
- query <code>object</code> - <p>An object with at least one matcher among $gt, $gte, $lt, $lte.</p>
| --- | --- | --- |
- [.$gt] <code>\*</code> - <p>Greater than matcher.</p>
| query | <code>object</code> | <p>An object with at least one matcher among $gt, $gte, $lt, $lte.</p> |
- [.$gte] <code>\*</code> - <p>Greater than or equal matcher.</p>
| [query.$gt] | <code>\*</code> | <p>Greater than matcher.</p> |
- [.$lt] <code>\*</code> - <p>Lower than matcher.</p>
| [query.$gte] | <code>\*</code> | <p>Greater than or equal matcher.</p> |
- [.$lte] <code>\*</code> - <p>Lower than or equal matcher.</p>
| [query.$lt] | <code>\*</code> | <p>Lower than matcher.</p> |
| [query.$lte] | <code>\*</code> | <p>Lower than or equal matcher.</p> |
- [.nodeWebkitAppName] <code>string</code> - <p>Optional, specify the name of your NW app if you want options.filename to be relative to the directory where Node Webkit stores application data such as cookies and local storage (the best place to store data in my opinion)</p>
| [options.corruptAlertThreshold] | <code>Number</code> | <p>Optional, threshold after which an alert is thrown if too much data is corrupt</p> |
- [.beforeDeserialization] [<code>serializationHook</code>](#serializationHook) - <p>Hook you can use to transform data after it was serialized and before it is written to disk.</p>
| [options.nodeWebkitAppName] | <code>string</code> | <p>Optional, specify the name of your NW app if you want options.filename to be relative to the directory where Node Webkit stores application data such as cookies and local storage (the best place to store data in my opinion)</p> |
- [.afterSerialization] [<code>serializationHook</code>](#serializationHook) - <p>Inverse of <code>afterSerialization</code>.</p>
| [options.beforeDeserialization] | <code>function</code> | <p>Hook you can use to transform data after it was serialized and before it is written to disk.</p> |
| [options.afterSerialization] | <code>function</code> | <p>Inverse of <code>afterSerialization</code>.</p> |
<aname="Persistence+persistCachedDatabase"></a>
<aname="Persistence+persistCachedDatabase"></a>
### persistence.persistCachedDatabase(callback)
### persistence.persistCachedDatabase([callback])
<p>Persist cached database
<p>Persist cached database
This serves as a compaction function since the cache always contains only the number of documents in the collection
This serves as a compaction function since the cache always contains only the number of documents in the collection
while the data file is append-only so it may grow larger
while the data file is append-only so it may grow larger</p>
This is an internal function, use compactDataFile which uses the executor</p>
<p>This is an internal function, use [compactDatafile](#Persistence+compactDatafile) which uses the [executor](#Datastore+executor).</p>
**Kind**: instance method of [<code>Persistence</code>](#Persistence)
**Kind**: instance method of [<code>Persistence</code>](#Persistence)
It consists of an Object with anything you want inside.</p>
**Kind**: global typedef
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| [_id] | <code>string</code> | <p>Internal <code>_id</code> of the document, which can be <code>null</code> or undefined at some points (when not inserted yet for example).</p> |
<aname="query"></a>
## query : <code>Object.<string, \*></code>
<p>Nedb query.</p>
<p>Each key of a query references a field name, which can use the dot-notation to reference subfields inside nested
documents, arrays, arrays of subdocuments and to match a specific element of an array.</p>
<p>Each value of a query can be one of the following:</p>
<ul>
<li><code>string</code>: matches all documents which have this string as value for the referenced field name</li>
<li><code>number</code>: matches all documents which have this number as value for the referenced field name</li>
<li><code>Regexp</code>: matches all documents which have a value that matches the given <code>Regexp</code> for the referenced field name</li>
<li><code>object</code>: matches all documents which have this object as deep-value for the referenced field name</li>
<li>Comparison operators: the syntax is <code>{ field: { $op: value } }</code> where <code>$op</code> is any comparison operator:
<ul>
<li><code>$lt</code>, <code>$lte</code>: less than, less than or equal</li>
<li><code>$gt</code>, <code>$gte</code>: greater than, greater than or equal</li>
<li><code>$in</code>: member of. <code>value</code> must be an array of values</li>
<li><code>$ne</code>, <code>$nin</code>: not equal, not a member of</li>
<li><code>$stat</code>: checks whether the document posses the property <code>field</code>. <code>value</code> should be true or false</li>
<li><code>$regex</code>: checks whether a string is matched by the regular expression. Contrary to MongoDB, the use of
<code>$options</code> with <code>$regex</code> is not supported, because it doesn't give you more power than regex flags. Basic
queries are more readable so only use the <code>$regex</code> operator when you need to use another operator with it</li>
<li><code>$size</code>: if the referenced filed is an Array, matches on the size of the array</li>
<li><code>$elemMatch</code>: matches if at least one array element matches the sub-query entirely</li>
</ul>
</li>
<li>Logical operators: You can combine queries using logical operators:
<ul>
<li>For <code>$or</code> and <code>$and</code>, the syntax is <code>{ $op: [query1, query2, ...] }</code>.</li>
<li>For <code>$not</code>, the syntax is <code>{ $not: query }</code></li>
<li>For <code>$where</code>, the syntax is:</li>
</ul>
<preclass="prettyprint source"><code>{ $where: function () {
<p>Flush data in OS buffer to storage if corresponding option is set</p>
<p>Flush data in OS buffer to storage if corresponding option is set.</p>
**Kind**: static method of [<code>storage</code>](#module_storage)
**Kind**: static method of [<code>storage</code>](#module_storage)
**Params**
| Param | Type | Default | Description |
- options <code>object</code> | <code>string</code> - <p>If options is a string, it is assumed that the flush of the file (not dir) called options was requested</p>
| --- | --- | --- | --- |
- [.filename] <code>string</code>
| options | <code>object</code> \| <code>string</code> | | <p>If options is a string, it is assumed that the flush of the file (not dir) called options was requested</p> |
- [.isDir] <code>boolean</code><code> = false</code> - <p>Optional, defaults to false</p>
| options | <code>object</code> \| <code>string</code> | | <p>If options is a string, it is assumed that the flush of the file (not dir) called options was requested</p> |
For a Node.js/Node Webkit database it's the file system
<p>This version is the browser version and uses [localforage](https://github.com/localForage/localForage) which chooses the best option depending on user browser (IndexedDB then WebSQL then localStorage).</p>
For a browser-side database it's localforage which chooses the best option depending on user browser (IndexedDB then WebSQL then localStorage)</p>
<p>This version is the browser version</p>
**See**
- module:storage
- module:storageReactNative
* [storageBrowser](#module_storageBrowser)
* [storageBrowser](#module_storageBrowser)
@ -33,37 +36,37 @@ For a browser-side database it's localforage which chooses the best option depen
<p>Ensure the datafile contains all the data, even if there was a crash during a full file write
<p>Shim for [ensureDatafileIntegrityAsync](#module_storage.ensureDatafileIntegrityAsync), nothing to do, no data corruption possible in the browser.</p>
Nothing to do, no data corruption possible in the browser</p>
**Kind**: static method of [<code>storageBrowser</code>](#module_storageBrowser)
**Kind**: static method of [<code>storageBrowser</code>](#module_storageBrowser)
For a Node.js/Node Webkit database it's the file system
<p>This version is the React-Native version and uses [@react-native-async-storage/async-storage](https://github.com/react-native-async-storage/async-storage).</p>
For a browser-side database it's localforage, which uses the best backend available (IndexedDB then WebSQL then localStorage)
For a react-native database, we use @react-native-async-storage/async-storage</p>
<p>Ensure the datafile contains all the data, even if there was a crash during a full file write
<p>Shim for [ensureDatafileIntegrityAsync](#module_storage.ensureDatafileIntegrityAsync), nothing to do, no data corruption possible in the browser.</p>
Nothing to do, no data corruption possible in the browser</p>
**Kind**: static method of [<code>storageReactNative</code>](#module_storageReactNative)
**Kind**: static method of [<code>storageReactNative</code>](#module_storageReactNative)
<p>Produces a duplicate-free version of the array, using === to test object equality. In particular only the first
<p>Produces a duplicate-free version of the array, using === to test object equality. In particular only the first
occurrence of each value is kept. If you want to compute unique items based on a transformation, pass an iteratee
occurrence of each value is kept. If you want to compute unique items based on a transformation, pass an iteratee
function.
function.</p>
Heavily inspired by https://underscorejs.org/#uniq</p>
<p>Heavily inspired by [https://underscorejs.org/#uniq](https://underscorejs.org/#uniq).</p>
**Kind**: static method of [<code>utils</code>](#module_utils)
**Kind**: static method of [<code>utils</code>](#module_utils)
**Params**
| Param | Type | Description |
- array <code>Array</code>
| --- | --- | --- |
- [iteratee] <code>function</code> - <p>transformation applied to every element before checking for duplicates. This will not
| array | <code>Array</code> | |
transform the items in the result.</p>
| [iteratee] | <code>function</code> | <p>transformation applied to every element before checking for duplicates. This will not transform the items in the result.</p> |
<aname="module_utils.isDate"></a>
<aname="module_utils.isDate"></a>
### utils.isDate(d) ⇒ <code>boolean</code>
### utils.isDate(d) ⇒ <code>boolean</code>
<p>Returns true if d is a Date.
<p>Returns true if d is a Date.</p>
Heavily inspired by https://underscorejs.org/#isDate</p>
<p>Heavily inspired by [https://underscorejs.org/#isDate](https://underscorejs.org/#isDate).</p>
**Kind**: static method of [<code>utils</code>](#module_utils)
**Kind**: static method of [<code>utils</code>](#module_utils)
**Params**
| Param | Type |
- d <code>\*</code>
| --- | --- |
| d | <code>\*</code> |
<aname="module_utils.isRegExp"></a>
<aname="module_utils.isRegExp"></a>
### utils.isRegExp(re) ⇒ <code>boolean</code>
### utils.isRegExp(re) ⇒ <code>boolean</code>
<p>Returns true if re is a RegExp.
<p>Returns true if re is a RegExp.</p>
Heavily inspired by https://underscorejs.org/#isRegExp</p>
<p>Heavily inspired by [https://underscorejs.org/#isRegExp](https://underscorejs.org/#isRegExp).</p>
**Kind**: static method of [<code>utils</code>](#module_utils)
**Kind**: static method of [<code>utils</code>](#module_utils)
**Params**
| Param | Type |
- re <code>\*</code>
| --- | --- |
| re | <code>\*</code> |
<aname="module_utils..isObject"></a>
<aname="module_utils..isObject"></a>
### utils~isObject(arg) ⇒ <code>boolean</code>
### utils~isObject(arg) ⇒ <code>boolean</code>
<p>Returns true if arg is an Object. Note that JavaScript arrays and functions are objects, while (normal) strings
<p>Returns true if arg is an Object. Note that JavaScript arrays and functions are objects, while (normal) strings
and numbers are not.
and numbers are not.</p>
Heavily inspired by https://underscorejs.org/#isObject</p>
<p>Heavily inspired by [https://underscorejs.org/#isObject](https://underscorejs.org/#isObject).</p>
**Kind**: inner method of [<code>utils</code>](#module_utils)
**Kind**: inner method of [<code>utils</code>](#module_utils)
Timothée Rebours
3 years ago