✨Introduce the --canon-- module

One of the principles of PlatformScript is for there to be very little
magic, and what magic there is should be confined to limited
cases. This runs afoul of the "magical" values that are needed to make
things actually work. These are the "magical" values like React
constructors on the browser, or file system access on Unix systems.

It is anticipated that PS will run in many different contexts and so
we have to be able to swap out what is magically available without
that process seeming magical.

To do this, we make all magical values appear within a normal
module. Instead of them just appearing in your scope, they are
accessed by a special module called `--canon--`.

The "canon" can be passed into the module loader and any module that
requests the`--canon--` shall receive it. Eventually, we can use this
canonical value to typecheck code that accesses the canon.

The word canon was chosen because it refers to an established body of
work that can be drawn upon to perform contemporty tasks. Like the
canon of law, or the canon of prayer. Also because "env" was taken
already and we want to reserve "context" for a runtime api.

Author: cowboyd

load.ts

@@ -1,4 +1,4 @@
-import type { PSEnv, PSModule, PSValue } from "./types.ts";
+import type { PSEnv, PSMap, PSModule, PSValue } from "./types.ts";
 import type { Operation } from "./deps.ts";
 
 import { expect, useAbortSignal } from "./deps.ts";
@@ -11,30 +11,32 @@ export interface LoadOptions {
   location: string | URL;
   base?: string;
   env?: PSEnv;
+  canon?: PSMap;
 }
 
 export function* load(options: LoadOptions): Operation<PSModule> {
-  let { location, base, env } = options;
+  let { location, base, env, canon } = options;
   let url = typeof location === "string" ? new URL(location, base) : location;
 
   let content = yield* read(url);
   let source = parse(content);
 
-  return yield* moduleEval({ source, location: url, env });
+  return yield* moduleEval({ source, location: url, env, canon });
 }
 
 export interface ModuleEvalOptions {
   location: string | URL;
   source: PSValue;
   env?: PSEnv;
+  canon?: PSMap;
 }
 
 export function* moduleEval(options: ModuleEvalOptions): Operation<PSModule> {
   let { location, source, env = createYSEnv() } = options;
   let url = typeof location === "string" ? new URL(location) : location;
 
   let mod: PSModule = {
-    url,
+    location: location.toString(),
     source,
     value: source,
     imports: [],
@@ -45,6 +47,7 @@ export function* moduleEval(options: ModuleEvalOptions): Operation<PSModule> {
   }
 
   let scope = data.map({});
+  let canon = options.canon ?? data.map({});
 
   let imports = lookup("$import", source);
   let rest = exclude(["$import"], source);
@@ -67,11 +70,19 @@ export function* moduleEval(options: ModuleEvalOptions): Operation<PSModule> {
         );
       }
       let bindings = matchBindings(names.value);
-      let dep = yield* load({
-        location: loc.value,
-        base: url.toString(),
-        env,
-      });
+
+      let dep = loc.value === "--canon--"
+        ? ({
+          location: loc.value,
+          source: canon,
+          value: canon,
+          imports: [],
+        })
+        : yield* load({
+          location: loc.value,
+          base: url.toString(),
+          env,
+        });
 
       mod.imports.push({
         module: dep,
@@ -85,13 +96,13 @@ export function* moduleEval(options: ModuleEvalOptions): Operation<PSModule> {
           value = dep.value;
         } else if (dep.value.type !== "map") {
           throw new Error(
-            `tried to import a name from ${dep.url}, but it is not a 'map'. It is a ${dep.value.type}`,
+            `tried to import a name from ${dep.location}, but it is not a 'map'. It is a ${dep.value.type}`,
           );
         } else {
           let result = lookup(binding.name, dep.value);
           if (result.type === "nothing") {
             throw new Error(
-              `module ${dep.url} does not have a member named '${binding.name}'`,
+              `module ${dep.location} does not have a member named '${binding.name}'`,
             );
           } else {
             value = result.value;

platformscript.ts

@@ -1,7 +1,6 @@
 import type { PSEnv, PSFn, PSMap, PSModule, PSValue } from "./types.ts";
 import type { Operation, Task } from "./deps.ts";
 import { createYSEnv, global } from "./evaluate.ts";
-import { concat } from "./psmap.ts";
 import { load, moduleEval } from "./load.ts";
 import { map } from "./data.ts";
 import { run as $run } from "./deps.ts";
@@ -14,16 +13,11 @@ export interface PlatformScript {
   load(url: string | URL, base?: string): Task<PSModule>;
 }
 
-export function createPlatformScript(
-  globals?: (ps: PlatformScript) => PSMap,
-): PlatformScript {
-  let env = lazy(() => {
-    let ext = globals ? globals(platformscript) : map({});
-    return createYSEnv(concat(global, ext));
-  });
+export function createPlatformScript(canon = map({})): PlatformScript {
+  let env = createYSEnv(global);
 
   function run<T>(block: (env: PSEnv) => Operation<T>): Task<T> {
-    return $run(() => block(env()));
+    return $run(() => block(env));
   }
 
   let platformscript: PlatformScript = {
@@ -35,20 +29,13 @@ export function createPlatformScript(
       return run((env) => env.eval(value, bindings));
     },
     moduleEval(value, url) {
-      return run((env) => moduleEval({ source: value, location: url, env }));
+      return run((env) =>
+        moduleEval({ source: value, location: url, env, canon })
+      );
     },
     load(location, base) {
-      return run((env) => load({ location, base, env }));
+      return run((env) => load({ location, base, env, canon }));
     },
   };
   return platformscript;
 }
-
-function lazy<T>(create: () => T): () => T {
-  let thunk = () => {
-    let value = create();
-    thunk = () => value;
-    return value;
-  };
-  return () => thunk();
-}

test/external.test.ts

@@ -6,58 +6,46 @@ import * as _ from "https://raw.githubusercontent.com/lodash/lodash/4.17.21-es/l
 describe("external", () => {
   it("can represent any arbitrary javascript value", async () => {
     let obj = { unqiue: "object" };
-    let ps = createPlatformScript(() =>
-      map({
-        "extern": external(obj),
-      })
-    );
-    expect((await ps.eval(parse("$extern"))).value).toBe(obj);
+    let binding = map({
+      "extern": external(obj),
+    });
+
+    let ps = createPlatformScript();
+    expect((await ps.eval(parse("$extern"), binding)).value).toBe(obj);
   });
 
   it("can define new PS values from the external value", async () => {
     let obj = { I: { contain: { the: { number: number(5) } } } };
-    let ps = createPlatformScript(() =>
-      map({
-        "truly": external(obj, (path, o) => _.get(o, path)),
-      })
-    );
+    let binding = map({
+      "truly": external(obj, (path, o) => _.get(o, path)),
+    });
+    let ps = createPlatformScript();
 
     let program = parse("$truly.I.contain.the.number");
-    expect((await ps.eval(program)).value).toEqual(5);
+    expect((await ps.eval(program, binding)).value).toEqual(5);
   });
   it("errors if a dereference is undefined", async () => {
-    let ps = createPlatformScript(() =>
-      map({
-        "oops": external({}, () => void 0),
-      })
-    );
-    try {
-      await ps.eval(parse("$oops.i.did.it.again"));
-      throw new Error("expected block to throw, but it did not");
-    } catch (error) {
-      expect(error.name).toEqual("ReferenceError");
-    }
+    let binding = map({
+      "oops": external({}, () => void 0),
+    });
+    let ps = createPlatformScript();
+
+    await expect(ps.eval(parse("$oops.i.did.it.again"), binding)).rejects
+      .toHaveProperty("name", "ReferenceError");
   });
   it("errors if a derefenence does not return a PSValue", async () => {
-    let ps = createPlatformScript(() =>
-      map({
-        "oops": external(
-          { wrong: "type" },
-          //@ts-expect-error situation could happen if you are using JavaScript...
-          () => ({ type: "WAT!!", value: "hi" }),
-        ),
-      })
+    let binding = map({
+      "oops": external(
+        { wrong: "type" },
+        //@ts-expect-error situation could happen if you are using JavaScript...
+        () => ({ type: "WAT!!", value: "hi" }),
+      ),
+    });
+    let ps = createPlatformScript();
+    await expect(ps.eval(parse("$oops.wrong"), binding)).rejects.toHaveProperty(
+      "name",
+      "TypeError",
     );
-
-    try {
-      await ps.eval(parse("$oops.wrong"));
-      throw new Error("expected block to throw, but it did not");
-    } catch (error) {
-      expect(error.message).toMatch(
-        /did not resolve to a platformscript value/,
-      );
-      expect(error.name).toEqual("TypeError");
-    }
   });
   // it("can handle an exception that happens during dereference");
 });

test/fn.test.ts

@@ -73,13 +73,12 @@ $say: Hello
   });
 
   it("can reference values from arguments to native functions", async () => {
-    let interp = ps.createPlatformScript(() =>
-      ps.map({
-        id: ps.fn(function* $id({ arg, env }) {
-          return yield* env.eval(arg);
-        }, { name: "x" }),
-      })
-    );
+    let binding = ps.map({
+      id: ps.fn(function* $id({ arg, env }) {
+        return yield* env.eval(arg);
+      }, { name: "x" }),
+    });
+    let interp = ps.createPlatformScript();
 
     let program = ps.parse(`
 $let:
@@ -89,7 +88,7 @@ $do:
   $myid: hello world
 `);
 
-    let result = await interp.eval(program);
+    let result = await interp.eval(program, binding);
     expect(result.value).toEqual("hello world");
   });
 

test/module.test.ts

@@ -2,7 +2,7 @@ import type { PSMap, PSModule } from "../types.ts";
 import type { Task } from "../deps.ts";
 
 import { describe, expect, it, useStaticFileServer } from "./suite.ts";
-import { load, moduleEval, number, parse, ps2js, string } from "../mod.ts";
+import { load, map, moduleEval, number, parse, ps2js, string } from "../mod.ts";
 import { run } from "../deps.ts";
 import { lookup, lookup$ } from "../psmap.ts";
 
@@ -101,6 +101,18 @@ main: $myfive
       expect(lookup$("main", mod.value)).toEqual(number(5));
     });
   });
+
+  it("supports importing from the canonical module", async () => {
+    await run(function* () {
+      let source = parse(`$import:\n  five: --canon--\nhi: $five`);
+      let mod = yield* moduleEval({
+        source,
+        location: new URL(`modules/virtual-module.yaml`, import.meta.url),
+        canon: map({ "five": number(5) }),
+      });
+      expect(lookup$("hi", mod.value)).toEqual(number(5));
+    });
+  });
 });
 
 function loadmod(url: string): Task<PSModule> {

test/suite.ts

@@ -1,5 +1,5 @@
 export * from "https://deno.land/[email protected]/testing/bdd.ts";
-export { expect } from "https://deno.land/x/expect@v0.2.9/mod.ts";
+export { expect } from "https://deno.land/x/expect@v0.3.0/mod.ts";
 export * from "https://deno.land/[email protected]/testing/asserts.ts";
 
 import { createPlatformScript, js2ps, parse, ps2js, PSMap } from "../mod.ts";

types.ts

@@ -7,7 +7,7 @@ export interface PSEnv {
 }
 
 export interface PSModule {
-  url: URL;
+  location: string;
   source: PSValue;
   value: PSValue;
   imports: {