{"id":91,"date":"2020-05-26T15:01:42","date_gmt":"2020-05-26T22:01:42","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=91"},"modified":"2020-06-12T16:18:03","modified_gmt":"2020-06-12T23:18:03","slug":"async-iterators-in-the-azure-sdk-for-javascript-typescript","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/async-iterators-in-the-azure-sdk-for-javascript-typescript\/","title":{"rendered":"Async Iterators in the Azure SDK for JavaScript\/TypeScript"},"content":{"rendered":"

A common feature in cloud APIs is paging for list results. Result sets may be massive – you could have thousands of blobs in a container, for example. Getting all results at once can cause delays in transmission and excessive load on the backend, and might even be so big it won’t fit into memory in your client. So services offer potentially large collections in pages and developers request one page of results at a time.<\/p>\n

The Azure SDK for Javascript and TypeScript abstracts away the details of requesting pages from the service. You write a normal loop, and we take care of the rest. For example, here is the code that iterates through a list of containers in Storage:<\/p>\n

const containers = blobServiceClient.listContainers();\nfor await (const container of containers) {\n  console.log(`Container: ${container.name}`);\n}\n<\/code><\/pre>\n
How is this done? We use features that were added to recent editions of JavaScript; most notably async iterators. Async Iterators represent a stream of data that is loaded asynchronously. They are used across the Azure SDK to represent asynchronous streams of data such as paginated APIs like above.<\/p>\n
Async Iterators, the Async Generators that produce them, and the for-await-of<\/code> loops<\/a> loops that consume them were added in the ES2018 edition of the JavaScript standard. They are supported natively in recent version of modern browsers, but TypeScript can compile them down<\/a> to previous versions of JavaScript.<\/p>\n
If you’re already familiar with async functions, promises, generators, and iterators, feel free to skip the background below. If not, that’s great, most of this blog is for you!<\/p>\n
Background<\/h2>\n
At a high level, a function might produce one value or a (possibly unending) sequence of values. It also might do its work synchronously or asynchronously. Considered together, these modes create four possible ways functions might be declared and consumed. Put in a table it looks like the following:<\/p>\n\n\n\n\n\n\n
\n      <\/th>\n\n        One Value\n      <\/th>\n\n        Many Values\n      <\/th>\n<\/tr>\n<\/thead>\n
\n        Synchronous<\/strong>\n      <\/td>\n\n        function
Returns T\n      <\/td>\n		\n        generator function
Returns Iterator of T\n      <\/td>\n<\/tr>\n
\n        Asynchronous<\/strong>\n      <\/td>\n\n        async function
Returns Promise of T\n      <\/td>\n		\n        async generator 
Returns AsyncIterator of T\n      <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
When JavaScript debuted in 1995, it supported only synchronous functions that produce only a single return value. Developers who wanted to return multiple values, or wanted to produce values asynchronously, had to rely on libraries (for example, node’s Stream or promises).<\/p>\n
Iterators & Generators<\/h3>\n
The 6th edition of the JavaScript language, ES2015, added iterators, iterables, and the for-of<\/code> loop. Iterables are any object with a Symbol.iterator<\/code> method that returns an iterator. Iterators are objects with a next()<\/code> method. Calling next()<\/code> returns an object with value<\/code> and done<\/code> properties which tell you the current iteration value and whether more values are available. The for-of<\/code> loop provides handy syntax for looping over an iterable.<\/p>\n
Iterables and iterators aren’t types but protocols. Any object which has a Symbol.iterator<\/code> method is said to implement the Iterable<\/code> protocol. Likewise, any object with a next<\/code> method is said to implement the Iterator<\/code> protocol.<\/p>\n
Let’s get an understanding of Iterables and Iterators by building them from scratch. First, let’s make an Iterator<\/code>:<\/p>\n
const iterator = {\n  next() {\n    if (this.count <= 2) {\n      return { value: this.count++, done: false };\n    }\n\n    return { value: undefined, done: true };\n  },\n\n  count: 0,\n};\n\niterator.next(); \/\/ { value: 0, done: false }\niterator.next(); \/\/ { value: 1, done: false }\niterator.next(); \/\/ { value: 2, done: false }\niterator.next(); \/\/ { value: undefined, done: true }\n<\/code><\/pre>\n
Nothing too fancy here – we’ve implemented the Iterator<\/code> protocol because we have a next()<\/code> method which returns the next value in the sequence. Note how the iterator is stateful – it keeps track of its current position in the iteration. In practice this means you also need a way to vend fresh iterators. We can accomplish this by wrapping the iterator in a function:<\/p>\n
function getIterator() {\n  return {\n    next() {\n      if (this.count <= 2) {\n        return { value: this.count++, done: false };\n      }\n\n      return { value: undefined, done: true };\n    },\n\n    count: 0,\n  };\n}\n\nconst iterator1 = getIterator();\niterator1.next(); \/\/ { value: 0, done: false }\n\n\/\/ this iterator is a separate instance with its own internal count\nconst iterator2 = getIterator();\niterator2.next(); \/\/ { value: 0, done: false }\n<\/code><\/pre>\n
Now every time I call getIterator()<\/code>, I get a fresh iterator that starts at 0.<\/p>\n
We’ve actually implemented a generator function using regular functions! A generator function creates a function that return an iterator, just like getIterator<\/code> does. When a user calls next()<\/code> on an iterator, the generator function starts running until it hits a yield<\/code> or return<\/code>. If it hits a yield<\/code>, next()<\/code> will return the yielded value with done: false<\/code>, otherwise next()<\/code> will return the returned value with done: true<\/code>. It looks like this:<\/p>\n
\/\/ notice the * after function - it makes this a generator function\nfunction* getIterator() {\n  for (let i = 0; i <= 2; i++) {\n    yield i;\n  }\n}\n\nconst iterator1 = getIterator();\niterator1.next(); \/\/ { value: 0, done: false }\n<\/code><\/pre>\n
This is pretty handy on its own, but we still need a way to pass around an object that is iterable but isn’t itself an iterator. An array is an example of this – you want to pass around the array and let any code iterate over it as needed. This is what the Iterable<\/code> protocol is for – anything with a Symbol.iterator<\/code> method is iterable. Calling the method returns a fresh iterator.<\/p>\n
The following example shows encapsulating getIterator<\/code> above in a Counter<\/code> class. Note that I’m using the generator syntax, but I could have used the more verbose form we used early on – there is little difference.<\/p>\n
class Counter {\n  constructor(max) {\n    this.max = max;\n  }\n\n  \/\/ the star makes this a generator method\n  *[Symbol.iterator]() {\n    for (let i = 0; i < this.max; i++) {\n      yield i;\n    }\n  }\n}\n\nconst threeCounter = new Counter(3);\nconst iterator1 = threeCounter[Symbol.iterator]();\niterator1.next(); \/\/ { value: 0, done: true }\n<\/code><\/pre>\n
Now I know what you’re thinking: this looks horrible! I have to call some weird Symbol.iterator<\/code> method to get an iterator? Great news: in practice, it is rare to call the Symbol.iterator method yourself. In fact, it is rare to call iterator .next() methods too. Usually, you will use the for-of<\/code> loop:<\/p>\n
const threeCounter = new Counter(3);\nfor (let i of threeCounter) {\n  console.log(i);\n}\n\/\/ logs 0, 1, 2\n<\/code><\/pre>\n
The for-of<\/code> loop will call the Symbol.iterator<\/code> method on the iterable object for you. It will also call next()<\/code> on the resulting iterator<\/code>, passing each value into the loop, until next()<\/code> returns { done: true }<\/code>. Some other syntax and built-in libraries will also do this for you, like the spread operator and the Array.of method:<\/p>\n
[...threeCounter]; \/\/ [0, 1, 2]\nArray.from(threeCounter); \/\/ [0, 1, 2]\n<\/code><\/pre>\n
One more small point: Iterators should also be Iterable. The iterators created from the generator function are iterable, so you don’t have to do anything to use them with the for-of<\/code> loop. However, If you try to use our early examples where we used the for-of<\/code> loop, you’ll get an error saying that the iterator isn’t iterable. This can easily be fixed:<\/p>\n
const iterator = {\n  \/\/ add the Symbol.iterator method\n  [Symbol.iterator]() {\n    \/\/ `this` is an iterator, so just return it\n    return this;\n  },\n  next() {\n    if (this.count <= 2) {\n      return { value: this.count++, done: false };\n    }\n\n    return { value: undefined, done: true };\n  },\n\n  count: 0,\n};\n<\/code><\/pre>\n
And now you know why TypeScript has three similar-sounding types for iteration: Iterable, Iterator, and IterableIterator. Iterable is an interface with a Symbol.iterator<\/code> method, Iterator is an object with a next()<\/code> method, and IterableIterator has both!<\/p>\n
Promises & Async Functions<\/h3>\n
ES2015 added Promises to the language. I won’t cover the details of Promises here, but MDN has a good overview<\/a> complete with handy diagrams. Fundamentally, Promises represent a value that will be produced asynchronously.<\/p>\n
The 8th edition of the JavaScript language, ES2017, added async function<\/code>s which offered developers an easy way to define functions that returned Promises.<\/p>\n
Inside of an async function, you can await<\/code> any Promise which defers further execution of the function until the awaited Promise resolves successfully. Then you can return your final result and the Promise returned from the async function resolves.<\/p>\n
async function getValue() {\n  await delay(100);\n  return \"hi!\";\n}\n\n\/\/ invoke the async function\nconst p = getValue();\n\/\/ it returns a Promise immediately, we don't have the value yet.\n\n\/\/ but after 100ms, it will resolve with \"hi!\", triggering our callback:\np.then((v) => console.log(v));\n<\/code><\/pre>\n
Async Iterators & Async Generators<\/h2>\n
So far, we’ve gone over three ways to define a function:<\/p>\n
    \n
  1. The regular function<\/code>, which returns a single value synchronously.<\/li>\n
  2. The generator function, function*<\/code>, which returns an iterator for multiple values produced synchronously, and is consumed with the for-of<\/code> loop.<\/li>\n
  3. The async function<\/code>, which returns a promise for a value produced asynchronously, and is consumed using await<\/code>.<\/li>\n<\/ol>\n
    The only remaining part of the puzzle is how do we produce and consume multiple values produced asychronously? Enter the async generators, async function*<\/code>, which return async iterators and are consumed with the for-await-of<\/code> loop!<\/p>\n
    Async iterators are a mashup of promises and iterators. Like a regular iterator, an async iterator is just an object with a next()<\/code> method, however it returns a promise<\/em> for the iteration result rather than the result itself.<\/p>\n
    Likewise, async generators are a mashup of async functions and generators – you can both await asynchronous work and yield values to consumers.<\/p>\n
    Let’s write our counter example from above, except where each value is produced after a delay of 100ms:<\/p>\n
    async function* getAsyncIterator() {\n  for (i = 0; i < 3 i++) {\n    await delay(100);\n    yield i;\n  }\n}\n\nconst iterator = getAsyncIterator();\n\/\/ since iterator.next() returns a promise, we await its value.\nawait iterator.next(); \/\/ { value: 0, done: false }\nawait iterator.next(); \/\/ { value: 1, done: false }\nawait iterator.next(); \/\/ { value: 2, done: false }\nawait iterator.next(); \/\/ { value: undefined, done: true }\n<\/code><\/pre>\n
    Much like iterators, typically you will not consume the async iterator directly, but use it in conjunction with the for-await-of<\/code> loop which handles all the ceremony for you:<\/p>\n
    for await (let i of getAsyncIterator()) {\n  console.log(i);\n}\n\n\/\/ logs 0, 1, 2\n<\/code><\/pre>\n
    As with iterators and generators, the async iterators returned from async generators are also AsyncIterable<\/code>. An AsyncIterable<\/code> is an object with a Symbol.asyncIterable<\/code> method that returns an AsyncIterator. The for-await-of<\/code> loop calls this method to get an object’s async iterator.<\/p>\n
    Hence, the three TypeScript types for async iteration: AsyncIterator<\/code>, AsyncIterable<\/code>, and AsyncIterableIterator<\/code>. An AsyncIterator has a next()<\/code> method that returns a promise for an iteration result, an AsyncIterable<\/code> has a Symbol.asyncIterable<\/code> method that returns an AsyncIterator<\/code>, and an AsyncIterableIterator<\/code> has both!<\/p>\n
    Async Iterators in the Azure SDK for JavaScript & TypeScript<\/h2>\n
    Our new SDKs use async iterators whenever there is a large collection a developer wants to iterate over. A common example is paginated APIs. Let’s take an example:<\/p>\n
    const containers = blobServiceClient.listContainers();\nfor await (const container of containers) {\n  console.log(`Container: ${container.name}`);\n}\n<\/code><\/pre>\n
    containers<\/code> is what we call a PagedAsyncIterableIterator<\/code>. It’s an async iterator with an additional method, byPage()<\/code>, that exposes an async iterator for the underlying pages. Sometimes pages are more convenient to work with:<\/p>\n
    const containerPages = blobServiceClient.listContainers().byPage();\n\/\/ loop over each page\nfor await (const page of containerPages) {\n  \/\/ loop over each item in the page\n  for (const container of page) {\n    console.log(`Container: ${container.name}`);\n  }\n}\n<\/code><\/pre>\n
    The three major advantages of using async iterators over manual pagination or APIs that return all items in an array are that:<\/p>\n
      \n
    1. You can consume asynchronous sequences of values using a fairly standard loop syntax. The complexity of dealing with paginated APIs is completely encapsulated behind the Async Iterator interface.<\/li>\n
    2. You pull new items from the service on-demand as needed. If for whatever reason you don’t need to iterate any longer, just break<\/code> like any old loop and you won’t fetch any more data.<\/li>\n
    3. We’re set up for a future where async iterators, like iterators, have deep integration in the language and great support across the ecosystem.<\/li>\n<\/ol>\n
      Let’s dive a bit deeper into each of these.<\/p>\n
      Standard loop syntax<\/h4>\n
      The for-await-of<\/code> loop makes consuming async iterators easy. No messy code dealing with promises and plumbing continuation tokens.<\/p>\n
      Pull items on demand<\/h4>\n
      When using iterating an async iterator, you’re pulling data as you need it, not all in advance. That means you don’t need to fetch a potentially huge list and store it in memory. It also means you don’t fetch more data than you need. To understand how this works, let’s walk through the example above.<\/p>\n
      First, we call listContainers()<\/code>, which returns an async iterator. At this point, the service hasn’t even been called.<\/p>\n
      On the next line, we start the for-await-of<\/code> loop. JavaScript calls .next()<\/code> on the iterator and awaits the result. Our library code will fetch the next page if needed, pull out the next container in the page, and yield it back, kicking off the loop body. Once the loop body is finished executing, the process repeats.<\/p>\n
      If at any point you break out of the for-await-of<\/code> loop, or an error is thrown, then no more data is requested from the service.<\/p>\n
      Language & library integration<\/h4>\n
      Async iterators are a fairly recent addition to the language and thus far don’t have much support other than the for-await-of<\/code> loop. Thankfully this is a major win and more than enough to justify using async iterators today. However, the future will likely bring further support for async iterators such as methods for applying array-like operators like map<\/code>, filter<\/code>, and friends.<\/p>\n
      But more exciting is that Async Iterators are a standard feature and so libraries have stepped in to fill the gaps.<\/p>\n
      For example, sometimes it is really convenient to get all of your items into an array. Generally we don’t offer a simple API in our libraries to do this because there’s a good chance you’ll pull down huge amounts of data you don’t need and end up with a hefty bill. That said, sometimes you know you’re dealing with a small collection and just want to do array things on it. A library like ix<\/code> provides a function to do just this:<\/p>\n
      import { toArray } from \"ixjs\/asynciterable\";\nlet items = await toArray(client.listThings());\n\/\/ now items is a regular array of items!\n<\/code><\/pre>\n
      You’ll find other libraries on npm for doing all sorts of things with async iterators, and in the future this support will only grow. Adopting async iterators in the Azure SDK makes sure we’ll interoperate seamlessly with great libraries across our ecosystem.<\/p>\n
      Further reading<\/h2>\n