Indexed Database API

Opening a database

WorkerUtils objects MUST implement the IDBEnvironmentSync interface.

readonly attribute IDBFactorySync indexedDBSync: This attribute provides applications a mechanism for accessing capabilities of indexed databases.

IDBDatabaseSync open()

When invoked, this method MUST throw a DOMException of type InvalidStateError when it is called within the IDBTransactionCallback of a transaction method or the IDBVersionChangeCallback of a open method. Otherwise this method synchronously runs the steps for opening a database. Let origin be the origin of the IDBEnvironmentSync used to access this IDBFactorySync, name, version and upgrade callback be the name, version and upgradeCallback arguments passed to this function.

If no version is specified and a database exists, use the current database version and follow the steps for opening a database. If no version is specified and no database exists, set database version to 1, follow the steps for opening a database, and return a database without object stores.

If a timeout parameter was supplied, then this limits the total waiting time allowed in step 3 of steps for opening a database and step 4 of the steps for running a "versionchange" transaction. If more waiting time would be needed in order to progress, then abort those algorithms and throw a DOMException of type TimeoutError.

The timeout parameter does not affect how long the upgradeCallback can run.

If an error is returned from the steps above, then the implementation MUST throw a DOMException with its name and message set to appropriate values for the error.

If the steps above are successful, the implementation MUST create an IDBDatabaseSync object representing the created connection and return it.

Processing a open call may take a long time as it could require running a "versionchange" transaction which requires all other connections to the database to be closed, which in turn may depend on user input or other long-running tasks. If blocking for a long period of time is not acceptable for a given scenario then the asynchronous API should be used for version changes.

If the value for version is 0 (zero) or a negative number, this method MUST throw a JavaScript TypeError exception.

DOMString name: The name for the database
[EnforceRange] optional unsigned long long version: The version for the database
IDBVersionChangeCallback upgradeCallback: Callback used if the database version needs to be upgraded before the database can be opened.
optional unsigned long timeout: Defines a transaction timeout value in milliseconds that will limit the how long waiting for the "versionchange" transaction. If the parameter is not provided, the value of timeout is infinite.

InvalidStateError: The open method was called within the IDBTransactionCallback of a transaction method or IDBVersionChangeCallback of a open method.
TimeoutError: Was unable to open the database with the requested version within the given timeout period.
TypeError: The value of version is 0 (zero) or a negative number.

void deleteDatabase()

When invoked, this method synchronously runs the steps for deleting a database. Let origin be the origin of the IDBEnvironmentSync used to access this IDBFactorySync and name be the name argument passed to this function.

If an error is returned from the steps above, then the implementation MUST throw a DOMException with its name and message set to appropriate values for the error.

DOMString name: The name of the database to be deleted.

short cmp()

When invoked, this method MUST compare two keys. The method returns 1 if the first key is greater than the second, -1 if the first is less than the second, and 0 if the first is equal to the second.

any first: The first key to compare.
any second: The second key to compare.

DataError: One of the supplied keys was not a valid key.

Database

A database object provides access to the schema and data of a particular database.

readonly attribute DOMString name

On getting, this attribute MUST return the name of the connected database. The function MUST return this name even if the closePending flag is set on the connection. In other words, the return value from this function stays constant for the lifetime of the IDBDatabaseSync instance.

readonly attribute unsigned long long version

On getting, this attribute MUST return the version of the database when this IDBDatabaseSync instance was created. When a IDBDatabaseSync instance is created, this is always the number passed as the version argument passed to the open call used to create the IDBDatabaseSync instance. This value remains constant for the lifetime of the IDBDatabaseSync object. If the connection is closed, this attribute represents a snapshot of the version that the database had when the connection was closed. Even if another connection is later used to modify the version, that attribute on closed instances are not changed.

readonly attribute DOMStringList objectStoreNames

On getting, this attribute MUST return a list of names of the object stores currently in the connected database. The list MUST be sorted in ascending order using the algorithm defined by step 4 of section 11.8.5, The Abstract Relational Comparison Algorithm of the ECMAScript Language Specification [[!ECMA-262]]. Once the closePending flag is set on the connection, this function MUST return a snapshot of the list of names of the object stores taken at the time when the close method was called. Even if other connections are later used to change the set of object stores that exist in the database. In other words, the return value from this function stays constant for the lifetime of the IDBDatabaseSync instance except during a "versionchange" transaction if createObjectStore or deleteObjectStore is called on this IDBDatabaseSync instance itself.

IDBObjectStoreSync createObjectStore()

This method creates and returns a new object store with the given name in the connected database. This method should only be called from inside a "versionchange" transaction.

This method synchronously modifies the IDBDatabaseSync.objectStoreNames property. However it only modifies the IDBDatabaseSync.objectStoreNames property on the IDBDatabaseSync instance on which it was called.

If the optionalParameters argument is specified and has a keyPath property which is not null, then set keyPath to the value of this property. If keyPath is an Array, then each item in the array is converted to a string. If keyPath is not an Array, it is converted to a string.

If keyPath is not a valid key path then a DOMException of type SyntaxError MUST be thrown. Otherwise set the created object store's key path to the value of keyPath.

If the optionalParameters parameter is specified, and autoIncrement is set to true, and the keyPath parameter is specified to the empty string, or specified to an Array, this function MUST throw a InvalidAccessError exception.

DOMString name: The name of a new object store
optional IDBObjectStoreParameters optionalParameters: The options object whose attributes are optional parameters to this function. keyPath specifies the key path of the new object store. If the attribute is null no key path is specified and thus keys are out-of-line. autoIncrement specifies whether the object store created should have a key generator.

InvalidStateError: This method was not called from a "versionchange" transaction. Also occurs if a request is made on a source object that has been deleted or removed.
ConstraintError: If an object store with the same name, compared in a case-sensitive manner, already exists in the connected database.
InvalidAccessError: If autoIncrement is set to true, and keyPath either is the empty string, or an Array containing the empty string.

void deleteObjectStore()

This method destroys an object store with the given name as well as all indexes that are referencing that object store. This method should only be called from inside a "versionchange" transaction.

This method synchronously modifies the IDBDatabaseSync.objectStoreNames property. However it only modifies the IDBDatabaseSync.objectStoreNames property on the IDBDatabaseSync instance on which it was called.

DOMString name: The name of an existing object store

InvalidStateError: This method was not called from a "versionchange" transaction callback. Also occurs if a request is made on a source object that has been deleted or removed.
NotFoundError: If the object store with the given name, compared in a case-sensitive manner, does not already exist in the connected database.

void transaction()

This method, when called MUST execute the steps for creating a transaction in a sychronous fashion. The storeNames, callback, mode, and timeout arguments are forwarded to the algorithm as-is. The connection argument is set to the IDBDatabaseSync that the transaction() method was called on.

The method returns an IDBTransactionSync object representing the transaction returned by the steps above.

This method MUST throw an DOMException of type InvalidStateError when it is called within the IDBTransactionCallback of a transaction method or the IDBVersionChangeCallback of a open method.

any storeNames: The names of object stores and indexes in the scope of the new transaction
IDBTransactionCallback callback: A callback which will be called with the newly created transaction. When the callback returns, the transaction is committed.
optional DOMString mode: The mode for isolating access to data inside the given object stores. If this parameter is not provided, the default access mode is "readonly".
optional unsigned long timeout: The interval in milliseconds which this operation is allowed to take to reserve all the database objects identified in the new transaction's scope. The default is user agent specific

TimeoutError: If starting the transaction takes longer than the specified timeout.
InvalidStateError: The close() method has been called on this IDBDatabase instance. Also thrown when The transaction() method was called within the IDBTransactionCallback of a transaction method or the IDBVersionChangeCallback of a open method.
NotFoundError: One of the names provided in the storeNames argument doesn't exist in this database.
TypeError: The value for the mode parameter is invalid.
InvalidAccessError: The function was called with an empty list of store names

void close()

This method synchronously performs the steps for closing a database connection and returns once the database has been closed.

void transactionStarted()

Called once the transaction is allowed to run. The actions taken in this function make up the body of the transaction.

IDBTransactionSync transaction: The newly started transaction

void transactionStarted()

Called if a database upgrade is needed once the transaction used to upgrade the database is allowed to run. The actions taken in this function make up the body of the transaction.

IDBTransactionSync transaction: The newly started transaction
unsigned long long oldVersion: The version that the database had before the upgrade was needed. 0 if the database was newly created.

Object Store

In the following example, we set up an object store to use the key path id. This object store is also designed to use a key generator.

var db = indexedDBSync.open('AddressBook', 1, function(trans, oldVersion) { trans.db.createObjectStore('Contact', {keyPath:'id', autoIncrement:true} ); });

Using this database, we can store records in the Contact object store.

var tx = db.transaction(); var store = tx.objectStore('Contact'); var contact = store.add({name: 'Lincoln', number: '7012'}); // contact.id === 1

A stored value can be retrieved using the same key used by the first put operation.

var contact = store.get(1); // contact.name === 'Lincoln'

A put operation will overwrite the record stored by the first add operation with the same key.

var abraham = {id: 1, name: 'Abraham', number: '2107'}; store.put(abraham);

Now when the object store is read with the same key, the result is different compared to the object read earlier.

var contact = store.get(1); // contact.id === 1 && contact.name === 'Abraham';

Additionally, all the records of an object store matching a certain key range can be retrieved in key order.

var range = new IDBKeyRange.bound(2, 4); var cursor = store.openCursor(range); // each value is a contact and each key is the id for that // contact whose id is between 2 and 4, both inclusive cursor.continue();

readonly attribute DOMString name

On getting, provide the name of this object store.

readonly attribute any keyPath

On getting, provide the key path of this object store. This will be either a DOMString, an Array of DOMStrings or null.

readonly attribute DOMStringList indexNames

On getting, provide a list of the names of indexes on objects in this object store. The list MUST be sorted in ascending order using the algorithm defined by step 4 of section 11.8.5, The Abstract Relational Comparison Algorithm of the ECMAScript Language Specification [[!ECMA-262]].

readonly attribute IDBTransactionSync transaction

On getting, returns the transaction this object store belongs to.

readonly attribute boolean autoIncremenent;

On getting, provides the auto increment flag for this object store.

any put()

This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync belongs to has its mode set to "readonly". If any of the following conditions are true, this method throws a DOMException of type DataError:

The object store uses in-line keys and the key parameter was provided.
The object store uses out-of-line keys and has no key generator and the key parameter was not provided.
The object store uses in-line keys and the result of evaluating the object store's key path yields a value and that value is not a valid key.
The object store uses in-line keys but no key generator and the result of evaluating the object store's key path does not yield a value.
The key parameter was provided but does not contain a valid key.

Otherwise this method creates a structured clone of the value parameter. If the structured clone algorithm throws an exception, that exception is rethrown. Otherwise, run the steps for synchronously executing a request and return the result, in this case the key of the stored object. The steps are run with this IDBObjectStoreSync as source and the steps for storing a record into an object store as operation, using this IDBObjectStoreSync as store, the created clone as value, the key parameter as key, and with the no-overwrite flag flag set to false.

any value: The value to be stored in the record
optional any key: The key used to identify the record

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
ReadOnlyError: The mode of the associated transaction is "readonly".
DataError: The calculated key for the insertion was not a valid key.
ConstraintError: Another record in this object store has the same value for the keyPath of a unique index.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.
DataCloneError: The data being stored could not be cloned by the internal structured cloning algorithm.

any add()

This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync belongs to is has its mode set to "readonly". If any of the following conditions are true, this method throws a DOMException of type DataError:

The object store uses in-line keys and the key parameter was provided.
The object store uses out-of-line keys and has no key generator and the key parameter was not provided.
The object store uses in-line keys and the result of evaluating the object store's key path yields a value and that value is not a valid key.
The object store uses in-line keys but no key generator and the result of evaluating the object store's key path does not yield a value.
The key parameter was provided but does not contain a valid key.

Otherwise this method creates a structured clone of the value parameter. If the structured clone algorithm throws an exception, that exception is rethrown. Otherwise, run the steps for synchronously executing a request and return the key of the stored object. The steps are run with this IDBObjectStoreSync as source and the steps for storing a record into an object store as operation, using this IDBObjectStoreSync as store, the created clone as value, the key parameter as key, and with the no-overwrite flag flag set to true.

any value: The value to be stored in the record
optional any key: The key used to identify the record

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
ReadOnlyError: The mode of the associated transaction is "readonly".
DataError: The calculated key for the insertion was not a valid key.
ConstraintError: A record exists in this object store for the key key parameter, or another record in this object store has the same value for the keyPath of a unique index.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.
DataCloneError: The data being stored could not be cloned by the internal structured cloning algorithm.

boolean delete()

This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync belongs to is has its mode set to "readonly". If the key parameter is not a valid key or a key range this method throws a DOMException of type DataError.

Otherwise this method runs the steps for synchronously executing a request. The steps are run with this IDBObjectStoreSync as source and the steps for deleting records from an object store as operation, using this IDBObjectStoreSync as store and the key parameter as key. The function returns the result of running these steps.

Unlike other methods which take keys or key ranges, this method does not allow null to be passed as key. This is to reduce the risk that a small bug would clear a whole object store.

any key: Key identifying the record to be deleted

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
ReadOnlyError: The mode of the transaction this IDBObjectStoreSync belongs to is "readonly".
NotFoundError: A record did not exist in this object store for the key key parameter.

any get()

If the key parameter is not a valid key or a key range, this method throws a DOMException of type DataError. Otherwise, this method runs the steps for synchronously executing a request and returns the result of the operation. The steps are run with this IDBObjectStoreSync as source and the steps for retrieving a value from an object store as operation, using this IDBObjectStoreSync as store and the key parameter as key.

This function produces the same result if a record with the given key doesn't exist as when a record exists, but has undefined as value. If you need to tell the two situations apart, you can use openCursor with the same key. This will return a cursor with undefined as value if a record exists, or no cursor if no such record exists.

any key: Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case the function retrieves the first existing value in that range.

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
DataError: The key parameter was not passed a valid value.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

void clear()

This method throws a DOMException of type ReadOnlyError if the transaction which this IDBObjectStoreSync belongs to is has its mode set to "readonly".

Otherwise this method runs the steps for synchronously executing a request. The steps are run with this IDBObjectStoreSync as source and the steps for clearing an object store as operation, using this IDBObjectStoreSync as store.

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
ReadOnlyError: The mode of the transaction this IDBObjectStoreSync belongs to is "readonly".
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

IDBIndexSync createIndex()

This creates and returns a new index with the given name and parameters in the connected database. Note that this method must only be called from a "versionchange" transaction. The created index has its unique and multiEntry flags are set to the values of the unique and multiEntry properties in the optionalParameters argument.

If the keyPath argument is an Array, then each item in the array is converted to a DOMString. If keyPath is not an Array, it is converted to a DOMString.

If keyPath is not a valid key path then a DOMException of type SyntaxError MUST be thrown. Otherwise set the created object store's key path to the value of keyPath. If keyPath is an Array and the multiEntry property in the optionalParameters is true, then a DOMException of type InvalidAccessError MUST be thrown. Otherwise set the created index's key path to the value of keyPath.

DOMString name: The name of a new index
any keyPath: The key path used by the new index
optional IDBIndexParameters optionalParameters: The options object whose attributes are optional parameters to this function. unique specifies whether the index's unique flag is set. multiEntry specifies whether the index's multiEntry flag is set.

InvalidStateError: This method was not called from a "versionchange" transaction. Also occurs if a request is made on a source object that has been deleted or removed.
ConstraintError: An index with the same name, compared in a case-sensitive manner, already exists in the connected database. Also thrown when creating a unique index on top of an object store that already contains records that violate the unique constraint.

IDBIndexSync index()

Returns an IDBIndexSync representing an index that is part of the object store. Every call to this function on the same IDBObjectStoreSync instance and with the same name returns the same IDBIndexSync instance. However the retured IDBIndexSync instance is specific to this IDBObjectStoreSync instance. If this function is called on a different IDBObjectStoreSync instance, a different IDBIndexSync instance is returned. A result of this is that different IDBTransactionSyncs use different IDBIndexSync instances to represent the same index.

DOMString name: The name of an existing index

NotFoundError: If the index with the given name does not exist in the connected database.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed, or if the transaction the object store belongs to has finished.

void deleteIndex()

This method destroys the index with the given name in the connected database. Note that this method must only be called from a "versionchange" transaction.

DOMString indexName: The name of an existing index

NotFoundError: If the index with the given name does not exist in the connected database.
InvalidStateError: This method was not called from a "versionchange" transaction.

IDBCursorWithValueSync openCursor()

If the range parameter is specified but is not a valid key or a key range, this method throws a DOMException of type DataError. Otherwise, this method creates a cursor. The cursor MUST implement the IDBCursorWithValueSync interface.

The newly created cursor MUST have an undefined position, a direction set to the value of the direction parameter, false as iterable flag value, and undefined key and value. The source of the cursor is the IDBObjectStoreSync this function was called on.

If the range parameter is a key range then the cursor's range is set to that range. Otherwise, if the range parameter is a valid key then the cursor's range is set to key range containing only that key value. If the range parameter is not specified, the cursor's key range is left as undefined.

This method runs the steps for synchronously executing a request and returns the result of the operation, in this case an IDBCursorSync object. The steps are run with this IDBObjectStoreSync as source and the steps for iterating a cursor as operation, using the created cursor as cursor and with undefined as key.

optional any? range: The key range to use as the cursor's range
optional DOMString direction: The cursor's required direction

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
TypeError: The value for the direction parameter is invalid.
DataError: The range parameter was not passed key range or a valid key.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

unsigned long count()

If the optional key parameter is not a valid key or a key range, this method throws a DOMException of type DataError. This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBObjectStore as source and the steps for iterating a cursor as operation, using the created cursor as cursor. If provided, use the key parameter as key, otherwise, use undefined as key. If the result of the algorithm is null return 0 (zero) as the result for the request. Otherwise, use the return cursor to determine the total number of objects that share the key or key range and return that value as the result for the request.

optional any key: Key identifying the record to be retrieved. This can also be an IDBKeyRange.

TransactionInactiveError: The transaction this IDBObjectStoreSync belongs to is not active.
DataError: The key parameter is not a valid key or a key range.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

Index

An index can be created for retrieving records other than by using record keys. Continuing the earlier example, an index could be maintained on the name property of objects in the Contact object store.

For example, the id of an object with the name property value 'Lincoln' can be retrieved using the ContactName index.

var index = store.openIndex('ContactName'); var id = index.get('Lincoln'); // id === 1

Additionally, all the records of an object store matching a certain range index keys can be retrieved in key order. When objects are retrieved from the Contact object store, they are arranged by the value of the id attribute. On the other hand, when objects are retrieved using the ContactName index, they are arranged by the value of the name property.

var range = new IDBKeyRange.bound('L', 'M'); var cursor = index.openCursor(range); // each value is a contact and each key is the name for that // contact whose name's first letter is either L or M cursor.continue();

If, on the other hand, we only want the names and keys but not the whole Contact objects for a given range, then we can use a different mechanism for that.

var range = new IDBKeyRange.bound('L', 'M'); var cursor = index.openKeyCursor(range); // each value is a contact id and each key is the name for that // contact whose name's first letter is either L or M cursor.continue();

readonly attribute DOMString name

On getting, provide the name of this index.

readonly attribute IDBObjectStoreSync objectStore

On getting, returns a reference to the IDBObjectStoreSync instance for the referenced object store in this IDBIndexSync's transaction. This MUST return the same IDBObjectStoreSync instance as was used to get a reference to this IDBIndexSync.

readonly attribute any keyPath

On getting, returns the key path of this index. This will be either a DOMString or an Array of DOMStrings.

readonly attribute boolean multiEntry

On getting, provide the multiEntry flag of this index.

readonly attribute boolean unique

On getting, provide the unique flag of this index.

IDBCursorWithValueSync openCursor()

If the range parameter is specified but is not a valid key or a key range, this method throws a DOMException of type DataError. Otherwise, this method creates a cursor. The cursor MUST implement the IDBCursorWithValueSync interface.

The newly created cursor MUST have an undefined position, a direction set to the value of the direction parameter, false as iterable flag value, and undefined key and value. The source of the cursor is the IDBIndexSync this function was called on.

If the range parameter is a key range then the cursor's range is set to that range. Otherwise, if the range parameter is a valid key then the cursor's range is set to key range containing only that key value. If the range parameter is not specified, the cursor's key range is left as undefined.

This method runs the steps for synchronously executing a request and returns the result, in this case a cursor object. The steps are run with this IDBIndexSync as source and the steps for iterating a cursor as operation, using the created cursor as cursor and with undefined as key

optional any? range: The key range to use as the cursor's range
optional DOMString direction: The cursor's required direction

TransactionInactiveError: The transaction this IDBIndexSync belongs to is not active.
TypeError: The value for the direction parameter is invalid.
DataError: The range parameter was not passed a valid value.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

IDBCursorSync openKeyCursor()

If the range parameter is specified but is not a valid key or a key range, this method throws a DOMException of type DataError. Otherwise, this method creates a cursor. The cursor MUST implement the IDBCursorSync interface and MUST NOT implement the IDBCursorWithValueSync interface.

The newly created cursor MUST have an undefined position, a direction set to the value of the direction parameter, false as iterable flag value, and undefined key and value. The source of the cursor is the IDBIndexSync this function was called on.

If the range parameter is a key range then the cursor's range is set to that range. Otherwise, if the range parameter is a valid key then the cursor's range is set to key range containing only that key value. If the range parameter is not specified, the cursor's key range is left as undefined.

This method runs the steps for synchronously executing a request and returns the result, in this case a cursor object. The steps are run with this IDBIndexSync as source and the steps for iterating a cursor as operation, using the created cursor as cursor and with undefined as key

optional any? range: The key range to use as the cursor's range
optional DOMString direction: The cursor's required direction

TransactionInactiveError: The transaction this IDBIndexSync belongs to is not active.
TypeError: The value for the direction parameter is invalid.
DataError: The range parameter was not passed key range or a valid key.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

any get()

If the key parameter is not a valid key or a key range, this method throws a DOMException of type DataError. This method runs the steps for synchronously executing a request and returns the result from that, in this case an object from the underlying store. The steps are run with this IDBIndexSync as source and the steps for retrieving a referenced value from an index as operation, using this IDBIndexSync as index and the key parameter as key.

This function produces the same result if a record with the given key doesn't exist as when a record exists, but has undefined as value. If you need to tell the two situations apart, you can use openCursor with the same key. This will return a cursor with undefined as value if a record exists, or no cursor if no such record exists.

any key: Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case the function retreives the first existing value in that range.

TransactionInactiveError: The transaction this IDBIndexSync belongs to is not active.
DataError: The key parameter was not passed a valid value.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

any getKey()

If the key parameter is not a valid key or a key range, this method throws a DOMException of type DataError. This method runs the steps for synchronously executing a request and returns the result from that, in this case an index value (a key). The steps are run with the IDBObjectStoreSync associated with this index as source and the steps for retrieving a value from an index as operation, using this IDBIndexSync as index and the key parameter as key.

any key: Key identifying the record to be retrieved. This can also be an IDBKeyRange in which case the function retreives the first existing value in that range.

TransactionInactiveError: The transaction this IDBIndexSync belongs to is not active.
DataError: The key parameter was not passed a valid value.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

unsigned long count()

If the optional key parameter is not a valid key or a key range, this method throws a DOMException of type DataError. This method runs the steps for asynchronously executing a request and returns the IDBRequest created by these steps. The steps are run with this IDBIndex as source and the steps for iterating a cursor as operation, using the created cursor as cursor. If provided, use the key parameter as key, otherwise, use undefined as key. If the result of the algorithm is null return 0 (zero) as the result for the request. Otherwise, use the return cursor to determine the total number of objects that share the key or key range and return that value as the result for the request.

optional any key: Key identifying the record to be retrieved. This can also be an IDBKeyRange.

TransactionInactiveError: The transaction this IDBIndexSync belongs to is not active.
DataError: The key parameter is not a valid key or a key range.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed.

Cursor

Using the synchronous API, an application can process all the records in the cursor's range.

By default, a cursor walks over objects starting at the first record and ending at the last record including all the duplicates encountered along the way.

var tx = db.transaction('Contact'); var store = tx.objectStore('Contact'); var cursor = store.openCursor(); while(cursor.continue()) { var value = cursor.value; // act on each object or key }

To start at the last record and end in the first record, the cursor should be created with the direction parameter "prev".

var cursor = store.openCursor("prev"); while(cursor.continue()) { // act on each object or key }

To start at a certain key and end in the last record, i.e., for a lower-bounded cursor, while skipping duplicates, the cursor should be created with both the required start key and the direction parameter.

var range = IDBKeyRange.leftBound(key); var cursor = store.openCursor(range, IDBCursorSync.NEXT_NO_DUPLICATE);

It is also possible to create a bounded cursor, i.e., with application-specified starting and ending points, the cursor should be created with both the required keys. If the range is inclusive of both keys, then additional flags are required. In the following example, all keys with values in the inclusive range (start, end) are returned with all their duplicates, from the beginning of the range to its end.

var range = IDBKeyRange.bound(start, end); var cursor = objects.openCursor(range);

readonly attribute Object source

On getting, returns the IDBObjectStoreSync or IDBIndexSync which this cursor is iterating. This function never returns null or throws an exception, even if the cursor is currently being iterated, has iterated past its end, or its transaction is not active.

readonly attribute DOMString direction

On getting, provide the traversal direction of the cursor.

Returns the cursor's current key. Note that if this property returns an object (specifically an Array), it returns the same object instance every time it is inspected, until the cursor is iterated. This means that if the object is modified, those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object does not modify the contents of the database.

readonly attribute any primaryKey

Returns the cursor's current effective key. Note that if this property returns an object (specifically an Array), it returns the same object instance every time it is inspected, until the cursor is iterated. This means that if the object is modified, those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object does not modify the contents of the database.

IDBRequest update()

This method throws a DOMException of type ReadOnlyError if the transaction which this IDBCursorSync belongs to has its mode set to "readonly". If this cursor's got value flag is false or if this cursor was created using openKeyCursor, this method throws a DOMException of type InvalidStateError. If the effective object store of this cursor uses in-line keys and evaluating the key path of the value parameter results in a different value than the cursor's effective key, this method throws DOMException of type DataError.

Otherwise this method creates a structured clone of the value parameter. If the structured clone algorithm throws an exception, that exception is rethrown. Otherwise, run the steps for synchronously executing a request and return the result returned by these steps. The steps are run with this IDBCursorSync as source and the steps for storing a record into an object store as operation, using this cursor's effective object store as store, the created clone as value, this cursor's effective key as key, and with the no-overwrite flag flag set to false.

A result of running the steps for storing a record into an object store is that if the record has been deleted since the cursor moved to it, a new record will be created.

any value: The new value to store at the current position.

TransactionInactiveError: The transaction this IDBCursor belongs to is not active.
ReadOnlyError: The mode of the transaction this IDBCursor belongs to is "readonly"
InvalidStateError: Thrown if cursor was created using openKeyCursor or if the cursor is currently being iterated or has iterated past the end.
DataError: The underlying object store uses in-line keys and the property in value at the object store's key path does not match the key in this cursor's position.
DataCloneError: The data being stored could not be cloned by the internal structured cloning algorithm.

boolean advance()

This method runs the steps for synchronously executing a request. The steps are run with the cursor's source as source. The operation runs the steps for iterating a cursor count number of times with null as key and this cursor as cursor. If the steps for synchronously executing a request returns a cursor, then this function returns true. Otherwise this function returns false.

Before this method returns, unless an exception was thrown, it sets the got value flag in the cursor to false.

Calling this method more than once before new cursor data has been loaded is not allowed and results in a DOMException of type InvalidStateError being thrown. For example, calling advance() twice from the same onsuccess handler results in a DOMException of type InvalidStateError being thrown on the second call.

If the value for count is 0 (zero) or a negative number, this method MUST throw a JavaScript TypeError exception.

[EnforceRange] unsigned long count: The number of advances forward the cursor should make.

TypeError: The value passed into the count parameter was zero or a negative number.
TransactionInactiveError: The transaction this IDBCursorSync belongs to is not active.
InvalidStateError: The cursor is currently being iterated, or has iterated past its end.

boolean continue()

If this cursor's got value flag is false, this method throws a DOMException of type InvalidStateError. If the key parameter is specified and fulfills any of these conditions this method MUST throw a DOMException of type DataError:

The parameter is not a valid key.
The parameter is less than or equal to this cursor's position and this cursor's direction is "next" or "nextunique".
The parameter is greater than or equal to this cursor's position and this cursor's direction is "prev" or "prevunique".

Otherwise this method runs the steps for synchronously executing a request. The steps are run with the cursor's source as source and the steps for iterating a cursor as operation, using the cursor this is called on as cursor and the key parameter as key. If the steps for synchronously executing a request returns a cursor, then this function returns true. Otherwise this function returns false.

Before this method returns, unless an exception was thrown, it sets the got value flag in the cursor to false.

Calling this method more than once before new cursor data has been loaded is not allowed and results in a DOMException of type InvalidStateError being thrown. For example, calling continue() twice from the same onsuccess handler results in a DOMException of type InvalidStateError being thrown on the second call.

optional any key: The next key to position this cursor at

TransactionInactiveError: The transaction this IDBCursorSync belongs to is not active.
InvalidStateError: The cursor is currently being iterated, or has iterated past its end.
DataError: The key parameter was specified but did not contain a valid key.

boolean delete()

This method throws a DOMException of type ReadOnlyError if the transaction which this IDBCursorSync belongs to has its mode set to "readonly". If this cursor's got value flag is false, or if this cursor was created using openKeyCursor a DOMException of type InvalidStateError is thrown.

Otherwise this method runs the steps for synchronously executing a request. The steps are run with this IDBCursorSync as source and the steps for deleting records from an object store as operation, using this cursor's effective object store and effective key as store and key respectively. The function returns the result of running these steps.

TransactionInactiveError: The transaction this IDBCursorSync belongs to is not active.
ReadOnlyError: The mode of the transaction this IDBCursorSync belongs to is "readonly".
InvalidStateError: The cursor was created using openKeyCursor or the cursor is currently being iterated or has iterated past the end.

attribute any value: Returns the cursor's current value. Note that if this property returns an object, it returns the same object instance every time it is inspected, until the cursor is iterated. This means that if the object is modified, those modifications will be seen by anyone inspecting the value of the cursor. However modifying such an object does not modify the contents of the database.

Transaction

When an application creates a transaction synchronously, it blocks until the user agent is able to reserve the required database objects.

readonly attribute DOMString mode

On getting, provide the mode for isolating access to data inside the object stores that are in the scope of the transaction.

attribute IDBDatabaseSync db

The database connection of which this transaction is a part

readonly attribute DOMError error

If this transaction is not finished, is finished but was successfully committed, or was aborted due to a call to the abort function, this property returns null. If this transaction was aborted due to a failed request, this property returns the same DOMError as the request which caused this transaction to be aborted. If this transaction was aborted due to an error when committing the transaction, and not due to a failed request, this property returns a DOMError which contains the reason for the transaction failure (e.g. QuotaExceededError or UnknownError).

IDBObjectStoreSync objectStore()

Returns an IDBObjectStoreSync representing an object store that is within the scope of this transaction. Every call to this function on the same IDBTransactionSync instance and with the same name returns the same IDBObjectStoreSync instance. However the retured IDBObjectStoreSync instance is specific to this IDBTransactionSync. If this function is called on a different IDBTransactionSync, a different IDBObjectStoreSync instance is returned.

DOMString name: The requested object store

NotFoundError: If the requested object store is not in this transaction's scope.
InvalidStateError: Occurs if a request is made on a source object that has been deleted or removed, or if the transaction has finished.

void abort()

If this transaction is finished, throw a DOMException of type InvalidStateError. Otherwise this method sets the transactions's active flag to false and aborts the transaction by running the steps for aborting a transaction with the error parameter set to null.

InvalidStateError: If this transaction has already been committed or aborted.

Applications MUST not assume that committing the transaction produces an instantaneously durable result. The user agent MAY delay flushing data to durable storage until an appropriate time.

Once a transaction is aborted or committed, the active transaction on this database connection is removed. A new transaction can be created to perform operations atomically.