@weborigami/language 0.2.5 → 0.2.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Jan Miksovsky and other contributors
+Copyright (c) 2025 Jan Miksovsky and other contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/language",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Web Origami expression language compiler and runtime",
   "type": "module",
   "main": "./main.js",
@@ -12,8 +12,8 @@
     "yaml": "2.6.1"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.2.5",
-    "@weborigami/types": "0.2.5",
+    "@weborigami/async-tree": "0.2.6",
+    "@weborigami/types": "0.2.6",
     "watcher": "2.3.1"
   },
   "scripts": {

package/src/compiler/compile.js

@@ -1,8 +1,6 @@
-import { trailingSlash } from "@weborigami/async-tree";
 import { createExpressionFunction } from "../runtime/expressionFunction.js";
-import { ops } from "../runtime/internal.js";
+import optimize from "./optimize.js";
 import { parse } from "./parse.js";
-import { annotate, undetermined } from "./parserHelpers.js";
 
 function compile(source, options) {
   const { macros, startRule } = options;
@@ -14,9 +12,8 @@ function compile(source, options) {
     grammarSource: source,
     startRule,
   });
-  const cache = {};
-  const modified = transformReferences(code, cache, enableCaching, macros);
-  const fn = createExpressionFunction(modified);
+  const optimized = optimize(code, enableCaching, macros);
+  const fn = createExpressionFunction(optimized);
   return fn;
 }
 
@@ -40,100 +37,3 @@ export function templateDocument(source, options = {}) {
     startRule: "templateDocument",
   });
 }
-
-/**
- * Transform any remaining undetermined references to scope references.
- *
- * At the same time, transform those or explicit ops.scope calls to ops.external
- * calls unless they refer to local variables (variables defined by object
- * literals or lambda parameters).
- *
- * Also apply any macros to the code.
- */
-export function transformReferences(
-  code,
-  cache,
-  enableCaching,
-  macros,
-  locals = {}
-) {
-  const [fn, ...args] = code;
-
-  let additionalLocalNames;
-  switch (fn) {
-    case undetermined:
-    case ops.scope:
-      const key = args[0];
-      const normalizedKey = trailingSlash.remove(key);
-      if (macros?.[normalizedKey]) {
-        // Apply macro
-        const macroBody = macros[normalizedKey];
-        const modified = transformReferences(
-          macroBody,
-          cache,
-          enableCaching,
-          macros,
-          locals
-        );
-        // @ts-ignore
-        annotate(modified, code.location);
-        return modified;
-      } else if (enableCaching && !locals[normalizedKey]) {
-        // Upgrade to cached external reference
-        const modified = [ops.external, key, cache];
-        // @ts-ignore
-        annotate(modified, code.location);
-        return modified;
-      } else if (fn === undetermined) {
-        // Transform undetermined reference to regular scope call
-        const modified = [ops.scope, key];
-        // @ts-ignore
-        annotate(modified, code.location);
-        return modified;
-      } else {
-        // Internal ops.scope call; leave as is
-        return code;
-      }
-
-    case ops.lambda:
-      const parameters = args[0];
-      additionalLocalNames = parameters;
-      break;
-
-    case ops.object:
-      const entries = args;
-      additionalLocalNames = entries.map(([key]) => trailingSlash.remove(key));
-      break;
-  }
-
-  let updatedLocals = { ...locals };
-  if (additionalLocalNames) {
-    for (const key of additionalLocalNames) {
-      updatedLocals[key] = true;
-    }
-  }
-
-  const modified = code.map((child) => {
-    if (Array.isArray(child)) {
-      // Review: This currently descends into arrays that are not instructions,
-      // such as the parameters of a lambda. This should be harmless, but it'd
-      // be preferable to only descend into instructions. This would require
-      // surrounding ops.lambda parameters with ops.literal, and ops.object
-      // entries with ops.array.
-      return transformReferences(
-        child,
-        cache,
-        enableCaching,
-        macros,
-        updatedLocals
-      );
-    } else {
-      return child;
-    }
-  });
-
-  if (code.location) {
-    annotate(modified, code.location);
-  }
-  return modified;
-}

package/src/compiler/optimize.js

@@ -0,0 +1,124 @@
+import { pathFromKeys, trailingSlash } from "@weborigami/async-tree";
+import { ops } from "../runtime/internal.js";
+import { annotate, undetermined } from "./parserHelpers.js";
+
+/**
+ * Optimize an Origami code instruction:
+ *
+ * - Transform any remaining undetermined references to scope references.
+ * - Transform those or explicit ops.scope calls to ops.external calls unless
+ *   they refer to local variables (variables defined by object literals or
+ *   lambda parameters).
+ * - Apply any macros to the code.
+ */
+export default function optimize(
+  code,
+  enableCaching = true,
+  macros = {},
+  cache = {},
+  locals = {}
+) {
+  // See if we can optimize this level of the code
+  const [fn, ...args] = code;
+  let additionalLocalNames;
+  switch (fn) {
+    case ops.lambda:
+      const parameters = args[0];
+      additionalLocalNames = parameters;
+      break;
+
+    case ops.object:
+      const entries = args;
+      additionalLocalNames = entries.map(([key]) => trailingSlash.remove(key));
+      break;
+
+    // Both of these are handled the same way
+    case undetermined:
+    case ops.scope:
+      const key = args[0];
+      const normalizedKey = trailingSlash.remove(key);
+      if (macros?.[normalizedKey]) {
+        // Apply macro
+        const macro = macros?.[normalizedKey];
+        return applyMacro(macro, code, enableCaching, macros, cache, locals);
+      } else if (enableCaching && !locals[normalizedKey]) {
+        // Upgrade to cached external scope reference
+        const optimized = [ops.external, key, [ops.scope, key], cache];
+        // @ts-ignore
+        annotate(optimized, code.location);
+        return optimized;
+      } else if (fn === undetermined) {
+        // Transform undetermined reference to regular scope call
+        const optimized = [ops.scope, key];
+        // @ts-ignore
+        annotate(optimized, code.location);
+        return optimized;
+      } else {
+        // Internal ops.scope call; leave as is
+        return code;
+      }
+
+    case ops.traverse:
+      // Is the first argument a nonscope/undetermined reference?
+      const isScopeRef =
+        args[0]?.[0] === ops.scope || args[0]?.[0] === undetermined;
+      if (enableCaching && isScopeRef) {
+        // Is the first argument a nonlocal reference?
+        const normalizedKey = trailingSlash.remove(args[0][1]);
+        if (!locals[normalizedKey]) {
+          // Are the remaining arguments all literals?
+          const allLiterals = args
+            .slice(1)
+            .every((arg) => arg[0] === ops.literal);
+          if (allLiterals) {
+            // Convert to ops.external
+            const keys = args.map((arg) => arg[1]);
+            const path = pathFromKeys(keys);
+            const optimized = [ops.external, path, code, cache];
+            // @ts-ignore
+            annotate(optimized, code.location);
+            return optimized;
+          }
+        }
+      }
+      break;
+  }
+
+  // Add any locals introduced by this code to the list that will be consulted
+  // when we descend into child nodes.
+  let updatedLocals;
+  if (additionalLocalNames) {
+    updatedLocals = { ...locals };
+    for (const key of additionalLocalNames) {
+      updatedLocals[key] = true;
+    }
+  } else {
+    updatedLocals = locals;
+  }
+
+  // Optimize children
+  const optimized = code.map((child) => {
+    if (Array.isArray(child)) {
+      // Review: This currently descends into arrays that are not instructions,
+      // such as the parameters of a lambda. This should be harmless, but it'd
+      // be preferable to only descend into instructions. This would require
+      // surrounding ops.lambda parameters with ops.literal, and ops.object
+      // entries with ops.array.
+      return optimize(child, enableCaching, macros, cache, updatedLocals);
+    } else {
+      return child;
+    }
+  });
+
+  if (code.location) {
+    annotate(optimized, code.location);
+  }
+  return optimized;
+}
+
+function applyMacro(macro, code, enableCaching, macros, cache, locals) {
+  const optimized = optimize(macro, enableCaching, macros, cache, locals);
+  // @ts-ignore
+  annotate(optimized, code.location);
+  return optimized;
+}

package/src/runtime/evaluate.js

@@ -20,7 +20,7 @@ export default async function evaluate(code) {
   }
 
   let evaluated;
-  const unevaluatedFns = [ops.lambda, ops.object, ops.literal];
+  const unevaluatedFns = [ops.external, ops.lambda, ops.object, ops.literal];
   if (unevaluatedFns.includes(code[0])) {
     // Don't evaluate instructions, use as is.
     evaluated = code;

package/src/runtime/ops.js

@@ -131,16 +131,27 @@ addOpLabel(exponentiation, "«ops.exponentiation»");
  *
  * @this {AsyncTree|null}
  */
-export async function external(key, cache) {
-  if (key in cache) {
-    return cache[key];
+export async function external(path, code, cache) {
+  if (!this) {
+    throw new Error("Tried to get the scope of a null or undefined tree.");
+  }
+
+  if (path in cache) {
+    // Cache hit
+    return cache[path];
   }
-  // First save a promise for the value
-  const promise = scope.call(this, key);
-  cache[key] = promise;
+
+  // Don't await: might get another request for this before promise resolves
+  const promise = evaluate.call(this, code);
+  // Save promise so another request will get the same promise
+  cache[path] = promise;
+
+  // Now wait for the value
   const value = await promise;
-  // Now update with the actual value
-  cache[key] = value;
+
+  // Update the cache with the actual value
+  cache[path] = value;
+
   return value;
 }
 

package/test/compiler/compile.test.js

@@ -87,30 +87,6 @@ describe("compile", () => {
     assert.equal(bob, "Hello, Bob!");
   });
 
-  test("converts non-local ops.scope calls to ops.external", async () => {
-    const expression = `
-      (name) => {
-        a: 1
-        b: a            // local, should be left as ops.scope
-        c: nonLocal     // non-local, should be converted to ops.cache
-        d: name         // local, should be left as ops.scope
-      }
-    `;
-    const fn = compile.expression(expression);
-    const code = fn.code;
-    assert.deepEqual(stripCodeLocations(code), [
-      ops.lambda,
-      ["name"],
-      [
-        ops.object,
-        ["a", [ops.literal, 1]],
-        ["b", [ops.scope, "a"]],
-        ["c", [ops.external, "nonLocal", {}]],
-        ["d", [ops.scope, "name"]],
-      ],
-    ]);
-  });
-
   test("can apply a macro", async () => {
     const literal = [ops.literal, 1];
     const expression = `{ a: literal }`;

package/test/compiler/optimize.test.js

@@ -0,0 +1,44 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import * as compile from "../../src/compiler/compile.js";
+import optimize from "../../src/compiler/optimize.js";
+import { ops } from "../../src/runtime/internal.js";
+import { stripCodeLocations } from "./stripCodeLocations.js";
+
+describe("optimize", () => {
+  test("optimize non-local ops.scope calls to ops.external", async () => {
+    const expression = `
+      (name) => {
+        a: 1
+        b: a            // local, should be left as ops.scope
+        c: elsewhere    // external, should be converted to ops.external
+        d: name         // local, should be left as ops.scope
+      }
+    `;
+    const fn = compile.expression(expression);
+    const code = fn.code;
+    assert.deepEqual(stripCodeLocations(code), [
+      ops.lambda,
+      ["name"],
+      [
+        ops.object,
+        ["a", [ops.literal, 1]],
+        ["b", [ops.scope, "a"]],
+        ["c", [ops.external, "elsewhere", [ops.scope, "elsewhere"], {}]],
+        ["d", [ops.scope, "name"]],
+      ],
+    ]);
+  });
+
+  test("optimize scope traversals with all literal keys", async () => {
+    // Compilation of `x/y.js`
+    const code = [ops.traverse, [ops.scope, "x/"], [ops.literal, "y.js"]];
+    const optimized = optimize(code);
+    assert.deepEqual(stripCodeLocations(optimized), [
+      ops.external,
+      "x/y.js",
+      code,
+      {},
+    ]);
+  });
+});

package/test/runtime/ops.test.js

@@ -1,4 +1,4 @@
-import { ObjectTree } from "@weborigami/async-tree";
+import { DeepObjectTree, ObjectTree } from "@weborigami/async-tree";
 import assert from "node:assert";
 import { describe, test } from "node:test";
 
@@ -99,14 +99,21 @@ describe("ops", () => {
     assert.strictEqual(ops.exponentiation(2, 0), 1);
   });
 
-  test("ops.external looks up a value in scope and memoizes it", async () => {
+  test("ops.external evaluates code and cache its result", async () => {
     let count = 0;
-    const tree = new ObjectTree({
-      get count() {
-        return ++count;
+    const tree = new DeepObjectTree({
+      group: {
+        get count() {
+          return ++count;
+        },
       },
     });
-    const code = createCode([ops.external, "count", {}]);
+    const code = createCode([
+      ops.external,
+      "group/count",
+      [ops.traverse, [ops.scope, "group"], [ops.literal, "count"]],
+      {},
+    ]);
     const result = await evaluate.call(tree, code);
     assert.strictEqual(result, 1);
     const result2 = await evaluate.call(tree, code);