Class: Collection

Collection

new Collection()

Creates a new collection. Collections store multiple documents and handle CRUD against those documents.
Source:

Methods

(static) collateAdd(collection, keyNameopt)

Adds a data source to collate data from and specifies the key name to collate data to.
Parameters:
Name Type Attributes Description
collection Collection The collection to collate data from.
keyName String <optional>
 Optional name of the key to collate data to. If none is provided the record CRUD is operated on the root collection data.
Source:

(static) collateAdd(collection, process)

Adds a data source to collate data from and specifies a process method that will handle the collation functionality (for custom collation).
Parameters:
Name Type Description
collection Collection The collection to collate data from.
process function The process method.
Source:

(static) drop(removePersistent)

Drop collection and optionally drop persistent storage.
Parameters:
Name Type Description
removePersistent Boolean True to drop persistent storage, false to keep it.
Source:

(static) drop(removePersistent, callback)

Drop collections and optionally drop persistent storage with callback.
Parameters:
Name Type Description
removePersistent Boolean True to drop persistent storage, false to keep it.
callback function Callback method.
Source:

(static) drop(removePersistent)

Drop collection and optionally drop persistent storage.
Parameters:
Name Type Description
removePersistent Boolean True to drop persistent storage, false to keep it.
Source:

(static) drop(callback)

Drop collection and persistent storage with callback.
Parameters:
Name Type Description
callback function Callback method.
Source:

(static) drop()

Drop collection and persistent storage.
Source:

(static) drop()

Drop collection and persistent storage.
Source:

(static) drop(callback)

Drop collection and persistent storage with callback.
Parameters:
Name Type Description
callback function Callback method.
Source:

(static) drop(removePersistent, callback)

Drop collections and optionally drop persistent storage with callback.
Parameters:
Name Type Description
removePersistent Boolean True to drop persistent storage, false to keep it.
callback function Callback method.
Source:

(static) grid(selector, template, optionsopt) → {*}

Creates a grid and assigns the collection as its data source.
Parameters:
Name Type Attributes Description
selector String jQuery selector of grid output target.
template String The table template to use when rendering the grid.
options Object <optional>
 The options object to apply to the grid.
Source:
Returns:
Type
*

(static) isLinked() → {Boolean}

Checks if the instance is data-bound to any DOM elements.
Source:
Returns:
True if linked, false if not.
Type
Boolean
Creates a link to the DOM between the collection data and the elements in the passed output selector. When new elements are needed or changes occur the passed templateSelector is used to get the template that is output to the DOM.
Parameters:
Name Type Attributes Description
outputTargetSelector
templateSelector
options Object <optional>
 Optional extra options.
Source:
See:
  • unlink
Creates a link to the DOM between the collection data and the elements in the passed output selector. When new elements are needed or changes occur the passed templateSelector is used to get the template that is output to the DOM.
Parameters:
Name Type Attributes Description
scope
varName
options Object <optional>
 Optional extra options.
beforeAngularToForerunner function <optional>
 Provides an optional function that allows you to modify data before angularJS updates ForerunnerDB with data from a view that has changed (like when a user edits a form element value that has been data-bound via ng-model).
Source:
See:
  • unlink
Creates a link to the DOM between the collection data and the elements in the passed output selector. When new elements are needed or changes occur the passed templateSelector is used to get the template that is output to the DOM.
Parameters:
Name Type Attributes Description
scope
varName
options Object <optional>
 Optional extra options.
Source:
See:
  • unlink

(static) setData(data, options)

Sets the collection's data to the array / documents passed. If any data already exists in the collection it will be removed before the new data is set via the remove() method, and the remove event will fire as well.
Parameters:
Name Type Description
data Array | Object The array of documents or a single document that will be set as the collections data.
options Object Optional options object.
Source:

(static) setData(data)

Sets the collection's data to the array / documents passed. If any data already exists in the collection it will be removed before the new data is set via the remove() method, and the remove event will fire as well.
Parameters:
Name Type Description
data Array | Object The array of documents or a single document that will be set as the collections data.
Source:

(static) setData(data, options, callback)

Sets the collection's data to the array / documents passed. If any data already exists in the collection it will be removed before the new data is set via the remove() method, and the remove event will fire as well.
Parameters:
Name Type Description
data Array | Object The array of documents or a single document that will be set as the collections data.
options * Optional options object.
callback * Optional callback function.
Source:

(static) setData(data, options, callback)

Sets the collection's data to the array / documents passed. If any data already exists in the collection it will be removed before the new data is set via the remove() method, and the remove event will fire as well.
Parameters:
Name Type Description
data Array | Object The array of documents or a single document that will be set as the collections data.
options * Optional options object.
callback function Optional callback function.
Source:

(static) setData(data, callback)

Sets the collection's data to the array / documents passed. If any data already exists in the collection it will be removed before the new data is set via the remove() method, and the remove event will fire as well.
Parameters:
Name Type Description
data Array | Object The array of documents or a single document that will be set as the collections data.
callback function Optional callback function.
Source:

(static) setData(data, options, callback)

Sets the collection's data to the array / documents passed. If any data already exists in the collection it will be removed before the new data is set via the remove() method, and the remove event will fire as well.
Parameters:
Name Type Description
data Array | Object The array of documents or a single document that will be set as the collections data.
options Object Optional options object.
callback function Optional callback function.
Source:

(static) sync(objectType, objectName, query, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
objectType String The type of object to sync to e.g. "collection" or "view".
objectName String The name of the object to sync from.
query Object A query object.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(query, options, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
query Object A query object.
options Object An options object.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(collectionName, query, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
collectionName String The collection to sync from.
query Object A query object.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(objectType, objectName, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
objectType String The type of object to sync to e.g. "collection" or "view".
objectName String The name of the object to sync from.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(query, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
query Object A query object.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(objectType, objectName, query, options, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
objectType String The type of object to sync to e.g. "collection" or "view".
objectName String The name of the object to sync from.
query Object A query object.
options Object An options object.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(collectionName, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
collectionName String The collection to sync from.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(collectionName, query, options, callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
collectionName String The collection to sync from.
query Object A query object.
options Object An options object.
callback function The callback method to call once the connection to the server has been established.
Source:

(static) sync(callback)

Sync with this collection on the server-side.
Parameters:
Name Type Description
callback function The callback method to call once the connection to the server has been established.
Source:

(static) unGrid(selector, template, optionsopt) → {*}

Removes a grid safely from the DOM. Must be called when grid is no longer required / is being removed from DOM otherwise references will stick around and cause memory leaks.
Parameters:
Name Type Attributes Description
selector String jQuery selector of grid output target.
template String The table template to use when rendering the grid.
options Object <optional>
 The options object to apply to the grid.
Source:
Returns:
Type
*
Removes a link to the DOM between the collection data and the elements in the passed output selector that was created using the link() method.
Parameters:
Name Type Description
outputTargetSelector
templateSelector
Source:

_insertHandle(data, indexopt, callbackopt)

Inserts a document or array of documents into the collection.
Parameters:
Name Type Attributes Description
data Object | Array Either a document object or array of document
index Number <optional>
 Optional index to insert the record at.
callback Collection.insertCallback <optional>
 Optional callback called once the insert is complete.
Source:

count() → {Number}

Returns the number of documents currently in the collection.
Source:
Returns:
Type
Number

data() → {Array}

Get the data array that represents the collection's data. This data is returned by reference and should not be altered outside of the provided CRUD functionality of the collection as doing so may cause unstable index behaviour within the collection.
Source:
Returns:
Type
Array

diff(collection) → {Object}

Generates a difference object that contains insert, update and remove arrays representing the operations to execute to make this collection have the same data as the one passed.
Parameters:
Name Type Description
collection Collection The collection to diff against.
Source:
Returns:
Type
Object

distinct(path, queryopt, optionsopt) → {Array}

Find the distinct values for a specified field across a single collection and returns the values as a results array.
Parameters:
Name Type Attributes Description
path String The field path to return distinct values for e.g. "person.name".
query Object <optional>
 The query to use to filter the documents used to return values from.
options Object <optional>
 The query options to use when running the query.
Source:
Returns:
Type
Array

drop(callbackopt) → {boolean}

Drops a collection and all it's stored data from the database.
Parameters:
Name Type Attributes Description
callback function <optional>
 A callback method to call once the operation has completed.
Source:
Returns:
True on success, false on failure.
Type
boolean

dropChart(selector)

Removes a chart from the page by it's selector.
Parameters:
Name Type Description
selector String The chart selector.
Source:

ensureIndex(keys, options) → {*}

Creates an index on the specified keys.
Parameters:
Name Type Description
keys Object The object containing keys to index.
options Object An options object.
Source:
Returns:
Type
*

explain(query, optionsopt) → {Object}

Provides a query plan / operations log for a query.
Parameters:
Name Type Attributes Description
query Object The query to execute.
options Object <optional>
 Optional options object.
Source:
Returns:
The query plan.
Type
Object

filter(queryopt, optionsopt, func) → {Array}

Executes a method against each document that matches query and returns an array of documents that may have been modified by the method.
Parameters:
Name Type Attributes Description
query Object <optional>
 The optional query object.
options Object <optional>
 Optional options object. If you specify an options object you MUST also specify a query object.
func function The method that each document is passed to. If this method returns false for a particular document it is excluded from the results. If you return a modified object from the one passed to it will be included in the results as the modified version but will not affect the data in the collection at all. Your function will be called with a single object as the first argument and will be called once for every document in your initial query result.
Source:
Returns:
Type
Array

filterUpdate(query, func, optionsopt) → {Array}

Executes a method against each document that matches query and then executes an update based on the return data of the method.
Parameters:
Name Type Attributes Description
query Object The query object.
func function The method that each document is passed to. If this method returns false for a particular document it is excluded from the update.
options Object <optional>
 Optional options object passed to the initial find call.
Source:
Returns:
Type
Array

find(query, optionsopt, callbackopt) → {Array}

Queries the collection based on the query object passed.
Parameters:
Name Type Attributes Description
query Object The query key/values that a document must match in order for it to be returned in the result array.
options Object <optional>
 An optional options object.
callback function <optional>
 !! DO NOT USE, THIS IS NON-OPERATIONAL !! Optional callback. If specified the find process will not return a value and will assume that you wish to operate under an async mode. This will break up large find requests into smaller chunks and process them in a non-blocking fashion allowing large datasets to be queried without causing the browser UI to pause. Results from this type of operation will be passed back to the callback once completed.
Source:
Returns:
The results array from the find operation, containing all documents that matched the query.
Type
Array

findById(id, optionsopt) → {Array}

Helper method to find a document by it's id.
Parameters:
Name Type Attributes Description
id String The id of the document.
options Object <optional>
 The options object, allowed keys are sort and limit.
Source:
Returns:
The items that were updated.
Type
Array

findOne() → {*}

Returns one document that satisfies the specified query criteria. If multiple documents satisfy the query, this method returns the first document to match the query.
Source:
Returns:
Type
*

findSub(match, path, subDocQueryopt, subDocOptionsopt) → {*}

Finds sub-documents from the collection's documents.
Parameters:
Name Type Attributes Description
match Object The query object to use when matching parent documents from which the sub-documents are queried.
path String The path string used to identify the key in which sub-documents are stored in parent documents.
subDocQuery Object <optional>
 The query to use when matching which sub-documents to return.
subDocOptions Object <optional>
 The options object to use when querying for sub-documents.
Source:
Returns:
Type
*

findSubOne(match, path, subDocQueryopt, subDocOptionsopt) → {Object}

Finds the first sub-document from the collection's documents that matches the subDocQuery parameter.
Parameters:
Name Type Attributes Description
match Object The query object to use when matching parent documents from which the sub-documents are queried.
path String The path string used to identify the key in which sub-documents are stored in parent documents.
subDocQuery Object <optional>
 The query to use when matching which sub-documents to return.
subDocOptions Object <optional>
 The options object to use when querying for sub-documents.
Source:
Returns:
Type
Object

group(groupObj, arr) → {Object}

Groups an array of documents into multiple array fields, named by the value of the given group path.
Parameters:
Name Type Description
groupObj * The key path the array objects should be grouped by.
arr Array The array of documents to group.
Source:
Returns:
Type
Object

index(name) → {*}

Gets an index by it's name.
Parameters:
Name Type Description
name String The name of the index to retreive.
Source:
Returns:
Type
*

indexOf(query, optionsopt) → {Number}

Gets the index in the collection data array of the first item matched by the passed query object.
Parameters:
Name Type Attributes Description
query Object The query to run to find the item to return the index of.
options Object <optional>
 An options object.
Source:
Returns:
Type
Number

indexOfDocById(itemLookup, optionsopt) → {Number}

Returns the index of the document identified by the passed item's primary key.
Parameters:
Name Type Attributes Description
itemLookup * The document whose primary key should be used to lookup or the id to lookup.
options Object <optional>
 An options object.
Source:
Returns:
The index the item with the matching primary key is occupying.
Type
Number

init()

Creates a new collection. Collections store multiple documents and handle CRUD against those documents.
Source:

insert(data, indexopt, callbackopt)

Inserts a document or array of documents into the collection.
Parameters:
Name Type Attributes Description
data Object | Array Either a document object or array of document
index Number <optional>
 Optional index to insert the record at.
callback Collection.insertCallback <optional>
 Optional callback called once the insert is complete.
Source:

insertIndexViolation(doc) → {Boolean}

Checks that the passed document will not violate any index rules if inserted into the collection.
Parameters:
Name Type Description
doc Object The document to check indexes against.
Source:
Returns:
Either false (no violation occurred) or true if a violation was detected.
Type
Boolean

isProcessingQueue() → {Boolean}

Checks if any CRUD operations have been deferred and are still waiting to be processed.
Source:
Returns:
True if there are still deferred CRUD operations to process or false if all queues are clear.
Type
Boolean

isSubsetOf(collection) → {Boolean}

Checks if the collection is a subset of the passed collection.
Parameters:
Name Type Description
collection Collection The collection to test against.
Source:
Returns:
True if the passed collection is the parent of the current collection.
Type
Boolean

lastOp() → {Object}

Gets the last reporting operation's details such as run time.
Source:
Returns:
Type
Object

load(callbackopt)

Loads an entire collection's data from persistent storage.
Parameters:
Name Type Attributes Description
callback function <optional>
 The method to call when the load function has completed.
Source:

load(callbackopt)

Loads an entire collection's data from persistent storage.
Parameters:
Name Type Attributes Description
callback function <optional>
 The method to call when the load function has completed.
Source:

loadCustom(myData, callback)

Loads custom data loaded by a third-party plugin into the collection.
Parameters:
Name Type Description
myData Object Data object previously saved by using saveCustom()
callback function A callback method to receive notification when data has loaded.
Source:

odm() → {Odm}

Get the ODM instance for this collection.
Source:
Returns:
Type
Odm

options(objopt) → {Object}

Generates an options object with default values or adds default values to a passed object if those values are not currently set to anything.
Parameters:
Name Type Attributes Description
obj Object <optional>
 Optional options object to modify.
Source:
Returns:
The options object.
Type
Object

peek(search, optionsopt) → {Array}

Finds all documents that contain the passed string or search object regardless of where the string might occur within the document. This will match strings from the start, middle or end of the document's string (partial match).
Parameters:
Name Type Attributes Description
search String The string to search for. Case sensitive.
options Object <optional>
 A standard find() options object.
Source:
Returns:
An array of documents that matched the search string.
Type
Array

persistedSize(callback)

Determines the byte size of a persisted collection
Parameters:
Name Type Description
callback persistedSizeCallback The method to call when the size check is complete
Source:

primaryKey(keyNameopt) → {*}

Gets / sets the primary key for this collection.
Parameters:
Name Type Attributes Description
keyName String <optional>
 The name of the primary key.
Source:
Returns:
Type
*

processQueue(type, callback, resultObjopt)

Processes a deferred action queue.
Parameters:
Name Type Attributes Description
type String The queue name to process.
callback function A method to call when the queue has processed.
resultObj Object <optional>
 A temp object to hold results in.
Source:

remove(queryopt, optionsopt, callbackopt) → {Array}

Removes any documents from the collection that match the search query key/values.
Parameters:
Name Type Attributes Description
query Object <optional>
 The query identifying the documents to remove. If no query object is passed, all documents will be removed from the collection.
options Object <optional>
 An options object.
callback function <optional>
 A callback method.
Source:
Returns:
An array of the documents that were removed.
Type
Array

removeById(id) → {Object}

Helper method that removes a document that matches the given id.
Parameters:
Name Type Description
id String The id of the document to remove.
Source:
Returns:
The document that was removed or undefined if nothing was removed.
Type
Object

removeByIndex(index) → {Object}

Removes a document from the collection by it's index in the collection's data array.
Parameters:
Name Type Description
index Number The index of the document to remove.
Source:
Returns:
The document that has been removed or false if none was removed.
Type
Object

save(callbackopt)

Saves an entire collection's data to persistent storage.
Parameters:
Name Type Attributes Description
callback function <optional>
 The method to call when the save function has completed.
Source:

save(callbackopt)

Saves an entire collection's data to persistent storage.
Parameters:
Name Type Attributes Description
callback function <optional>
 The method to call when the save function has completed.
Source:

saveCustom(callback)

Gets the data that represents this collection for easy storage using a third-party method / plugin instead of using the standard persistent storage system.
Parameters:
Name Type Description
callback function The method to call with the data response.
Source:

sort(sortObj, arr) → {Array}

Sorts an array of documents by the given sort path.
Parameters:
Name Type Description
sortObj * The keys and orders the array objects should be sorted by.
arr Array The array of documents to sort.
Source:
Returns:
Type
Array

subset(query, optionsopt) → {*}

Uses the passed query to generate a new collection with results matching the query parameters.
Parameters:
Name Type Attributes Description
query Object The query object to generate the subset with.
options Object <optional>
 An options object.
Source:
Returns:
Type
*

transform(obj) → {*}

Gets / sets the collection transform options.
Parameters:
Name Type Description
obj Object A collection transform options object.
Source:
Returns:
Type
*

transformIn(data) → {*}

Transforms data using the set transformIn method.
Parameters:
Name Type Description
data Object The data to transform.
Source:
Returns:
Type
*

transformOut(data) → {*}

Transforms data using the set transformOut method.
Parameters:
Name Type Description
data Object The data to transform.
Source:
Returns:
Type
*

truncate() → {Collection}

Clears all data from the collection.
Source:
Returns:
Type
Collection

unSync() → {boolean}

Disconnects an existing connection to a sync server.
Source:
Returns:
True if a connection existed, false if no connection existed.
Type
boolean

update(query, update, optionsopt, callbackopt) → {Array}

Modifies an existing document or documents in a collection. This will update all matches for 'query' with the data held in 'update'. It will not overwrite the matched documents with the update document.
Parameters:
Name Type Attributes Description
query Object The query that must be matched for a document to be operated on.
update Object The object containing updated key/values. Any keys that match keys on the existing document will be overwritten with this data. Any keys that do not currently exist on the document will be added to the document.
options Object <optional>
 An options object.
callback function <optional>
 The callback method to call when the update is complete.
Source:
Returns:
The items that were updated.
Type
Array

updateById(id, update, optionsopt, callbackopt) → {Object}

Helper method to update a document via it's id.
Parameters:
Name Type Attributes Description
id String The id of the document.
update Object The object containing the key/values to update to.
options Object <optional>
 An options object.
callback function <optional>
 The callback method to call when the update is complete.
Source:
Returns:
The document that was updated or undefined if no document was updated.
Type
Object

upsert(obj, callbackopt) → {Array}

Inserts a new document or updates an existing document in a collection depending on if a matching primary key exists in the collection already or not. If the document contains a primary key field (based on the collections's primary key) then the database will search for an existing document with a matching id. If a matching document is found, the document will be updated. Any keys that match keys on the existing document will be overwritten with new data. Any keys that do not currently exist on the document will be added to the document. If the document does not contain an id or the id passed does not match an existing document, an insert is performed instead. If no id is present a new primary key id is provided for the document and the document is inserted.
Parameters:
Name Type Attributes Description
obj Object The document object to upsert or an array containing documents to upsert.
callback function <optional>
 Optional callback method.
Source:
Returns:
An array containing an object for each operation performed. Each object contains two keys, "op" contains either "none", "insert" or "update" depending on the type of operation that was performed and "result" contains the return data from the operation used.
Type
Array

view(name, query, options) → {*}

Creates a view and assigns the collection as its data source.
Parameters:
Name Type Description
name String The name of the new view.
query Object The query to apply to the new view.
options Object The options object to apply to the view.
Source:
Returns:
Type
*

when(query) → {Condition}

Creates a condition handler that will react to changes in data on the collection.
Parameters:
Name Type Description
query Object The query that will trigger the condition's then() callback.
Source:
See:
Returns:
Type
Condition
Example
Create a condition handler that reacts when data changes.
	var coll = db.collection('test'),
		condition = coll.when({_id: 'test1', val: 1})
		.then(function () {
			console.log('Condition met!');
	 	})
	 	.else(function () {
	 		console.log('Condition un-met');
	 	});

	 	coll.insert({_id: 'test1', val: 1});

Members

areaChart :Overload

Creates an area chart from the collection.
Type:
Source:

barChart :Overload

Creates a bar chart from the collection.
Type:
Source:

columnChart :Overload

Creates a column chart from the collection.
Type:
Source:

lineChart :Overload

Creates a line chart from the collection.
Type:
Source:

pieChart :Overload

Creates a pie chart from the collection.
Type:
Source:

stackedBarChart :Overload

Creates a stacked bar chart from the collection.
Type:
Source:

Type Definitions

insertCallback(result)

The insert operation's callback.
Parameters:
Name Type Description
result Object The result object will contain two arrays (inserted and failed) which represent the documents that did get inserted and those that didn't for some reason (usually index violation). Failed items also contain a reason. Inspect the failed array for further information. A third field called "deferred" is a boolean value to indicate if the insert operation was deferred across more than one CPU cycle (to avoid blocking the main thread).
Source: