Variable-scoped input shadowing (#349)

* add shadow and unshadow for variables

* update tests

* review feedback

* Update test/variable/shadow-test.js

Co-authored-by: Mike Bostock <[email protected]>

* review feedback

* Update src/module.js

Co-authored-by: Mike Bostock <[email protected]>

* Update src/variable.js

Co-authored-by: Mike Bostock <[email protected]>

* Update src/variable.js

Co-authored-by: Mike Bostock <[email protected]>

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Duane Barlow

src/module.js

@@ -50,8 +50,8 @@ function module_import() {
   return v.import.apply(v, arguments);
 }
 
-function module_variable(observer) {
-  return new Variable(TYPE_NORMAL, this, observer);
+function module_variable(observer, options) {
+  return new Variable(TYPE_NORMAL, this, observer, options);
 }
 
 async function module_value(name) {

src/variable.js

@@ -10,7 +10,7 @@ export const TYPE_DUPLICATE = 3; // created on duplicate definition
 
 export const no_observer = Symbol("no-observer");
 
-export function Variable(type, module, observer) {
+export function Variable(type, module, observer, options) {
   if (!observer) observer = no_observer;
   Object.defineProperties(this, {
     _observer: {value: observer, writable: true},
@@ -26,6 +26,7 @@ export function Variable(type, module, observer) {
     _promise: {value: Promise.resolve(undefined), writable: true},
     _reachable: {value: observer !== no_observer, writable: true}, // Is this variable transitively visible?
     _rejector: {value: variable_rejector(this)},
+    _shadow: {value: initShadow(module, options)},
     _type: {value: type},
     _value: {value: undefined, writable: true},
     _version: {value: 0, writable: true}
@@ -36,11 +37,20 @@ Object.defineProperties(Variable.prototype, {
   _pending: {value: variable_pending, writable: true, configurable: true},
   _fulfilled: {value: variable_fulfilled, writable: true, configurable: true},
   _rejected: {value: variable_rejected, writable: true, configurable: true},
+  _resolve: {value: variable_resolve, writable: true, configurable: true},
   define: {value: variable_define, writable: true, configurable: true},
   delete: {value: variable_delete, writable: true, configurable: true},
   import: {value: variable_import, writable: true, configurable: true}
 });
 
+function initShadow(module, options) {
+  if (!options?.shadow) return null;
+  return new Map(
+    Object.entries(options.shadow)
+      .map(([name, definition]) => [name, (new Variable(TYPE_IMPLICIT, module)).define([], definition)])
+  );
+}
+
 function variable_attach(variable) {
   variable._module._runtime._dirty.add(variable);
   variable._outputs.add(this);
@@ -89,11 +99,15 @@ function variable_define(name, inputs, definition) {
   }
   return variable_defineImpl.call(this,
     name == null ? null : String(name),
-    inputs == null ? [] : map.call(inputs, this._module._resolve, this._module),
+    inputs == null ? [] : map.call(inputs, this._resolve, this),
     typeof definition === "function" ? definition : constant(definition)
   );
 }
 
+function variable_resolve(name) {
+  return this._shadow?.get(name) ?? this._module._resolve(name);
+}
+
 function variable_defineImpl(name, inputs, definition) {
   const scope = this._module._scope, runtime = this._module._runtime;
 

test/variable/shadow-test.js

@@ -0,0 +1,68 @@
+import {Runtime} from "@observablehq/runtime";
+import {valueof} from "./valueof.js";
+import assert from "assert";
+
+it("module.variable(…, {shadow}) can define a shadow input", async () => {
+  const runtime = new Runtime();
+  const module = runtime.module();
+
+  module.define("val", [], 1000);
+  const a = module.variable(true, {shadow: {val: 100}}).define("a", ["val"], (val) => val);
+
+  assert.deepStrictEqual(await valueof(a), {value: 100});
+});
+
+it("module.variable(…, {shadow}) can define shadow inputs that differ between variables", async () => {
+  const runtime = new Runtime();
+  const module = runtime.module();
+
+  module.define("val", [], 1000);
+  const a = module.variable(true, {shadow: {val: 100}}).define("a", ["val"], (val) => val);
+  const b = module.variable(true, {shadow: {val: 200}}).define("b", ["val"], (val) => val);
+  assert.deepStrictEqual(await valueof(a), {value: 100});
+  assert.deepStrictEqual(await valueof(b), {value: 200});
+});
+
+it("module.variable(…, {shadow}) variables that are downstream will also use the shadow input", async () => {
+  const runtime = new Runtime();
+  const module = runtime.module();
+
+  module.define("val", [], 1000);
+  const a = module.variable(true, {shadow: {val: 100}}).define("a", ["val"], (val) => val);
+  const b = module.variable(true, {shadow: {val: 200}}).define("b", ["val"], (val) => val);
+  const c = module.variable(true).define("c", ["a", "b"], (a, b) => `${a}, ${b}`);
+
+  assert.deepStrictEqual(await valueof(a), {value: 100});
+  assert.deepStrictEqual(await valueof(b), {value: 200});
+  assert.deepStrictEqual(await valueof(c), { value: "100, 200" });
+});
+
+it("module.variable(…, {shadow}) variables a->b->c that shadow the same inputs will each use their own shadows", async () => {
+  const runtime = new Runtime();
+  const main = runtime.module();
+
+  const a = main
+    .variable(true, {shadow: {val: 100}})
+    .define("a", ["val"], (val) => val);
+  const b = main
+    .variable(true, {shadow: {val: 200}})
+    .define("b", ["val", "a"], (val, a) => `${val}, ${a}`);
+  const c = main
+    .variable(true, {shadow: {val: 300}})
+    .define("c", ["val", "b", "a"], (val, b, a) => `${val}, (${b}), ${a}`);
+
+  assert.deepStrictEqual(await valueof(a), {value: 100});
+  assert.deepStrictEqual(await valueof(b), {value: "200, 100"});
+  assert.deepStrictEqual(await valueof(c), {value: "300, (200, 100), 100"});
+});
+
+it("module.variable(…, {shadow}) can shadow a non-existent variable", async () => {
+  const runtime = new Runtime();
+  const main = runtime.module();
+
+  const a = main
+    .variable(true, {shadow: {val: 100}})
+    .define("a", ["val"], (val) => val);
+
+  assert.deepStrictEqual(await valueof(a), {value: 100});
+});