CKTIS / JavaScript
IndexedDB: Read and move a cursor with `value` and `continue()`
Read the current IndexedDB record from a cursor, then request the next record or use a key to skip ahead in the cursor’s direction.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
cursor.value // Read-only property of IDBCursorWithValue
cursor.continue() // Request the next eligible position; returns undefined
cursor.continue(key) // Request the next eligible position at or beyond key in the cursor's direction; returns undefinedIDBCursor.value/continue is shorthand for two API members: the read-only IDBCursorWithValue.value property and the inherited IDBCursor.continue() method. When an openCursor() request yields a cursor, cursor.value gives you the current record’s stored value. Editing fields on the retrieved object does not save changes; to write them, use an operation such as cursor.update() in a readwrite transaction. A cursor from openKeyCursor() has continue() but no value property.
cursor.continue() queues a move to the next eligible record in the cursor’s direction and returns undefined. cursor.continue(key) seeks the first subsequent position with a key >= key for next or nextunique, or <= key for prev or prevunique. The target key need not exist, and the original range still applies. On an object store this comparison uses the primary key; on an index it uses the index key (cursor.key).
Read request.result in each success event on the same request. A result of null means there were no matches or the scan has ended. Read the value and call continue() at most once before yielding control to a later task, such as a timer callback. An invalid key or one that is not strictly ahead in the chosen direction causes DataError. Moving again before the next result, having no current position, or having a deleted source can cause InvalidStateError; an inactive transaction causes TransactionInactiveError.
IndexedDB is a Web API, not part of ECMAScript 2024. Availability depends on the runtime and context, and access to the data follows the same-origin policy.
Examples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB cursor example</title>
</head>
<body>
<script>
(() => {
const name = `cktis-cursor-${crypto.randomUUID()}`;
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => {
const store = open.result.createObjectStore('items');
store.add({ name: 'Ada' }, 1);
store.add({ name: 'Bo' }, 2);
store.add({ name: 'Lin' }, 4);
};
open.onerror = () => console.error(open.error);
open.onsuccess = () => {
const db = open.result;
const tx = db.transaction('items', 'readonly');
const request = tx.objectStore('items').openCursor();
const cleanup = () => {
db.close();
const deletion = indexedDB.deleteDatabase(name);
deletion.onerror = () => console.error(deletion.error);
};
tx.oncomplete = cleanup;
tx.onabort = () => {
console.error(tx.error);
cleanup();
};
request.onsuccess = () => {
const cursor = request.result;
if (cursor === null) {
console.log('Done');
return;
}
console.log(`${cursor.key}: ${cursor.value.name}`);
if (cursor.key === 1) {
cursor.continue(3);
} else {
cursor.continue();
}
};
};
})();
</script>
</body>
</html>Result
1: Ada 4: Lin Done
Open this HTML document over HTTPS in a top-level browser tab with IndexedDB and `crypto.randomUUID()` available. Read the output in the developer console. The example creates a separate demo database and requests its deletion when finished. `continue(3)` skips key `2` and lands on `4` because key `3` is absent. The next `continue()` yields a `null` result, so the handler prints `Done`.
Related lessons
- JavaScript · Lesson 21 · Intermediate · Version: 3
Sources
- IDBCursorWithValue: value property
- IDBCursor: continue() method
- IDBObjectStore: openCursor() method
- IDBIndex: openCursor() method
- IDBObjectStore: openKeyCursor() method
- IDBCursor: update() method
- IDBTransaction
- IndexedDB API
- Crypto: randomUUID() method
- IDBFactory: deleteDatabase() method
- ECMAScript 2024 Language Specification: Hosts and Implementations