Class: Collection

Collection

new Collection()

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

Members

(private) _addView

Adds a view to the internal view lookup.
Source:

(private) _removeView

Removes a view from the internal view lookup.
Source:

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:

crc

Returns a checksum of a string.
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:

Methods

(private, static) _addGrid(grid) → {Collection}

Adds a grid to the internal grid lookup.
Parameters:
Name Type Description
grid Grid The grid to add.
Source:
Returns:
Type
Collection

(private, static) _removeGrid(grid) → {Collection}

Removes a grid from the internal grid lookup.
Parameters:
Name Type Description
grid Grid The grid to remove.
Source:
Returns:
Type
Collection

(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) 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
scope
varName
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
outputTargetSelector
templateSelector
options Object <optional>
 Optional extra options.
Source:
See:
  • unlink

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

(private) _addOldView(view) → {Collection}

Adds a view to the internal view lookup.
Parameters:
Name Type Description
view View The view to add.
Source:
Returns:
Type
Collection

(private) _analyseQuery(query, options, op) → {Object}

Internal method that takes a search query and options and returns an object containing details about the query which can be used to optimise the search.
Parameters:
Name Type Description
query
options
op
Source:
Returns:
Type
Object

(private) _bucketSort(keyArr, arr) → {*}

Takes array of sort paths and sorts them into buckets before returning final array fully sorted by multi-keys.
Parameters:
Name Type Description
keyArr
arr
Source:
Returns:
Type
*

(private) _dataInsertAtIndex(index, doc)

Inserts a document into the internal collection data array at Inserts a document into the internal collection data array at the specified index.
Parameters:
Name Type Description
index number The index to insert at.
doc object The document to insert.
Source:

(private) _dataRemoveAtIndex(index)

Removes a document from the internal collection data array at the specified index.
Parameters:
Name Type Description
index number The index to remove from.
Source:

(private) _dataReplace(data)

Replaces all data in the collection's internal data array with the passed array of data.
Parameters:
Name Type Description
data array The array of data to replace existing data with.
Source:

(private) _insert(doc, indexopt) → {Boolean|Object}

Internal method to insert a document into the collection. Will check for index violations before allowing the document to be inserted.
Parameters:
Name Type Attributes Description
doc Object The document to insert after passing index violation tests.
index Number <optional>
 Optional index to insert the document at.
Source:
Returns:
True on success, false if no document passed, or an object containing details about an index violation if one occurred.
Type
Boolean | Object

_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 function <optional>
 Optional callback called once action is complete. objects to insert into the collection.
Source:

(private) _insertIntoIndexes(doc)

Inserts a document into the collection indexes.
Parameters:
Name Type Description
doc Object The document to insert.
Source:

(private) _isPositionalKey(key) → {Boolean}

Determines if the passed key has an array positional mark (a dollar at the end of its name).
Parameters:
Name Type Description
key String The key to check.
Source:
Returns:
True if it is a positional or false if not.
Type
Boolean

(private) _onChange()

Handles any change to the collection.
Source:

(private) _onInsert(inserted, failed)

Handles insert events and routes changes to binds and views as required.
Parameters:
Name Type Description
inserted Array An array of inserted documents.
failed Array An array of documents that failed to insert.
Source:

(private) _onRemove(items)

Handles remove events and routes changes to binds and views as required.
Parameters:
Name Type Description
items Array An array of removed documents.
Source:

(private) _onUpdate(items)

Handles update events and routes changes to binds and views as required.
Parameters:
Name Type Description
items Array An array of updated documents.
Source:

(private) _queryReferencesCollection(query, collection, path) → {*}

Checks if the passed query references this collection.
Parameters:
Name Type Description
query
collection
path
Source:
Returns:
Type
*

(private) _rebuildIndexes()

Rebuild collection indexes.
Source:

(private) _removeFromIndexes(doc)

Removes a document from the collection indexes.
Parameters:
Name Type Description
doc Object The document to remove.
Source:

(private) _removeOldView(view) → {Collection}

Removes a view from the internal view lookup.
Parameters:
Name Type Description
view View The view to remove.
Source:
Returns:
Type
Collection

(private) _replaceObj(currentObj, newObj) → {*}

Replaces an existing object with data from the new object without breaking data references.
Parameters:
Name Type Description
currentObj Object The object to alter.
newObj Object The new object to overwrite the existing one with.
Source:
Returns:
Chain.
Type
*

(private) _sort(key, arr) → {Array|*}

Sorts array by individual sort path.
Parameters:
Name Type Description
key
arr
Source:
Returns:
Type
Array | *

(private) _updateIndexes(oldDoc, newDoc)

Updates collection index data for the passed document.
Parameters:
Name Type Description
oldDoc Object The old document as it was before the update.
newDoc Object The document as it now is after the update.
Source:

bucket(key, arr) → {Object}

Takes an array of objects and returns a new object with the array items split into buckets by the passed key.
Parameters:
Name Type Description
key String The key to split the array into buckets by.
arr Array An array of objects.
Source:
Returns:
Type
Object

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(key, queryopt, optionsopt) → {Array}

Find the distinct values for a specified field across a single collection and returns the results in an array.
Parameters:
Name Type Attributes Description
key 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() → {boolean}

Drops a collection and all it's stored data from the database.
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
*

(private) ensurePrimaryKey(obj)

Checks for a primary key on the document and assigns one if none currently exists.
Parameters:
Name Type Description
obj Object The object to check a primary key against.
Source:

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(query, func, optionsopt) → {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 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 results.
options Object <optional>
 Optional options object.
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
*

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

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 function <optional>
 Optional callback called once action is complete. objects to insert into the collection.
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:

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, options) → {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 Description
search The string to search for. Case sensitive.
options A standard find() options object.
Source:
Returns:
An array of documents that matched the search string.
Type
Array

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:

(private) rebuildPrimaryKeyIndex(optionsopt)

Drops and rebuilds the primary key index for all documents in the collection.
Parameters:
Name Type Attributes Description
options Object <optional>
 An optional options object.
Source:

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

Removes any documents from the collection that match the search query key/values.
Parameters:
Name Type Attributes Description
query Object The query object.
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) → {Array}

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:
An array of documents that were removed.
Type
Array

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:

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

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

update(query, update, optionsopt) → {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.
Source:
Returns:
The items that were updated.
Type
Array

updateById(id, update) → {Array}

Helper method to update a document from it's id.
Parameters:
Name Type Description
id String The id of the document.
update Object The object containing the key/values to update to.
Source:
Returns:
The items that were updated.
Type
Array

(private) updateObject(doc, update, query, options, path, opType) → {Boolean}

Internal method for document updating.
Parameters:
Name Type Description
doc Object The document to update.
update Object The object with key/value pairs to update the document with.
query Object The query object that we need to match to perform an update.
options Object An options object.
path String The current recursive path.
opType String The type of update operation to perform, if none is specified default is to set new data against matching fields.
Source:
Returns:
True if the document was updated with new / changed data or false if it was not updated because the data was the same.
Type
Boolean

upsert(obj, callbackopt) → {Object}

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
obj Object The document object to upsert or an array containing documents to upsert. 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 item.
callback function <optional>
 Optional callback method.
Source:
Returns:
An object containing two keys, "op" contains either "insert" or "update" depending on the type of operation that was performed and "result" contains the return data from the operation used.
Type
Object

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
*