@weborigami/language 0.2.5 → 0.2.7

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.7",
   "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.7",
+    "@weborigami/types": "0.2.7",
     "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/compiler/parserHelpers.js

@@ -235,12 +235,17 @@ export function makeObject(entries, op) {
 
   for (let [key, value] of entries) {
     if (key === ops.spread) {
-      // Spread entry; accumulate
-      if (currentEntries.length > 0) {
-        spreads.push([op, ...currentEntries]);
-        currentEntries = [];
+      if (value[0] === ops.object) {
+        // Spread of an object; fold into current object
+        currentEntries.push(...value.slice(1));
+      } else {
+        // Spread of a tree; accumulate
+        if (currentEntries.length > 0) {
+          spreads.push([op, ...currentEntries]);
+          currentEntries = [];
+        }
+        spreads.push(value);
       }
-      spreads.push(value);
       continue;
     }
 
@@ -253,15 +258,6 @@ export function makeObject(entries, op) {
         // Optimize a getter for a primitive value to a regular property
         value = value[1];
       }
-      // else if (
-      //   value[0] === ops.object ||
-      //   (value[0] === ops.getter &&
-      //     value[1] instanceof Array &&
-      //     (value[1][0] === ops.object || value[1][0] === ops.merge))
-      // ) {
-      //   // Add a trailing slash to key to indicate value is a subtree
-      //   key = trailingSlash.add(key);
-      // }
     }
 
     currentEntries.push([key, value]);

package/src/runtime/evaluate.js

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

package/src/runtime/expressionObject.js

@@ -34,11 +34,13 @@ export default async function expressionObject(entries, parent) {
 
   let tree;
   const eagerProperties = [];
+  const propertyIsEnumerable = {};
   for (let [key, value] of entries) {
     // Determine if we need to define a getter or a regular property. If the key
     // has an extension, we need to define a getter. If the value is code (an
     // array), we need to define a getter -- but if that code takes the form
-    // [ops.getter, <primitive>], we can define a regular property.
+    // [ops.getter, <primitive>] or [ops.literal, <value>], we can define a
+    // regular property.
     let defineProperty;
     const extname = extension.extname(key);
     if (extname) {
@@ -48,6 +50,9 @@ export default async function expressionObject(entries, parent) {
     } else if (value[0] === ops.getter && !(value[1] instanceof Array)) {
       defineProperty = true;
       value = value[1];
+    } else if (value[0] === ops.literal) {
+      defineProperty = true;
+      value = value[1];
     } else {
       defineProperty = false;
     }
@@ -58,6 +63,7 @@ export default async function expressionObject(entries, parent) {
       key = key.slice(1, -1);
       enumerable = false;
     }
+    propertyIsEnumerable[key] = enumerable;
 
     if (defineProperty) {
       // Define simple property
@@ -105,7 +111,7 @@ export default async function expressionObject(entries, parent) {
   Object.defineProperty(object, symbols.keys, {
     configurable: true,
     enumerable: false,
-    value: () => keys(object, eagerProperties, entries),
+    value: () => keys(object, eagerProperties, propertyIsEnumerable, entries),
     writable: true,
   });
 
@@ -158,6 +164,8 @@ function entryKey(object, eagerProperties, entry) {
   return trailingSlash.toggle(key, entryCreatesSubtree);
 }
 
-function keys(object, eagerProperties, entries) {
-  return entries.map((entry) => entryKey(object, eagerProperties, entry));
+function keys(object, eagerProperties, propertyIsEnumerable, entries) {
+  return entries
+    .filter(([key]) => propertyIsEnumerable[key])
+    .map((entry) => entryKey(object, eagerProperties, entry));
 }

package/src/runtime/mergeTrees.js

@@ -2,6 +2,7 @@ import {
   isPlainObject,
   isUnpackable,
   merge,
+  setParent,
   Tree,
 } from "@weborigami/async-tree";
 
@@ -59,5 +60,6 @@ export default async function mergeTrees(...trees) {
 
   // Merge the trees.
   const result = merge(...unpacked);
+  setParent(result, this);
   return result;
 }

package/src/runtime/ops.js

@@ -33,6 +33,17 @@ export function addition(a, b) {
 }
 addOpLabel(addition, "«ops.addition»");
 
+/**
+ * Construct an array.
+ *
+ * @this {AsyncTree|null}
+ * @param {any[]} items
+ */
+export async function array(...items) {
+  return items;
+}
+addOpLabel(array, "«ops.array»");
+
 export function bitwiseAnd(a, b) {
   return a & b;
 }
@@ -53,17 +64,6 @@ export function bitwiseXor(a, b) {
 }
 addOpLabel(bitwiseXor, "«ops.bitwiseXor»");
 
-/**
- * Construct an array.
- *
- * @this {AsyncTree|null}
- * @param {any[]} items
- */
-export async function array(...items) {
-  return items;
-}
-addOpLabel(array, "«ops.array»");
-
 /**
  * Like ops.scope, but only searches for a builtin at the top of the scope
  * chain.
@@ -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;
 }
 
@@ -317,9 +328,41 @@ export async function logicalOr(head, ...tail) {
  * Merge the given trees. If they are all plain objects, return a plain object.
  *
  * @this {AsyncTree|null}
- * @param {import("@weborigami/async-tree").Treelike[]} trees
+ * @param {Code[]} codes
  */
-export async function merge(...trees) {
+export async function merge(...codes) {
+  // First pass: evaluate the direct property entries in a single object
+  let treeSpreads = false;
+  const directEntries = [];
+  for (const code of codes) {
+    if (code[0] === object) {
+      directEntries.push(...code.slice(1));
+    } else {
+      treeSpreads = true;
+    }
+  }
+
+  const directObject = directEntries
+    ? await expressionObject(directEntries, this)
+    : null;
+  if (!treeSpreads) {
+    // No tree spreads, we're done
+    return directObject;
+  }
+
+  // Second pass: evaluate the trees with the direct properties object in scope
+  let context;
+  if (directObject) {
+    context = Tree.from(directObject);
+    context.parent = this;
+  } else {
+    context = this;
+  }
+
+  const trees = await Promise.all(
+    codes.map(async (code) => evaluate.call(context, code))
+  );
+
   return mergeTrees.call(this, ...trees);
 }
 addOpLabel(merge, "«ops.merge»");
@@ -427,7 +470,7 @@ addOpLabel(shiftRightUnsigned, "«ops.shiftRightUnsigned»");
  * The spread operator is a placeholder during parsing. It should be replaced
  * with an object merge.
  */
-export function spread(...args) {
+export function spread(arg) {
   throw new Error(
     "Internal error: a spread operation wasn't compiled correctly."
   );

package/src/runtime/typos.js

@@ -15,6 +15,12 @@ export function isTypo(s1, s2) {
     return false;
   }
 
+  // If strings are both a single character, we don't want to consider them
+  // typos.
+  if (length1 === 1 && length2 === 1) {
+    return false;
+  }
+
   // If length difference is more than 1, distance can't be 1
   if (Math.abs(length1 - length2) > 1) {
     return false;

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/compiler/parse.test.js

@@ -701,6 +701,11 @@ describe("Origami parser", () => {
       [ops.object, ["a", [ops.literal, 1]]],
       [ops.scope, "b"],
     ]);
+    assertParse("objectLiteral", "{ a: 1, ...{ b: 2 } }", [
+      ops.object,
+      ["a", [ops.literal, 1]],
+      ["b", [ops.literal, 2]],
+    ]);
     assertParse("objectLiteral", "{ (a): 1 }", [
       ops.object,
       ["(a)", [ops.literal, 1]],

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);
@@ -213,6 +220,45 @@ describe("ops", () => {
     assert.strictEqual(await ops.logicalOr(true, errorFn), true);
   });
 
+  test("ops.merge", async () => {
+    // {
+    //   a: 1
+    //   …fn(a)
+    // }
+    const scope = new ObjectTree({
+      fn: (a) => ({ b: 2 * a }),
+    });
+    const code = createCode([
+      ops.merge,
+      [ops.object, ["a", [ops.literal, 1]]],
+      [
+        [ops.builtin, "fn"],
+        [ops.scope, "a"],
+      ],
+    ]);
+    const result = await evaluate.call(scope, code);
+    assert.deepEqual(result, { a: 1, b: 2 });
+  });
+
+  test("ops.merge lets all direct properties see each other", async () => {
+    // {
+    //   a: 1
+    //   ...more
+    //   c: a
+    // }
+    const scope = new ObjectTree({
+      more: { b: 2 },
+    });
+    const code = createCode([
+      ops.merge,
+      [ops.object, ["a", [ops.literal, 1]]],
+      [ops.scope, "more"],
+      [ops.object, ["c", [ops.scope, "a"]]],
+    ]);
+    const result = await evaluate.call(scope, code);
+    assert.deepEqual(result, { a: 1, b: 2, c: 1 });
+  });
+
   test("ops.multiplication multiplies two numbers", async () => {
     assert.strictEqual(ops.multiplication(3, 4), 12);
     assert.strictEqual(ops.multiplication(-3, 4), -12);

package/test/runtime/typos.test.js

@@ -12,6 +12,7 @@ describe("typos", () => {
     assert(isTypo("cat", "cta")); // transposition
     assert(isTypo("cat", "act")); // transposition
     assert(!isTypo("cat", "dog")); // more than 1 edit
+    assert(!isTypo("a", "b")); // single character
   });
 
   test("typos", () => {