@weborigami/origami 0.6.16 → 0.7.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.6.16",
+  "version": "0.7.0-beta.1",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -13,24 +13,24 @@
   "main": "./main.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "25.3.2",
-    "typescript": "5.9.3"
+    "@types/node": "25.9.1",
+    "typescript": "6.0.3"
   },
   "dependencies": {
-    "@hpcc-js/wasm-graphviz": "^1.21.0",
-    "@weborigami/async-tree": "0.6.16",
+    "@hpcc-js/wasm-graphviz": "1.21.7",
+    "@weborigami/async-tree": "0.7.0-beta.1",
     "@weborigami/json-feed-to-rss": "1.0.1",
-    "@weborigami/language": "0.6.16",
-    "css-tree": "3.1.0",
+    "@weborigami/language": "0.7.0-beta.1",
+    "css-tree": "3.2.1",
     "highlight.js": "11.11.1",
-    "jsdom": "28.1.0",
-    "marked": "17.0.3",
-    "marked-gfm-heading-id": "4.1.3",
-    "marked-highlight": "2.2.3",
-    "marked-smartypants": "1.1.11",
+    "jsdom": "29.1.1",
+    "marked": "18.0.4",
+    "marked-gfm-heading-id": "4.1.4",
+    "marked-highlight": "2.2.4",
+    "marked-smartypants": "1.1.12",
     "sharp": "0.34.5",
     "whatwg-mimetype": "5.0.0",
-    "yaml": "2.8.2"
+    "yaml": "2.9.0"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/cli/cli.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 
 import { Tree } from "@weborigami/async-tree";
-import { formatError, projectRootFromPath } from "@weborigami/language";
+import {
+  activeProjectRoot,
+  formatError,
+  projectRootFromPath,
+} from "@weborigami/language";
 import path from "node:path";
 import process, { stdout } from "node:process";
 import help from "../dev/help.js";
@@ -12,10 +16,6 @@ const TypedArray = Object.getPrototypeOf(Uint8Array);
 async function main(...args) {
   const expression = args.join(" ");
 
-  // Find the project root.
-  const currentDirectory = process.cwd();
-  const projectRoot = await projectRootFromPath(currentDirectory);
-
   // If no arguments were passed, show usage.
   if (!expression) {
     const usage = await help();
@@ -23,6 +23,11 @@ async function main(...args) {
     return;
   }
 
+  // Find the project root.
+  const currentDirectory = process.cwd();
+  const projectRoot = await projectRootFromPath(currentDirectory);
+  activeProjectRoot.set(projectRoot);
+
   // Traverse from the project root to the current directory.
   const relative = path.relative(projectRoot.path, currentDirectory);
   const parent = await Tree.traversePath(projectRoot, relative);

package/src/common/hashBytes.js

@@ -0,0 +1,26 @@
+import { toString } from "@weborigami/async-tree";
+import { createHash } from "node:crypto";
+
+/**
+ * Given data, return a 256-bit hash of that data. The data can be a string or a
+ * Uint8Array.
+ *
+ * @typedef {import("@weborigami/async-tree").Stringlike} Stringlike
+ *
+ * @param {Uint8Array|Stringlike} data
+ */
+export default function hashBytes(data) {
+  let bytes;
+  if (data instanceof Uint8Array) {
+    bytes = data;
+  } else {
+    const text = toString(data);
+    if (!text) {
+      throw new TypeError("Data must be a string or Uint8Array");
+    }
+    bytes = new TextEncoder().encode(text);
+  }
+
+  const hash = createHash("sha256").update(bytes).digest();
+  return hash;
+}

package/src/common/serialize.js

@@ -43,6 +43,9 @@ export async function toJson(object) {
  * @returns {Promise<string>}
  */
 export async function toYaml(object) {
+  // TODO: The toPlainValue will remove trailing slashes from keys, which should
+  // only happen for maps that support trailing slash keys. For maps that don't,
+  // we should preserve trailing slashes.
   const serializable = await toPlainValue(object, reduceToMap);
   return YAML.stringify(serializable);
 }

package/src/dev/OriCommandTransform.js

@@ -1,5 +1,5 @@
 import { isUnpackable, scope, trailingSlash } from "@weborigami/async-tree";
-import { projectGlobals } from "@weborigami/language";
+import { getGlobalsForTree } from "@weborigami/language";
 
 /**
  * Add support for commands prefixed with `!`.
@@ -28,11 +28,11 @@ export default function OriCommandTransform(Base) {
         }
 
         // Key is an Origami command; invoke it.
-        const globals = await projectGlobals(/** @type {any} */ (this));
+        const globals = getGlobalsForTree(this);
         const commandName = trailingSlash.remove(key.slice(1).trim());
 
         // Look for command as a global or Dev command
-        const command = globals[commandName] ?? globals.Dev?.[commandName];
+        const command = globals?.[commandName] ?? globals?.Dev?.[commandName];
         if (command) {
           value = await command(this);
         } else {

package/src/dev/changes.js

@@ -1,10 +1,4 @@
-import {
-  args,
-  isStringlike,
-  toString,
-  trailingSlash,
-  Tree,
-} from "@weborigami/async-tree";
+import { args, isStringlike, toString, Tree } from "@weborigami/async-tree";
 
 /**
  * Given an old tree and a new tree, return a tree of changes indicated
@@ -25,51 +19,20 @@ export default async function changes(oldMaplike, newMaplike) {
     position: 2,
   });
 
-  const oldKeys = await Tree.keys(oldTree);
-  const newKeys = await Tree.keys(newTree);
-
-  const oldKeysNormalized = oldKeys.map(trailingSlash.remove);
-  const newKeysNormalized = newKeys.map(trailingSlash.remove);
-
-  let result;
-
-  for (const oldKey of oldKeys) {
-    const oldNormalized = trailingSlash.remove(oldKey);
-    if (!newKeysNormalized.includes(oldNormalized)) {
-      result ??= {};
-      result[oldKey] = "deleted";
-      continue;
-    }
-
-    const oldValue = await oldTree.get(oldKey);
-    const newValue = await newTree.get(oldKey);
-
-    if (Tree.isMap(oldValue) && Tree.isMap(newValue)) {
-      const treeChanges = await changes(oldValue, newValue);
-      if (treeChanges && Object.keys(treeChanges).length > 0) {
-        result ??= {};
-        result[oldKey] = treeChanges;
-      }
-    } else if (isStringlike(oldValue) && isStringlike(newValue)) {
-      const oldText = toString(oldValue);
-      const newText = toString(newValue);
-      if (oldText !== newText) {
-        result ??= {};
-        result[oldKey] = "changed";
-      }
-    } else {
-      result ??= {};
-      result[oldKey] = "changed";
-    }
-  }
+  const combination = await Tree.combine(oldTree, newTree, compare);
+  return combination;
+}
 
-  for (const newKey of newKeys) {
-    const newNormalized = trailingSlash.remove(newKey);
-    if (!oldKeysNormalized.includes(newNormalized)) {
-      result ??= {};
-      result[newKey] = "added";
-    }
+function compare(oldValue, newValue) {
+  if (oldValue !== undefined && newValue === undefined) {
+    return "deleted";
+  } else if (oldValue === undefined && newValue !== undefined) {
+    return "added";
+  } else if (isStringlike(oldValue) && isStringlike(newValue)) {
+    const oldText = toString(oldValue);
+    const newText = toString(newValue);
+    return oldText === newText ? undefined : "changed";
+  } else {
+    return oldValue === newValue ? undefined : "changed";
   }
-
-  return result;
 }

package/src/dev/debug2/debug2.js

@@ -1,5 +1,3 @@
-import { OrigamiFileMap } from "@weborigami/language";
-import path from "node:path";
 import debugParent from "./debugParent.js";
 
 /**
@@ -42,39 +40,7 @@ export default async function debug2(code, state) {
     parentPath,
   });
 
-  // Watch the parent files for changes
-  const tree = new OrigamiFileMap(parentPath);
-  tree.watch();
-  tree.addEventListener?.("change", async (event) => {
-    // @ts-ignore
-    const { filePath } = event.options;
-    if (isJavaScriptFile(filePath)) {
-      // Need to restart the child process
-      console.log("JavaScript file changed, restarting server…");
-      await server.restart();
-    } else if (path.basename(filePath) === "package.json") {
-      // Need to restart the child process
-      console.log("package.json changed, restarting server…");
-      await server.restart();
-    } else {
-      // Just have the child reevaluate the expression
-      console.log("File changed, reloading site…");
-      await server.reevaluate();
-    }
-  });
-
-  // When server closes, stop watching for file changes
-  server.on("close", () => {
-    tree.unwatch();
-  });
-
   console.log(`Server running at ${server.origin}. Press Ctrl+C to stop.`);
 }
 debug2.needsState = true;
 debug2.unevaluatedArgs = true;
-
-function isJavaScriptFile(filePath) {
-  const extname = path.extname(filePath).toLowerCase();
-  const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
-  return jsExtensions.includes(extname);
-}

package/src/dev/debug2/debugChild.js

@@ -1,4 +1,11 @@
+import { AsyncMap, Tree } from "@weborigami/async-tree";
+import {
+  activeProjectRoot,
+  projectRootFromPath,
+  systemCache,
+} from "@weborigami/language";
 import http from "node:http";
+import path from "node:path";
 import { requestListener } from "../../server/server.js";
 import expressionTree from "./expressionTree.js";
 
@@ -36,13 +43,26 @@ if (parentPath === undefined) {
   fail("Missing Origami parent");
 }
 
-const quiet = process.env.ORIGAMI_QUIET === "1";
+const projectRoot = await projectRootFromPath(parentPath);
+activeProjectRoot.set(projectRoot);
+projectRoot.watch();
 
-// An indirect pointer to the tree of resources;
-let treeHandle = {};
+// Traverse from the project root to the indicated parent.
+const relative = path.relative(projectRoot.path, parentPath);
+const parent = await Tree.traversePath(projectRoot, relative);
 
-// Initial evaluation of the expression
-await evaluateExpression();
+// Notify parent if a file changes
+projectRoot.addEventListener("change", async (/** @type {any} */ event) => {
+  const { filePath } = event.options;
+  if (filePath) {
+    process.send?.({ type: "VALUE_CHANGE", path: filePath });
+  }
+});
+
+const quiet = process.env.ORIGAMI_QUIET === "1";
+
+// Get a handle to the tree produced by evaluating the expression
+const treeHandle = await handleToEvaluatedExpression(expression, parent);
 
 // Serve the tree of resources
 const listener = requestListener(treeHandle, { quiet });
@@ -59,20 +79,26 @@ server.on("connection", (socket) => {
 server.keepAliveTimeout = 1000;
 server.headersTimeout = 5000;
 
-// Draining state
-let draining = false;
+// Closing state
+let closing = false;
 let serverClosed = false;
 
-function beginDrain() {
-  if (draining) return;
-  draining = true;
+function beginClose() {
+  if (closing) {
+    return;
+  }
+
+  closing = true;
 
   // Stop accepting new connections.
   server.close(() => {
     serverClosed = true;
-    maybeFinishDrain();
+    maybeFinishClose();
   });
 
+  // Stop watching files
+  projectRoot.unwatch();
+
   // Give in-flight requests a moment, then force-close remaining sockets.
   const GRACE_MS = 1200;
   setTimeout(() => {
@@ -81,7 +107,7 @@ function beginDrain() {
       socket.destroy();
     }
     // socket "close" events will shrink the set; check again soon.
-    setTimeout(maybeFinishDrain, 50).unref();
+    setTimeout(maybeFinishClose, 50).unref();
   }, GRACE_MS).unref();
 
   // Absolute last resort: don’t hang forever.
@@ -89,50 +115,54 @@ function beginDrain() {
   setTimeout(() => process.exit(0), HARD_MS).unref();
 }
 
-async function evaluateExpression() {
-  const tree = await expressionTree({
-    expression,
-    parentPath,
+async function handleToEvaluatedExpression(expression, parent) {
+  const handle = Object.assign(new AsyncMap(), {
+    async get(key) {
+      const tree = await this.getTree();
+      return tree.get(key);
+    },
+
+    async getTree() {
+      const tree = await systemCache.getOrInsertComputedAsync(
+        "_debug",
+        async () =>
+          expressionTree({
+            expression,
+            parent,
+          }),
+      );
+      return tree;
+    },
+
+    async keys() {
+      const tree = await this.getTree();
+      return tree.keys();
+    },
   });
-  if (!tree) {
-    fail("Dev.debug2: expression did not evaluate to a maplike resource tree");
-  }
-  Object.setPrototypeOf(treeHandle, tree);
 
-  // Clean the handle of any named properties or symbols that have been set
-  // directly on it.
-  try {
-    for (const key of Object.getOwnPropertyNames(treeHandle)) {
-      delete treeHandle[key];
-    }
-    for (const key of Object.getOwnPropertySymbols(treeHandle)) {
-      delete treeHandle[key];
-    }
-  } catch {
-    // Ignore errors.
-  }
+  // Trigger initial expression evaluation but don't wait for it. This lets some
+  // evaluation happen while the user launches/refreshes their browser.
+  handle.getTree();
 
-  process.send?.({ type: "EVALUATED" });
+  return handle;
 }
 
-function maybeFinishDrain() {
-  if (!draining) return;
+function maybeFinishClose() {
+  if (!closing) return;
   if (serverClosed && sockets.size === 0) {
-    process.send?.({ type: "DRAINED" });
+    process.send?.({ type: "CLOSED" });
     process.exit(0);
   }
 }
 
-// Drain when instructed by parent, or if parent dies.
+// Close when instructed by parent, or if parent dies.
 process.on("message", async (/** @type {any} */ message) => {
-  if (message?.type === "DRAIN") {
-    beginDrain();
-  } else if (message?.type === "REEVALUATE") {
-    await evaluateExpression();
+  if (message?.type === "CLOSE") {
+    beginClose();
   }
 });
-process.on("SIGTERM", beginDrain);
-process.on("SIGINT", beginDrain);
+process.on("SIGTERM", beginClose);
+process.on("SIGINT", beginClose);
 
 process.on("disconnect", () => {
   // Parent process died, exit immediately

package/src/dev/debug2/debugCommands.js

@@ -8,4 +8,5 @@ export { default as index } from "../../origami/indexPage.js";
 export { default as yaml } from "../../origami/yaml.js";
 export { default as explore } from "../explore.js";
 export { default as svg } from "../svg.js";
+export { default as syscache } from "../syscache.js";
 export { default as version } from "../version.js";

package/src/dev/debug2/debugParent.js

@@ -1,10 +1,9 @@
 import { fork } from "node:child_process";
 import { EventEmitter } from "node:events";
 import http from "node:http";
+import path from "node:path";
 import { findOpenPort } from "../../common/findOpenPort.js";
 
-const PUBLIC_HOST = "127.0.0.1";
-
 // Module that loads the server in the child process
 const childModuleUrl = new URL("./debugChild.js", import.meta.url);
 
@@ -58,20 +57,18 @@ export default async function debugParent(options) {
   }
 
   const port = options.port ?? (await findOpenPort());
-  publicOrigin = `http://${PUBLIC_HOST}:${port}`;
+  publicOrigin = `http://localhost:${port}`;
 
   publicServer = http.createServer(proxyRequest);
-  await new Promise((resolve) =>
-    publicServer.listen(port, PUBLIC_HOST, resolve),
-  );
+  await new Promise((resolve) => publicServer.listen(port, undefined, resolve));
   await startChild(options);
 
   emitter = Object.assign(new EventEmitter(), {
     close,
     origin: publicOrigin,
-    reevaluate,
     restart: () => startChild(options),
   });
+
   return emitter;
 }
 
@@ -112,16 +109,16 @@ async function drainAndStopChild(childProcess) {
     return;
   }
 
-  // Ask it to drain first.
+  // Ask it to close first.
   try {
-    childProcess.send({ type: "DRAIN" });
+    childProcess.send({ type: "CLOSE" });
   } catch {
     // ignore
   }
 
-  const drained = new Promise((resolve) => {
+  const closed = new Promise((resolve) => {
     const onMessage = (msg) => {
-      if (msg && typeof msg === "object" && msg.type === "DRAINED") {
+      if (msg && typeof msg === "object" && msg.type === "CLOSED") {
         cleanup(resolve);
       }
     };
@@ -140,7 +137,7 @@ async function drainAndStopChild(childProcess) {
   // Give it a short grace window to finish in-flight work.
   const GRACE_MS = 1500;
   await Promise.race([
-    drained,
+    closed,
     new Promise((r) => setTimeout(r, GRACE_MS).unref()),
   ]);
 
@@ -157,6 +154,20 @@ async function drainAndStopChild(childProcess) {
   }, GRACE_MS).unref();
 }
 
+function isJavaScriptFile(filePath) {
+  const extname = path.extname(filePath).toLowerCase();
+  const jsExtensions = [".cjs", ".js", ".mjs", ".ts"];
+  return jsExtensions.includes(extname);
+}
+
+async function onFileChange(filePath) {
+  if (isJavaScriptFile(filePath)) {
+    // Need to restart the child process
+    console.log("JavaScript file changed, restarting server…");
+    await emitter.restart();
+  }
+}
+
 /**
  * Proxy incoming requests to the active child server, or return a 503 if not
  * ready.
@@ -186,7 +197,7 @@ function proxyRequest(request, response) {
 
   const upstreamRequest = http.request(
     {
-      host: PUBLIC_HOST,
+      host: "localhost",
       port,
       method: request.method,
       path: request.url,
@@ -237,30 +248,6 @@ function proxyRequest(request, response) {
   request.pipe(upstreamRequest);
 }
 
-async function reevaluate() {
-  if (!activeChild) {
-    return;
-  }
-
-  const child = activeChild;
-
-  // Wait for the next EVALUATED message from the child
-  const evaluated = /** @type {Promise<void>} */ (
-    new Promise((resolve) => {
-      const onMessage = (/** @type {any} */ msg) => {
-        if (msg && typeof msg === "object" && msg.type === "EVALUATED") {
-          child.process.off("message", onMessage);
-          resolve();
-        }
-      };
-      child.process.on("message", onMessage);
-    })
-  );
-
-  child.process.send({ type: "REEVALUATE" });
-  await evaluated;
-}
-
 /**
  * Start a new child process.
  *
@@ -332,11 +319,12 @@ function startChild(options) {
             // console.log("Child process superseded by newer one, killing it...");
             childProcess.kill("SIGTERM");
           }
-        } else if (message.type === "EVALUATED") {
-          // Let caller know child has reevaluated the expression (after a file change)
-          if (emitter) {
-            emitter.emit("evaluated");
-          }
+        } else if (
+          message.type === "VALUE_CHANGE" &&
+          typeof message.path === "string"
+        ) {
+          // REVIEW: We don't await this -- is that a problem?
+          onFileChange(message.path);
         } else if (message.type === "FATAL") {
           // Child couldn't start (import error, etc.)
           // Keep previous active child if any; otherwise we'll serve 500/503.

package/src/dev/debug2/debugTransform.js

@@ -23,27 +23,10 @@ import * as debugCommands from "./debugCommands.js";
  * Also transform a simple object result to YAML for viewing.
  *
  * @typedef {import("@weborigami/async-tree").Maplike} Maplike
- * @typedef {import("@weborigami/async-tree").Packed} Packed
  *
- * @param {Maplike|Packed} input
+ * @param {Maplike} input
  */
 export default function debugTransform(input) {
-  if (isUnpackable(input)) {
-    // If the value isn't a tree, but has a tree attached via an `unpack`
-    // method, destructively wrap the unpack method to add this transform.
-    const original = input.unpack.bind(input);
-    input.unpack = async () => {
-      const content = await original();
-      if (!Tree.isTraversable(content) || typeof content === "function") {
-        return content;
-      }
-      /** @type {any} */
-      let tree = Tree.from(content);
-      return debugTransform(tree);
-    };
-    return input;
-  }
-
   const source = Tree.from(input, { deep: true });
 
   return Object.assign(new AsyncMap(), {
@@ -85,8 +68,10 @@ export default function debugTransform(input) {
 
       // Ensure this transform is applied to any map result, or any object with
       // an unpack method that returns a map.
-      if (Tree.isMap(value) || value?.unpack) {
+      if (Tree.isMap(value)) {
         value = debugTransform(value);
+      } else if (value?.unpack) {
+        value = debugPackedValue(value);
       }
 
       return value;
@@ -99,15 +84,42 @@ export default function debugTransform(input) {
     // If this value is given to the server, the server will call this pack()
     // method. We respond with the index page.
     async pack() {
-      return this.get("index.html");
+      // @ts-ignore
+      return source.pack?.() ?? this.get("index.html");
     },
 
+    // @ts-ignore
+    parent: source.parent,
+
     source,
 
     trailingSlashKeys: true,
   });
 }
 
+/**
+ * If the value isn't a tree, but has a tree attached via an `unpack` method,
+ * destructively wrap the unpack method to add this transform.
+ *
+ * @typedef {import("@weborigami/async-tree").Packed} Packed
+ * @param {Packed} packed
+ */
+function debugPackedValue(packed) {
+  if (isUnpackable(packed)) {
+    const original = packed.unpack.bind(packed);
+    packed.unpack = async () => {
+      const content = await original();
+      if (!Tree.isTraversable(content) || typeof content === "function") {
+        return content;
+      }
+      /** @type {any} */
+      let tree = Tree.from(content);
+      return debugTransform(tree);
+    };
+  }
+  return packed;
+}
+
 async function invokeOrigamiCommand(tree, key) {
   // Key is an Origami command; invoke it.
   const commandName = trailingSlash.remove(key.slice(1).trim());