nedb/API.md at dbcc3647d12f9bf9fc8dc7a6d5adbab219f9dcb9 - nedb

The JavaScript Database, for Node.js, nw.js, electron and the browser

hacktoberfest database javascript

54 KiB

Raw Blame History

Classes

Cursor ⇐ Promise

Manage access to data, be it to find, update or remove it.

It extends Promise so that its methods (which return this) are chainable & awaitable.

Datastore ⇐ EventEmitter

The Datastore class is the main class of NeDB.

Persistence

Under the hood, NeDB's persistence uses an append-only format, meaning that all updates and deletes actually result in lines added at the end of the datafile, for performance reasons. The database is automatically compacted (i.e. put back in the one-line-per-document format) every time you load each database within your application.

You can manually call the compaction function with yourDatabase.persistence.compactDatafile which takes no argument. It queues a compaction of the datafile in the executor, to be executed sequentially after all pending operations. The datastore will fire a compaction.done event once compaction is finished.

You can also set automatic compaction at regular intervals with yourDatabase.persistence.setAutocompactionInterval(interval), interval in milliseconds (a minimum of 5s is enforced), and stop automatic compaction with yourDatabase.persistence.stopAutocompaction().

Keep in mind that compaction takes a bit of time (not too much: 130ms for 50k records on a typical development machine) and no other operation can happen when it does, so most projects actually don't need to use it.

Compaction will also immediately remove any documents whose data line has become corrupted, assuming that the total percentage of all corrupted documents in that database still falls below the specified corruptAlertThreshold option's value.

Durability works similarly to major databases: compaction forces the OS to physically flush data to disk, while appends to the data file do not (the OS is responsible for flushing the data). That guarantees that a server crash can never cause complete data loss, while preserving performance. The worst that can happen is a crash between two syncs, causing a loss of all data between the two syncs. Usually syncs are 30 seconds appart so that's at most 30 seconds of data. This post by Antirez on Redis persistence explains this in more details, NeDB being very close to Redis AOF persistence with appendfsync option set to no.

Typedefs

NoParamCallback : function

Callback with no parameter

compareStrings ⇒ number

String comparison function.

  if (a < b) return -1
  if (a > b) return 1
  return 0

MultipleDocumentsCallback : function

Callback that returns an Array of documents

SingleDocumentCallback : function

Callback that returns a single document

AsyncFunction ⇒ Promise.<*>

Generic async function

GenericCallback : function

Callback with generic parameters

document : Object.<string, *>

Generic document in NeDB. It consists of an Object with anything you want inside.

query : Object.<string, *>

Nedb query.

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.

Each value of a query can be one of the following:

string: matches all documents which have this string as value for the referenced field name
number: matches all documents which have this number as value for the referenced field name
Regexp: matches all documents which have a value that matches the given Regexp for the referenced field name
object: matches all documents which have this object as deep-value for the referenced field name
Comparison operators: the syntax is { field: { $op: value } } where $op is any comparison operator:
- $lt, $lte: less than, less than or equal
- $gt, $gte: greater than, greater than or equal
- $in: member of. value must be an array of values
- $ne, $nin: not equal, not a member of
- $stat: checks whether the document posses the property field. value should be true or false
- $regex: checks whether a string is matched by the regular expression. Contrary to MongoDB, the use of $options with $regex is not supported, because it doesn't give you more power than regex flags. Basic queries are more readable so only use the $regex operator when you need to use another operator with it
- $size: if the referenced filed is an Array, matches on the size of the array
- $elemMatch: matches if at least one array element matches the sub-query entirely
Logical operators: You can combine queries using logical operators:
- For $or and $and, the syntax is { $op: [query1, query2, ...] }.
- For $not, the syntax is { $not: query }
- For $where, the syntax is:
```
{ $where: function () {
  // object is 'this'
  // return a boolean
} }
```

projection : Object.<string, (0|1)>

Nedb projection.

You can give find and findOne an optional second argument, projections. The syntax is the same as MongoDB: { a: 1, b: 1 } to return only the a and b fields, { a: 0, b: 0 } to omit these two fields. You cannot use both modes at the time, except for _id which is by default always returned and which you can choose to omit. You can project on nested documents.

To reference subfields, you can use the dot-notation.

serializationHook ⇒ string

The beforeDeserialization and afterDeserialization callbacks are hooks which are executed respectively before parsing each document and after stringifying them. They can be used for example to encrypt the Datastore. The beforeDeserialization should revert what afterDeserialization has done.

rawIndex

Cursor ⇐ `Promise`

Manage access to data, be it to find, update or remove it.

It extends Promise so that its methods (which return this) are chainable & awaitable.

Kind: global class
Extends: Promise

Cursor ⇐ Promise
- new Cursor(db, query, [mapFn])
- instance
  - .db : Datastore
  - .query : query
  - .limit(limit) ⇒ Cursor
  - .skip(skip) ⇒ Cursor
  - .sort(sortQuery) ⇒ Cursor
  - .projection(projection) ⇒ Cursor
  - .exec(_callback)
  - .execAsync() ⇒ Promise.<(Array.<document>|*)>
- inner
  - ~mapFn ⇒ * | Promise.<*>
  - ~execCallback : function

new Cursor(db, query, [mapFn])

Create a new cursor for this collection

Params

db Datastore -
The datastore this cursor is bound to
query query -
The query this cursor will operate on
[mapFn] mapFn -
Handler to be executed after cursor has found the results and before the callback passed to find/findOne/update/remove

cursor.db : `Datastore`

Kind: instance property of Cursor
Access: protected

cursor.query : `query`

Kind: instance property of Cursor
Access: protected

cursor.limit(limit) ⇒ `Cursor`

Set a limit to the number of results

Kind: instance method of Cursor
Params

limit Number

cursor.skip(skip) ⇒ `Cursor`

Skip a number of results

Kind: instance method of Cursor
Params

skip Number

cursor.sort(sortQuery) ⇒ `Cursor`

Sort results of the query

Kind: instance method of Cursor
Params

sortQuery Object.<string, number> -
sortQuery is { field: order }, field can use the dot-notation, order is 1 for ascending and -1 for descending

cursor.projection(projection) ⇒ `Cursor`

Add the use of a projection

Kind: instance method of Cursor
Params

projection Object.<string, number> -
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.

cursor.exec(_callback)

Get all matching elements Will return pointers to matched elements (shallow copies), returning full copies is the role of find or findOne

Kind: instance method of Cursor
Params

_callback execCallback

cursor.execAsync() ⇒ `Promise.<(Array.<document>|*)>`

Async version of [exec](#Cursor+exec).

Kind: instance method of Cursor
See: Cursor#exec

Cursor~mapFn ⇒ `` | `Promise.<>`

Has a callback

Kind: inner typedef of Cursor
Params

res Array.<document>

Cursor~execCallback : `function`

Kind: inner typedef of Cursor
Params

err Error
res Array.<document> | * -
If an mapFn was given to the Cursor, then the type of this parameter is the one returned by the mapFn.

Datastore ⇐ `EventEmitter`

The Datastore class is the main class of NeDB.

Kind: global class
Extends: EventEmitter
Emits: Datastore#event:"compaction.done"

Datastore ⇐ EventEmitter
- new Datastore(options)
- instance
  - .inMemoryOnly : boolean
  - .autoload : boolean
  - .timestampData : boolean
  - .filename : string
  - .persistence : Persistence
  - .executor : Executor
  - .indexes : Object.<string, Index>
  - .ttlIndexes : Object.<string, number>
  - .autoloadPromise : Promise
  - .compareStrings() : compareStrings
  - .loadDatabase([callback])
  - .loadDatabaseAsync() ⇒ Promise
  - .getAllData() ⇒ Array.<document>
  - .ensureIndex(options, [callback])
  - .ensureIndexAsync(options) ⇒ Promise.<void>
  - .removeIndex(fieldName, callback)
  - .removeIndexAsync(fieldName) ⇒ Promise.<void>
  - .insert(newDoc, [callback])
  - .insertAsync(newDoc) ⇒ Promise.<(document|Array.<document>)>
  - .count(query, [callback]) ⇒ Cursor.<number> | undefined
  - .countAsync(query) ⇒ Cursor.<number>
  - .find(query, [projection], [callback]) ⇒ Cursor.<Array.<document>> | undefined
  - .findAsync(query, [projection]) ⇒ Cursor.<Array.<document>>
  - .findOne(query, [projection], [callback]) ⇒ Cursor.<document> | undefined
  - .findOneAsync(query, projection) ⇒ Cursor.<document>
  - .update(query, update, [options|], [cb])
  - .updateAsync(query, update, [options]) ⇒ Promise.<{numAffected: number, affectedDocuments: (Array.<document>|document|null), upsert: boolean}>
  - .remove(query, [options], [cb])
  - .removeAsync(query, [options]) ⇒ Promise.<number>
  - "event:compaction.done"
- inner
  - ~countCallback : function
  - ~findOneCallback : function
  - ~updateCallback : function
  - ~removeCallback : function

new Datastore(options)

Create a new collection, either persistent or in-memory.

If you use a persistent datastore without the autoload option, you need to call [loadDatabase](#Datastore+loadDatabase) or [loadDatabaseAsync](#Datastore+loadDatabaseAsync) manually. This function fetches the data from datafile and prepares the database. Don't forget it! If you use a persistent datastore, no command (insert, find, update, remove) will be executed before it is called, so make sure to call it yourself or use the autoload option.

Also, if loading fails, all commands registered to the [executor](#Datastore+executor) afterwards will not be executed. They will be registered and executed, in sequence, only after a successful loading.

Params

options object | string -
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 options.filename. Giving a string is deprecated, and will be removed in the next major version.
- [.filename] string = null -
  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 ~ which is used in the temporary files NeDB uses to perform crash-safe writes. Not used if options.inMemoryOnly is true.
- [.inMemoryOnly] boolean = false -
  If set to true, no data will be written in storage. This option has priority over options.filename.
- [.timestampData] boolean = false -
  If set to true, createdAt and updatedAt will be created and populated automatically (if not specified by user)
- [.autoload] boolean = false -
  If used, the database will automatically be loaded from the datafile upon creation (you don't need to call loadDatabase). 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 onload callback, or you can use this.autoloadPromise which resolves (or rejects) when autloading is done.
- [.onload] NoParamCallback -
  If you use autoloading, this is the handler called after the loadDatabase. It takes one error argument. If you use autoloading without specifying this handler, and an error happens during load, an error will be thrown.
- [.beforeDeserialization] serializationHook -
  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, which must absolutely not contain a \n character (or data will be lost).
- [.afterSerialization] serializationHook -
  Inverse of afterSerialization. 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.
- [.corruptAlertThreshold] number = 0.1 -
  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.
- [.compareStrings] compareStrings -
  If specified, it overrides default string comparison which is not well adapted to non-US characters in particular accented letters. Native localCompare will most of the time be the right choice.

neDB.inMemoryOnly : `boolean`

Determines if the Datastore keeps data in-memory, or if it saves it in storage. Is not read after instanciation.

Kind: instance property of Datastore
Access: protected

neDB.autoload : `boolean`

Determines if the Datastore should autoload the database upon instantiation. Is not read after instanciation.

Kind: instance property of Datastore
Access: protected

neDB.timestampData : `boolean`

Determines if the Datastore should add createdAt and updatedAt fields automatically if not set by the user.

Kind: instance property of Datastore
Access: protected

neDB.filename : `string`

If null, it means inMemoryOnly is true. The filename is the name given to the storage module. Is not read after instanciation.

Kind: instance property of Datastore
Access: protected

neDB.persistence : `Persistence`

The Persistence instance for this Datastore.

Kind: instance property of Datastore

neDB.executor : `Executor`

The Executor instance for this Datastore. It is used in all methods exposed by the Datastore, any Cursor produced by the Datastore and by this.persistence.compactDataFile & this.persistence.compactDataFileAsync to ensure operations are performed sequentially in the database.

Kind: instance property of Datastore
Access: protected

neDB.indexes : `Object.<string, Index>`

Indexed by field name, dot notation can be used. _id is always indexed and since _ids are generated randomly the underlying binary search tree is always well-balanced

Kind: instance property of Datastore
Access: protected

neDB.ttlIndexes : `Object.<string, number>`

Stores the time to live (TTL) of the indexes created. The key represents the field name, the value the number of seconds after which data with this index field should be removed.

Kind: instance property of Datastore
Access: protected

neDB.autoloadPromise : `Promise`

A Promise that resolves when the autoload has finished.

The onload callback is not awaited by this Promise, it is started immediately after that.

Kind: instance property of Datastore

neDB.compareStrings() : `compareStrings`

Overrides default string comparison which is not well adapted to non-US characters in particular accented letters. Native localCompare will most of the time be the right choice

Kind: instance method of Datastore
Access: protected

neDB.loadDatabase([callback])

Callback version of [loadDatabaseAsync](#Datastore+loadDatabaseAsync).

Kind: instance method of Datastore
See: Datastore#loadDatabaseAsync
Params

[callback] NoParamCallback

neDB.loadDatabaseAsync() ⇒ `Promise`

Load the database from the datafile, and trigger the execution of buffered commands if any.

Kind: instance method of Datastore

neDB.getAllData() ⇒ `Array.<document>`

Get an array of all the data in the database.

Kind: instance method of Datastore

neDB.ensureIndex(options, [callback])

Callback version of [ensureIndex](#Datastore+ensureIndex).

Kind: instance method of Datastore
See: Datastore#ensureIndex
Params

options object
- .fieldName string
- [.unique] boolean = false
- [.sparse] boolean = false
- [.expireAfterSeconds] number
[callback] NoParamCallback

neDB.ensureIndexAsync(options) ⇒ `Promise.<void>`

Ensure an index is kept for this field. Same parameters as lib/indexes This function acts synchronously on the indexes, however the persistence of the indexes is deferred with the executor.

Kind: instance method of Datastore
Params

options object
- .fieldName string -
  Name of the field to index. Use the dot notation to index a field in a nested document.
- [.unique] boolean = false -
  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.
- [.sparse] boolean = false -
  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.
- [.expireAfterSeconds] number -
  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 expireAfterSeconds. Documents where the indexed field is not specified or not a Date object are ignored.

neDB.removeIndex(fieldName, callback)

Remove an index Previous versions said explicitly the callback was optional, it is now recommended setting one.

Kind: instance method of Datastore
Params

fieldName string -
Field name of the index to remove. Use the dot notation to remove an index referring to a field in a nested document.
callback NoParamCallback -
Optional callback, signature: err

neDB.removeIndexAsync(fieldName) ⇒ `Promise.<void>`

Async version of [removeIndex](#Datastore+removeIndex).

Kind: instance method of Datastore
See: Datastore#removeIndex
Params

fieldName string -
Field name of the index to remove. Use the dot notation to remove an index referring to a field in a nested document.

neDB.insert(newDoc, [callback])

Callback version of [insertAsync](#Datastore+insertAsync).

Kind: instance method of Datastore
See: Datastore#insertAsync
Params

newDoc document | Array.<document>
[callback] SingleDocumentCallback | MultipleDocumentsCallback

neDB.insertAsync(newDoc) ⇒ `Promise.<(document|Array.<document>)>`

Insert a new document, or new documents.

Kind: instance method of Datastore
Returns: Promise.<(document|Array.<document>)> -

The document(s) inserted.

Params

newDoc document | Array.<document> -
Document or array of documents to insert.

neDB.count(query, [callback]) ⇒ `Cursor.<number>` | `undefined`

Callback-version of [countAsync](#Datastore+countAsync).

Kind: instance method of Datastore
See: Datastore#countAsync
Params

query query
[callback] countCallback

neDB.countAsync(query) ⇒ `Cursor.<number>`

Count all documents matching the query.

Kind: instance method of Datastore
Returns: Cursor.<number> -

count

Params

query query -
MongoDB-style query

neDB.find(query, [projection], [callback]) ⇒ `Cursor.<Array.<document>>` | `undefined`

Callback version of [findAsync](#Datastore+findAsync).

Kind: instance method of Datastore
See: Datastore#findAsync
Params

query query
[projection] projection | MultipleDocumentsCallback = {}
[callback] MultipleDocumentsCallback

neDB.findAsync(query, [projection]) ⇒ `Cursor.<Array.<document>>`

Find all documents matching the query. We return the [Cursor](#Cursor) that the user can either await directly or use to can [limit](#Cursor+limit) or [skip](#Cursor+skip) before.

Kind: instance method of Datastore
Params

query query -
MongoDB-style query
[projection] projection = {} -
MongoDB-style projection

neDB.findOne(query, [projection], [callback]) ⇒ `Cursor.<document>` | `undefined`

Callback version of [findOneAsync](#Datastore+findOneAsync).

Kind: instance method of Datastore
See: Datastore#findOneAsync
Params

query query
[projection] projection | SingleDocumentCallback = {}
[callback] SingleDocumentCallback

neDB.findOneAsync(query, projection) ⇒ `Cursor.<document>`

Find one document matching the query. We return the [Cursor](#Cursor) that the user can either await directly or use to can [skip](#Cursor+skip) before.

Kind: instance method of Datastore
Params

query query -
MongoDB-style query
projection projection -
MongoDB-style projection

neDB.update(query, update, [options|], [cb])

Update all docs matching query.

Kind: instance method of Datastore
Params

query query -
is the same kind of finding query you use with find and findOne
update document | * -
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!). Using a new document will replace the matched docs. Using a set of modifiers will create the fields they need to modify if they don't exist, and you can apply them to subdocs. Available field modifiers are $set to change a field's value, $unset to delete a field, $inc to increment a field's value and $min/$max to change field's value, only if provided value is less/greater than current value. To work on arrays, you have $push, $pop, $addToSet, $pull, and the special $each and $slice.
[options|] Object | updateCallback -
Optional options
- [.multi] boolean = false -
  If true, can update multiple documents
- [.upsert] boolean = false -
  If true, can insert a new document corresponding to the update rules if your query doesn't match anything. If your update is a simple object with no modifiers, it is the inserted document. In the other case, the query is stripped from all operator recursively, and the update is applied to it.
- [.returnUpdatedDocs] boolean = false -
  (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.
[cb] updateCallback = () => {} -
Optional callback

neDB.updateAsync(query, update, [options]) ⇒ `Promise.<{numAffected: number, affectedDocuments: (Array.<document>|document|null), upsert: boolean}>`

Async version of [update](#Datastore+update).

Kind: instance method of Datastore
See: Datastore#update
Params

query query -
is the same kind of finding query you use with find and findOne
update document | * -
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!). Using a new document will replace the matched docs. Using a set of modifiers will create the fields they need to modify if they don't exist, and you can apply them to subdocs. Available field modifiers are $set to change a field's value, $unset to delete a field, $inc to increment a field's value and $min/$max to change field's value, only if provided value is less/greater than current value. To work on arrays, you have $push, $pop, $addToSet, $pull, and the special $each and $slice.
[options] Object = {} -
Optional options
- [.multi] boolean = false -
  If true, can update multiple documents
- [.upsert] boolean = false -
  If true, can insert a new document corresponding to the update rules if your query doesn't match anything. If your update is a simple object with no modifiers, it is the inserted document. In the other case, the query is stripped from all operator recursively, and the update is applied to it.
- [.returnUpdatedDocs] boolean = false -
  (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.

neDB.remove(query, [options], [cb])

Remove all docs matching the query.

Kind: instance method of Datastore
Params

query query
[options] object | removeCallback = {} -
Optional options
- [.multi] boolean = false -
  If true, can update multiple documents
[cb] removeCallback = () => {} -
Optional callback

neDB.removeAsync(query, [options]) ⇒ `Promise.<number>`

Remove all docs matching the query. Use Datastore.removeAsync which has the same signature

Kind: instance method of Datastore
Returns: Promise.<number> -

How many documents were removed

Params

query query
[options] object = {} -
Optional options
- [.multi] boolean = false -
  If true, can update multiple documents

"event:compaction.done"

Compaction event. Happens when the Datastore's Persistence has been compacted. It happens when calling datastore.persistence.compactDatafile, which is called periodically if you have called datastore.persistence.setAutocompactionInterval.

Kind: event emitted by Datastore

Datastore~countCallback : `function`

Kind: inner typedef of Datastore
Params

err Error
count number

Datastore~findOneCallback : `function`

Kind: inner typedef of Datastore
Params

err Error
doc document

Datastore~updateCallback : `function`

If update was an upsert, upsert flag is set to true, affectedDocuments can be one of the following:

For an upsert, the upserted document
For an update with returnUpdatedDocs option false, null
For an update with returnUpdatedDocs true and multi false, the updated document
For an update with returnUpdatedDocs true and multi true, the array of updated documents

WARNING: The API was changed between v1.7.4 and v1.8, for consistency and readability reasons. Prior and including to v1.7.4, the callback signature was (err, numAffected, updated) where updated was the updated document in case of an upsert or the array of updated documents for an update if the returnUpdatedDocs option was true. That meant that the type of affectedDocuments in a non multi update depended on whether there was an upsert or not, leaving only two ways for the user to check whether an upsert had occured: checking the type of affectedDocuments or running another find query on the whole dataset to check its size. Both options being ugly, the breaking change was necessary.

Kind: inner typedef of Datastore
Params

err Error
numAffected number
affectedDocuments ?Array.<document> | document
upsert boolean

Datastore~removeCallback : `function`

Kind: inner typedef of Datastore
Params

err Error
numRemoved number

Persistence

Kind: global class

Persistence
- new Persistence()
- instance
  - .persistCachedDatabaseAsync() ⇒ Promise.<void>
  - .compactDatafile([callback])
  - .compactDatafileAsync()
  - .setAutocompactionInterval(interval)
  - .stopAutocompaction()
  - .persistNewStateAsync(newDocs) ⇒ Promise
  - .treatRawData(rawData) ⇒ Object
  - .treatRawStreamAsync(rawStream) ⇒ Promise.<{data: Array.<document>, indexes: Object.<string, rawIndex>}>
  - .loadDatabase(callback)
  - .loadDatabaseAsync() ⇒ Promise.<void>
- static
  - .ensureDirectoryExistsAsync(dir) ⇒ Promise.<void>

new Persistence()

Create a new Persistence object for database options.db

Params

- .db [<code>Datastore</code>](#Datastore)
- [.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>
- [.afterSerialization] [<code>serializationHook</code>](#serializationHook) - <p>Inverse of <code>afterSerialization</code>.</p>

persistence.persistCachedDatabaseAsync() ⇒ `Promise.<void>`

Persist cached database 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

This is an internal function, use [compactDatafileAsync](#Persistence+compactDatafileAsync) which uses the [executor](#Datastore+executor).

Kind: instance method of Persistence
Access: protected

persistence.compactDatafile([callback])

Queue a rewrite of the datafile

Kind: instance method of Persistence
See: Persistence#persistCachedDatabaseAsync
Params

[callback] NoParamCallback = () => {}

persistence.compactDatafileAsync()

Async version of [compactDatafile](#Persistence+compactDatafile).

Kind: instance method of Persistence
See: Persistence#compactDatafile

persistence.setAutocompactionInterval(interval)

Set automatic compaction every interval ms

Kind: instance method of Persistence
Params

interval Number -
in milliseconds, with an enforced minimum of 5000 milliseconds

persistence.stopAutocompaction()

Stop autocompaction (do nothing if automatic compaction was not running)

Kind: instance method of Persistence

persistence.persistNewStateAsync(newDocs) ⇒ `Promise`

Persist new state for the given newDocs (can be insertion, update or removal) Use an append-only format

Do not use directly, it should only used by a [Datastore](#Datastore) instance.

Kind: instance method of Persistence
Params

newDocs Array.<document> -
Can be empty if no doc was updated/removed

persistence.treatRawData(rawData) ⇒ `Object`

From a database's raw data, return the corresponding machine understandable collection.

Do not use directly, it should only used by a [Datastore](#Datastore) instance.

Kind: instance method of Persistence
Access: protected
Params

rawData string -
database file

persistence.treatRawStreamAsync(rawStream) ⇒ `Promise.<{data: Array.<document>, indexes: Object.<string, rawIndex>}>`

From a database's raw data stream, return the corresponding machine understandable collection Is only used by a [Datastore](#Datastore) instance.

Is only used in the Node.js version, since [React-Native](module:storageReactNative) & [browser](module:storageBrowser) storage modules don't provide an equivalent of [readFileStream](#module_storage.readFileStream).

Do not use directly, it should only used by a [Datastore](#Datastore) instance.

Kind: instance method of Persistence
Access: protected
Params

rawStream Readable

persistence.loadDatabase(callback)

Load the database

Create all indexes
Insert all data
Compact the database

This means pulling data out of the data file or creating it if it doesn't exist Also, all data is persisted right away, which has the effect of compacting the database file This operation is very quick at startup for a big collection (60ms for ~10k docs)

Do not use directly as it does not use the [Executor](Datastore.executor), use [loadDatabase](#Datastore+loadDatabase) instead.

Kind: instance method of Persistence
Access: protected
Params

callback NoParamCallback

persistence.loadDatabaseAsync() ⇒ `Promise.<void>`

Async version of [loadDatabase](#Persistence+loadDatabase)

Kind: instance method of Persistence
See: Persistence#loadDatabase

Persistence.ensureDirectoryExistsAsync(dir) ⇒ `Promise.<void>`

Check if a directory stat and create it on the fly if it is not the case.

Kind: static method of Persistence
Params

dir string

NoParamCallback : `function`

Callback with no parameter

Kind: global typedef
Params

err Error

compareStrings ⇒ `number`

String comparison function.

  if (a < b) return -1
  if (a > b) return 1
  return 0

Kind: global typedef
Params

a string
b string

MultipleDocumentsCallback : `function`

Callback that returns an Array of documents

Kind: global typedef
Params

err Error
docs Array.<document>

SingleDocumentCallback : `function`

Callback that returns a single document

Kind: global typedef
Params

err Error
docs document

AsyncFunction ⇒ `Promise.<*>`

Generic async function

Kind: global typedef
Params

...args *

GenericCallback : `function`

Callback with generic parameters

Kind: global typedef
Params

err Error
...args *

document : `Object.<string, *>`

Generic document in NeDB. It consists of an Object with anything you want inside.

Kind: global typedef
Properties

Name	Type	Description
[_id]	`string`	Internal `_id` of the document, which can be `null` or undefined at some points (when not inserted yet for example).

query : `Object.<string, *>`

Nedb query.

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.

Each value of a query can be one of the following:

string: matches all documents which have this string as value for the referenced field name
number: matches all documents which have this number as value for the referenced field name
Regexp: matches all documents which have a value that matches the given Regexp for the referenced field name
object: matches all documents which have this object as deep-value for the referenced field name
Comparison operators: the syntax is { field: { $op: value } } where $op is any comparison operator:
- $lt, $lte: less than, less than or equal
- $gt, $gte: greater than, greater than or equal
- $in: member of. value must be an array of values
- $ne, $nin: not equal, not a member of
- $stat: checks whether the document posses the property field. value should be true or false
- $regex: checks whether a string is matched by the regular expression. Contrary to MongoDB, the use of $options with $regex is not supported, because it doesn't give you more power than regex flags. Basic queries are more readable so only use the $regex operator when you need to use another operator with it
- $size: if the referenced filed is an Array, matches on the size of the array
- $elemMatch: matches if at least one array element matches the sub-query entirely
Logical operators: You can combine queries using logical operators:
- For $or and $and, the syntax is { $op: [query1, query2, ...] }.
- For $not, the syntax is { $not: query }
- For $where, the syntax is:
```
{ $where: function () {
  // object is 'this'
  // return a boolean
} }
```

Kind: global typedef

projection : `Object.<string, (0|1)>`

Nedb projection.

To reference subfields, you can use the dot-notation.

Kind: global typedef

serializationHook ⇒ `string`

Kind: global typedef
Params

x string

rawIndex

Kind: global typedef
Properties

Name	Type
fieldName	`string`
[unique]	`boolean`
[sparse]	`boolean`

54 KiB Raw Blame History

Classes

Typedefs

Cursor ⇐ Promise

new Cursor(db, query, [mapFn])

cursor.db : Datastore

cursor.query : query

cursor.limit(limit) ⇒ Cursor

cursor.skip(skip) ⇒ Cursor

cursor.sort(sortQuery) ⇒ Cursor

cursor.projection(projection) ⇒ Cursor

cursor.exec(_callback)

cursor.execAsync() ⇒ Promise.<(Array.<document>|*)>

Cursor~mapFn ⇒ * | Promise.<*>

Cursor~execCallback : function

Datastore ⇐ EventEmitter

new Datastore(options)

neDB.inMemoryOnly : boolean

neDB.autoload : boolean

neDB.timestampData : boolean

neDB.filename : string

neDB.persistence : Persistence

neDB.executor : Executor

neDB.indexes : Object.<string, Index>

neDB.ttlIndexes : Object.<string, number>

neDB.autoloadPromise : Promise

neDB.compareStrings() : compareStrings

neDB.loadDatabase([callback])

neDB.loadDatabaseAsync() ⇒ Promise

neDB.getAllData() ⇒ Array.<document>

neDB.ensureIndex(options, [callback])

neDB.ensureIndexAsync(options) ⇒ Promise.<void>

neDB.removeIndex(fieldName, callback)

neDB.removeIndexAsync(fieldName) ⇒ Promise.<void>

neDB.insert(newDoc, [callback])

neDB.insertAsync(newDoc) ⇒ Promise.<(document|Array.<document>)>

neDB.count(query, [callback]) ⇒ Cursor.<number> | undefined

neDB.countAsync(query) ⇒ Cursor.<number>

neDB.find(query, [projection], [callback]) ⇒ Cursor.<Array.<document>> | undefined

neDB.findAsync(query, [projection]) ⇒ Cursor.<Array.<document>>

neDB.findOne(query, [projection], [callback]) ⇒ Cursor.<document> | undefined

neDB.findOneAsync(query, projection) ⇒ Cursor.<document>

neDB.update(query, update, [options|], [cb])

neDB.updateAsync(query, update, [options]) ⇒ Promise.<{numAffected: number, affectedDocuments: (Array.<document>|document|null), upsert: boolean}>

neDB.remove(query, [options], [cb])

neDB.removeAsync(query, [options]) ⇒ Promise.<number>

"event:compaction.done"

Datastore~countCallback : function

Datastore~findOneCallback : function

Datastore~updateCallback : function

Datastore~removeCallback : function

Persistence

new Persistence()

persistence.persistCachedDatabaseAsync() ⇒ Promise.<void>

persistence.compactDatafile([callback])

persistence.compactDatafileAsync()

persistence.setAutocompactionInterval(interval)

persistence.stopAutocompaction()

persistence.persistNewStateAsync(newDocs) ⇒ Promise

persistence.treatRawData(rawData) ⇒ Object

persistence.treatRawStreamAsync(rawStream) ⇒ Promise.<{data: Array.<document>, indexes: Object.<string, rawIndex>}>

persistence.loadDatabase(callback)

persistence.loadDatabaseAsync() ⇒ Promise.<void>

Persistence.ensureDirectoryExistsAsync(dir) ⇒ Promise.<void>

NoParamCallback : function

compareStrings ⇒ number

MultipleDocumentsCallback : function

SingleDocumentCallback : function

AsyncFunction ⇒ Promise.<*>

GenericCallback : function

document : Object.<string, *>

query : Object.<string, *>

projection : Object.<string, (0|1)>

serializationHook ⇒ string

rawIndex

54 KiB

Raw Blame History

Cursor ⇐ `Promise`

cursor.db : `Datastore`

cursor.query : `query`

cursor.limit(limit) ⇒ `Cursor`

cursor.skip(skip) ⇒ `Cursor`

cursor.sort(sortQuery) ⇒ `Cursor`

cursor.projection(projection) ⇒ `Cursor`

cursor.execAsync() ⇒ `Promise.<(Array.<document>|*)>`

Cursor~mapFn ⇒ `` | `Promise.<>`

Cursor~execCallback : `function`

Datastore ⇐ `EventEmitter`

neDB.inMemoryOnly : `boolean`

neDB.autoload : `boolean`

neDB.timestampData : `boolean`

neDB.filename : `string`

neDB.persistence : `Persistence`

neDB.executor : `Executor`

neDB.indexes : `Object.<string, Index>`

neDB.ttlIndexes : `Object.<string, number>`

neDB.autoloadPromise : `Promise`

neDB.compareStrings() : `compareStrings`

neDB.loadDatabaseAsync() ⇒ `Promise`

neDB.getAllData() ⇒ `Array.<document>`

neDB.ensureIndexAsync(options) ⇒ `Promise.<void>`

neDB.removeIndexAsync(fieldName) ⇒ `Promise.<void>`

neDB.insertAsync(newDoc) ⇒ `Promise.<(document|Array.<document>)>`

neDB.count(query, [callback]) ⇒ `Cursor.<number>` | `undefined`

neDB.countAsync(query) ⇒ `Cursor.<number>`

neDB.find(query, [projection], [callback]) ⇒ `Cursor.<Array.<document>>` | `undefined`

neDB.findAsync(query, [projection]) ⇒ `Cursor.<Array.<document>>`

neDB.findOne(query, [projection], [callback]) ⇒ `Cursor.<document>` | `undefined`

neDB.findOneAsync(query, projection) ⇒ `Cursor.<document>`

neDB.updateAsync(query, update, [options]) ⇒ `Promise.<{numAffected: number, affectedDocuments: (Array.<document>|document|null), upsert: boolean}>`

neDB.removeAsync(query, [options]) ⇒ `Promise.<number>`

Datastore~countCallback : `function`

Datastore~findOneCallback : `function`

Datastore~updateCallback : `function`

Datastore~removeCallback : `function`

persistence.persistCachedDatabaseAsync() ⇒ `Promise.<void>`

persistence.persistNewStateAsync(newDocs) ⇒ `Promise`

persistence.treatRawData(rawData) ⇒ `Object`

persistence.treatRawStreamAsync(rawStream) ⇒ `Promise.<{data: Array.<document>, indexes: Object.<string, rawIndex>}>`

persistence.loadDatabaseAsync() ⇒ `Promise.<void>`

Persistence.ensureDirectoryExistsAsync(dir) ⇒ `Promise.<void>`

NoParamCallback : `function`

compareStrings ⇒ `number`

MultipleDocumentsCallback : `function`

SingleDocumentCallback : `function`

AsyncFunction ⇒ `Promise.<*>`

GenericCallback : `function`

document : `Object.<string, *>`

query : `Object.<string, *>`

projection : `Object.<string, (0|1)>`

serializationHook ⇒ `string`