Add notes to explain the effect of asynchronous derivations introduced in VanJS 1.5.0

Author: Tao-VanJS

sitegen/tutorial.ts

@@ -182,6 +182,12 @@ van.add(document.body, Table({
       },
       returns: ["The created derived ", Symbol("State"), " object."],
     }),
+    p("Note that: Since ", Link(VanJS(), " 1.5.0", "https://github.com/vanjs-org/van/discussions/290"), ", we have changed the execution of state derivation from synchronous to asynchronous as an optimization to avoid potentially unnecessary derivations. That is, instead of executing state derivations immediately, the derivations are scheduled to execute as soon as the next event cycle of browser context (i.e.: after the current call stack is cleared, which is equivalent to ", InlineJs("setTimeout(..., 0)"), "). The effect of the asynchronous derivation can be illustrated by the code below:"),
+    Js(`const a = van.state(1)
+const b = van.derive(() => a.val * 2)
+a.val = 2
+console.log("b.val =", b.val) // Expecting 2
+setTimeout(() => console.log("b.val =", b.val), 10) // Expecting 4`),
     H3("Side effect"),
     p(Symbol("van.derive"), " can be used to declare side effects as well. You can discard the return value of ", Symbol("van.derive"), " if you are not interested. The code below is a modified ", Symbol("Counter App"), " which logs the counter to console whenever it changes:"),
     JsFile("effect.code.js"),

tutorial.html

@@ -147,7 +147,11 @@ <h1 class="w3-padding-16 w3-xxxlarge">
 }
 
 van.add(document.body, DerivedState())
-</code></pre><p><b>Demo:</b> <span id="demo-derived-state"></span></p><p><a href="https://jsfiddle.net/gh/get/library/pure/vanjs-org/vanjs-org.github.io/tree/master/jsfiddle/tutorial/derived-state">Try on jsfiddle</a></p><h3 class="w3-large w3-text-red" id="api-derive"><a class="self-link" href="#api-derive">API reference: <code class="symbol">van.derive</code></a></h3><table><tbody><tr><td><b>Signature</b></td><td><code class="language-js">van.derive(f) =&gt; &lt;the created derived state&gt;</code></td></tr><tr><td><b>Description</b></td><td>Creates a derived <code class="symbol">State</code> object based on the derivation function <code class="symbol">f</code>. The <code class="symbol">val</code> of the derived state is always in sync with the result of <code class="symbol">f</code>. i.e.: whenever the <code class="symbol">val</code> of its dependency changes, <code class="symbol">f</code> will be called to update the <code class="symbol">val</code> of the derived state, synchronously.</td></tr><tr><td><b>Parameters</b></td><td><ul><li><b><code class="symbol">f</code></b> - The derivation function, which takes no parameter and returns a single value.</li></ul></td></tr><tr><td><b>Returns</b></td><td>The created derived <code class="symbol">State</code> object.</td></tr></tbody></table><h3 class="w3-large w3-text-red" id="side-effect"><a class="self-link" href="#side-effect">Side effect</a></h3><p><code class="symbol">van.derive</code> can be used to declare side effects as well. You can discard the return value of <code class="symbol">van.derive</code> if you are not interested. The code below is a modified <code class="symbol">Counter App</code> which logs the counter to console whenever it changes:</p><pre><code class="language-js">const {button, span} = van.tags
+</code></pre><p><b>Demo:</b> <span id="demo-derived-state"></span></p><p><a href="https://jsfiddle.net/gh/get/library/pure/vanjs-org/vanjs-org.github.io/tree/master/jsfiddle/tutorial/derived-state">Try on jsfiddle</a></p><h3 class="w3-large w3-text-red" id="api-derive"><a class="self-link" href="#api-derive">API reference: <code class="symbol">van.derive</code></a></h3><table><tbody><tr><td><b>Signature</b></td><td><code class="language-js">van.derive(f) =&gt; &lt;the created derived state&gt;</code></td></tr><tr><td><b>Description</b></td><td>Creates a derived <code class="symbol">State</code> object based on the derivation function <code class="symbol">f</code>. The <code class="symbol">val</code> of the derived state is always in sync with the result of <code class="symbol">f</code>. i.e.: whenever the <code class="symbol">val</code> of its dependency changes, <code class="symbol">f</code> will be called to update the <code class="symbol">val</code> of the derived state, synchronously.</td></tr><tr><td><b>Parameters</b></td><td><ul><li><b><code class="symbol">f</code></b> - The derivation function, which takes no parameter and returns a single value.</li></ul></td></tr><tr><td><b>Returns</b></td><td>The created derived <code class="symbol">State</code> object.</td></tr></tbody></table><p>Note that: Since <a href="https://github.com/vanjs-org/van/discussions/290" class="w3-hover-opacity"><b>VanJS</b> 1.5.0</a>, we have changed the execution of state derivation from synchronous to asynchronous as an optimization to avoid potentially unnecessary derivations. That is, instead of executing state derivations immediately, the derivations are scheduled to execute as soon as the next event cycle of browser context (i.e.: after the current call stack is cleared, which is equivalent to <code class="language-js">setTimeout(..., 0)</code>). The effect of the asynchronous derivation can be illustrated by the code below:</p><pre><code class="language-js">const a = van.state(1)
+const b = van.derive(() =&gt; a.val * 2)
+a.val = 2
+console.log("b.val =", b.val) // Expecting 2
+setTimeout(() =&gt; console.log("b.val =", b.val), 10) // Expecting 4</code></pre><h3 class="w3-large w3-text-red" id="side-effect"><a class="self-link" href="#side-effect">Side effect</a></h3><p><code class="symbol">van.derive</code> can be used to declare side effects as well. You can discard the return value of <code class="symbol">van.derive</code> if you are not interested. The code below is a modified <code class="symbol">Counter App</code> which logs the counter to console whenever it changes:</p><pre><code class="language-js">const {button, span} = van.tags
 
 const Counter = () =&gt; {
   const counter = van.state(0)

tutorial/index.html

@@ -147,7 +147,11 @@ <h1 class="w3-padding-16 w3-xxxlarge">
 }
 
 van.add(document.body, DerivedState())
-</code></pre><p><b>Demo:</b> <span id="demo-derived-state"></span></p><p><a href="https://jsfiddle.net/gh/get/library/pure/vanjs-org/vanjs-org.github.io/tree/master/jsfiddle/tutorial/derived-state">Try on jsfiddle</a></p><h3 class="w3-large w3-text-red" id="api-derive"><a class="self-link" href="#api-derive">API reference: <code class="symbol">van.derive</code></a></h3><table><tbody><tr><td><b>Signature</b></td><td><code class="language-js">van.derive(f) =&gt; &lt;the created derived state&gt;</code></td></tr><tr><td><b>Description</b></td><td>Creates a derived <code class="symbol">State</code> object based on the derivation function <code class="symbol">f</code>. The <code class="symbol">val</code> of the derived state is always in sync with the result of <code class="symbol">f</code>. i.e.: whenever the <code class="symbol">val</code> of its dependency changes, <code class="symbol">f</code> will be called to update the <code class="symbol">val</code> of the derived state, synchronously.</td></tr><tr><td><b>Parameters</b></td><td><ul><li><b><code class="symbol">f</code></b> - The derivation function, which takes no parameter and returns a single value.</li></ul></td></tr><tr><td><b>Returns</b></td><td>The created derived <code class="symbol">State</code> object.</td></tr></tbody></table><h3 class="w3-large w3-text-red" id="side-effect"><a class="self-link" href="#side-effect">Side effect</a></h3><p><code class="symbol">van.derive</code> can be used to declare side effects as well. You can discard the return value of <code class="symbol">van.derive</code> if you are not interested. The code below is a modified <code class="symbol">Counter App</code> which logs the counter to console whenever it changes:</p><pre><code class="language-js">const {button, span} = van.tags
+</code></pre><p><b>Demo:</b> <span id="demo-derived-state"></span></p><p><a href="https://jsfiddle.net/gh/get/library/pure/vanjs-org/vanjs-org.github.io/tree/master/jsfiddle/tutorial/derived-state">Try on jsfiddle</a></p><h3 class="w3-large w3-text-red" id="api-derive"><a class="self-link" href="#api-derive">API reference: <code class="symbol">van.derive</code></a></h3><table><tbody><tr><td><b>Signature</b></td><td><code class="language-js">van.derive(f) =&gt; &lt;the created derived state&gt;</code></td></tr><tr><td><b>Description</b></td><td>Creates a derived <code class="symbol">State</code> object based on the derivation function <code class="symbol">f</code>. The <code class="symbol">val</code> of the derived state is always in sync with the result of <code class="symbol">f</code>. i.e.: whenever the <code class="symbol">val</code> of its dependency changes, <code class="symbol">f</code> will be called to update the <code class="symbol">val</code> of the derived state, synchronously.</td></tr><tr><td><b>Parameters</b></td><td><ul><li><b><code class="symbol">f</code></b> - The derivation function, which takes no parameter and returns a single value.</li></ul></td></tr><tr><td><b>Returns</b></td><td>The created derived <code class="symbol">State</code> object.</td></tr></tbody></table><p>Note that: Since <a href="https://github.com/vanjs-org/van/discussions/290" class="w3-hover-opacity"><b>VanJS</b> 1.5.0</a>, we have changed the execution of state derivation from synchronous to asynchronous as an optimization to avoid potentially unnecessary derivations. That is, instead of executing state derivations immediately, the derivations are scheduled to execute as soon as the next event cycle of browser context (i.e.: after the current call stack is cleared, which is equivalent to <code class="language-js">setTimeout(..., 0)</code>). The effect of the asynchronous derivation can be illustrated by the code below:</p><pre><code class="language-js">const a = van.state(1)
+const b = van.derive(() =&gt; a.val * 2)
+a.val = 2
+console.log("b.val =", b.val) // Expecting 2
+setTimeout(() =&gt; console.log("b.val =", b.val), 10) // Expecting 4</code></pre><h3 class="w3-large w3-text-red" id="side-effect"><a class="self-link" href="#side-effect">Side effect</a></h3><p><code class="symbol">van.derive</code> can be used to declare side effects as well. You can discard the return value of <code class="symbol">van.derive</code> if you are not interested. The code below is a modified <code class="symbol">Counter App</code> which logs the counter to console whenever it changes:</p><pre><code class="language-js">const {button, span} = van.tags
 
 const Counter = () =&gt; {
   const counter = van.state(0)