Use async iterators for iterateCursor and iterateKeyCursor

[mariusGundersen]

async iterators seem like a good fit for the cursors, and since the spec is close to done it should be safe to implement a (shimable) api using them

[jakearchibald]

Agreed! I'll make this a priority when it isn't behind a flag in the preview release of a browser.

[jakearchibald]

I've got a rough plan for this for 4.0.

import { openDb, iterateRecords } from 'idb';

// …

for await (const cursor of iterateRecords(storeOrIndex, optionalRange, optionalDirection)) {
  // Any of the cursor advancing methods can be called here.
  // If none are called, cursor.continue() will be called automatically.
}

[jakearchibald]

Scratch that, it should be:

import { openDb, iterateRecords } from 'idb';

// …

for await (const cursor of iterateRecords(storeOrIndex.openCursor(…))) {
  // Any of the cursor advancing methods can be called here.
  // If none are called, cursor.continue() will be called automatically.
}

Where iterateRecords takes a cursor or a promise for a cursor.

[mariusGundersen]

Why is the iterateRecord method needed? I'm sure there is a reason, but it's not obvious

[jakearchibald]

I'm looking to make it an optional import, so you don't pay the cost of it if you don't use it.

[matthewp]

Is this at all blocked by the problem described here? I was looking to make my own iterator in my own project but didn't because I felt like that issue might prevent it from working...

[jakearchibald]

That problem is gone in modern browsers.

I'm looking to add async iteration as an optional part of the next version of the library. I just need to figure out the right API.

[jakearchibald]

I've started landing the code for this in the 4.0.0 branch https://github.com/jakearchibald/idb/blob/4.0.0/lib/async-iterators.ts.

Here's how it works:

// Iterate over a store
const store = db.transaction('store-name').store;

for await (const cursor of store) {
  console.log(cursor.key, cursor.value);
}

// Iterate over an index
const index = store.index('index-name');

for await (const cursor of index) {
  console.log(cursor.key, cursor.value);
}

// Iterate over a cursor
let cursor = await index.openCursor();
if (cursor) cursor = await cursor.advance(50);
if (cursor) for await (const cursor of cursor) {
  console.log(cursor.key, cursor.value);
}

// You can update/delete/skip entries:
for await (const cursor of store) {
  // Update the value.
  cursor.update(cursor.value + 1);
  // Skip over an item.
  cursor.advance(2);
}

[quasicomputational]

That looks pretty nifty. I do have one comment, though: when iterating over a cursor, often you're happy to execute the loop zero times if the cursor returns no results. But, as openCursor will return null when the provided query doesn't match, this necessitates that if (cursor) check. Maybe it'd be nice to have a different flavour (openCursorIterable?) that will always return an async iterator, finishing immediately in the no-values-found case, allowing this code:

for await (const cursor of index.openCursorIterable(query)) {
  doStuff(cursor.value);
}

[jakearchibald]

Yeah, that's a good idea

[jakearchibald]

Added .iterate to stores and indexes. Takes the same args are openCursor. 1337312#diff-c6b8a053edbb56620d53f014adc13bf1

[jakearchibald]

Added in v4