JSDoc: Class: Loki

new Loki(filename, optionsopt)

Loki: The main database class

Parameters:

Name Type Attributes Description

filename

string

name of the file to be saved to

options

object

(Optional) config options object

Properties

Name	Type	Attributes	Default	Description
`env`	string			override environment detection as 'NODEJS', 'BROWSER', 'CORDOVA'
`verbose`	boolean	<optional>	false	enable console output
`autosave`	boolean	<optional>	false	enables autosave
`autosaveInterval`	int	<optional>	5000	time interval (in milliseconds) between saves (if dirty)
`autoload`	boolean	<optional>	false	enables autoload on loki instantiation
`autoloadCallback`	function			user callback called after database load
`adapter`	adapter			an instance of a loki persistence adapter
`serializationMethod`	string	<optional>	'normal'	['normal', 'pretty', 'destructured']
`destructureDelimiter`	string			string delimiter used for destructured serialization
`throttledSaves`	boolean	<optional>	true	debounces multiple calls to to saveDatabase reducing number of disk I/O operations and guaranteeing proper serialization of the calls.

Implements:

LokiEventEmitter

Source:

lokijs.js, line 764

Methods

addCollection(name, optionsopt) → {Collection}

Adds a collection to the database.

Parameters:

Name Type Attributes Description

name

string

name of collection to add

options

object

(optional) options to configure collection with.

Properties

Name	Type	Attributes	Default	Description
`unique`	array	<optional>	[]	array of property names to define unique constraints for
`exact`	array	<optional>	[]	array of property names to define exact constraints for
`indices`	array	<optional>	[]	array property names to define binary indexes for
`asyncListeners`	boolean	<optional>	false	whether listeners are called asynchronously
`disableMeta`	boolean	<optional>	false	set to true to disable meta property on documents
`disableChangesApi`	boolean	<optional>	true	set to false to enable Changes Api
`disableDeltaChangesApi`	boolean	<optional>	true	set to false to enable Delta Changes API (requires Changes API, forces cloning)
`autoupdate`	boolean	<optional>	false	use Object.observe to update objects automatically
`clone`	boolean	<optional>	false	specify whether inserts and queries clone to/from user
`cloneMethod`	string	<optional>	'parse-stringify'	'parse-stringify', 'jquery-extend-deep', 'shallow, 'shallow-assign'
`ttl`	int	<optional>		age of document (in ms.) before document is considered aged/stale.
`ttlInterval`	int	<optional>		time interval for clearing out 'aged' documents; not set by default.

Source:

lokijs.js, line 1047

Returns:

a reference to the collection which was just added

Type: Collection

clearChanges()

(Changes API) : clears all the changes in all collections.

Source:

lokijs.js, line 1786

close(callbackopt)

Emits the close event. In autosave scenarios, if the database is dirty, this will save and disable timer. Does not actually destroy the db.

Parameters:

Name	Type	Attributes	Description
`callback`	function	<optional>	(Optional) if supplied will be registered with close event before emitting.

Source:

lokijs.js, line 1722

configureOptions(options, initialConfig)

Allows reconfiguring database options

Parameters:

Name Type Description

options

object

configuration options to apply to loki db object

Properties

Name	Type	Description
`env`	string	override environment detection as 'NODEJS', 'BROWSER', 'CORDOVA'
`verbose`	boolean	enable console output (default is 'false')
`autosave`	boolean	enables autosave
`autosaveInterval`	int	time interval (in milliseconds) between saves (if dirty)
`autoload`	boolean	enables autoload on loki instantiation
`autoloadCallback`	function	user callback called after database load
`adapter`	adapter	an instance of a loki persistence adapter
`serializationMethod`	string	['normal', 'pretty', 'destructured']
`destructureDelimiter`	string	string delimiter used for destructured serialization

initialConfig

boolean

(internal) true is passed when loki ctor is invoking

Source:

lokijs.js, line 905

copy(options)

Copies 'this' database into a new Loki instance. Object references are shared to make lightweight.

Parameters:

Name Type Description

options

object

apply or override collection level settings

Properties

Name	Type	Description
`removeNonSerializable`	bool	nulls properties not safe for serialization.

Source:

lokijs.js, line 1003

deleteDatabase(callbackopt)

Handles deleting a database from file system, local storage, or adapter (indexeddb) This method utilizes loki configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided).

Parameters:

Name	Type	Attributes	Description
`callback`	function	<optional>	(Optional) user supplied async callback / error handler

Source:

lokijs.js, line 2670

deserializeCollection(destructuredSource, optionsopt) → {array}

Collection level utility function to deserializes a destructured collection.

Parameters:

Name Type Attributes Description

destructuredSource

string | array

destructured representation of collection to inflate

options

object

used to describe format of destructuredSource input

Properties

Name	Type	Attributes	Default	Description
`delimited`	int	<optional>	false	whether source is delimited string or an array
`delimiter`	string	<optional>		if delimited, this is delimiter to use (if other than default)

Source:

lokijs.js, line 1520

Returns:

an array of documents to attach to collection.data.

Type: array

deserializeDestructured(destructuredSource, optionsopt) → {object|array}

Database level destructured JSON deserialization routine to minimize memory overhead. Internally, Loki supports destructuring via loki "serializationMethod' option and the optional LokiPartitioningAdapter class. It is also available if you wish to do your own structured persistence or data exchange.

Parameters:

Name Type Attributes Description

destructuredSource

string | array

destructured json or array to deserialize from

options

object

source format options

Properties

Name	Type	Attributes	Default	Description
`partitioned`	bool	<optional>	false	whether db and each collection are separate
`partition`	int	<optional>		can be used to deserialize only a single partition
`delimited`	bool	<optional>	true	whether subitems are delimited or subarrays
`delimiter`	string	<optional>		override default delimiter

Source:

lokijs.js, line 1414

Returns:

An object representation of the deserialized database, not yet applied to 'this' db or document array

Type: object | array

generateChangesNotification(optionalopt) → {array}

(Changes API) : takes all the changes stored in each collection and creates a single array for the entire database. If an array of names of collections is passed then only the included collections will be tracked.

Parameters:

Name	Type	Attributes	Description
`optional`	array	<optional>	array of collection names. No arg means all collections are processed.

Source:

lokijs.js, line 1758

See:

private method createChange() in Collection

Returns:

array of changes

Type: array

getCollection(collectionName) → {Collection}

Retrieves reference to a collection by name.

Parameters:

Name	Type	Description
`collectionName`	string	name of collection to look up

Source:

lokijs.js, line 1091

Returns:

Reference to collection in database by that name, or null if not found

Type: Collection

listCollections() → {Array.<object>}

Returns a list of collections in the database.

Source:

lokijs.js, line 1128

Returns:

array of objects containing 'name', 'type', and 'count' properties.

Type: Array.<object>

loadDatabase(options, callbackopt)

Handles manually loading from file system, local storage, or adapter (such as indexeddb) This method utilizes loki configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided). To avoid contention with any throttledSaves, we will drain the save queue first.

If you are configured with autosave, you do not need to call this method yourself.

Parameters:

Name Type Attributes Description

options

object

if throttling saves and loads, this controls how we drain save queue before loading

Properties

Name	Type	Description
`recursiveWait`	boolean	(default: true) wait recursively until no saves are queued
`recursiveWaitLimit`	bool	(default: false) limit our recursive waiting to a duration
`recursiveWaitLimitDelay`	int	(default: 2000) cutoff in ms to stop recursively re-draining

callback

function

(Optional) user supplied async callback / error handler

Source:

lokijs.js, line 2529

Example

db.loadDatabase({}, function(err) {
  if (err) {
    console.log("error : " + err);
  }
  else {
    console.log("database loaded.");
  }
});

loadJSON(serializedDb, optionsopt)

Inflates a loki database from a serialized JSON string

Parameters:

Name Type Attributes Description

serializedDb

string

a serialized loki database string

options

object

apply or override collection level settings

Properties

Name	Type	Description
`retainDirtyFlags`	bool	whether collection dirty flags will be preserved

Source:

lokijs.js, line 1562

loadJSONObject(dbObject, optionsopt)

Inflates a loki database from a JS object

Parameters:

Name Type Attributes Description

dbObject

object

a serialized loki database string

options

object

apply or override collection level settings

Properties

Name	Type	Description
`retainDirtyFlags`	bool	whether collection dirty flags will be preserved

Source:

lokijs.js, line 1587

removeCollection(collectionName)

Removes a collection from the database.

Parameters:

Name	Type	Description
`collectionName`	string	name of collection to remove

Source:

lokijs.js, line 1148

renameCollection(oldName, newName) → {Collection}

Renames an existing loki collection

Parameters:

Name	Type	Description
`oldName`	string	name of collection to rename
`newName`	string	new name of collection

Source:

lokijs.js, line 1113

Returns:

reference to the newly renamed collection

Type: Collection

saveDatabase(callbackopt)

Handles manually saving to file system, local storage, or adapter (such as indexeddb) This method utilizes loki configuration options (if provided) to determine which persistence method to use, or environment detection (if configuration was not provided).

If you are configured with autosave, you do not need to call this method yourself.

Parameters:

Name	Type	Attributes	Description
`callback`	function	<optional>	(Optional) user supplied async callback / error handler

Source:

lokijs.js, line 2623

Example

db.saveDatabase(function(err) {
  if (err) {
    console.log("error : " + err);
  }
  else {
    console.log("database saved.");
  }
});

serialize() → {string}

Serialize database to a string which can be loaded via Loki#loadJSON

Source:

lokijs.js, line 1196

Returns:

Stringified representation of the loki database.

Type: string

serializeChanges() → {string}

(Changes API) - stringify changes for network transmission

Source:

lokijs.js, line 1778

Returns:

string representation of the changes

Type: string

serializeCollection(optionsopt) → {string|array}

Collection level utility method to serialize a collection in a 'destructured' format

Parameters:

Name Type Attributes Description

options

object

used to determine output of method

Properties

Name	Type	Description
`delimited`	int	whether to return single delimited string or an array
`delimiter`	string	(optional) if delimited, this is delimiter to use
`collectionIndex`	int	specify which collection to serialize data for

Source:

lokijs.js, line 1362

Returns:

A custom, restructured aggregation of independent serializations for a single collection.

Type: string | array

serializeDestructured(optionsopt) → {string|array}

Database level destructured JSON serialization routine to allow alternate serialization methods. Internally, Loki supports destructuring via loki "serializationMethod' option and the optional LokiPartitioningAdapter class. It is also available if you wish to do your own structured persistence or data exchange.

Parameters:

Name Type Attributes Description

options

object

output format options for use externally to loki

Properties

Name	Type	Attributes	Description
`partitioned`	bool	<optional>	(default: false) whether db and each collection are separate
`partition`	int	<optional>	can be used to only output an individual collection or db (-1)
`delimited`	bool	<optional>	(default: true) whether subitems are delimited or subarrays
`delimiter`	string	<optional>	override default delimiter

Source:

lokijs.js, line 1229

Returns:

A custom, restructured aggregation of independent serializations.

Type: string | array

throttledSaveDrain(callback, optionsopt)

Wait for throttledSaves to complete and invoke your callback when drained or duration is met.

Parameters:

Name Type Attributes Description

callback

function

callback to fire when save queue is drained, it is passed a sucess parameter value

options

object

configuration options

Properties

Name	Type	Description
`recursiveWait`	boolean	(default: true) if after queue is drained, another save was kicked off, wait for it
`recursiveWaitLimit`	bool	(default: false) limit our recursive waiting to a duration
`recursiveWaitLimitDelay`	int	(default: 2000) cutoff in ms to stop recursively re-draining

Source:

lokijs.js, line 2386