EntreeJS Class: Cursor

new Cursor(provider, query, options)

Constructor for a cursor object that handles all the operations on query result using select. This cursor object is unidirectional and cannot traverse backwards. Clients should not be creating a cursor directly, but use select to acquire a cursor.

Options

skip {number}, The number of items to skip from the beginning of the matching result.
limit {number}, Limit the number of items to return.
sort {object}, Controls the order that the query returns matching items.
map {object}, Specifies which fields from the item should be returned.

Parameters:

Name	Type	Argument	Description
`provider`	object		the provider that created this cursor.
`query`	object		an object containing the conditions for an item to be included in the result set.
`options`	object	<optional>	additional options for the cursor.

Source:

cursor.js, line 75

Members

<static> CLOSED

Cursor closed

Source:

cursor.js, line 582

<static> INIT

Init state

Source:

cursor.js, line 568

<static> OPEN

Cursor open

Source:

cursor.js, line 575

Methods

count(callback) → {null}

Counts the number of items matching the select query.

Parameters:

Name	Type	Description
`callback`	function	Will be called after executing this method. The first parameter will contain an error object on error while the second parameter will contain the number of matching items.

Source:

cursor.js, line 446

Returns:

Type: null

Example

 provider
     .select({"publisher.name": "TLC"})
     .count(function (err, count) {
         if (err) {
             console.log(err);
         } else {
             console.log(count);
         }
     });

delete(callback) → {null}

Deletes all items that match the select query.

Parameters:

Name	Type	Description
`callback`	function	Will be called after executing this method. The first parameter will contain an error object on error while the second parameter will contain the number of deleted items.

Source:

cursor.js, line 505

Returns:

Type: null

each(callback) → {null}

Iterates over all the items for this cursor. As with {cursor.toArray}, not all of the elements will be iterated if this cursor had been previouly accessed.

Parameters:

Name	Type	Description
`callback`	function	Will be called for while iterating every item of the query result. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the item.

Source:

cursor.js, line 365

Returns:

Type: null

first(callback) → {null}

Gets the first item that matches the select query and sorting criteria.

Parameters:

Name	Type	Description
`callback`	function	Will be called after executing this method. The first parameter will contain an error object on error while the second parameter will contain the first item that matches the query.

Source:

cursor.js, line 475

Returns:

Type: null

limit(limit, callback) → {Cursor}

Sets the limit parameter of this cursor to the given value.

Parameters:

Name	Type	Argument	Description
`limit`	number		the new limit.
`callback`	function	<optional>	An optional callback that will be called after executing this method. The first parameter will contain an error object when the limit given is not a valid number or when the cursor is already closed while the second parameter will contain a reference to this object upon successful execution.

Source:

cursor.js, line 102

Returns:

an instance of this object.

Type: Cursor

map(mapping, callback) → {Cursor}

Specifies which fields from the item should be returned.

Parameters:

Name	Type	Description
`mapping`	object \| Array.<string>	Either, an object specifying which fields to include or exclude (not both) or an array of field names to include.
`callback`	function	Will be called after executing this method. The first parameter will contain an error object when the cursor is already closed while the second parameter will contain a reference to this object upon successful execution.

Source:

cursor.js, line 296

Returns:

An instance of this object.

Type: Cursor

Examples

 provider
     .select()
     .map(["name", "age"])
     .toArray(function (err, arr) {
         // -> The items in the array will have only name and age fields.
     });

 provider
     .select()
     .map({ name: 1, age: 1 })
     .toArray(function (err, arr) {
         // -> The items in the array will have only name and age fields.
     });

next(callback)

Gets the next object from the cursor.

Parameters:

Name	Type	Description
`callback`	function	Will be called after executing this method. The first parameter will contain an error object on error while the second parameter will contain a object from the returned result or null if there are no more results.

Source:

cursor.js, line 406

skip(skip, callback) → {Cursor}

Sets the skip parameter of this cursor to the given value.

Parameters:

Name	Type	Argument	Description
`skip`	number		the new skip value.
`callback`	function	<optional>	this optional callback will be called after executing this method. The first parameter will contain an error object when the skip value given is not a valid number or when the cursor is already closed while the second parameter will contain a reference to this object upon successful execution.

Source:

cursor.js, line 146

Returns:

an instance of this object.

Type: Cursor

sort(criteria, callback) → {Cursor}

Sets the sort parameter of this cursor to the given value.

Parameters:

Name	Type	Description
`criteria`	object	the criteria by which the result set will be sorted.
`callback`	function	Will be called after executing this method. The first parameter will contain an error object when the cursor is already closed while the second parameter will contain a reference to this object upon successful execution.

Source:

cursor.js, line 183

Returns:

an instance of this object.

Type: Cursor

take()

This method is just an alias to Cursor.limit() method.

Source:

cursor.js, line 134

toArray(callback) → {null}

Returns an array of items. The caller is responsible for making sure that there is enough memory to store the results.

Parameters:

Name	Type	Description
`callback`	function	Will be called after executing this method successfully. The first parameter will contain the Error object if an error occurred, or null otherwise. The second parameter will contain an array of objects as a result of the query.

Source:

cursor.js, line 323

Returns:

Type: null

update(data, callback) → {null}

Updates all items that match the select query.

Parameters:

Name	Type	Description
`data`	object	An object containing the fields and values to update.
`callback`	function	Will be called after executing this method. The first parameter will contain an error object on error while the second parameter will return the number of updated items.

Source:

cursor.js, line 494

Returns:

Type: null

Example

 provider
     .select({"publisher.name": "TLC"})
     .update({$set: { age: 555 }});