Add __mutator__

LICENCE

@@ -12,4 +12,23 @@ FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
 OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
-THIS SOFTWARE.
+THIS SOFTWARE.
+
+---
+
+Portions of this software are derived from Observable Notebook Kit, which is
+released under the ISC license.
+
+Copyright 2025 Observable, Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

runtime/index.js

@@ -6,11 +6,13 @@ import {group} from "d3-array";
 import {dispatch as d3Dispatch} from "d3-dispatch";
 import * as stdlib from "./stdlib.js";
 import {OUTPUT_MARK} from "./constant.js";
+import {Mutator} from "./mutator.js";
 
 const PREFIX = `//${OUTPUT_MARK}`;
 
 const BUILTINS = {
   recho: () => stdlib,
+  __Mutator__: () => Mutator,
 };
 
 function uid() {
@@ -248,7 +250,8 @@ export function createRuntime(initialCode) {
       for (const variable of variables) variable.delete();
     }
 
-    // @ref https://github.com/observablehq/notebook-kit/blob/02914e034fd21a50ebcdca08df57ef5773864125/src/runtime/define.ts#L33
+    // Derived from Observable Notebook Kit's define.
+    // https://github.com/observablehq/notebook-kit/blob/02914e034fd21a50ebcdca08df57ef5773864125/src/runtime/define.ts#L33
     for (const node of enter) {
       const vid = uid();
       const state = {values: [], variables: [], error: null, doc: false};

runtime/mutator.js

@@ -0,0 +1,34 @@
+// Derived from Observable Notebook Kit's mutable and mutator.
+// https://github.com/observablehq/notebook-kit/blob/main/src/runtime/stdlib/mutable.ts
+import {observe} from "./observe.js";
+
+// Mutable returns a generator with a value getter/setting that allows the
+// generated value to be mutated. Therefore, direct mutation is only allowed
+// within the defining cell, but the cell can also export functions that allows
+// other cells to mutate the value as desired.
+function Mutable(value) {
+  let change = undefined;
+  const mutable = observe((_) => {
+    change = _;
+    if (value !== undefined) change(value);
+  });
+  return Object.defineProperty(mutable, "value", {
+    get: () => value,
+    set: (x) => ((value = x), void change?.(value)),
+  });
+}
+
+export function Mutator(value) {
+  const mutable = Mutable(value);
+  return [
+    mutable,
+    {
+      get value() {
+        return mutable.value;
+      },
+      set value(v) {
+        mutable.value = v;
+      },
+    },
+  ];
+}

runtime/observe.js

@@ -0,0 +1,37 @@
+// Derived from Observable Notebook Kit's observe.
+// https://github.com/observablehq/notebook-kit/blob/main/src/runtime/stdlib/generators/observe.ts
+
+export async function* observe(initialize) {
+  let resolve = undefined;
+  let value = undefined;
+  let stale = false;
+
+  const dispose = initialize((x) => {
+    value = x;
+    if (resolve) {
+      resolve(x);
+      resolve = undefined;
+    } else {
+      stale = true;
+    }
+    return x;
+  });
+
+  if (dispose != null && typeof dispose !== "function") {
+    throw new Error(
+      typeof dispose === "object" && "then" in dispose && typeof dispose.then === "function"
+        ? "async initializers are not supported"
+        : "initializer returned something, but not a dispose function",
+    );
+  }
+
+  try {
+    while (true) {
+      yield stale ? ((stale = false), value) : new Promise((_) => (resolve = _));
+    }
+  } finally {
+    if (dispose != null) {
+      dispose();
+    }
+  }
+}

test/js/index.js

@@ -14,3 +14,4 @@ export {mandelbrotSet} from "./mandelbrot-set.js";
 export {matrixRain} from "./matrix-rain.js";
 export {jsDocString} from "./js-doc-string.js";
 export {commentLink} from "./comment-link.js";
+export {mutable} from "./mutable.js";

test/js/mutable.js

@@ -0,0 +1,13 @@
+export const mutable = `const [a, mutator$$a] = __Mutator__(0);
+
+new Promise((resolve) => {
+  setTimeout(() => {
+    for (let i = 0; i < 10; i++) {
+      mutator$$a.value += 1;
+    }
+  }, 1000);
+});
+
+{
+  echo(a);
+}`;

test/main.js

@@ -48,28 +48,6 @@ function createSelect(onchange) {
   select.style.height = "20px";
   select.style.marginBottom = "10px";
   select.onchange = onchange;
-  document.onkeydown = (event) => {
-    if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) {
-      return;
-    }
-    switch (event.key) {
-      case "ArrowLeft": {
-        if (select.selectedIndex > 0) {
-          select.selectedIndex--;
-          select.onchange();
-        } else alert("This is the first test case.");
-        break;
-      }
-      case "ArrowRight": {
-        if (select.selectedIndex < select.options.length - 1) {
-          select.selectedIndex++;
-          select.onchange();
-        } else alert("This is the last test case.");
-        break;
-      }
-    }
-  };
-
   return select;
 }