# Class: Collection

## Collection

#### new Collection()

Collection object used to store data.

Source:
  - Collection.js, line 25

### Members

#### crc

Returns a checksum of a string.

Source:
  - Collection.js, line 89

### Methods

#### _insertHandle(data, indexopt, callbackopt)

Inserts a document or array of documents into the collection.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`data` |  |  |
`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:
  - Collection.js, line 1321

#### 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:
  - Collection.js, line 2336

##### Returns:

Type
  Object

#### count() → {Number}

Returns the number of documents currently in the collection.

Source:
  - Collection.js, line 2535

##### Returns:

Type
  Number

#### data() → {Array}

Get the internal data

Source:
  - Collection.js, line 109

##### 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:
  - Collection.js, line 2738

##### 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:
  - Collection.js, line 1617

##### Returns:

Type
  Array

#### drop() → {boolean}

Drops a collection and all it's stored data from the database.

Source:
  - Collection.js, line 117

##### Returns:

True on success, false on failure.

Type
  boolean

#### 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:
  - Collection.js, line 2639

##### 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:
  - Collection.js, line 1696

##### 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:
  - Collection.js, line 488

##### 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:
  - Collection.js, line 501

##### Returns:

Type
  Array

#### find(query, optionsopt) → {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.

Source:
  - Collection.js, line 1725

##### 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:
  - Collection.js, line 1648

##### 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:
  - Collection.js, line 2127

##### Returns:

Type
  *

#### findSub(match, path, subDocQuery, subDocOptions) → {*}

Finds sub-documents from the collection's documents.

##### Parameters:

Name | Type | Description
--- | --- | ---
`match` |  |
`path` |  |
`subDocQuery` |  |
`subDocOptions` |  |

Source:
  - Collection.js, line 2552

##### 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:
  - Collection.js, line 2717

##### Returns:

Type
  *

#### indexOf(query) → {Number}

Gets the index in the collection data array of the first item matched by the passed query object.

##### Parameters:

Name | Type | Description
--- | --- | ---
`query` | Object | The query to run to find the item to return the index of.

Source:
  - Collection.js, line 2137

##### Returns:

Type
  Number

#### indexOfDocById(item) → {Number}

Returns the index of the document identified by the passed item's primary key.

##### Parameters:

Name | Type | Description
--- | --- | ---
`item` | Object | The item whose primary key should be used to lookup.

Source:
  - Collection.js, line 1565

##### 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` |  |  |
`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:
  - Collection.js, line 1298

#### 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:
  - Collection.js, line 2605

##### Returns:

Either false (no violation occurred) or true if a violation was detected.

Type
  Boolean

#### lastOp() → {Object}

Gets the last reporting operation's details such as run time.

Source:
  - Collection.js, line 2727

##### Returns:

Type
  Object

#### 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:
  - Collection.js, line 1708

##### 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:
  - Collection.js, line 1663

##### 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:
  - Collection.js, line 168

##### Returns:

Type
  *

#### processQueue(type, callback)

Processes a deferred action queue.

##### Parameters:

Name | Type | Description
--- | --- | ---
`type` | String | The queue name to process.
`callback` | function | A method to call when the queue has processed.

Source:
  - Collection.js, line 1260

#### 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:
  - Collection.js, line 1132

##### 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:
  - Collection.js, line 1220

##### Returns:

An array of documents that were removed.

Type
  Array

#### setData(data, options, callback)

Sets the collection's data to the array of documents passed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`data` |  |
`options` |  | Optional options object.
`callback` |  | Optional callback function.

Source:
  - Collection.js, line 235

#### 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:
  - Collection.js, line 2230

##### Returns:

Type
  Array

#### subset(query, options) → {*}

Uses the passed query to generate a new collection with results matching the query parameters.

##### Parameters:

Name | Type | Description
--- | --- | ---
`query` |  |
`options` |  |

Source:
  - Collection.js, line 1581

##### Returns:

Type
  *

#### subsetOf() → {Collection}

Gets the collection that this collection is a subset of.

Source:
  - Collection.js, line 1594

##### Returns:

Type
  Collection

#### transform(obj) → {*}

Gets / sets the collection transform options.

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | A collection transform options object.

Source:
  - Collection.js, line 2150

##### Returns:

Type
  *

#### transformIn(data) → {*}

Transforms data using the set transformIn method.

##### Parameters:

Name | Type | Description
--- | --- | ---
`data` | Object | The data to transform.

Source:
  - Collection.js, line 2183

##### Returns:

Type
  *

#### transformOut(data) → {*}

Transforms data using the set transformOut method.

##### Parameters:

Name | Type | Description
--- | --- | ---
`data` | Object | The data to transform.

Source:
  - Collection.js, line 2206

##### Returns:

Type
  *

#### truncate() → {Collection}

Clears all data from the collection.

Source:
  - Collection.js, line 361

##### 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:
  - Collection.js, line 538

##### 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:
  - Collection.js, line 664

##### Returns:

The items that were updated.

Type
  Array

#### 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:
  - Collection.js, line 403

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