Class: ControlDB

ControlDB(filename, optionsopt)

new ControlDB(filename, optionsopt)

ControlDB: The main database class

Parameters:
Name Type Attributes Description
filename string

name of the file to be saved to
options object <optional>

(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 control instantiation
autoloadCallback function

user callback called after database load
adapter adapter

an instance of a control 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:
Source:

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>

(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:
Returns:

a reference to the collection which was just added

Type
Collection

clearChanges()

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

Source:

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:

configureOptions(options, initialConfig)

Allows reconfiguring database options

Parameters:
Name Type Description
options object

configuration options to apply to control 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 control instantiation
autoloadCallback function

user callback called after database load
adapter adapter

an instance of a control persistence adapter
serializationMethod string

['normal', 'pretty', 'destructured']
destructureDelimiter string

string delimiter used for destructured serialization
initialConfig boolean

(internal) true is passed when control ctor is invoking
Source:

copy(options)

Copies 'this' database into a new ControlDB 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:

deleteDatabase(callbackopt)

Handles deleting a database from file system, local storage, or adapter (indexeddb) This method utilizes control 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:

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 <optional>

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:
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, ControlDB supports destructuring via control "serializationMethod' option and the optional ControlDBPartitioningAdapter 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 <optional>

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:
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:
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:
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:
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 control 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>

(Optional) user supplied async callback / error handler
Source:
Example
db.loadDatabase({}, function(err) {
  if (err) {
    console.log("error : " + err);
  }
  else {
    console.log("database loaded.");
  }
});

loadJSON(serializedDb, optionsopt)

Inflates a control database from a serialized JSON string

Parameters:
Name Type Attributes Description
serializedDb string

a serialized control database string
options object <optional>

apply or override collection level settings

Properties
Name Type Description
retainDirtyFlags bool

whether collection dirty flags will be preserved
Source:

loadJSONObject(dbObject, optionsopt)

Inflates a control database from a JS object

Parameters:
Name Type Attributes Description
dbObject object

a serialized control database string
options object <optional>

apply or override collection level settings

Properties
Name Type Description
retainDirtyFlags bool

whether collection dirty flags will be preserved
Source:

removeCollection(collectionName)

Removes a collection from the database.

Parameters:
Name Type Description
collectionName string

name of collection to remove
Source:

renameCollection(oldName, newName) → {Collection}

Renames an existing control collection

Parameters:
Name Type Description
oldName string

name of collection to rename
newName string

new name of collection
Source:
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 control 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:
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 ControlDB#loadJSON

Source:
Returns:

Stringified representation of the control database.

Type
string

serializeChanges() → {string}

(Changes API) - stringify changes for network transmission

Source:
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 <optional>

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:
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, ControlDB supports destructuring via control "serializationMethod' option and the optional ControlDBPartitioningAdapter class. It is also available if you wish to do your own structured persistence or data exchange.

Parameters:
Name Type Attributes Description
options object <optional>

output format options for use externally to control

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:
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 <optional>

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: