Implement Symbol.asyncIterator for cursors

[pluma]

Not sure if this breaks compat with older node versions.

const cursor = await db.query("FOR i IN 1..100 RETURN i");
for await (const value of cursor) {
  console.log(value);
}

[JonDum]

Hey, @pluma. This is a really cool addition because I've found myself really wanting ArrayCursor.each/map to support async handlers, but I think this is probably not what you want most of the time because if you use any await inside the for loop b/c it will process and await serially. Worse, if you don't use await then the execution will go right past the loop before it's done.

Example:

const {Database} = require('arangojs')
const db = new Database({url: 'http://localhost:8529'})

const sleep = (ms = 1000) => new Promise(resolve => setTimeout(resolve, ms))

const getSomething = async (value) => {
    await sleep()
    return value * value
}

const doSomething = async (value, thing) => {
    await sleep()
    console.log('doSomething: ', value, thing)
}

async function forOfTest() {
    const cursor = await db.query("FOR i IN 1..10000 RETURN i");

    for await (const value of cursor) {
        const thing = await getSomething(value)
        await doSomething(value, thing)
    }
    console.log('done')
}

forOfTest()

Output

doSomething 1 1
(2s pause)
doSomething 2 4
(2s pause)
doSomething 4 16
(2s pause)
....
(20,000s later....)
...
done

That's most likely not what the user wants. And if instead you move it to a different function like so:

const processThing = async (value) => {
	const thing = await getSomething(value)
	await doSomething(value, thing)
}

async function forOfTest() {
    const cursor = await db.query("FOR i IN 1..10000 RETURN i");

    for await (const value of cursor) {
        processThing(value)
    }

	console.log('done')
}

Output

done
(2s pause)
doSomething 1 1
doSomething 2 4
doSomething 4 16
....

It doesn't wait through the loop :(

What I've found most useful is processing the cursor batch by batch and awaiting on that. Something like this:

const {Database} = require('arangojs')
const db = new Database({url: 'http://localhost:8529'})

const sleep = (ms = 1000) => new Promise(resolve => setTimeout(resolve, ms))

const getSomething = async (value) => {
    await sleep()
    return value * value
}

const doSomething = async (value, thing) => {
    await sleep()
    console.log('doSomething: ', value, thing)
}

async function process(cursor, fn) {
	while(cursor.hasNext) {
		const batch = await cursor.nextBatch()
		if(batch) {
			await Promise.all(batch.map(fn))
		}
	}
}

async function forOfTest() {
    const cursor = await db.query("FOR i IN 1..10000 RETURN i")

	await process(cursor, async (value) => {
		const thing = await getSomething(value)
		await doSomething(value, thing)
	})
        // properly awaits, process batch by batch
	console.log('done')
}

forOfTest()

It would be really awesome if that process function could be built into ArrayCursor somehow (possibly forEach?)

[pluma]

I don't see how doing it batchwise rather than item by item solves the problem of the cursor going away if you're too slow. Is the idea that this might help with situations where items in the same batch could be processed in parallel?

[pluma]

I could imagine having something like cursor.batched return a BatchedArrayCursor that mimics the API but only provides batch-wise access instead of item-wise. This would require a fair bit of duplication but it would allow me to remove all the batch logic from ArrayCursor.

[pluma]

@JonDum I've implemented a BatchedArrayCursor in #673, please check if that suits your needs. It provides exactly the same API ArrayCursor does except batch-wise rather than item-wise. The cursor is exposed as cursor.batches (which links back via batchedCursor.items). This also removes cursor.nextBatch, moves cursor.hasMore to batchedCursor.hasMore and adds batchedCursor.loadAll to fetch all remaining batches from the server.

[pluma]

Here's how your forOfTest function would look like using for-await-of with the batch-wise API:

async function forOfTest() {
  const cursor = await db.query("FOR i IN 1..10000 RETURN i");

  for await (const batch of cursor.batches) {
    await Promise.all(
      batch.map(async (value) => {
        const thing = await getSomething(value);
        await doSomething(value, thing);
      })
    );
  }

  console.log("done");
}

[JonDum]

@pluma Holy moly! That's awesome!

I think this will give devs a lot more power to iterate through large collections without running oom!

Excited to see this drop in v7

[pluma]

The PR has been merged into the v7 branch: https://arangodb.github.io/arangojs/devel/classes/_cursor_.batchedarraycursor.html