Repository files navigation

The iterator interface (introduced in ECMAScript 2015) is a sequential data access protocol which enables the development of generic and composable data consumers and transformers. Their primary interface is anext() method which returns a{ value, done } tuple, wheredone is a boolean indicating whether the end of the iterator has been reached, andvalue is the yielded value in the sequence.

Since both the next value in the sequence and the "done" state of the data source must be known at the time that the iterator method returns, iterators are only suitable for representingsynchronous data sources. While many data sources encountered by the JavaScript programmer are synchronous (such as in-memory lists and other data structures), many others are not. For instance, any data source which requires I/O access will be typically represented using an event-based or streamingasynchronous API. Unfortunately, iterators cannot be used to represent such data sources.

(Even an iterator of promises is not sufficient, since that only allows asynchronous determination of the value, but requires synchronous determination of the "done" state.)

In order to provide a generic data access protocol for asynchronous data sources, we introduce theAsyncIterator interface, an asynchronous iteration statement (for-await-of), and async generator functions.

An async iterator is much like an iterator, except that itsnext() method returns a promise for a{ value, done } pair. As noted above, we must return a promise for the iterator result pair because both the next value and the "done" state of the iterator are potentially unknown at the time the iterator method returns.

const{ value, done}=syncIterator.next();asyncIterator.next().then(({ value, done})=>/* ... */);

Furthermore, we introduce a new symbol used for obtaining an async iterator from a given object,Symbol.asyncIterator. This allows arbitrary objects to advertise that they areasync iterables, similar to howSymbol.iterator allows you to advertise being a normal, synchronous iterable. An example of a class that might use this is areadable stream.

Implicit in the concept of the async iterator is the concept of arequest queue. Since iterator methods may be called many times before the result of a prior request is resolved, each method call must be queued internally until all previous request operations have completed.

We introduce a variation of thefor-of iteration statement which iterates over async iterable objects. An example usage would be:

forawait(constlineofreadLines(filePath)){console.log(line);}

Async for-of statements are only allowed within async functions and async generator functions (see below for the latter).

During execution, an async iterator is created from the data source using the[Symbol.asyncIterator]() method.

Each time we access the next value in the sequence, we implicitlyawait the promise returned from the iterator method.

Async generator functions are similar to generator functions, with the following differences:

• When called, async generator functions return an object, anasync generator whose methods (next,throw, andreturn) return promises for{ value, done }, instead of directly returning{ value, done }. This automatically makes the returned async generator objectsasync iterators.
• await expressions andfor-await-of statements are allowed.
• The behavior ofyield* is modified to support delegation to async iterables.

For example:

asyncfunction*readLines(path){letfile=awaitfileOpen(path);try{while(!file.EOF){yieldawaitfile.readLine();}}finally{awaitfile.close();}}

This function then returns an async generator object, which can be consumed withfor-await-of as shown in the previous example.

• Chakra:outstanding issue
• JavaScriptCore:shipping in Safari Tech Preview 40
• SpiderMonkey:shipping in Firefox 57;launch bug
• V8:shipping in Chrome 63;launch bug