Add examples for queueMicrotask()

Also rearranges the domintro and normative definition to come first,
before the explanatory text.

Author: domenic

source

@@ -2805,6 +2805,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li><dfn data-x="concept-fetch-terminate" data-x-href="https://fetch.spec.whatwg.org/#concept-fetch-terminate">terminate</dfn></li>
      <li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#requestcredentials"><code>RequestCredentials</code></dfn> enumeration</li>
      <li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#requestdestination"><code>RequestDestination</code></dfn> enumeration</li>
+     <li>the <dfn data-x-href="https://fetch.spec.whatwg.org/#dom-global-fetch"><code>fetch()</code></dfn> method</li>
      <li>
       <dfn data-x="concept-response"
       data-x-href="https://fetch.spec.whatwg.org/#concept-response">response</dfn> and its
@@ -91365,6 +91366,19 @@ scheduleWork(); // queues a task to do lots of work</code></pre>
 
   <h3>Microtask queuing</h3>
 
+  <dl class="domintro">
+   <dt><var>self</var> . <code subdfn
+   data-x="dom-queueMicrotask">queueMicrotask</code>(<var>callback</var>)</dt>
+   <dd><p><span data-x="queue a microtask">Queues</span> a <span>microtask</span> to run the given
+   <var>callback</var>.</p></dd>
+  </dl>
+
+  <p w-nodev>The <dfn><code
+  data-x="dom-queueMicrotask">queueMicrotask(<var>callback</var>)</code></dfn> method must
+  <span>queue a microtask</span> to <span data-x="es-invoking-callback-functions">invoke</span>
+  <var>callback</var>, and if <var>callback</var> throws an exception, <span>report the
+  exception</span>.</p>
+
   <p>The <code data-x="dom-queueMicrotask">queueMicrotask()</code> method allows authors to schedule
   a callback on the <span>microtask queue</span>. This allows their code to run after the
   currently-executing <span data-x="concept-task">task</span> has run to completion and the
@@ -91380,18 +91394,94 @@ scheduleWork(); // queues a task to do lots of work</code></pre>
   before the next rendering cycle, that is the purpose of <code
   data-x="dom-window-requestAnimationFrame">requestAnimationFrame()</code>.</p>
 
-  <dl class="domintro">
-   <dt><var>self</var> . <code subdfn
-   data-x="dom-queueMicrotask">queueMicrotask</code>(<var>callback</var>)</dt>
-   <dd><p><span data-x="queue a microtask">Queues</span> a <span>microtask</span> to run the given
-   <var>callback</var>.</p></dd>
-  </dl>
+  <p>As can be seen from the following examples, the best way of thinking about <code
+  data-x="dom-queueMicrotask">queueMicrotask()</code> is as a mechanism for rearranging synchronous
+  code, effectively placing the queued code immediately after the current task's worth of non-queued
+  JavaScript.</p>
 
-  <p w-nodev>The <dfn><code
-  data-x="dom-queueMicrotask">queueMicrotask(<var>callback</var>)</code></dfn> method must
-  <span>queue a microtask</span> to <span data-x="es-invoking-callback-functions">invoke</span>
-  <var>callback</var>, and if <var>callback</var> throws an exception, <span>report the
-  exception</span>.</p>
+  <div class="example">
+   <p>The most common reason for using <code data-x="dom-queueMicrotask">queueMicrotask()</code> is
+   to create consistent ordering, even in the cases where information is available synchronously,
+   without introducing undue delay.</p>
+
+   <p>For example, consider a custom element firing a <code data-x="">load</code> event, that also
+   maintains an internal cache of previously-loaded data. A na&iuml;ve implementation might look
+   like:</p>
+
+   <pre><code class="js" data-x="">MyElement.prototype.loadData = function (url) {
+  if (this._cache[url]) {
+    this._setData(this._cache[url]);
+    this.dispatchEvent(new Event("load"));
+  } else {
+    fetch(url).then(res => res.arrayBuffer()).then(data => {
+      this._cache[url] = data;
+      this._setData(data);
+      this.dispatchEvent(new Event("load"));
+    });
+  }
+};</code></pre>
+
+   <p>This na&iuml;ve implementation is problematic, however, in that it causes its users to
+   experience inconsistent behavior. For example, code such as</p>
+
+   <pre><code class="js" data-x="">element.addEventListener("load", () => console.log("loaded"));
+console.log("1");
+element.loadData();
+console.log("2");</code></pre>
+
+   <p>will sometimes log "1, 2, loaded" (if the data needs to be fetched), and sometimes log "1,
+   loaded, 2" (if the data is already cached). Similarly, after the call to <code
+   data-x="">loadData()</code>, it will be inconsistent whether or not the data is set on the
+   element.</p>
+
+   <p>To get a consistent ordering, <code data-x="dom-queueMicrotask">queueMicrotask()</code> can be
+   used:</p>
+
+   <pre><code class="js" data-x="">MyElement.prototype.loadData = function (url) {
+  if (this._cache[url]) {<strong>
+    queueMicrotask(() => {
+      this._setData(this._cache[url]);
+      this.dispatchEvent(new Event("load"));
+    });</strong>
+  } else {
+    fetch(url).then(res => res.arrayBuffer()).then(data => {
+      this._cache[url] = data;
+      this._setData(data);
+      this.dispatchEvent(new Event("load"));
+    });
+  }
+};</code></pre>
+
+   <p>By essentially rearranging the queued code to be after the currently-executing task, this
+   ensures a consistent ordering and update of the element's state.</p>
+  </div>
+
+  <div class="example">
+   <p>Another interesting use of <code data-x="dom-queueMicrotask">queueMicrotask()</code> is to
+   allow uncoordinated "batching" of work by multiple callers. For example, consider a library
+   function that wants to send data somewhere as soon as possible, but doesn't want to make multiple
+   network requests if doing so is easily avoidable. One way to balance this would be like so:</p>
+
+   <pre><code class="js" data-x="">const queuedToSend = [];
+
+function sendData(data) {
+  queuedToSend.push(data);
+
+  if (queuedToSend.length === 1) {
+    queueMicrotask(() => {
+      const stringToSend = JSON.stringify(queuedToSend);
+      queuedToSend.length = 0;
+
+      fetch("/endpoint", string);
+    });
+  }
+}</code></pre>
+
+   <p>With this architecture, multiple subsequent calls to <code data-x="">sendData()</code> within
+   the same turn of the event loop will be batched together into one <code>fetch()</code> call, but
+   with no intervening event loop tasks preempting the fetch (as would have happened with similar
+   code that instead used <code data-x="dom-setTimeout">setTimeout()</code>).</p>
+  </div>
 
 
   <h3>User prompts</h3>