View Source  |  Submit Feedback

Class ydn.db.Iterator

Abstract class Iterator, denoted as cursor range iterator, represents a continuous segment of cursors from an object store. There are four concrete classes, KeyIterator, ValueIterator, IndexIterator and IndexValueIterator that implements Iterator.

A cursor iterator is enumerated by its effective key in a specified direction, giving rise to its reference value. If the reference value of an cursor range is primary key, it is called a key iterator, otherwise it is called a value iterator.

If the iterator is operating on primary key, it is called primary iterator or iterator simply. If the iterator is operating on secondary key or index key, it is called index iterator.

Iterator Effective key Reference value
KeyIterator Primary key Primary key
ValueIterator Primary key Record value
IndexIterator Index key Primary key
IndexValueIterator Index key Record value

A iterator has the follow possible four states:

State done key Description
Initial undefined undefined Initial state. The iterator is not feed to the storage.
Working undefined {*} The iterator is iterating.
Resting false {*} The iterator exist iteration process.
Completed true {*} The iterator exist iteration process without remaining records.

An iterator can be attached by peer stores.


Constructor
ydn.db.KeyIterator(store_name, key_range, reverse) core
ydn.db.ValueIterator(store_name, key_range, reverse)
Create a primary value cursor iterator or primary key cursor iterator.

Key range can be defined by IDBKeyRange, an JSON object in the following format or constructed from ydn.db.KeyRange.

key_range = {
    lower: lower_value,     // optional, either number or string
    upper: upper_value,     // optional, either number or string
    lowerOpen: true,        // optional, boolean
    upperOpen: true         // optional, boolean
}

The following creating an iterator having keys between 'a' and 'b'.

var iterator = new ydn.db.ValueIterator('people', {lower: 'a', upper: 'b'}));
Parameters:
{string} store_name
Store name.
{(!ydn.db.KeyRange|IDBKeyRange|Object)=} key_range
Optional. The key range.
{boolean=} reversed
Optional. true to reverse direction.
ydn.db.IndexIterator(store_name, index, key_range, reversed, distinct)
ydn.db.IndexValueIterator(store_name, index, key_range, reversed, distinct)
Create an index cursor iterator.

Index iterator is a primary building block in iterator operation for an indexed database (IndexedDB). Index iterator are iterable for both key and value.

The following example illustrate filtering cursor record of indexed field location to equal string value to Singapore.

var iterator = new ydn.db.Iterator('people', 'location', ydn.db.KeyRange.only('Singapore'));
Parameters:
{string} store_name
Store name.
{string} index
Index name.
{(!ydn.db.KeyRange|IDBKeyRange|Object)=} key_range
Optional. The key range.
{boolean=} reversed
Optional. true to reverse direction.
{boolean=} distinct
Optional. true to skip repeated index key value.
Static Methods
ydn.db.KeyIterator.where(store_name, op, value, op_2, value_2)
Create a new primary key cursor range iterator using where clause.

Where clause is evaluate to a boolean value by the operator using given left value and right value from the record object. If optional second operator is given, the two operators are evaluated with logical AND.

Parameters:
{string} store_name
The store name.
{enum.<string>} op
Operator symbol. One of '<', '<=', '=', '>', '>=', '^'. The last operator is for string value having starts with.
{*} value
Left value for the operator.
{enum.<string>=} op_2
Operator symbol 2.
{*=} value_2
Left value for the operator 2.
Returns:
{!ydn.db.KeyIterator} Newly create iterator.
ydn.db.ValueIterator.where(store_name, op, value, op_2, value_2)
Create a new value cursor range iterator using where clause.
Parameters:
{string} store_name
The store name.
{enum.<string>} op
Operator symbol. 
{*} value
Left value for the operator.
{enum.<string>} op_2
Operator symbol 2.
{*} value_2
Left value for the operator 2.
Returns:
{!ydn.db.ValueIterator} Newly create iterator.
ydn.db.IndexKeyCursors.where(store_name, index_name, op, value, op_2, value_2)
Create a new index key cursor range iterator using where clause.
Parameters:
{string} store_name
The store name.
{string} index_name
The index name.
{enum.<string>} op
Operator symbol. 
{*} value
Left value for the operator.
{enum.<string>} op_2
Operator symbol 2.
{*} value_2
Left value for the operator 2.
Returns:
{!ydn.db.IndexKeyCursors} Newly create iterator.
ydn.db.IndexIterator.where(store_name, index_name, op, value, op_2, value_2)
Create a new index value cursor range iterator using where clause.
Parameters:
{string} store_name
The store name.
{string} index_name
The index name.
{enum.<string>} op
Operator symbol. 
{*} value
Left value for the operator.
{enum.<string>} op_2
Operator symbol 2.
{*} value_2
Left value for the operator 2.
Returns:
{!ydn.db.IndexIterator} Newly create iterator.
Methods
getState()
Get cursor state property.
Returns:
{enum.<string>} cursor state value, either one of 'init', 'busy', 'rest', 'done'.
getIndexName()
Get index name.
Returns:
{string|undefined} index name.
getStoreName()
Get store name.
Returns:
{string|undefined} store name.
getKeyRange()
Get key range.
Returns:
{ydn.db.KeyRange|undefined} key range.
isReversed()
Get reverse flag.
Returns:
{boolean} Return true if and only if cursor direction is either PREV or PREV_UNIQUE.
isUnique()
Get unique flag.
Returns:
{boolean} Return true if and only if cursor direction is either PREV_UNIQUE or PREV_UNIQUE.
getKey()
Get state property current effective key.
 Current key value is initially undefined. The value is set beginning of each iteration.
Returns:
{IDbKey|undefined} current effective key.
getPrimaryKey()
Get state property current primary key.
 Current primary key value is initially undefined. The value is set beginning of each iteration for index cursor iteration.
Returns:
{IDbKey|undefined} current primary key.
reset()
Reset cursor state properties.
Returns:
{!ydn.db.Iterator} Newly created iterator with initial state.
resume(key, index_key)
Set state property to resume the iterator.
Parameters:
{*} key
Start position key.
{*=} index_key
Start position index key.
Returns:
{!ydn.db.Iterator} Newly created iterator with start position applied.
reverse(key, primary_key)
Create a new iterator on reverse direction.
Parameters:
{*=} key
Start position effective key.
{*=} primary_key
Start position primary key.
Returns:
{!ydn.db.Iterator} Newly created iterator in reverse direction.