davidbgk
/
larlet-fr-david-cache

<!doctype html><!-- This is a valid HTML5 document. -->
<!-- Screen readers, SEO, extensions and so on. -->
<html lang=fr>
<!-- Has to be within the first 1024 bytes, hence before the <title>
  See: https://www.w3.org/TR/2012/CR-html5-20121217/document-metadata.html#charset -->
<meta charset=utf-8>
<!-- Why no `X-UA-Compatible` meta: https://stackoverflow.com/a/6771584 -->
<!-- The viewport meta is quite crowded and we are responsible for that.
  See: https://codepen.io/tigt/post/meta-viewport-for-2015 -->
<meta name=viewport content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no">
<!-- Required to make a valid HTML5 document. -->
<title>ES6 generators in depth (archive) — David Larlet</title>
<!-- Generated from https://realfavicongenerator.net/ such a mess. -->
<link rel="apple-touch-icon" sizes="180x180" href="/static/david/icons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/static/david/icons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/static/david/icons/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<link rel="mask-icon" href="/static/david/icons/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/static/david/icons/favicon.ico">
<meta name="apple-mobile-web-app-title" content="David Larlet">
<meta name="application-name" content="David Larlet">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="msapplication-config" content="/static/david/icons/browserconfig.xml">
<meta name="theme-color" content="#f0f0ea">
<!-- That good ol' feed, subscribe :p. -->
<link rel=alternate type="application/atom+xml" title=Feed href="/david/log/">

  <meta name="robots" content="noindex, nofollow">
  <meta content="origin-when-cross-origin" name="referrer">
  <!-- Canonical URL for SEO purposes -->
  <link rel="canonical" href="http://www.2ality.com/2015/03/es6-generators.html">

<style>
/* http://meyerweb.com/eric/tools/css/reset/ */
html, body, div, span,
h1, h2, h3, h4, h5, h6, p, blockquote, pre,
a, abbr, address, big, cite, code,
del, dfn, em, img, ins,
small, strike, strong, tt, var,
dl, dt, dd, ol, ul, li,
fieldset, form, label, legend,
table, caption, tbody, tfoot, thead, tr, th, td,
article, aside, canvas, details, embed,
figure, figcaption, footer, header, hgroup,
menu, nav, output, ruby, section, summary,
time, mark, audio, video {
  margin: 0;
  padding: 0;
  border: 0;
  font-size: 100%;
  font: inherit;
  vertical-align: baseline;
}
/* HTML5 display-role reset for older browsers */
article, aside, details, figcaption, figure,
footer, header, hgroup, menu, nav, section { display: block; }
body { line-height: 1; }
blockquote, q { quotes: none; }
blockquote:before, blockquote:after,
q:before, q:after {
  content: '';
  content: none;
}
table {
  border-collapse: collapse;
  border-spacing: 0;
}

/* http://practicaltypography.com/equity.html */
/* https://calendar.perfplanet.com/2016/no-font-face-bulletproof-syntax/ */
/* https://www.filamentgroup.com/lab/js-web-fonts.html */
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Regular-webfont.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Italic-webfont.woff') format('woff');
  font-weight: 300;
  font-style: italic;
  font-display: swap;
}
@font-face {
  font-family: 'EquityTextB';
  src: url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff2') format('woff2'),
       url('/static/david/css/fonts/Equity-Text-B-Bold-webfont.woff') format('woff');
  font-weight: 700;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'ConcourseT3';
  src: url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff2') format('woff2'),
       url('/static/david/css/fonts/concourse_t3_regular-webfont-20190806.woff') format('woff');
  font-weight: 300;
  font-style: normal;
  font-display: swap;
}


/* http://practice.typekit.com/lesson/caring-about-opentype-features/ */
body {
  /* http://www.cssfontstack.com/ Palatino 99% Win 86% Mac */
  font-family: "EquityTextB", Palatino, serif;
  background-color: #f0f0ea;
  color: #07486c;
  font-kerning: normal;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: subpixel-antialiased;
  text-rendering: optimizeLegibility;
  font-variant-ligatures: common-ligatures contextual;
  font-feature-settings: "kern", "liga", "clig", "calt";
}
pre, code, kbd, samp, var, tt {
  font-family: 'TriplicateT4c', monospace;
}
em {
  font-style: italic;
  color: #323a45;
}
strong {
  font-weight: bold;
  color: black;
}
nav {
  background-color: #323a45;
  color: #f0f0ea;
  display: flex;
  justify-content: space-around;
  padding: 1rem .5rem;
}
  nav:last-child {
    border-bottom: 1vh solid #2d7474;
  }
  nav a {
    color: #f0f0ea;
  }
  nav abbr {
    border-bottom: 1px dotted white;
  }

h1 {
  border-top: 1vh solid #2d7474;
  border-bottom: .2vh dotted #2d7474;
  background-color: #e3e1e1;
  color: #323a45;
  text-align: center;
  padding: 5rem 0 4rem 0;
  width: 100%;
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
}
  h1.single {
    padding-bottom: 10rem;
  }
  h1 span {
    position: absolute;
    top: 1vh;
    left: 20%;
    line-height: 0;
  }
    h1 span a {
      line-height: 1.7;
      padding: 1rem 1.2rem .6rem 1.2rem;
      border-radius: 0 0 6% 6%;
      background: #2d7474;
      font-size: 1.3rem;
      color: white;
      text-decoration: none;
    }
h2 {
  margin: 4rem 0 1rem;
  border-top: .2vh solid #2d7474;
  padding-top: 1vh;
}
h3 {
  text-align: center;
  margin: 3rem 0 .75em;
}
hr {
  height: .4rem;
  width: .4rem;
  border-radius: .4rem;
  background: #07486c;
  margin: 2.5rem auto;
}
time {
  display: bloc;
  margin-left: 0 !important;
}
ul, ol {
  margin: 2rem;
}
ul {
  list-style-type: square;
}
a {
  text-decoration-skip-ink: auto;
  text-decoration-thickness: 0.05em;
  text-underline-offset: 0.09em;
}
article {
  max-width: 50rem;
  display: flex;
  flex-direction: column;
  margin: 2rem auto;
}
  article.single {
    border-top: .2vh dotted #2d7474;
    margin: -6rem auto 1rem auto;
    background: #f0f0ea;
    padding: 2rem;
  }
  article p:last-child {
    margin-bottom: 1rem;
  }
p {
  padding: 0 .5rem;
  margin-left: 3rem;
}
  p + p,
  figure + p {
    margin-top: 2rem;
  }

blockquote {
  background-color: #e3e1e1;
  border-left: .5vw solid #2d7474;
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 1rem;
  margin: 1.5rem;
}
  blockquote cite {
    font-style: italic;
  }
  blockquote p {
    margin-left: 0;
  }

figure {
  border-top: .2vh solid #2d7474;
  background-color: #e3e1e1;
  text-align: center;
  padding: 1.5rem 0;
  margin: 1rem 0 0;
  font-size: 1.5rem;
  width: 100%;
}
  figure img {
    max-width: 250px;
    max-height: 250px;
    border: .5vw solid #323a45;
    padding: 1px;
  }
figcaption {
  padding: 1rem;
  line-height: 1.4;
}
aside {
  display: flex;
  flex-direction: column;
  background-color: #e3e1e1;
  padding: 1rem 0;
  border-bottom: .2vh solid #07486c;
}
  aside p {
    max-width: 50rem;
    margin: 0 auto;
  }

/* https://fvsch.com/code/css-locks/ */
p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
  font-size: 1rem;
  line-height: calc( 1.5em + 0.2 * 1rem );
}
h1 {
  font-size: 1.9rem;
  line-height: calc( 1.2em + 0.2 * 1rem );
}
h2 {
  font-size: 1.6rem;
  line-height: calc( 1.3em + 0.2 * 1rem );
}
h3 {
  font-size: 1.35rem;
  line-height: calc( 1.4em + 0.2 * 1rem );
}
@media (min-width: 20em) {
  /* The (100vw - 20rem) / (50 - 20) part
     resolves to 0-1rem, depending on the
     viewport width (between 20em and 50em). */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.5em + 0.2 * (100vw - 50rem) / (20 - 50) );
    margin-left: 0;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.2em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.3em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * (100vw - 20rem) / (50 - 20) );
    line-height: calc( 1.4em + 0.2 * (100vw - 50rem) / (20 - 50) );
  }
}
@media (min-width: 50em) {
  /* The right part of the addition *must* be a
     rem value. In this example we *could* change
     the whole declaration to font-size:2.5rem,
     but if our baseline value was not expressed
     in rem we would have to use calc. */
  p, li, pre, code, kbd, samp, var, tt, time, details, figcaption {
    font-size: calc( 1rem + .6 * 1rem );
    line-height: 1.5em;
  }
  p, li, pre, details {
    margin-left: 3rem;
  }
  h1 {
    font-size: calc( 1.9rem + 1.5 * 1rem );
    line-height: 1.2em;
  }
  h2 {
    font-size: calc( 1.5rem + 1.5 * 1rem );
    line-height: 1.3em;
  }
  h3 {
    font-size: calc( 1.35rem + 1.5 * 1rem );
    line-height: 1.4em;
  }
  figure img {
    max-width: 500px;
    max-height: 500px;
  }
}

figure.unsquared {
  margin-bottom: 1.5rem;
}
  figure.unsquared img {
    height: inherit;
  }


@media print {
  body { font-size: 100%; }
  a:after { content: " (" attr(href) ")"; }
  a, a:link, a:visited, a:after {
    text-decoration: underline;
    text-shadow: none !important;
    background-image: none !important;
    background: white;
    color: black;
  }
  abbr[title] { border-bottom: 0; }
  abbr[title]:after { content: " (" attr(title) ")"; }
  img { page-break-inside: avoid; }
  @page { margin: 2cm .5cm; }
  h1, h2, h3 { page-break-after: avoid; }
  p3 { orphans: 3; widows: 3; }
  img {
    max-width: 250px !important;
    max-height: 250px !important;
  }
  nav, aside { display: none; }
}

ul.with_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_columns {
    column-count: 2;
  }
}
@media (min-width: 50em) {
  ul.with_columns {
    column-count: 3;
  }
}
ul.with_two_columns {
  column-count: 1;
}
@media (min-width: 20em) {
  ul.with_two_columns {
    column-count: 1;
  }
}
@media (min-width: 50em) {
  ul.with_two_columns {
    column-count: 2;
  }
}

.gallery {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-around;
}
  .gallery figure img {
    margin-left: 1rem;
    margin-right: 1rem;
  }
  .gallery figure figcaption {
    font-family: 'ConcourseT3'
  }

footer {
  font-family: 'ConcourseT3';
  display: flex;
  flex-direction: column;
  border-top: 3px solid white;
  padding: 4rem 0;
  background-color: #07486c;
  color: white;
}
  footer > * {
    max-width: 50rem;
    margin: 0 auto;
  }
  footer a {
    color: #f1c40f;
  }
  footer .avatar {
    width: 200px;
    height: 200px;
    border-radius: 50%;
    float: left;
    -webkit-shape-outside: circle();
    shape-outside: circle();
    margin-right: 2rem;
    padding: 2px 5px 5px 2px;
    background: white;
    border-left: 1px solid #f1c40f;
    border-top: 1px solid #f1c40f;
    border-right: 5px solid #f1c40f;
    border-bottom: 5px solid #f1c40f;
  }
</style>

<h1>
  <span><a id="jumper" href="#jumpto" title="Un peu perdu ?">?</a></span>
  ES6 generators in depth (archive)
  <time>Pour la pérennité des contenus liés. Non-indexé, retrait sur simple email.</time>
</h1>
<section>
  <article>
    <h3><a href="http://www.2ality.com/2015/03/es6-generators.html">Source originale du contenu</a></h3>
    <p>This blog post is part of a series on iteration in ES6:</p>

<ol>
<li><a href="http://www.2ality.com/2015/02/es6-iteration.html">Iterables and iterators in ECMAScript 6</a></li>
<li><a href="http://www.2ality.com/2015/03/es6-generators.html">ES6 generators in depth</a></li>
</ol>

<p><hr/>
<p>Generators, a new feature of ECMAScript 6 <a class="ptr">[4]</a>, are functions that can be paused and resumed. This helps with many applications: iterators, asynchronous programming, etc. This blog post explains how generators work and gives an overview of their applications.</p>
<p>The following GitHub repository contains the example code: <a href="https://github.com/rauschma/generator-examples">generator-examples</a></p></p>
<h3 id="overview" class="countheads">Overview</h3>

<p>Two important applications of generators are:</p>

<ul>
<li>Implementing iterables</li>
<li>Blocking on asynchronous function calls</li>
</ul>

<p>The following subsections give brief overviews of these applications, more thorough explanations are provided later (plus discussions of other topics).</p>

<h4 id="implementing_iterables_via_generators">Implementing iterables via generators</h4>

<p>The following function returns an iterable over the properties of an object, one <code>[key,value]</code> pair per property:</p>

<pre class="javascript">
    // The asterisk after `function` means that
    // `objectEntries` is a generator
    function* objectEntries(obj) {
        let propKeys = Reflect.ownKeys(obj);

        for (let propKey of propKeys) {
            // `yield` returns a value and then pauses
            // the generator. Later, execution continues
            // where it was previously paused.
            yield [propKey, obj[propKey]];
        }
    }
</pre>

<p>How exactly <code>objectEntries()</code> works is explained later. It is used like this:</p>

<pre class="javascript">
    let jane = { first: 'Jane', last: 'Doe' };
    for (let [key,value] of objectEntries(jane)) {
        console.log(`${key}: ${value}`);
    }
    // Output:
    // first: Jane
    // last: Doe
</pre>

<h4 id="blocking_on_asynchronous_function_calls">Blocking on asynchronous function calls</h4>

<p>In the following code, I use <a href="https://github.com/tj/co">the control flow library co</a> to asynchronously retrieve two JSON files. Note how, in line (A), execution blocks (waits) until the result of <code>Promise.all()</code> is ready. That means that the code looks synchronous while performing asynchronous operations.</p>

<pre class="javascript">
    co(function* () {
        try {
            let [croftStr, bondStr] = yield Promise.all([  // (A)
                getFile('http://localhost:8000/croft.json'),
                getFile('http://localhost:8000/bond.json'),
            ]);
            let croftJson = JSON.parse(croftStr);
            let bondJson = JSON.parse(bondStr);

            console.log(croftJson);
            console.log(bondJson);
        } catch (e) {
            console.log('Failure to read: ' + e);
        }
    });
</pre>

<p><code>getFile(url)</code> retrieves the file pointed to by <code>url</code>. Its implementation is shown later. I’ll also explain how <code>co</code> works.</p>

<h3 id="what_are_generators%3F">What are generators?</h3>

<p><em>Generators</em> are functions that can be paused and resumed, which enables a variety of applications.</p>

<p>As a first example, consider the following generator function whose name is <code>genFunc</code>:</p>

<pre class="javascript">
    function* genFunc() {
        console.log('First');
        yield; // (A)
        console.log('Second'); // (B)
    }
</pre>

<p>Two things distinguish <code>genFunc</code> from a normal function declaration:</p>

<ul>
<li>It starts with the “keyword” <code>function*</code>.</li>
<li>It is paused in the middle via <code>yield</code>.</li>
</ul>

<p>Calling <code>genFunc</code> does not execute it. Instead, it returns a so-called <em>generator object</em> that lets us control <code>genFunc</code>’s execution:</p>

<pre class="repl">
    &gt; let genObj = genFunc();
</pre>

<p><code>genFunc()</code> is initially suspended at the beginning of its body. The method <code>genObj.next()</code> continues the execution of <code>genFunc</code>, until the next <code>yield</code>:</p>

<pre class="repl">
    &gt; genObj.next()
    First
    { value: undefined, done: false }
</pre>

<p>As you can see in the last line, <code>genObj.next()</code> also returns an object. Let’s ignore that for now. It will matter once we look at generators as iterators.</p>

<p><code>genFunc</code> is now paused in line (A). If we call <code>next()</code> again, execution resumes and line (B) is executed:</p>

<pre class="repl">
    &gt; genObj.next()
    Second
    { value: undefined, done: true }
</pre>

<p>Afterwards, the function is finished, execution has left the body and further calls of <code>genObj.next()</code> have no effect.</p>

<h4 id="ways_of_creating_generators">Ways of creating generators</h4>

<p>There are four ways in which you can create generators:</p>

<ol>
<li><p>Via a generator function declaration:</p>
<pre class="javascript">
    function* genFunc() { ··· }
    let genObj = genFunc();
</pre>
</li>
<li><p>Via a generator function expression:</p>
<pre class="javascript">
    const genFunc = function* () { ··· };
    let genObj = genFunc();
</pre>
</li>
<li><p>Via a generator method definition in an object literal:</p>
<pre class="javascript">
    let obj = {
        * generatorMethod() {
            ···
        }
    };
    let genObj = obj.generatorMethod();
</pre>
</li>
<li><p>Via a generator method definition in a class definition (which can be a class declaration or a class expression <a class="ptr">[11]</a>):</p>
<pre class="javascript">
    class MyClass {
        * generatorMethod() {
            ···
        }
    }
    let myInst = new MyClass();
    let genObj = myInst.generatorMethod();
</pre>
</li>
</ol>

<h4 id="roles_played_by_generators">Roles played by generators</h4>

<p>Generators can play three roles:</p>

<ol>
<li><p>Iterators (data producers): Each <code>yield</code> can return a value via <code>next()</code>, which means that generators can produce sequences of values via loops and recursion. Due to generator objects implementing the interface <code>Iterable</code> <a class="ptr">[5]</a>, these sequences can be processed by any ECMAScript 6 construct that supports iterables. Two examples are: <code>for-of</code> loops and the spread operator (<code>...</code>).</p>
</li>
<li><p>Observers (data consumers): <code>yield</code> can also receive a value from <code>next()</code> (via a parameter). That means that generators become data consumers that pause until a new value is pushed into them via <code>next()</code>.</p>
</li>
<li><p>Coroutines (data producers and consumers): Given that generators are pausable and can be both data producers and data consumers, not much work is needed to turn them into coroutines (cooperatively multitasked tasks).</p>
</li>
</ol>

<p>The next sections provide deeper explanations of these roles.</p>

<h3 id="generators_as_iterators_%28data_production%29">Generators as iterators (data production)</h3>

<p>As explained before, generator objects can be data producers, data consumers or both. This section looks at them as data producers, where they implement both the interfaces <code>Iterable</code> and <code>Iterator</code> (shown below). Note that that means that the result of a generator function is both an iterable and an iterator. The full interface of generator objects will be shown later.</p>

<pre class="javascript">
    interface Iterable {
        [Symbol.iterator]() : Iterator;
    }
    interface Iterator {
        next() : IteratorResult;
        return?(value? : any) : IteratorResult;
    }
    interface IteratorResult {
        value : any;
        done : boolean;
    }
</pre>

<p>A generator function produces a sequence of values via <code>yield</code>, a data consumer consumes thoses values via the iterator method <code>next()</code>. For example, the following generator function produces the values <code>'a'</code> and <code>'b'</code>:</p>

<pre class="javascript">
    function* genFunc() {
        yield 'a';
        yield 'b';
    }
</pre>

<p>This interaction shows how to retrieve the yielded values via the generator object <code>genObj</code>:</p>

<pre class="repl">
    &gt; let genObj = genFunc();
    &gt; genObj.next()
    { value: 'a', done: false }
    &gt; genObj.next()
    { value: 'b', done: false }
    &gt; genObj.next() // end of sequence reached
    ( value: undefined, done: true }
</pre>

<h4 id="ways_of_iterating_over_a_generator">Ways of iterating over a generator</h4>

<p>As generator objects are iterable, ES6 language constructs that support iterables can be applied to them. The following three ones are especially important.</p>

<p>First, the <code>for-of</code> loop:</p>

<pre class="javascript">
    for (let x of genFunc()) {
        console.log(x);
    }
    // Output:
    // a
    // b
</pre>

<p>Second, the spread operator (<code>...</code>), which turns iterated sequences into elements of an array (consult <a class="ptr">[7]</a> for more information on this operator):</p>

<pre class="javascript">
    let arr = [...genFunc()]; // ['a', 'b']
</pre>

<p>Third, destructuring <a class="ptr">[6]</a>:</p>

<pre class="repl">
    &gt; let [x, y] = genFunc();
    &gt; x
    'a'
    &gt; y
    'b'
</pre>

<h4 id="returning_from_a_generator">Returning from a generator</h4>

<p>The previous generator function did not contain an explicit <code>return</code>. An implicit <code>return</code> is equivalent to returning <code>undefined</code>. Let’s examine a generator with an explicit <code>return</code>:</p>

<pre class="javascript">
    function* genFuncWithReturn() {
        yield 'a';
        yield 'b';
        return 'result';
    }
</pre>

<p>The returned value shows up in the last object returned by <code>next()</code>, whose property <code>done</code> is <code>true</code>:</p>

<pre class="repl">
    &gt; let genObjWithReturn = genFuncWithReturn();
    &gt; genObjWithReturn.next()
    { value: 'a', done: false }
    &gt; genObjWithReturn.next()
    { value: 'b', done: false }
    &gt; genObjWithReturn.next()
    { value: 'result', done: true }
</pre>

<p>However, most constructs that work with iterables ignore the value inside the <code>done</code> object:</p>

<pre class="javascript">
    for (let x of genFuncWithReturn()) {
        console.log(x);
    }
    // Output:
    // a
    // b

    let arr = [...genFuncWithReturn()]; // ['a', 'b']
</pre>

<p><code>yield*</code>, an operator for making recursive generator calls, does consider values inside <code>done</code> objects. It is explained later.</p>

<h4 id="example%3A_iterating_over_properties">Example: iterating over properties</h4>

<p>Let’s look at an example that demonstrates how convenient generators are for implementing iterables. The following function, <code>objectEntries()</code>, returns an iterable over the properties of an object:</p>

<pre class="javascript">
    function* objectEntries(obj) {
        // In ES6, you can use strings or symbols as property keys,
        // Reflect.ownKeys() retrieves both
        let propKeys = Reflect.ownKeys(obj);

        for (let propKey of propKeys) {
            yield [propKey, obj[propKey]];
        }
    }
</pre>

<p>This function enables you to iterate over the properties of an object <code>jane</code> via the <code>for-of</code> loop:</p>

<pre class="javascript">
    let jane = { first: 'Jane', last: 'Doe' };
    for (let [key,value] of objectEntries(jane)) {
        console.log(`${key}: ${value}`);
    }
    // Output:
    // first: Jane
    // last: Doe
</pre>

<p>For comparison – an implementation of <code>objectEntries()</code> that doesn’t use generators is much more complicated:</p>

<pre class="javascript">
    function objectEntries(obj) {
        let index = 0;
        let propKeys = Reflect.ownKeys(obj);

        return {
            [Symbol.iterator]() {
                return this;
            },
            next() {
                if (index &lt; propKeys.length) {
                    let key = propKeys[index];
                    index++;
                    return { value: [key, obj[key]] };
                } else {
                    return { done: true };
                }
            }
        };
    }
</pre>

<h4 id="recursion_via_yield*_%28for_output%29">Recursion via <code>yield*</code> (for output)</h4>

<p>The <code>yield*</code> operator lets you call another generator from within a generator, as if you made a function call. For now, I only explain how this works if both generators produce output, I’ll later explain how things work if input is involved.</p>

<p>How can one generator recursively call another generator? Let’s assume you have written a generator function <code>foo</code>:</p>

<pre class="javascript">
    function* foo() {
        yield 'a';
        yield 'b';
    }
</pre>

<p>How would you call <code>foo</code> from another generator function <code>bar</code>? The following approach does not work!</p>

<pre class="javascript">
    function* bar() {
        yield 'x';
        foo(); // does nothing!
        yield 'y';
    }
</pre>

<p>Calling <code>foo()</code> returns an object, but does not actually execute <code>foo()</code>. That’s why ECMAScript 6 has the operator <code>yield*</code> for making recursive generator calls:</p>

<pre class="javascript">
    function* bar() {
        yield 'x';
        yield* foo();
        yield 'y';
    }

    // Collect all values yielded by bar() in an array
    let arr = [...bar()];
        // ['x', 'a', 'b', 'y']
</pre>

<p>Internally, <code>yield*</code> works roughly as follows:</p>

<pre class="javascript">
    function* bar() {
        yield 'x';
        for (let value of foo()) {
            yield value;
        }
        yield 'y';
    }
</pre>

<p>The operand of <code>yield*</code> does not have to be a generator object, it can be any iterable:</p>

<pre class="javascript">
    function* bla() {
        yield 'sequence';
        yield* ['of', 'yielded'];
        yield 'values';
    }

    let arr = [...bla()];
        // ['sequence', 'of', 'yielded', 'values']
</pre>

<h5 id="yield*_considers_end-of-iteration_values"><code>yield*</code> considers end-of-iteration values</h5>

<p>Most constructs that support iterables ignore the value included in the end-of-iteration object (whose property <code>done</code> is <code>true</code>). Generators provide that value via <code>return</code>. The result of <code>yield*</code> is the end-of-iteration value:</p>

<pre class="javascript">
    function* genFuncWithReturn() {
        yield 'a';
        yield 'b';
        return 'The result';
    }
    function* logReturned(genObj) {
        let result = yield* genObj;
        console.log(result); // (A)
    }
</pre>

<p>If we want to get to line (A), we first must iterate over all values yielded by <code>logReturned()</code>:</p>

<pre class="repl">
    &gt; [...logReturned(genFuncWithReturn())]
    The result
    [ 'a', 'b' ]
</pre>

<h5 id="iterating_over_trees">Iterating over trees</h5>

<p>Iterating over a tree with recursion is simple, writing an iterator for a tree with traditional means is complicated. That’s why generators shine here: they let you implement an iterator via recursion. As an example, consider the following data structure for binary trees. It is iterable, because it has a method whose key is <code>Symbol.iterator</code>. That method is a generator method and returns an iterator when called.</p>

<pre class="javascript">
    class BinaryTree {
        constructor(value, left=null, right=null) {
            this.value = value;
            this.left = left;
            this.right = right;
        }

        /** Prefix iteration */
        * [Symbol.iterator]() {
            yield this.value;
            if (this.left) {
                yield* this.left;
            }
            if (this.right) {
                yield* this.right;
            }
        }
    }
</pre>

<p>The following code creates a binary tree and iterates over it via <code>for-of</code>:</p>

<pre class="javascript">
    let tree = new BinaryTree('a',
        new BinaryTree('b',
            new BinaryTree('c'),
            new BinaryTree('d')),
        new BinaryTree('e'));

    for (let x of tree) {
        console.log(x);
    }
    // Output:
    // a
    // b
    // c
    // d
    // e
</pre>

<h4 id="you_can_only_yield_in_generators">You can only <code>yield</code> in generators</h4>

<p>A significant limitation of generators is that you can only yield while you are (statically) inside a generator function. That is, yielding in callbacks doesn’t work:</p>

<pre class="javascript">
    function* genFunc() {
        ['a', 'b'].forEach(x =&gt; yield x); // SyntaxError
    }
</pre>

<p><code>yield</code> is not allowed inside non-generator functions, which is why the previous code causes a syntax error. In this case, it is easy to rewrite the code so that it doesn’t use callbacks (as shown below). But unfortunately that isn’t always possibe.</p>

<pre class="javascript">
    function* genFunc() {
        for (let x of ['a', 'b']) {
            yield x; // OK
        }
    }
</pre>

<p>The upsides of this limitation are explained later: they make generators easier to implement and compatible with event loops.</p>

<h3 id="generators_as_observers_%28data_consumption%29">Generators as observers (data consumption)</h3>

<p>As consumers of data, generator objects conform to the second half of the generator interface, <code>Observer</code>:</p>

<pre class="javascript">
    interface Observer {
        next(value? : any) : void;
        return(value? : any) : void;
        throw(error) : void;
    }
</pre>

<p>As an observer, a generator pauses until it receives input. There are three kinds of input, transmitted via the methods specified by the interface:</p>

<ul>
<li><code>next()</code> sends normal input.</li>
<li><code>return()</code> terminates the generator.</li>
<li><code>throw()</code> signals an error.</li>
</ul>

<h4 id="sending_values_via_next%28%29">Sending values via <code>next()</code></h4>

<p>If you use a generator as an observer, you send values to it via <code>next()</code> and it receives those values via <code>yield</code>:</p>

<pre class="javascript">
    function* dataConsumer() {
        console.log('Started');
        console.log(`1. ${yield}`); // (A)
        console.log(`2. ${yield}`);
        return 'result';
    }
</pre>

<p>Let’s use this generator interactively. First, we create a generator object:</p>

<pre class="repl">
    &gt; let genObj = dataConsumer();
</pre>

<p>We now call <code>genObj.next()</code>, which starts the generator. Execution continues until the first <code>yield</code>, which is where the generator pauses. The result of <code>next()</code> is the value yielded in line (A) (<code>undefined</code>, because <code>yield</code> doesn’t have an operand). In this section, we are not interested in what <code>next()</code> returns, because we only use it to send values, not to retrieve values.</p>

<pre class="javascript">
    &gt; genObj.next()
    Started
    { value: undefined, done: false }
</pre>

<p>We call <code>next()</code> two more times, in order to send the value <code>'a'</code> to the first <code>yield</code> and the value <code>'b'</code> to the second <code>yield</code>:</p>

<pre class="javascript">
    &gt; genObj.next('a')
    1. a
    { value: undefined, done: false }

    &gt; genObj.next('b')
    2. b
    { value: 'result', done: true }
</pre>

<p>The result of the last <code>next()</code> is the value returned from <code>dataConsumer()</code>. <code>done</code> being <code>true</code> indicates that the generator is finished.</p>

<p>Unfortunately, <code>next()</code> is asymmetric, but that can’t be helped: It always sends a value to the currently suspended <code>yield</code>, but returns the operand of the following <code>yield</code>.</p>

<h5 id="the_first_next%28%29">The first <code>next()</code></h5>

<p>When using a generator as an observer, it is important to note that the only purpose of the first invocation of <code>next()</code> is to start the observer. It is only ready for input afterwards, because this first invocation has advanced execution to the first <code>yield</code>. Therefore, you can’t send input via the first <code>next()</code> – you even get an error if you do:</p>

<pre class="repl">
    &gt; function* g() { yield }
    &gt; g().next('hello')
    TypeError: attempt to send 'hello' to newborn generator
</pre>

<p>The following utility function fixes this issue:</p>

<pre class="javascript">
    /**
     * Returns a function that, when called,
     * returns a generator object that is immediately
     * ready for input via `next()`
     */
    function coroutine(generatorFunction) {
        return function (...args) {
            let generatorObject = generatorFunction(...args);
            generatorObject.next();
            return generatorObject;
        };
    }
</pre>

<p>To see how <code>coroutine()</code> works, let’s compare a wrapped generator with a normal one:</p>

<pre class="javascript">
    const wrapped = coroutine(function* () {
        console.log(`First input: ${yield}`);
        return 'DONE';
    });
    const normal = function* () {
        console.log(`First input: ${yield}`);
        return 'DONE';
    };
</pre>

<p>The wrapped generator is immediately ready for input:</p>

<pre class="repl">
    &gt; wrapped().next('hello!')
    First input: hello!
</pre>

<p>The normal generator needs an extra <code>next()</code> until it is ready for input:</p>

<pre class="repl">
    &gt; let genObj = normal();
    &gt; genObj.next()
    { value: undefined, done: false }
    &gt; genObj.next('hello!')
    First input: hello!
    { value: 'DONE', done: true }
</pre>

<h4 id="yield_binds_loosely"><code>yield</code> binds loosely</h4>

<p><code>yield</code> binds very loosely, so that we don’t have to put its operand in parentheses:</p>

<pre class="javascript">
    yield a + b + c;
</pre>

<p>This is treated as:</p>

<pre class="javascript">
    yield (a + b + c);
</pre>

<p>Not as:</p>

<pre class="javascript">
    (yield a) + b + c;
</pre>

<p>As a consequence, many operators bind more tightly than <code>yield</code> and you have to put <code>yield</code> in parentheses if you want to use it as an operand. For example, you get a SyntaxError if you make an unparenthesized <code>yield</code> an operand of plus:</p>

<pre class="javascript">
    console.log('Hello' + yield); // SyntaxError
    console.log('Hello' + yield 123); // SyntaxError

    console.log('Hello' + (yield)); // OK
    console.log('Hello' + (yield 123)); // OK
</pre>

<p>You do not need parens if <code>yield</code> is a direct argument in a function or method call:</p>

<pre class="javascript">
    foo(yield 'a', yield 'b');
</pre>

<p>You also don’t need parens if you use <code>yield</code> on the right-hand side of an assignment:</p>

<pre class="javascript">
    let input = yield;
</pre>

<h5 id="grammar">Grammar</h5>

<p>The need for parens can be seen in the following grammar rules in the <a href="https://people.mozilla.org/~jorendorff/es6-draft.html#sec-expressions">ECMAScript 6 specification</a>. These rules describe how expressions are parsed. I list them here from general (loose binding, lower precedence) to specific (tight binding, higher precedence). Wherever a certain kind of expression is demanded, you can also use more specific ones. The opposite is not true. The hierarchy ends with <code>ParenthesizedExpression</code>, which means that you can mention any expression anywhere, if you put it in parentheses.</p>

<pre class="undefined">
    Expression :
        AssignmentExpression
        Expression , AssignmentExpression
    AssignmentExpression :
        ConditionalExpression
        YieldExpression
        ArrowFunction
        LeftHandSideExpression = AssignmentExpression
        LeftHandSideExpression AssignmentOperator AssignmentExpression

    ···

    AdditiveExpression :
        MultiplicativeExpression
        AdditiveExpression + MultiplicativeExpression
        AdditiveExpression - MultiplicativeExpression
    MultiplicativeExpression :
        UnaryExpression
        MultiplicativeExpression MultiplicativeOperator UnaryExpression

    ···

    PrimaryExpression :
        this
        IdentifierReference
        Literal
        ArrayLiteral
        ObjectLiteral
        FunctionExpression
        ClassExpression
        GeneratorExpression
        RegularExpressionLiteral
        TemplateLiteral
        ParenthesizedExpression
    ParenthesizedExpression :
        ( Expression )
</pre>

<p>The operands of an <code>AdditiveExpression</code> are an <code>AdditiveExpression</code> and a <code>MultiplicativeExpression</code>. Therefore, using a (more specific) <code>ParenthesizedExpression</code> as an operand is OK, but using a (more general) <code>YieldExpression</code> isn’t.</p>

<h4 id="return%28%29_and_throw%28%29"><code>return()</code> and <code>throw()</code></h4>

<p>Let’s recap how <code>next(x)</code> works (after the first invocation):</p>

<ol>
<li>The generator is currently suspended at a <code>yield</code> operator.</li>
<li>Send the value <code>x</code> to that <code>yield</code>, which means that it evaluates to <code>x</code>.</li>
<li>Proceed to the next <code>yield</code> or <code>return</code>:<ul>
<li><code>yield x</code> leads to <code>next()</code> returning with <code>{ value: x, done: false }</code></li>
<li><code>return x</code> leads to <code>next()</code> returning with <code>{ value: x, done: true }</code></li>
</ul>
</li>
</ol>

<p><code>return()</code> and <code>throw()</code> work similarly to <code>next()</code>, but they do something different in step 2:</p>

<ul>
<li><code>return(x)</code> executes <code>return x</code> at the location of <code>yield</code>.</li>
<li><code>throw(x)</code> executes <code>throw x</code> at the location of <code>yield</code>.</li>
</ul>

<h4 id="return%28%29_terminates_the_generator"><code>return()</code> terminates the generator</h4>

<p><code>return()</code> performs a <code>return</code> at the location of the <code>yield</code> that led to the last suspension of the generator. Let’s use the following generator function to see how that works.</p>

<pre class="javascript">
    function* genFunc1() {
        try {
            console.log('Started');
            yield; // (A)
        } finally {
            console.log('Exiting');
        }
    }
</pre>

<p>In the following interaction, we first use <code>next()</code> to start the generator and to proceed until the <code>yield</code> in line (A). Then we return from that location via <code>return()</code>.</p>

<pre class="repl">
    &gt; let genObj1 = genFunc1();
    &gt; genObj1.next()
    Started
    { value: undefined, done: false }
    &gt; genObj1.return('Result')
    Exiting
    { value: 'Result', done: true }
</pre>

<h5 id="preventing_termination">Preventing termination</h5>

<p>You can prevent <code>return()</code> from terminating the generator if you yield inside the <code>finally</code> clause (using a <code>return</code> statement in that clause is also possible):</p>

<pre class="javascript">
    function* genFunc2() {
        try {
            console.log('Started');
            yield;
        } finally {
            yield 'Not done, yet!';
        }
    }
</pre>

<p>This time, <code>return()</code> does not exit the generator function. Accordingly, the property <code>done</code> of the object it returns is <code>false</code>.</p>

<pre class="repl">
    &gt; let genObj2 = genFunc2();

    &gt; genObj2.next()
    Started
    { value: undefined, done: false }

    &gt; genObj2.return('Result')
    { value: 'Not done, yet!', done: false }
</pre>

<p>You can invoke <code>next()</code> one more time. Similarly to non-generator functions, the return value of the generator function is the value that was queued prior to entering the <code>finally</code> clause.</p>

<pre class="repl">
    &gt; genObj2.next()
    { value: 'Result', done: true }
</pre>

<h5 id="returning_from_a_newborn_generator">Returning from a newborn generator</h5>

<p>Returning a value from a <em>newborn</em> generator (that hasn’t started yet) is allowed:</p>

<pre class="repl">
    &gt; function* genFunc() {}
    &gt; genFunc().return('yes')
    { value: 'yes', done: true }
</pre>

<h4 id="throw%28%29_signals_an_error"><code>throw()</code> signals an error</h4>

<p><code>throw()</code> throws an exception at the location of the <code>yield</code> that led to the last suspension of the generator. Let’s examine how that works via the following generator function.</p>

<pre class="javascript">
    function* genFunc1() {
        try {
            console.log('Started');
            yield; // (A)
        } catch (error) {
            console.log('Caught: ' + error);
        }
    }
</pre>

<p>In the following interaction, we first use <code>next()</code> to start the generator and proceed until the <code>yield</code> in line (A). Then we throw an exception from that location.</p>

<pre class="javascript">
    &gt; let genObj1 = genFunc1();

    &gt; genObj1.next()
    Started
    { value: undefined, done: false }

    &gt; genObj1.throw(new Error('Problem!'))
    Caught: Error: Problem!
    { value: undefined, done: true }
</pre>

<p>The result of <code>throw()</code> (shown in the last line) stems from us leaving the function with an implicit <code>return</code>.</p>

<h5 id="uncaught_exceptions">Uncaught exceptions</h5>

<p>If you don’t catch the exception inside the generator, it is thrown by <code>throw()</code>. For example, the following generator function does not catch exceptions:</p>

<pre class="javascript">
    function* genFunc2() {
        console.log('Started');
        yield; // (A)
    }
</pre>

<p>If we use <code>throw()</code> to throw an instance of <code>Error</code> at line (A), the method itself throws that error:</p>

<pre class="repl">
    &gt; let genObj2 = genFunc2();
    &gt; genObj2.next()
    Started
    { value: undefined, done: false }
    &gt; genObj2.throw(new Error('Problem!'))
    Error: Problem!
</pre>

<h5 id="throwing_from_a_newborn_generator">Throwing from a newborn generator</h5>

<p>Throwing an exception in a <em>newborn</em> generator (that hasn’t started yet) is allowed:</p>

<pre class="repl">
    &gt; function* genFunc() {}
    &gt; genFunc().throw(new Error('Problem!'))
    Error: Problem!
</pre>

<h4 id="example%3A_processing_asynchronously_pushed_data">Example: processing asynchronously pushed data</h4>

<p>The fact that generators-as-observers pause while they wait for input makes them perfect for on-demand processing of data that is received asynchronously. The pattern for setting up a chain of generators for processing is as follows:</p>

<ul>
<li><p>First chain member: a normal function that has a parameter <code>target</code>, which is the generator object of the next element in the chain of generators. The function makes an asynchronous request and pushes the results to the target via <code>target.next()</code>.</p>
</li>
<li><p>Intermediate chain members: generators that have a parameter <code>target</code>. They receive data via <code>yield</code> and send data via <code>target.next()</code>.</p>
</li>
<li><p>Last chain member: a generator that has no parameter <code>target</code> and only receives data.</p>
</li>
</ul>

<p>As an example, let’s chain generators to process a file that is read asynchronously. The code shown in this section is a Node.js script that is executed via <code>babel-node</code> <a class="ptr">[8]</a>.</p>

<p>The following code sets up the chain, which starts with the normal function <code>readFile</code>, continues with the generators <code>splitLines</code> and <code>numberLines</code> and ends with the generator <code>printLines</code>:</p>

<pre class="javascript">
    let fileName = process.argv[2];
    readFile(fileName, chain(splitLines, numberLines, printLines));
</pre>

<p>I’ll explain what these functions do when I show their code. The following helper function sets up a chain of generators: Starting with the last generator, each generator function is called and the resulting generator object is used to start the generator via an initial <code>next()</code>. If a generator has a successor, it receives the successor’s generator object via the parameter <code>target</code>. The result of <code>chain()</code> is the generator object of the first generator function (in our example: <code>splitLines</code>).</p>

<pre class="javascript">
    function chain(...generatorFuncs) {
        if (generatorFuncs.length &lt; 1) {
            throw new Error('Need at least 1 argument');
        }
        let generatorObject = generatorFuncs[generatorFuncs.length-1]();
        generatorObject.next(); // generator is now ready for input
        for (let i=generatorFuncs.length-2; i &gt;= 0; i--) {
            let generatorFunction = generatorFuncs[i];
            // Link current generator to successor
            generatorObject = generatorFunction(generatorObject);
            // Start the generator
            generatorObject.next();
        }
        return generatorObject;
    }
</pre>

<p><code>readFile()</code> is the non-generator function that starts everything.</p>

<pre class="javascript">
    import {createReadStream} from 'fs';

    /**
     * Create an asynchronous ReadStream for the file whose name
     * is `fileName` and feed it to the generator object `target`.
     *
     * @see ReadStream https://nodejs.org/api/fs.html#fs_class_fs_readstream
     */
    function readFile(fileName, target) {
        let readStream = createReadStream(fileName,
            { encoding: 'utf8', bufferSize: 1024 });
        readStream.on('data', buffer =&gt; {
            let str = buffer.toString('utf8');
            target.next(str);
        });
        readStream.on('end', () =&gt; {
            // Signal end of output sequence
            target.return();
        });
    }
</pre>

<p>The chain of generators starts with <code>splitLines</code>:</p>

<pre class="javascript">
    /**
     * Turns a sequence of text chunks into a sequence of lines
     * (where lines are separated by newlines)
     */
    function* splitLines(target) {
        let previous = '';
        try {
            while (true) {
                previous += yield;
                let eolIndex;
                while ((eolIndex = previous.indexOf('\n')) &gt;= 0) {
                    let line = previous.slice(0, eolIndex);
                    target.next(line);
                    previous = previous.slice(eolIndex+1);
                }
            }
        } finally {
            // Handle the end of the input sequence
            // (signaled via `return()`)
            if (previous.length &gt; 0) {
                target.next(previous);
            }
            // Signal end of output sequence
            target.return();
        }
    }
</pre>

<p>Note an important pattern:</p>

<ul>
<li><code>readFile</code> uses the generator object method <code>return()</code> to signal the end of the sequence of chunks that it sends.</li>
<li><code>readFile</code> sends that signal while <code>splitLines</code> is waiting for input via <code>yield</code>, inside an infinite loop. <code>return()</code> breaks from that loop.</li>
<li><code>splitLines</code> uses a <code>finally</code> clause to handle the end-of-sequence.</li>
</ul>

<p>The next generator is <code>numberLines</code>:</p>

<pre class="javascript">
    /**
     * Prefixes numbers to a sequence of lines
     */
    function* numberLines(target) {
        try {
            for (let lineNo = 0; ; lineNo++) {
                let line = yield;
                target.next(`${lineNo}: ${line}`);
            }
        } finally {
            // Signal end of output sequence
            target.return();
        }
    }
</pre>

<p>The last generator is <code>printLines</code>:</p>

<pre class="javascript">
    /**
     * Receives a sequence of lines (without newlines)
     * and logs them (adding newlines).
     */
    function* printLines() {
        while (true) {
            let line = yield;
            console.log(line);
        }
    }
</pre>

<p>The neat thing about this code is that everything happens lazily (on demand): lines are split, numbered and printed as they arrive; we don’t have to wait for all of the text before we can start printing.</p>

<h4 id="yield*%3A_the_full_story"><code>yield*</code>: the full story</h4>

<p>So far, we have only seen one aspect of <code>yield</code>: it propagates yielded values from the callee to the caller. Now that we are interested in generators receiving input, another aspect becomes relevant: <code>yield*</code> also forwards input received by the caller to the callee.</p>

<p>I’ll first explain the complete semantics of <code>yield*</code> by showing how you’d implemented it in JavaScript. Then I give simple examples where input received by the caller via <code>next()</code>, <code>return()</code> and <code>throw()</code> is forwarded to the callee.</p>

<p>The following statement:</p>

<pre class="javascript">
    let yieldStarResult = yield* calleeFunc();
</pre>

<p>is roughly equivalent to:</p>

<pre class="javascript">
    let yieldStarResult;

    let calleeObj = calleeFunc();
    let prevReceived = undefined;
    while (true) {
        try {
            // Forward input previously received
            let item = calleeObj.next(prevReceived);
            if (item.done) {
                yieldStarResult = item.value;
                break;
            }
            prevReceived = yield item.value;
        } catch (e) {
            // Pretend `return` can be caught like an exception
            if (e instanceof Return) {
                // Forward input received via return()
                calleeObj.return(e.returnedValue);
                return e.returnedValue; // “re-throw”
            } else {
                // Forward input received via throw()
                calleeObj.throw(e); // may throw
            }
        }
    }
</pre>

<p>To keep things simple, several things are missing in this code:</p>

<ul>
<li><p>The operand of <code>yield*</code> can be any iterable value.</p>
</li>
<li><p><code>return()</code> and <code>throw()</code> are optional iterator methods. We should only call them if they exist.</p>
</li>
<li><p>If an exception is received and <code>throw()</code> does not exist, but <code>return()</code> does then <code>return()</code> is called (before throwing an exception) to give <code>calleeObject</code> the opportunity to clean up.</p>
</li>
<li><p><code>calleeObj</code> can refuse to close, by returning an object whose property <code>done</code> is <code>false</code>. Then the caller also has to refuse to close and <code>yield*</code> must continue to iterate.</p>
</li>
</ul>

<h5 id="example%3A_yield*_forwards_next%28%29">Example: <code>yield*</code> forwards <code>next()</code></h5>

<p>The following generator function <code>caller()</code> invokes the generator function <code>callee()</code> via <code>yield*</code>.</p>

<pre class="javascript">
    function* callee() {
        console.log('callee: ' + (yield));
    }
    function* caller() {
        while (true) {
            yield* callee();
        }
    }
</pre>

<p><code>callee</code> logs values received via <code>next()</code>, which allows us to check whether it receives the value <code>'a'</code> and <code>'b'</code> that we send to <code>caller</code>.</p>

<pre class="repl">
    &gt; let callerObj = caller();

    &gt; callerObj.next() // start
    { value: undefined, done: false }

    &gt; callerObj.next('a')
    callee: a
    { value: undefined, done: false }

    &gt; callerObj.next('b')
    callee: b
    { value: undefined, done: false }
</pre>

<h5 id="example%3A_yield*_forwards_throw%28%29">Example: <code>yield*</code> forwards <code>throw()</code></h5>

<p>Let’s use the following code to demonstrate how <code>throw()</code> works while <code>yield*</code> is delegating to another generator.</p>

<pre class="javascript">
    function* callee() {
        try {
            yield 'b'; // (A)
            yield 'c';
        } finally {
            console.log('finally callee');
        }
    }
    function* caller() {
        try {
            yield 'a';
            yield* callee();
            yield 'd';
        } catch (e) {
            console.log('[caller] ' + e);
        }
    }
</pre>

<p>We first create a generator object and advance until line (A).</p>

<pre class="repl">
    &gt; let genObj = caller();

    &gt; genObj.next().value
    'a'
    &gt; genObj.next().value
    'b'
</pre>

<p>In that line, we throw an exception:</p>

<pre class="repl">
    &gt; genObj.throw(new Error('Problem!'))
    finally callee
    [caller] Error: Problem!
    { value: undefined, done: true }
</pre>

<p><code>callee</code> doesn’t catch the exception, which is why it is propagated into <code>caller</code>, where it is logged before <code>caller</code> finishes.</p>

<h5 id="example%3A_yield*_forwards_return%28%29">Example: <code>yield*</code> forwards <code>return()</code></h5>

<p>Let’s use the following code to demonstrate how <code>return()</code> works while <code>yield*</code> is delegating to another generator.</p>

<pre class="javascript">
    function* callee() {
        try {
            yield 'b';
            yield 'c';
        } finally {
            console.log('finally callee');
        }
    }
    function* caller() {
        try {
            yield 'a';
            yield* callee();
            yield 'd';
        } finally {
            console.log('finally caller');
        }
    }
</pre>

<p>Destructuring closes an iterator via <code>return()</code> if one doesn’t iterate until the end:</p>

<pre class="javascript">
    let [x, y] = caller(); // ['a', 'b']

    // Output:
    // finally callee
    // finally caller
</pre>

<p>Interestingly, the <code>return()</code> is sent to <code>caller</code> and forwarded to <code>callee</code> (which it terminates early), but then also terminates <code>caller</code> (which is what someone invoking <code>return()</code> would expect). That is, <code>return</code> is propagated much like an exception.</p>

<h5 id="how_to_think_about_yield*">How to think about <code>yield*</code></h5>

<p>There are two ways to think about <code>yield*</code>:</p>

<ul>
<li>As a function call from generator to generator.</li>
<li>In order to understand <code>return()</code>, it helps to ask yourself: what should happen if I copy-pasted the code of the callee function into the code of the caller function.</li>
</ul>

<h3 id="generators_as_coroutines_%28cooperative_multitasking%29">Generators as coroutines (cooperative multitasking)</h3>

<p>We have seen generators being used as either sources or sinks of data. For many applications, it’s good practice to strictly separate these two roles, because it keeps things simpler. This section describes the full generator interface (which combines both roles) and one application where both roles are needed: cooperative multitasking, where tasks must be able to both send and receive information.</p>

<h4 id="the_full_generator_interface">The full generator interface</h4>

<p>The full interface of generator objects, <code>Generator</code>, handles both output and input and combines two interfaces that we have seen previously: <code>Iterator</code> for output and <code>Observer</code> for input.</p>

<pre class="javascript">
    interface Iterator { // data producer
        next() : IteratorResult;
        return?(value? : any) : IteratorResult;
    }

    interface Observer { // data consumer
        next(value? : any) : void;
        return(value? : any) : void;
        throw(error) : void;
    }
</pre>

<p>This is the full interface of generator objects (<a href="https://people.mozilla.org/~jorendorff/es6-draft.html#sec-properties-of-generator-prototype">as described by the ECMAScript language specification</a>):</p>

<pre class="javascript">
    interface Generator {
        next(value? : any) : IteratorResult;
        throw(value? : any) : IteratorResult;
        return(value? : any) : IteratorResult;
    }
    interface IteratorResult {
        value : any;
        done : boolean;
    }
</pre>

<h4 id="cooperative_multitasking">Cooperative multitasking</h4>

<p>Cooperative multitasking is an application of generators where we need them to handle both output and input. Before we get into how that works, let’s first review the current state of parallelism in JavaScript <a class="ptr">[9]</a>.</p>

<p>JavaScript runs in a single process. There are two ways in which this limitation is being abolished:</p>

<ul>
<li><p>Multiprocessing: <em>Web Workers</em> let you run JavaScript in multiple processes. Shared access to data is one of the biggest pitfalls of multiprocessing. Web Workers avoid it by not sharing any data. That is, if you want a Web Worker to have a piece of data, you must send it a copy or transfer your data to it (after which you can’t access it anymore).</p>
</li>
<li><p>Cooperative multitasking: There are various patterns and libraries that experiment with cooperative multitasking. Multiple tasks are run, but only one at a time. Each task must explicitly suspend itself, giving it full control over when a task switch happens. In these experiments, data is often shared between tasks. But due to explicit suspension, there are few risks.</p>
</li>
</ul>

<p>Two use cases benefit from cooperative multitasking, because they involve control flows that are mostly sequential, anyway, with occasional pauses:</p>

<ul>
<li>Asynchronous computations: A task blocks (pauses) until it receives the result of a long-running computation.</li>
<li>Streams: A task sequentially processes a stream of data and pauses if there is no data available.</li>
</ul>

<p>For binary streams, WHATWG is currently working on a <a href="https://streams.spec.whatwg.org/">standard proposal</a> that is based on callbacks and promises.</p>

<p>For streams of data, Communicating Sequential Processes (CSP) are an interesting solution. A generator-based CSP library is covered later in this blog post.</p>

<p>For asynchronous computations, Promises <a class="ptr">[10]</a> have become popular and are included in ECMAScript 6.</p>

<h5 id="simplifying_asynchronous_code_via_generators">Simplifying asynchronous code via generators</h5>

<p>Several promise-based libraries simplify asynchronous code via generators. Generators are ideal as clients of promises, because they can be suspended until a result arrives.</p>

<p>The following example demonstrates what that looks like if one uses <a href="https://github.com/tj/co">the library <em>co</em></a> by T.J. Holowaychuk. We need two libraries (if we run Node.js code via babel-node <a class="ptr">[8]</a>):</p>

<pre class="javascript">
    require('isomorphic-fetch'); // polyfill
    let co = require('co');
</pre>

<p><code>co</code> is the actual library for cooperative multitasking, <code>isomorphic-fetch</code> is a polyfill for the new promise-based <code>fetch</code> API (a replacement of <code>XMLHttpRequest</code>; read “<a href="http://jakearchibald.com/2015/thats-so-fetch/">That's so fetch!</a>” by Jake Archibald for more information). <code>fetch</code> makes it easy to write a function <code>getFile</code> that returns the text of a file at a <code>url</code> via a Promise:</p>

<pre class="javascript">
    function getFile(url) {
        return fetch(url)
            .then(request =&gt; request.text());
    }
</pre>

<p>We now have all the ingredients to use <code>co</code>. The following task reads the texts of two files, parses the JSON inside them and logs the result.</p>

<pre class="javascript">
    co(function* () {
        try {
            let [croftStr, bondStr] = yield Promise.all([  // (A)
                getFile('http://localhost:8000/croft.json'),
                getFile('http://localhost:8000/bond.json'),
            ]);
            let croftJson = JSON.parse(croftStr);
            let bondJson = JSON.parse(bondStr);

            console.log(croftJson);
            console.log(bondJson);
        } catch (e) {
            console.log('Failure to read: ' + e);
        }
    });
</pre>

<p>Note how nicely synchronous this code looks, even though it makes an asynchronous call in line (A). A generator-as-task makes an async call by yielding a promise to the scheduler function <code>co</code>. The yielding pauses the generator. Once the promise returns a result, the scheduler resumes the generator by passing it the result via <code>next()</code>. A simple version of <code>co</code> looks as follows.</p>

<pre class="javascript">
    function co(genFunc) {
        let genObj = genFunc();
        run();

        function run(promiseResult = undefined) {
            let item = genObj.next(promiseResult);
            if (!item.done) {
                // A promise was yielded
                item.value
                .then(result =&gt; run(result))
                .catch(error =&gt; {
                    genObj.throw(error);
                });
            }
        }
    }
</pre>

<h4 id="the_limitations_of_cooperative_multitasking_via_generators">The limitations of cooperative multitasking via generators</h4>

<p><em>Coroutines</em> are cooperatively multitasked tasks that have no limitations: Inside a coroutine, any function can suspend the whole coroutine (the function activation itself, the activation of the function’s caller, the caller’s caller, etc.).</p>

<p>In contrast, you can only suspend a generator from directly within a generator and only the current function activation is suspended. Due to these limitations, generators are occasionally called <em>shallow coroutines</em> <a class="ptr">[3]</a>.</p>

<h5 id="the_benefits_of_the_limitations_of_generators">The benefits of the limitations of generators</h5>

<p>The limitations of generators have two main benefits:</p>

<ul>
<li><p>Generators are compatible with <em>event loops</em>, which provide simple cooperative multitasking in browsers. I’ll explain the details momentarily.</p>
</li>
<li><p>Generators are relatively easy to implement, because only a single function activation needs to be suspended and because browsers can continue to use event loops.</p>
</li>
</ul>

<p>JavaScript already has a very simple style of cooperative multitasking: the event loop <a class="ptr">[9]</a>, which schedules the execution of tasks in a queue. Each task is started by calling a function and finished once that function is finished (that’s a simplification of how things actually work, but it’ll do for now). Events, <code>setTimeout()</code> and other mechanisms add tasks to the queue.</p>

<p>This style of multitasking makes one important guarantee: <em>run to completion</em>; every function can rely on not being interrupted by another task until it is finished. Functions become transactions and can perform complete algorithms without anyone seeing the data they operate on in an itermediate state. Concurrent access to shared data makes multitasking complicated and is not allowed by JavaScript’s concurrency model. That’s why run to completion is a good thing.</p>

<p>Alas, coroutines prevent run to completion, because any function could suspend its caller. For example, the following algorithm consists of multiple steps:</p>

<pre class="undefined">
    step1(sharedData);
    step2(sharedData);
    lastStep(sharedData);
</pre>

<p>If <code>step2</code> was to suspend the algorithm, other tasks could run before the last step of the algorithm is performed. Those tasks could contain other parts of the application which would see <code>sharedData</code> in an unfinished state.</p>

<p>Generators preserve run to completion, they only suspend themselves and return to their caller. <code>co</code> and similar libraries give you most of the power of coroutines:</p>

<ul>
<li>They provide schedulers for tasks defined via generators.</li>
<li>Tasks start with generators and can thus be fully suspended.</li>
<li>A recursive (generator) function call is only suspendable if it is done via <code>yield*</code>. That gives callers control over suspension.</li>
</ul>

<h3 id="examples_of_generators">Examples of generators</h3>

<p>This section gives several examples of what generators can be used for.</p>

<h4 id="implementing_iterables_via_generators_2">Implementing iterables via generators</h4>

<p>In the blog post “<a href="http://www.2ality.com/2015/02/es6-iteration.html">Iterables and iterators in ECMAScript 6</a>”, I implemented several iterables “by hand”. In this section, I use generators, instead.</p>

<h5 id="the_iterable_combinator_take%28%29">The iterable combinator <code>take()</code></h5>

<p><code>take()</code> converts a (potentially infinite) sequence of iterated values into a sequence of length <code>n</code>:</p>

<pre class="javascript">
    function* take(n, iterable) {
        for (let x of iterable) {
            if (n &lt;= 0) return;
            n--;
            yield x;
        }
    }
</pre>

<p>The following is an example of using it:</p>

<pre class="javascript">
    let arr = ['a', 'b', 'c', 'd'];
    for (let x of take(2, arr)) {
        console.log(x);
    }
    // Output:
    // a
    // b
</pre>

<p>An implementation of <code>take()</code> without generators is more complicated:</p>

<pre class="javascript">
    function take(n, iterable) {
        let iter = iterable[Symbol.iterator]();
        return {
            [Symbol.iterator]() {
                return this;
            },
            next() {
                if (n &gt; 0) {
                    n--;
                    return iter.next();
                } else {
                    iter.return()
                    return { done: true };
                }
            },
            return() {
                n = 0;
                iter.return();
            }
        };
    }
</pre>

<p>Note that the iterable combinator <code>zip()</code> does not profit much from being implemented via a generator, because multiple iterables are involved (and <code>for-of</code> can’t be used).</p>

<h5 id="infinite_iterables">Infinite iterables</h5>

<p><code>naturalNumbers()</code> returns an iterable over all natural numbers:</p>

<pre class="javascript">
    function* naturalNumbers() {
        for (let n=0;; n++) {
            yield n;
        }
    }
</pre>

<p>This function is often used in conjunction with a combinator:</p>

<pre class="javascript">
    for (let x of take(3, naturalNumbers())) {
        console.log(x);
    }
    // Output
    // 0
    // 1
    // 2
</pre>

<p>One last time, I show the non-generator implementation, so you can compare:</p>

<pre class="javascript">
    function naturalNumbers() {
        let n = 0;
        return {
            [Symbol.iterator]() {
                return this;
            },
            next() {
                return { value: n++ };
            }
        }
    }
</pre>

<h5 id="array-inspired_iterable_combinators%3A_map_filter">Array-inspired iterable combinators: <code>map</code>, <code>filter</code></h5>

<p>Arrays can be transformed via the methods <code>map</code> and <code>filter</code>. Those methods can be generalized to have iterables as input and iterables as output.</p>

<p>This is the generalized version of <code>map</code>:</p>

<pre class="javascript">
    function* map(iterable, mapFunc) {
        for (let x of iterable) {
            yield mapFunc(x);
        }
    }

    // Works with infinite iterables!
    let arr = [...take(4, map(naturalNumbers(), x =&gt; x * x))];
        // [0, 1, 4, 9]
</pre>

<p>This is the generalized version of <code>filter</code>:</p>

<pre class="javascript">
    function* filter(iterable, filterFunc) {
        for (let x of iterable) {
            if (filterFunc(x)) {
                yield x;
            }
        }
    }

    // Works with infinite iterables!
    let arr = [...take(4, filter(naturalNumbers(), x =&gt; (x % 2) === 0))];
        // [0, 2, 4, 6]
</pre>

<h4 id="generators_for_lazy_evaluation">Generators for lazy evaluation</h4>

<p>The next two examples show how generators can be used to process a stream of characters.</p>

<ul>
<li><p>The input is a stream of characters.</p>
</li>
<li><p>Step 1 – tokenize (characters → words): The characters are grouped into <em>words</em>, strings that match the regular expression <code>/^[A-Za-z0-9]$/</code>. Non-word characters are ignored, but they separate words. The input of this step is a stream of characters, the output a stream of words.</p>
</li>
<li><p>Step 2 – extract numbers (words → numbers): only keep words that match the regular expression <code>/^[0-9]+$/</code> and convert them to numbers.</p>
</li>
<li><p>Step 3 – add numbers (numbers → number): produce a single number by computing the total of all numbers in a stream.</p>
</li>
</ul>

<p>The neat thing is that everything is computed <em>lazily</em> (incrementally and on demand): computation starts as soon as the first character arrives. For example, we don’t have to wait until we have all characters to get the first word.</p>

<h5 id="lazy_pull_%28generators_as_iterators%29">Lazy pull (generators as iterators)</h5>

<p><strong>Step 1 – tokenize.</strong> The following trick makes the code a bit simpler: the end-of-sequence iterator result (whose property <code>done</code> is <code>false</code>) is converted into the sentinel value <code>END_OF_SEQUENCE</code>.</p>

<pre class="javascript">
    function* tokenize(chars) {
        let iterator = chars[Symbol.iterator]();
        let ch;
        do {
            ch = getNextItem(iterator);
            if (isWordChar(ch)) {
                let word = '';
                do {
                    word += ch;
                    ch = getNextItem(iterator);
                } while (isWordChar(ch));
                yield word;
            }
            // Ignore all other characters
        } while (ch !== END_OF_SEQUENCE);
    }
    const END_OF_SEQUENCE = Symbol();
    function getNextItem(iterator) {
        let item = iterator.next();
        return item.done ? END_OF_SEQUENCE : item.value;
    }
    function isWordChar(ch) {
        return typeof ch === 'string' &amp;&amp; /^[A-Za-z0-9]$/.test(ch);
    }
</pre>

<p>Let’s try out tokenization. Note that the spaces and the dot are non-words. They are ignored, but they separate words. We use the fact that strings are iterables over characters (Unicode code points). The final result is an iterable over words, which we turn into an array via the spread operator (<code>...</code>).</p>

<pre class="repl">
    &gt; [...tokenize('2 apples and 5 oranges.')]
    [ '2', 'apples', 'and', '5', 'oranges' ]
</pre>

<p><strong>Step 2 – extract numbers:</strong> This step is relatively simple, we only <code>yield</code> words that contain nothing but digits, after converting them to numbers via <code>Number()</code>.</p>

<pre class="javascript">
    function* extractNumbers(words) {
        for (let word of words) {
            if (/^[0-9]+$/.test(word)) {
                yield Number(word);
            }
        }
    }
</pre>

<p>The following example shows the transformation steps: characters → words → numbers.</p>

<pre class="repl">
    &gt; [...extractNumbers(tokenize('2 apples and 5 oranges.'))]
    [ 2, 5 ]
</pre>

<p><strong>Step 3 – add numbers:</strong> This last step is performed by a normal function that pulls the results and reports their total.</p>

<pre class="javascript">
    function summarize(numbers) {
        let result = 0;
        for (let n of numbers) {
            result += n;
        }
        return result;
    }
</pre>

<p>The final result shows us that there are 7 things in the input sentence.</p>

<pre class="repl">
    &gt; summarize(extractNumbers(tokenize('2 apples and 5 oranges.')))
    7
</pre>

<h5 id="lazy_push_%28generators_as_observables%29">Lazy push (generators as observables)</h5>

<p>Not much work is needed to convert the previous pull-based algorithm into a push-based one. The steps are the same. But instead of finishing via pulling, we start via pushing (in both cases, non-generator functions are used).</p>

<p>As previously explained, if generators receive input via <code>yield</code>, the first invocation of <code>next()</code> on the generator object doesn’t do anything. That’s why we again use the following helper function:</p>

<pre class="javascript">
    /**
     * Returns a function that, when called,
     * returns a generator object that is immediately
     * ready for input via `next()`
     */
    function coroutine(generatorFunction) {
        return function (...args) {
            let generatorObject = generatorFunction(...args);
            generatorObject.next();
            return generatorObject;
        };
    }
</pre>

<p>The following function <code>send()</code> wraps the chain of generators. Its parameter <code>receiver</code> holds the generator object of the first generator in the chain. <code>send()</code> pushes the contents of <code>iterable</code> to the <code>receiver</code>, via <code>next()</code>.</p>

<pre class="javascript">
    function send(iterable, receiver) {
        for (let x of iterable) {
            receiver.next(x);
        }
        receiver.return(); // signal end of stream
    }
</pre>

<p>When a generator processes a stream, it needs to be aware of the end of the stream, so that it can clean up properly. For pull, we did this via a special end-of-stream sentinel. For push, the end-of-stream is signaled via <code>return()</code>.</p>

<p>Let’s test <code>send()</code> via a generator that simply outputs everything it receives:</p>

<pre class="javascript">
    const logItems = coroutine(function* () {
        try {
            while (true) {
                let item = yield;
                console.log(item);
            }
        } finally {
            console.log('DONE');
        }
    });
</pre>

<p>Let’s send <code>logItems()</code> three “characters” via a string (which is an iterable over Unicode code points).</p>

<pre class="repl">
    &gt; send('abc', logItems());
    a
    b
    c
    DONE
</pre>

<p><strong>Step 1 – tokenize.</strong> Note how this generator reacts to the end of the stream (as signaled via <code>return()</code>) in two <code>finally</code> clauses. We depend on <code>return()</code> being sent to either one of the two <code>yield</code>s. Otherwise, the generator would never terminate, because the infinite loop starting in line (A) would never terminate.</p>

<pre class="javascript">
    const tokenize = coroutine(function* (receiver) {
        try {
            while (true) { // (A)
                let ch = yield;
                if (isWordChar(ch)) {
                    // A word has started
                    let word = '';
                    try {
                        do {
                            word += ch;
                            ch = yield;
                        } while (isWordChar(ch));
                    } finally {
                        // The word is finished.
                        // We get here if
                        // (a) the loop terminates normally
                        // (b) the loop is terminated via `return()`
                        receiver.next(word);
                    }
                }
                // Ignore all other characters
            }
        } finally {
            // We only get here if the infinite loop is terminated
            // via `return()`. Forward `return()` to `receiver` so
            // that it is also aware of the end of stream.
            receiver.return();
        }
    });

    function isWordChar(ch) {
        return /^[A-Za-z0-9]$/.test(ch);
    }
</pre>

<p><code>tokenize()</code> demonstrates that generators work well as implementations of linear state machines. In this case, the machine has two states: “inside a word” and “not inside a word”.</p>

<p>Let’s tokenize a string:</p>

<pre class="repl">
    &gt; send('2 apples and 5 oranges.', tokenize(logItems()));
    2
    apples
    and
    5
    oranges
</pre>

<p><strong>Step 2 – extract numbers:</strong> This step is straightforward.</p>

<pre class="javascript">
    const extractNumbers = coroutine(function* (receiver) {
        try {
            while (true) {
                let word = yield;
                if (/^[0-9]+$/.test(word)) {
                    receiver.next(Number(word));
                }
            }
        } finally {
            // Only reached via `return()`, forward.
            receiver.return();
        }
    });
</pre>

<p>Let’s log the numbers appearing in a string:</p>

<pre class="repl">
    &gt; send('2 apples and 5 oranges.', tokenize(extractNumbers(logItems())));
    2
    5
    DONE
</pre>

<p><strong>Step 3 – add numbers:</strong> This time, we react to the end of the stream by pushing a single value and then closing the receiver.</p>

<pre class="javascript">
    const addNumbers = coroutine(function* (receiver) {
        let result = 0;
        try {
            while (true) {
                result += yield;
            }
        } finally {
            // We received an end-of-stream
            receiver.next(result);
            receiver.return(); // signal end of stream
        }
    });
</pre>

<p>Let’s sum up the numbers appearing inside a string:</p>

<pre class="repl">
    &gt; send('2 apples and 5 oranges.', tokenize(extractNumbers(addNumbers(logItems()))));
    7
    DONE
</pre>

<p>As mentioned before, one benefit of a push-based approach is that it allows you to process data that you receive asynchronously.</p>

<h4 id="cooperative_multi-tasking_via_generators">Cooperative multi-tasking via generators</h4>

<h5 id="pausing_long-running_tasks">Pausing long-running tasks</h5>

<p>In this example, we create a counter that is displayed on a web page. We improve an initial version until we have a cooperatively multitasked version that doesn’t block the main thread and the user interface.</p>

<p>This is the part of the web page in which the counter should be displayed:</p>

<pre class="html">
    &lt;body&gt;
        Counter: &lt;span id="counter"&gt;&lt;/span&gt;
    &lt;/body&gt;
</pre>

<p>This function displays a counter that counts up forever (well, until the number overflows):</p>

<pre class="javascript">
    function countUp(start = 0) {
        const counterSpan = document.querySelector('#counter');
        while (true) {
            counterSpan.textContent = String(start);
            start++;
        }
    }
</pre>

<p>If you ran this function, it would completely block the user interface thread in which it runs and its tab would become unresponsive.</p>

<p>Let’s implement the same functionality via a generator that periodically pauses via <code>yield</code> (a scheduling function for running this generator is shown at the end):</p>

<pre class="javascript">
    function* countUp(start = 0) {
        const counterSpan = document.querySelector('#counter');
        while (true) {
            counterSpan.textContent = String(start);
            start++;
            yield; // pause
        }
    }
</pre>

<p>Let’s add one small improvement. We move the update of the user interface to another generator, <code>displayCounter</code>, which we call via <code>yield*</code>. As it is a generator, it can also take care of pausing.</p>

<pre class="javascript">
    function* countUp(start = 0) {
        while (true) {
            start++;
            yield* displayCounter(start);
        }
    }
    function* displayCounter(counter) {
        const counterSpan = document.querySelector('#counter');
        counterSpan.textContent = String(counter);
        yield; // pause
    }
</pre>

<p>Lastly, this is a scheduling function that we can use to run <code>countUp()</code>. Each execution step of the generator is handled by a separate task, which is created via <code>setTimeout()</code>. That means that the user interface can schedule other tasks in between and will remain responsive.</p>

<pre class="javascript">
    function run(generatorObject) {
        if (!generatorObject.next().done) {
            // Add a new task to the event queue
            setTimeout(function () {
                run(generatorObject);
            }, 1000);
        }
    }
</pre>

<p>With the help of <code>run</code>, we get a (nearly) infinite count-up that doesn’t block the user interface:</p>

<pre class="javascript">
    run(countUp());
</pre>

<h5 id="cooperative_multitasking_with_generators_and_node.js-style_callbacks">Cooperative multitasking with generators and Node.js-style callbacks</h5>

<p>If you call a generator function (or method), it does not have access to its generator object; its <code>this</code> is the <code>this</code> it would have if it were a non-generator function. A work-around is to pass the generator object into the generator function via <code>yield</code>.</p>

<p>The following Node.js script uses this technique, but wraps the generator object in a callback (<code>next</code>, line (A)). It must be run via <code>babel-node</code> <a class="ptr">[8]</a>.</p>

<pre class="javascript">
    import {readFile} from 'fs';

    let fileNames = process.argv.slice(2);

    console.log(fileNames, readFile);

    run(function* () {
        let next = yield; // (A)
        for (let f of fileNames) {
            let contents = yield readFile(f, { encoding: 'utf8' }, next);
            console.log('-------------', f);
            console.log(contents);
        }
    });
</pre>

<p>In line (A), we get a callback that we can use with functions that follow Node.js callback conventions. The callback uses the generator object to wake up the generator, as you can see in the implementation of <code>run()</code>:</p>

<pre class="javascript">
    function run(generatorFunction) {
        let generatorObject = generatorFunction();

        // Step 1: Proceed to first `yield`
        generatorObject.next();

        // Step 2: Pass in a function that the generator can use as a callback
        let nextFunction = createNextFunction(generatorObject);
        generatorObject.next(nextFunction);

        // Subsequent invocations of `next()` are triggered by `nextFunction`
    }

    function createNextFunction(generatorObject) {
        return function(error, result) {
            if (error) {
                generatorObject.throw(error);
            } else {
                generatorObject.next(result);
            }
        };
    }
</pre>

<h5 id="communicating_sequential_processes_%28csp%29">Communicating Sequential Processes (CSP)</h5>

<p>The library <a href="https://github.com/ubolonton/js-csp"><code>js-csp</code></a> brings Communicating Sequential Processes (CSP) to JavaScript, a style of cooperative multitasking that is similar to ClojureScript’s core.async and Go’s <em>goroutines</em>. <code>js-csp</code> has two abstractions:</p>

<ul>
<li>Processes: are cooperatively multitasked tasks and implemented by handing a generator function to the scheduling function <code>go()</code>.</li>
<li>Channels: are queues for communication between processes. Channels are created by calling <code>chan()</code>.</li>
</ul>

<p>As an example, let’s use CSP to handle DOM events, in a manner reminiscent of Functional Reactive Programming. The following code uses the function <code>listen()</code> (which is shown later) to create a channel that outputs <code>mousemove</code> events. It then continuously retrieves the output via <code>take</code>, inside an infinite loop. Thanks to <code>yield</code>, the process blocks until the channel has output.</p>

<pre class="javascript">
    import csp from 'js-csp';

    csp.go(function* () {
        let element = document.querySelector('#uiElement1');
        let channel = listen(element, 'mousemove');
        while (true) {
            let event = yield csp.take(channel);
            let x = event.layerX || event.clientX;
            let y = event.layerY || event.clientY;
            element.textContent = `${x}, ${y}`;
        }
    });
</pre>

<p><code>listen()</code> is implemented as follows.</p>

<pre class="javascript">
    function listen(element, type) {
        let channel = csp.chan();
        element.addEventListener(type,
            event =&gt; {
                csp.putAsync(channel, event);
            });
        return channel;
    }
</pre>

<p>This example is taken from the blog post “<a href="http://jlongster.com/Taming-the-Asynchronous-Beast-with-CSP-in-JavaScript">Taming the Asynchronous Beast with CSP Channels in JavaScript</a>” by James Long. Consult this blog post for more information on CSP.</p>

<h3 id="inheritance">Inheritance</h3>

<p>This is a diagram of how various objects are connected in ECMAScript 6 (it is based on <a href="https://people.mozilla.org/~jorendorff/es6-draft.html#sec-generatorfunction-objects">Allen Wirf-Brock’s diagram</a> in the ECMAScript specification):</p>

<div class="separator">
<a href="http://3.bp.blogspot.com/-kGgpHT0wjqU/VRkKCblRpRI/AAAAAAAAA70/BuiA8d-aZto/s1600/generator_inheritance.jpg" imageanchor="1"><img border="0" src="http://3.bp.blogspot.com/-kGgpHT0wjqU/VRkKCblRpRI/AAAAAAAAA70/BuiA8d-aZto/s1600/generator_inheritance.jpg"/></a></div>

<p>Legend:</p>

<ul>
<li>The white (hollow) arrows express the has-prototype relationship (inheritance) between objects. In other words: a white arrow from <code>x</code> to <code>y</code> means that <code>Object.getPrototypeOf(x) === y</code>.</li>
<li>Parentheses indicate that an object exists, but is not accessible via a global variable.</li>
<li>An <code>instanceof</code> arrow from <code>x</code> to <code>y</code> means that <code>x instanceof y</code>.<ul>
<li>Remember that <code>o instanceof C</code> is equivalent to <code>C.prototype.isPrototypeOf(o)</code>.</li>
</ul>
</li>
<li>A <code>prototype</code> arrow from <code>x</code> to <code>y</code> means that <code>x.prototype === y</code>.</li>
</ul>

<p>The diagram reveals two interesting facts:</p>

<p>First, a generator function <code>g</code> works very much like a constructor (you can even invoke it via <code>new</code>): The generator objects it creates are instances of it, methods added to <code>g.prototype</code> become prototype methods, etc.:</p>

<pre class="javascript">
    &gt; function* g() {}
    &gt; g.prototype.hello = function () { return 'hi!'};
    &gt; let obj = g();
    &gt; obj instanceof g
    true
    &gt; obj.hello()
    'hi!'
</pre>

<p>Second, if you want to make methods available for all generator objects, it’s best to add them to <code>(Generator.object)</code>. One way of accessing that object is as follows:</p>

<pre class="javascript">
    &gt; let Generator_prototype = Object.getPrototypeOf(function* () {}).prototype;
    &gt; Generator_prototype.hello = function () { return 'hi!'};
    &gt; let generatorObject = (function* () {})();
    &gt; generatorObject.hello()
    'hi!'
</pre>

<h4 id="iteratorprototype"><code>IteratorPrototype</code></h4>

<p>There is no <code>(Iterator)</code> in the diagram, because no such object exists. But, given how <code>instanceof</code> works and because <code>(IteratorPrototype)</code> is a prototype of <code>g1()</code>, you could still say that <code>g1()</code> is an instance of <code>Iterator</code>.</p>

<p>All iterators in ES6 have <code>(IteratorPrototype)</code> in their prototype chain. That object is iterable, because it has the following method. Therefore, all ES6 iterators are iterable (as a consequence, you can apply <code>for-of</code> etc. to them).</p>

<pre class="javascript">
    [Symbol.iterator]() {
        return this;
    }
</pre>

<p>The specification recommends to use the following code to access <code>(IteratorPrototype)</code>:</p>

<pre class="javascript">
    const proto = Object.getPrototypeOf.bind(Object);
    let IteratorPrototype = proto(proto([][Symbol.iterator]()));
</pre>

<p>You could also use:</p>

<pre class="javascript">
    let IteratorPrototype = proto(proto(function* () {}.prototype));
</pre>

<p>Quoting the ECMAScript 6 specification:</p>

<blockquote>
<p>ECMAScript code may also define objects that inherit from <code>IteratorPrototype</code>. The <code>IteratorPrototype</code> object provides a place where additional methods that are applicable to all iterator objects may be added.</p>
</blockquote>

<p><code>IteratorPrototype</code> will probably become directly accessible in an upcoming version of ECMAScript and contain tool methods such as <code>map()</code> and <code>filter()</code> (<a href="https://github.com/rwaldron/tc39-notes/blob/master/es6/2014-07/jul-30.md#47-revisit-comprehension-decision-from-last-meeting">source</a>).</p>

<h4 id="the_value_of_this_in_generators">The value of <code>this</code> in generators</h4>

<p>A generator function combines two concerns:</p>

<ol>
<li>It is a function that sets up and returns a generator object.</li>
<li>It contains the code that the generator object steps through.</li>
</ol>

<p>That’s why it’s not immediately obvious what the value of <code>this</code> should be inside a generator.</p>

<p>In function calls and method calls, <code>this</code> is what it would be if <code>gen()</code> wasn’t a generator function, but a normal function:</p>

<pre class="javascript">
    function* gen() {
        'use strict'; // just in case
        yield this;
    }

    // Retrieve the yielded value via destructuring
    let [functionThis] = gen();
    console.log(functionThis); // undefined

    let obj = { method: gen };
    let [methodThis] = obj.method();
    console.log(methodThis === obj); // true
</pre>

<p>If you access <code>this</code> in a generator that was invoked via <code>new</code>, you get a <code>ReferenceError</code> (<a href="https://people.mozilla.org/~jorendorff/es6-draft.html#sec-generator-function-definitions-runtime-semantics-evaluatebody">source: ES6 spec</a>):</p>

<pre class="javascript">
    function* gen() {
        console.log(this); // ReferenceError
    }
    new gen();
</pre>

<p>We have previously seen a simple work-around: wrap the generator in a normal function that hands the generator its generator object via <code>yield</code>.</p>

<h3 id="style_consideration%3A_whitespace_before_and_after_the_asterisk">Style consideration: whitespace before and after the asterisk</h3>

<p>Reasonable – and legal – variations of formatting the asterisk are:</p>

<ul>
<li><p>A space before and after it:<br/><code>function * foo(x, y) { ... }</code></p>
</li>
<li><p>A space before it:<br/><code>function *foo(x, y) { ... }</code></p>
</li>
<li><p>A space after it:<br/><code>function* foo(x, y) { ... }</code></p>
</li>
<li><p>No whitespace before and after it:<br/><code>function*foo(x, y) { ... }</code></p>
</li>
</ul>

<p>Let’s figure out which of these variations make sense for which constructs and why.</p>

<h4 id="generator_function_declarations_and_expressions">Generator function declarations and expressions</h4>

<p>Here, the star is only used because <code>generator</code> (or something similar) isn’t available as a keyword. If it were, then a generator function declaration would look like this:</p>

<pre class="javascript">
    generator foo(x, y) {
        ...
    }
</pre>

<p>Instead of <code>generator</code>, ECMAScript 6 marks the <code>function</code> keyword with an asterisk. Thus, <code>function*</code> can be seen as a synonym for <code>generator</code>, which suggests writing generator function declarations as follows.</p>

<pre class="javascript">
    function* foo(x, y) {
        ...
    }
</pre>

<p>Anonymous generator functions would be formatted like this:</p>

<pre class="javascript">
    const foo = function* (x, y) {
        ...
    }
</pre>

<h4 id="concise_generator_method_definitions">Concise generator method definitions</h4>

<p>When writing a concise generator method definitions, I recommend to format the asterisk as follows.</p>

<pre class="javascript">
    let obj = {
        * generatorMethod(x, y) {
            ...
        }
    };
</pre>

<p>There are three arguments in favor of writing a space after the asterisk.</p>

<p>First, the asterisk shouldn’t be part of the method name. On one hand, it isn’t part of the name of a generator function. On the other hand, the asterisk is only mentioned when defining a generator, not when using it.</p>

<p>Second, a concise generator method definition is an abbreviation for the following syntax. (To make my point, I’m redundantly giving the function expression a name, too.)</p>

<pre class="javascript">
    let obj = {
        generatorMethod: function* generatorMethod(x, y) {
            ...
        }
    };
</pre>

<p>If concise method definitions are about omitting the <code>function</code> keyword then the asterisk should probably be followed by a space.</p>

<p>Third, generator method definitions are syntactically similar to getters and setters (which are already available in ECMAScript 5):</p>

<pre class="javascript">
    let obj = {
        get foo() {
            ...
        }
        set foo(value) {
            ...
        }
    }
</pre>

<p>The keywords <code>get</code> and <code>set</code> can be seen as modifiers of a normal concise method definition. Arguably, an asterisk is also such a modifier.</p>

<h4 id="recursive_yield">Recursive <code>yield</code></h4>

<p>The following is an example of a generator function yielding its own yielded values recursively:</p>

<pre class="javascript">
    function* foo(x) {
        ...
        yield* foo(x - 1);
        ...
    }
</pre>

<p>The asterisk marks a different kind of <code>yield</code> operator, which is why the above way of writing it makes sense.</p>

<h4 id="documenting_generator_functions_and_methods">Documenting generator functions and methods</h4>

<p>Kyle Simpson (@getify) proposed something interesting: Given that we often append parentheses when we write about functions and methods such as <code>Math.max()</code>, wouldn’t it make sense to prepend an asterisk when writing about generator functions and methods? For example: should we write <code>*foo()</code> to refer to the generator function in the previous subsection? Let me argue against that.</p>

<p>When it comes to writing a function that returns an iterable, a generator is only one of the several options. I think it is better to not give away this implementation detail via marked function names.</p>

<p>Furthermore, you don’t use the asterisk when calling a generator function, but you do use parentheses.</p>

<p>Lastly, the asterisk doesn’t provide useful information – <code>yield*</code> can also be used with functions that return an iterable. But it may make sense to mark the names of functions and methods that return iterables (including generators). For example, via the suffix <code>Iter</code>.</p>

<h3 id="conclusion">Conclusion</h3>

<p>I hope that this blog post convinced you that generators are a useful and versatile tool.</p>

<p>I like that generators let you implement cooperatively multitasked tasks that block while making asynchronous function calls. In my opinion that’s the right mental model for async calls. I hope that JavaScript goes further in this direction in the future. If one generator async-calls another generator, the indirection via promises is not needed. It could be avoided by <a href="https://github.com/lukehoban/ecmascript-asyncawait">the generator-based async functions</a> that have been proposed for ECMAScript 2016.</p>

<h3 id="references">References</h3>

<p>Acknowledgement: items 1–3 are sources of this blog post.</p>

<ol class="reflist">
<li>“<a href="https://github.com/jhusain/asyncgenerator">Async Generator Proposal</a>” by Jafar Husain</li>
<li>“<a href="http://www.dabeaz.com/coroutines/">A Curious Course on Coroutines and Concurrency</a>” by David Beazley</li>
<li>“<a href="http://calculist.org/blog/2011/12/14/why-coroutines-wont-work-on-the-web/">Why coroutines won't work on the web</a>” by David Herman</li>
<li>“<a href="http://exploringjs.com/">Exploring ES6: Upgrade to the next version of JavaScript</a>”, book by Axel</li>
<li><a href="http://www.2ality.com/2015/02/es6-iteration.html">Iterables and iterators in ECMAScript 6</a></li>
<li><a href="http://www.2ality.com/2015/01/es6-destructuring.html">Destructuring and parameter handling in ECMAScript 6</a></li>
<li>”<a href="the_spread_operator_%28...%29">The spread operator (<code>...</code>)</a>”, a section in the blog post “Destructuring and parameter handling in ECMAScript 6”.</li>
<li><a href="http://www.2ality.com/2015/03/babel-on-node.html">Using the ES6 transpiler Babel on Node.js</a></li>
<li><a href="http://www.2ality.com/2014/09/es6-promises-foundations.html">ECMAScript 6 promises (1/2): foundations</a> [explains the event loop and more]</li>
<li><a href="http://www.2ality.com/2014/10/es6-promises-api.html">ECMAScript 6 promises (2/2): the API</a></li>
<li><a href="http://www.2ality.com/2015/02/es6-classes-final.html">Classes in ECMAScript 6 (final semantics)</a></li>
</ol>
  </article>
</section>


<nav id="jumpto">
  <p>
    <a href="/david/blog/">Accueil du blog</a> |
    <a href="http://www.2ality.com/2015/03/es6-generators.html">Source originale</a> |
    <a href="/david/stream/2019/">Accueil du flux</a>
  </p>
</nav>

<footer>
  <div>
    <img src="/static/david/david-larlet-avatar.jpg" loading="lazy" class="avatar" width="200" height="200">
    <p>
      Bonjour/Hi!
      Je suis <a href="/david/" title="Profil public">David&nbsp;Larlet</a>, je vis actuellement à Montréal et j’alimente cet espace depuis 15 ans. <br>
      Si tu as apprécié cette lecture, n’hésite pas à poursuivre ton exploration. Par exemple via les <a href="/david/blog/" title="Expériences bienveillantes">réflexions bimestrielles</a>, la <a href="/david/stream/2019/" title="Pensées (dés)articulées">veille hebdomadaire</a> ou en t’abonnant au <a href="/david/log/" title="S’abonner aux publications via RSS">flux RSS</a> (<a href="/david/blog/2019/flux-rss/" title="Tiens c’est quoi un flux RSS ?">so 2005</a>).
    </p>
    <p>
      Je m’intéresse à la place que je peux avoir dans ce monde. En tant qu’humain, en tant que membre d’une famille et en tant qu’associé d’une coopérative. De temps en temps, je fais aussi des <a href="https://github.com/davidbgk" title="Principalement sur Github mais aussi ailleurs">trucs techniques</a>. Et encore plus rarement, <a href="/david/talks/" title="En ce moment je laisse plutôt la place aux autres">j’en parle</a>.
    </p>
    
    <p>
      Voici quelques articles choisis :
      <a href="/david/blog/2019/faire-equipe/" title="Accéder à l’article complet">Faire équipe</a>,
      <a href="/david/blog/2018/bivouac-automnal/" title="Accéder à l’article complet">Bivouac automnal</a>,
      <a href="/david/blog/2018/commodite-effondrement/" title="Accéder à l’article complet">Commodité et effondrement</a>,
      <a href="/david/blog/2017/donnees-communs/" title="Accéder à l’article complet">Des données aux communs</a>,
      <a href="/david/blog/2016/accompagner-enfant/" title="Accéder à l’article complet">Accompagner un enfant</a>,
      <a href="/david/blog/2016/senior-developer/" title="Accéder à l’article complet">Senior developer</a>,
      <a href="/david/blog/2016/illusion-sociale/" title="Accéder à l’article complet">L’illusion sociale</a>,
      <a href="/david/blog/2016/instantane-scopyleft/" title="Accéder à l’article complet">Instantané Scopyleft</a>,
      <a href="/david/blog/2016/enseigner-web/" title="Accéder à l’article complet">Enseigner le Web</a>,
      <a href="/david/blog/2016/simplicite-defaut/" title="Accéder à l’article complet">Simplicité par défaut</a>,
      <a href="/david/blog/2016/minimalisme-esthetique/" title="Accéder à l’article complet">Minimalisme et esthétique</a>,
      <a href="/david/blog/2014/un-web-omni-present/" title="Accéder à l’article complet">Un web omni-présent</a>,
      <a href="/david/blog/2014/manifeste-developpeur/" title="Accéder à l’article complet">Manifeste de développeur</a>,
      <a href="/david/blog/2013/confort-convivialite/" title="Accéder à l’article complet">Confort et convivialité</a>,
      <a href="/david/blog/2013/testament-numerique/" title="Accéder à l’article complet">Testament numérique</a>,
      et <a href="/david/blog/" title="Accéder aux archives">bien d’autres…</a>
    </p>
    <p>
      On peut <a href="mailto:david%40larlet.fr" title="Envoyer un courriel">échanger par courriel</a>. Si éventuellement tu souhaites que l’on travaille ensemble, tu devrais commencer par consulter le <a href="http://larlet.com">profil dédié à mon activité professionnelle</a> et/ou contacter directement <a href="http://scopyleft.fr/">scopyleft</a>, la <abbr title="Société coopérative et participative">SCOP</abbr> dont je fais partie depuis six ans. Je recommande au préalable de lire <a href="/david/blog/2018/cout-site/" title="Attention ce qui va suivre peut vous choquer">combien coûte un site</a> et pourquoi je suis plutôt favorable à une <a href="/david/pro/devis/" title="Discutons-en !">non-demande de devis</a>.
    </p>
    <p>
      Je ne traque pas ta navigation mais mon
      <abbr title="Alwaysdata, 62 rue Tiquetonne 75002 Paris, +33.184162340">hébergeur</abbr>
      conserve des logs d’accès.
    </p>
  </div>
</footer>
<script type="text/javascript">
  ;(_ => {
    const jumper = document.getElementById('jumper')
    jumper.addEventListener('click', e => {
      e.preventDefault()
      const anchor = e.target.getAttribute('href')
      const targetEl = document.getElementById(anchor.substring(1))
      targetEl.scrollIntoView({behavior: 'smooth'})
    })
  })()
</script>