TheDude
/
nedb
mirror of https://github.com/seald/nedb
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
The JavaScript Database, for Node.js, nw.js, electron and the browser
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
998 Commits
4 Branches
51 Tags
5.9 MiB
 
 
Tag: Branch: Tree: f36aa5ae0f
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f36aa5ae0f'
${ noResults }
nedb/docs/Datastore.md

28 KiB
Raw Blame History

Datastore ⇐ EventEmitter

The Datastore class is the main class of NeDB.

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

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 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 loadDatabase is called, so make sure to call it yourself or use the autoload option.

Param Type Default Description
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.
[options.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.
[options.inMemoryOnly] boolean false

If set to true, no data will be written in storage.
[options.timestampData] boolean false

If set to true, createdAt and updatedAt will be created and populated automatically (if not specified by user)
[options.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.
[options.onload] function

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.
[options.beforeDeserialization] function

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).
[options.afterSerialization] function

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.
[options.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.
[options.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.
[options.nodeWebkitAppName] string

Deprecated: if you are using NeDB from whithin a Node Webkit app, specify its name (the same one you use in the package.json) in this field and the filename 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 require('nw.gui').App.dataPath 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.

datastore.persistence : Persistence

The Persistence instance for this Datastore.

Kind: instance property of Datastore

datastore.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

datastore.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

datastore.loadDatabase(callback)

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

Kind: instance method of Datastore

Param Type
callback function

datastore.loadDatabaseAsync() ⇒ Promise

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

Kind: instance method of Datastore

datastore.getAllData() ⇒ Array.<document>

Get an array of all the data in the database

Kind: instance method of Datastore

datastore.resetIndexes()

Reset all currently defined indexes

Kind: instance method of Datastore

datastore.ensureIndex(options, callback)

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. Previous versions said explicitly the callback was optional, it is now recommended setting one.

Kind: instance method of Datastore

Param Type Default Description
options object
options.fieldName string

Name of the field to index. Use the dot notation to index a field in a nested document.
[options.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.
[options.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.
[options.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
callback NoParamCallback

Callback, signature: err

datastore.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. Previous versions said explicitly the callback was optional, it is now recommended setting one.

Kind: instance method of Datastore

Param Type Default Description
options object
options.fieldName string

Name of the field to index. Use the dot notation to index a field in a nested document.
[options.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.
[options.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.
[options.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

datastore.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

Param Type Description
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

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

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

Kind: instance method of Datastore

Param Type Description
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.

datastore.removeFromIndexes(doc)

Remove one or several document(s) from all indexes

Kind: instance method of Datastore

Param Type
doc document

datastore.updateIndexes(oldDoc, [newDoc])

Update one or several documents in all indexes To update multiple documents, oldDoc must be an array of { oldDoc, newDoc } pairs If one update violates a constraint, all changes are rolled back

Kind: instance method of Datastore

Param Type Description
oldDoc document | Array.<{oldDoc: document, newDoc: document}>

Document to update, or an Array of {oldDoc, newDoc} pairs.
[newDoc] document

Document to replace the oldDoc with. If the first argument is an Array of {oldDoc, newDoc} pairs, this second argument is ignored.

datastore.insertAsync(newDoc) ⇒ Promise.<document>

Insert a new document Private Use Datastore.insertAsync which has the same signature

Kind: instance method of Datastore

Param Type
newDoc document | Array.<document>

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

Count all documents matching the query

Kind: instance method of Datastore

Param Type Description
query query

MongoDB-style query
[callback] countCallback

If given, the function will return undefined, otherwise it will return the Cursor.

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

Count all documents matching the query

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

count

Param Type Description
query query

MongoDB-style query

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

Find all documents matching the query If no callback is passed, we return the cursor so that user can limit, skip and finally exec

Kind: instance method of Datastore

Param Type Default Description
query query

MongoDB-style query
[projection] projection | MultipleDocumentsCallback {}

MongoDB-style projection. If not given, will be interpreted as the callback.
[callback] MultipleDocumentsCallback

Optional callback, signature: err, docs

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

Find all documents matching the query If no callback is passed, we return the cursor so that user can limit, skip and finally exec

Kind: instance method of Datastore

Param Type Default Description
query query

MongoDB-style query
[projection] projection {}

MongoDB-style projection

datastore.findOne(query, projection, callback) ⇒ Cursor.<document> | undefined

Find one document matching the query

Kind: instance method of Datastore

Param Type Description
query query

MongoDB-style query
projection projection

MongoDB-style projection
callback SingleDocumentCallback

Optional callback, signature: err, doc

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

Find one document matching the query

Kind: instance method of Datastore

Param Type Description
query query

MongoDB-style query
projection projection

MongoDB-style projection

datastore.update(query, update, [options], [cb])

Update all docs matching query.

Kind: instance method of Datastore

Param Type Default Description
query query

is the same kind of finding query you use with find and findOne
update document | update

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!):

  • A new document will replace the matched docs
  • 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 $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
[options.multi] boolean false

If true, can update multiple documents
[options.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.
[options.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

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

Update all docs matching query.

Kind: instance method of Datastore

Param Type Default Description
query query

is the same kind of finding query you use with find and findOne
update document | update

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!):

  • A new document will replace the matched docs
  • 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 $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
[options.multi] boolean false

If true, can update multiple documents
[options.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.
[options.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.

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

Remove all docs matching the query.

Kind: instance method of Datastore

Param Type Default Description
query query
[options] object

Optional options
[options.multi] boolean false

If true, can update multiple documents
[cb] removeCallback () => {}

Optional callback, signature: err, numRemoved

datastore.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

Param Type Default Description
query query
[options] object

Optional options
[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

Param Type
err Error
count number

Datastore~findOneCallback : function

Kind: inner typedef of Datastore

Param Type
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

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

Datastore~removeCallback : function

Kind: inner typedef of Datastore

Param Type
err Error
numRemoved number