-
Notifications
You must be signed in to change notification settings - Fork 62
Running Queries
To run queries, IDBWrapper provides a query() and an iterate() method. To create keyRanges, there is the makeKeyRange() method. In addition to these, IDBWrapper comes with a count() method. The query, iterate and count methods return the IDBTransaction they open.
iterate(/*Function*/ onItem, /*Object*/ iterateOptions)The onItem callback will be called once for every match. It will receive three arguments: the object that matched the query, a reference to the current cursor object (IDBWrapper uses IndexedDB's Cursor internally to iterate), and a reference to the current ongoing transaction.
There's one special situation: if you didn't pass an onEnd handler in the options objects (see below), the onItem handler will be called one extra time when the transaction is over. In this case, it will receive null as only argument. So, to check when the iteration is over and you won't get any more data objects, you can either pass an onEnd handler, or check for null in the onItem handler.
The iterateOptions object can contain one or more of the following properties:
The index property contains the name of the index to operate on. If you omit this, IDBWrapper will use the store's keyPath as index.
In the keyRange property you can pass a keyRange.
The order property can be set to 'ASC' or 'DESC', and determines the ordering direction of results. If you omit this, IDBWrapper will use 'ASC'.
The autoContinue property defaults to true. If you set this to false, IDBWrapper will not automatically advance the cursor to next result, but instead pause after it obtained a result. To move the cursor to the next result, you need to call the cursor object's continue() method (you get the cursor object as second argument to the onItem callback).
The filterDuplicates property is an interesting one: If you set this to true (it defaults to false), and have several objects that have the same value in their key, the store will only fetch the first of those. It is not about objects being the same, it's about their key being the same. For example, in the customers database are a couple of guys having 'Smith' as last name. Setting filterDuplicates to true in the above example will make iterate() call the onItem callback only for the first of those.
The writeAccess property defaults to false. If you need write access to the store during the iteration, you need to set this to true.
In the onEnd property you can pass a callback that gets called after the iteration is over and the transaction is closed. It does not receive any arguments.
In the onError property you can pass a custom error handler. In case of an error, it will be called and receives the Error object as only argument.
The limit property defaults to Infinity and is used to limit the resultset to the provided number.
The offset property defaults to 0 and is used to skip the provided number of results in the resultset.
query(/*Function*/ onSuccess, /*Object*/ queryOptions)The query() method is just like the iterate() method, except that it will call the onSuccess callback with an array of the matched objects instead of calling a callback for each item.
The onSuccess callback will be called if the operation was successful, and it
will receive an array objects as only argument.
The queryOptions object can contain one or more of the following properties:
The index property contains the name of the index to operate on. If you omit this, IDBWrapper will use the store's keyPath as index.
In the keyRange property you can pass a keyRange.
The order property can be set to 'ASC' or 'DESC', and determines the ordering direction of results. If you omit this, IDBWrapper will use 'ASC'.
The filterDuplicates property is an interesting one: If you set this to true (it defaults to false), and have several objects that have the same value in their key, the store will only fetch the first of those. It is not about objects being the same, it's about their key being the same. For example, in the customers database are a couple of guys having 'Smith' as last name. Setting filterDuplicates to true in the above example will make iterate() call the onItem callback only for the first of those.
In the onError property you can pass a custom error handler. In case of an error, it will be called and receives the Error object as only argument.
The limit property defaults to Infinity and is used to limit the resultset to the provided number.
The offset property defaults to 0 and is used to skip the provided number of results in the resultset.
makeKeyRange(/*Object*/ keyRangeOptions)Returns an IDBKeyRange.
The keyRangeOptions object must have one or more of the following properties:
lower: The lower bound of the range
excludeLower: Boolean, whether to exclude the lower bound itself. Default: false
upper: The upper bound of the range
excludeUpper: Boolean, whether to exclude the upper bound itself. Default: false
only: If you want a key range around only one value, pass just this property.
count(/*Function*/ onSuccess, /*Object*/ countOptions)The onSuccess receives the result of the count as only argument.
The countOptions object may have one or more of the following properties:
index: The name of an index to operate on.
keyRange: A keyRange to use