IDBWrapper

Class: IDBStore

IDBStore

new IDBStore(kwArgs, onStoreReady)

The IDBStore constructor
Parameters:
Name Type Argument Description
kwArgs Object <optional>
 An options object used to configure the store and set callbacks
Properties
Name Type Argument Default Description
storeName String <optional>
 'Store' The name of the store
storePrefix String <optional>
 'IDBWrapper-' A prefix that is internally used to construct the name of the database, which will be kwArgs.storePrefix + kwArgs.storeName
dbVersion Number <optional>
 1 The version of the store
keyPath String <optional>
 'id' The key path to use. If you want to setup IDBWrapper to work with out-of-line keys, you need to set this to `null`
autoIncrement Boolean <optional>
 true If set to true, IDBStore will automatically make sure a unique keyPath value is present on each object that is stored.
onStoreReady function <optional>
 A callback to be called when the store is ready to be used.
onError function <optional>
 throw A callback to be called when an error occurred during instantiation of the store.
indexes Array <optional>
 [] An array of indexData objects defining the indexes to use with the store. For every index to be used one indexData object needs to be passed in the array. An indexData object is defined as follows:
Properties
Name Type Argument Description
indexData Object <optional>
 An object defining the index to use
Properties
Name Type Argument Description
name String The name of the index
keyPath String <optional>
 The key path of the index
unique Boolean <optional>
 Whether the index is unique
multiEntry Boolean <optional>
 Whether the index is multi entry
implementationPreference Array <optional>
 ['indexedDB','webkitIndexedDB','mozIndexedDB','shimIndexedDB'] An array of strings naming implementations to be used, in order or preference
onStoreReady function <optional>
 A callback to be called when the store is ready to be used.
Version:
  • 1.7.2
Source:
Examples
// create a store for customers with an additional index over the
     // `lastname` property.
     var myCustomerStore = new IDBStore({
         dbVersion: 1,
         storeName: 'customer-index',
         keyPath: 'customerid',
         autoIncrement: true,
         onStoreReady: populateTable,
         indexes: [
             { name: 'lastname', keyPath: 'lastname', unique: false, multiEntry: false }
         ]
     });
// create a generic store
     var myCustomerStore = new IDBStore({
         storeName: 'my-data-store',
         onStoreReady: function(){
             // start working with the store.
         }
     });

Members

autoIncrement :Boolean

Whether IDBStore uses autoIncrement
Type:
  • Boolean
Source:

db :IDBDatabase

A reference to the IndexedDB object
Type:
  • IDBDatabase
Source:

dbName :String

The full name of the IndexedDB used by IDBStore, composed of this.storePrefix + this.storeName
Type:
  • String
Source:

dbVersion :Number

The version of the IndexedDB used by IDBStore
Type:
  • Number
Source:

implementation :String

The actual implementation being used
Type:
  • String
Source:

implementationPreference :Array

The implemantations to try to use, in order of preference
Type:
  • Array
Source:

indexes :Array

The indexes used by IDBStore
Type:
  • Array
Source:

keyPath :String

The key path
Type:
  • String
Source:

onError :function

The callback to be called if an error occurred during instantiation of the store
Type:
  • function
Source:

onStoreReady :function

The callback to be called when the store is ready to be used
Type:
  • function
Source:

store :IDBObjectStore

A reference to the objectStore used by IDBStore
Type:
  • IDBObjectStore
Source:

storeName :String

The store name
Type:
  • String
Source:

storePrefix :String

The prefix to prepend to the store name
Type:
  • String
Source:

version :String

The version of IDBStore
Type:
  • String
Source:

Methods

batch(dataArray, onSuccess, onError) → {IDBTransaction}

Runs a batch of put and/or remove operations on the store.
Parameters:
Name Type Argument Description
dataArray Array An array of objects containing the operation to run and the data object (for put operations).
onSuccess function <optional>
 A callback that is called if all operations were successful.
onError function <optional>
 A callback that is called if an error occurred during one of the operations.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

clear(onSuccess, onError) → {IDBTransaction}

Clears the store, i.e. deletes all entries in the store.
Parameters:
Name Type Argument Description
onSuccess function <optional>
 A callback that will be called if the operation was successful.
onError function <optional>
 A callback that will be called if an error occurred during the operation.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

count(onSuccess, options) → {IDBTransaction}

Runs a query against the store, but only returns the number of matches instead of the matches itself.
Parameters:
Name Type Argument Description
onSuccess function A callback to be called if the opration was successful.
options Object <optional>
 An object defining specific options
Properties
Name Type Argument Default Description
index String <optional>
 null A name of an IDBIndex to operate on
keyRange IDBKeyRange <optional>
 null An IDBKeyRange to use
onError function <optional>
 throw A callback to be called if an error occurred during the operation.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

deleteDatabase(onSuccess, onError)

Deletes the database used for this store if the IDB implementations provides that functionality.
Parameters:
Name Type Argument Description
onSuccess function <optional>
 A callback that is called if deletion was successful.
onError function <optional>
 A callback that is called if deletion failed.
Source:

get(key, onSuccess, onError) → {IDBTransaction}

Retrieves an object from the store. If no entry exists with the given id, the success handler will be called with null as first and only argument.
Parameters:
Name Type Argument Description
key * The id of the object to fetch.
onSuccess function <optional>
 A callback that is called if fetching was successful. Will receive the object as only argument.
onError function <optional>
 A callback that will be called if an error occurred during the operation.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

getAll(onSuccess, onError) → {IDBTransaction}

Fetches all entries in the store.
Parameters:
Name Type Argument Description
onSuccess function <optional>
 A callback that is called if the operation was successful. Will receive an array of objects.
onError function <optional>
 A callback that will be called if an error occurred during the operation.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

getBatch(keyArray, onSuccess, onError, arrayType) → {IDBTransaction}

Takes an array of keys and fetches matching objects
Parameters:
Name Type Argument Default Description
keyArray Array An array of keys identifying the objects to fetch
onSuccess function <optional>
 A callback that is called if all operations were successful.
onError function <optional>
 A callback that is called if an error occurred during one of the operations.
arrayType String <optional>
 'sparse' The type of array to pass to the success handler. May be one of 'sparse', 'dense' or 'skip'. Defaults to 'sparse'. This parameter specifies how to handle the situation if a get operation did not throw an error, but there was no matching object in the database. In most cases, 'sparse' provides the most desired behavior. See the examples for details.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction
Example
// given that there are two objects in the database with the keypath
         // values 1 and 2, and the call looks like this:
         myStore.getBatch([1, 5, 2], onError, function (data) { … }, arrayType);

         // this is what the `data` array will be like:

         // arrayType == 'sparse':
         // data is a sparse array containing two entries and having a length of 3:
         [Object, 2: Object]
         0: Object
         2: Object
         length: 3
         // calling forEach on data will result in the callback being called two
         // times, with the index parameter matching the index of the key in the
         // keyArray.

         // arrayType == 'dense':
         // data is a dense array containing three entries and having a length of 3,
         // where data[1] is of type undefined:
         [Object, undefined, Object]
         0: Object
         1: undefined
         2: Object
         length: 3
         // calling forEach on data will result in the callback being called three
         // times, with the index parameter matching the index of the key in the
         // keyArray, but the second call will have undefined as first argument.

         // arrayType == 'skip':
         // data is a dense array containing two entries and having a length of 2:
         [Object, Object]
         0: Object
         1: Object
         length: 2
         // calling forEach on data will result in the callback being called two
         // times, with the index parameter not matching the index of the key in the
         // keyArray.

getIndexList() → {DOMStringList}

Returns a DOMStringList of index names of the store.
Source:
Returns:
The list of index names
Type
DOMStringList

hasIndex(indexName) → {Boolean}

Checks if an index with the given name exists in the store.
Parameters:
Name Type Description
indexName String The name of the index to look for
Source:
Returns:
Whether the store contains an index with the given name
Type
Boolean

indexComplies(actual, expected) → {Boolean}

Checks if an actual index complies with an expected index.
Parameters:
Name Type Description
actual IDBIndex The actual index found in the store
expected Object An Object describing an expected index
Source:
Returns:
Whether both index definitions are identical
Type
Boolean

iterate(onItem, options) → {IDBTransaction}

Iterates over the store using the given options and calling onItem for each entry matching the options.
Parameters:
Name Type Argument Description
onItem function A callback to be called for each match
options Object <optional>
 An object defining specific options
Properties
Name Type Argument Default Description
index String <optional>
 null A name of an IDBIndex to operate on
order String <optional>
 ASC The order in which to provide the results, can be 'DESC' or 'ASC'
autoContinue Boolean <optional>
 true Whether to automatically iterate the cursor to the next result
filterDuplicates Boolean <optional>
 false Whether to exclude duplicate matches
keyRange IDBKeyRange <optional>
 null An IDBKeyRange to use
writeAccess Boolean <optional>
 false Whether grant write access to the store in the onItem callback
onEnd function <optional>
 null A callback to be called after iteration has ended
onError function <optional>
 throw A callback to be called if an error occurred during the operation.
limit Number <optional>
 Infinity Limit the number of returned results to this number
offset Number <optional>
 0 Skip the provided number of results in the resultset
allowItemRejection Boolean <optional>
 false Allows the onItem function to return a Boolean to accept or reject the current item
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

makeKeyRange(options) → {IDBKeyRange}

Creates a key range using specified options. This key range can be handed over to the count() and iterate() methods. Note: You must provide at least one or both of "lower" or "upper" value.
Parameters:
Name Type Description
options Object The options for the key range to create
Properties
Name Type Argument Description
lower * <optional>
 The lower bound
excludeLower Boolean <optional>
 Whether to exclude the lower bound passed in options.lower from the key range
upper * <optional>
 The upper bound
excludeUpper Boolean <optional>
 Whether to exclude the upper bound passed in options.upper from the key range
only * <optional>
 A single key value. Use this if you need a key range that only includes one value for a key. Providing this property invalidates all other properties.
Source:
Returns:
The IDBKeyRange representing the specified options
Type
IDBKeyRange

normalizeIndexData(indexData)

Normalizes an object containing index data and assures that all properties are set.
Parameters:
Name Type Description
indexData Object The index data object to normalize
Properties
Name Type Argument Description
name String The name of the index
keyPath String <optional>
 The key path of the index
unique Boolean <optional>
 Whether the index is unique
multiEntry Boolean <optional>
 Whether the index is multi entry
Source:

put(key, value, onSuccess, onError) → {IDBTransaction}

Puts an object into the store. If an entry with the given id exists, it will be overwritten. This method has a different signature for inline keys and out-of-line keys; please see the examples below.
Parameters:
Name Type Argument Description
key * <optional>
 The key to store. This is only needed if IDBWrapper is set to use out-of-line keys. For inline keys - the default scenario - this can be omitted.
value Object The data object to store.
onSuccess function <optional>
 A callback that is called if insertion was successful.
onError function <optional>
 A callback that is called if insertion failed.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction
Examples
// Storing an object, using inline keys (the default scenario):
         var myCustomer = {
             customerid: 2346223,
             lastname: 'Doe',
             firstname: 'John'
         };
         myCustomerStore.put(myCustomer, mySuccessHandler, myErrorHandler);
         // Note that passing success- and error-handlers is optional.
// Storing an object, using out-of-line keys:
         var myCustomer = {
             lastname: 'Doe',
             firstname: 'John'
         };
         myCustomerStore.put(2346223, myCustomer, mySuccessHandler, myErrorHandler);
         // Note that passing success- and error-handlers is optional.

putBatch(dataArray, onSuccess, onError) → {IDBTransaction}

Takes an array of objects and stores them in a single transaction.
Parameters:
Name Type Argument Description
dataArray Array An array of objects to store
onSuccess function <optional>
 A callback that is called if all operations were successful.
onError function <optional>
 A callback that is called if an error occurred during one of the operations.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

query(onSuccess, options) → {IDBTransaction}

Runs a query against the store and passes an array containing matched objects to the success handler.
Parameters:
Name Type Argument Description
onSuccess function A callback to be called when the operation was successful.
options Object <optional>
 An object defining specific options
Properties
Name Type Argument Default Description
index String <optional>
 null A name of an IDBIndex to operate on
order String <optional>
 ASC The order in which to provide the results, can be 'DESC' or 'ASC'
filterDuplicates Boolean <optional>
 false Whether to exclude duplicate matches
keyRange IDBKeyRange <optional>
 null An IDBKeyRange to use
onError function <optional>
 throw A callback to be called if an error occurred during the operation.
limit Number <optional>
 Infinity Limit the number of returned results to this number
offset Number <optional>
 0 Skip the provided number of results in the resultset
filter function <optional>
 null A custom filter function to apply to query resuts before returning. Must return `false` to reject an item. Can be combined with keyRanges.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

remove(key, onSuccess, onError) → {IDBTransaction}

Removes an object from the store.
Parameters:
Name Type Argument Description
key * The id of the object to remove.
onSuccess function <optional>
 A callback that is called if the removal was successful.
onError function <optional>
 A callback that will be called if an error occurred during the operation.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

removeBatch(keyArray, onSuccess, onError) → {IDBTransaction}

Takes an array of keys and removes matching objects in a single transaction.
Parameters:
Name Type Argument Description
keyArray Array An array of keys to remove
onSuccess function <optional>
 A callback that is called if all operations were successful.
onError function <optional>
 A callback that is called if an error occurred during one of the operations.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

upsertBatch(dataArray, options, onSuccess, onError) → {IDBTransaction}

Like putBatch, takes an array of objects and stores them in a single transaction, but allows processing of the result values. Returns the processed records containing the key for newly created records to the onSuccess calllback instead of only returning true or false for success. In addition, added the option for the caller to specify a key field that should be set to the newly created key.
Parameters:
Name Type Argument Description
dataArray Array An array of objects to store
options Object <optional>
 An object containing optional options
Properties
Name Type Argument Default Description
keyField String <optional>
 this.keyPath Specifies a field in the record to update with the auto-incrementing key. Defaults to the store's keyPath.
onSuccess function <optional>
 A callback that is called if all operations were successful.
onError function <optional>
 A callback that is called if an error occurred during one of the operations.
Source:
Returns:
The transaction used for this operation.
Type
IDBTransaction

Copyright © 2017 Jens Arps
Documentation generated by JSDoc 3.5.5 on 2017-11-28T12:57:49+01:00