@weborigami/origami 0.6.16 → 0.7.0-beta.1

package/src/dev/debug2/expressionTree.js

@@ -4,7 +4,7 @@ import {
   setParent,
   Tree,
 } from "@weborigami/async-tree";
-import { evaluate, OrigamiFileMap, projectGlobals } from "@weborigami/language";
+import { evaluate, getGlobalsForTree } from "@weborigami/language";
 import debugTransform from "./debugTransform.js";
 
 // So we can distinguish different trees in the debugger
@@ -16,18 +16,22 @@ let version = 0;
  *
  * @param {Object} options
  * @param {string} options.expression
- * @param {string} options.parentPath
+ * @param {import("@weborigami/language").OrigamiFileMap} options.parent
  */
 export default async function expressionTree(options) {
-  const { expression, parentPath } = options;
+  const { expression, parent } = options;
 
-  const parent = new OrigamiFileMap(parentPath);
-  const globals = await projectGlobals(parent);
+  const globals = getGlobalsForTree(parent);
+
+  const source = {
+    text: expression,
+    cachePath: "_tree",
+  };
 
   let maplike;
   try {
     // Evaluate the expression
-    maplike = await evaluate(expression, { globals, mode: "shell", parent });
+    maplike = await evaluate(source, { globals, mode: "shell", parent });
     if (isUnpackable(maplike)) {
       maplike = await maplike.unpack();
     }

package/src/dev/debug2/oriEval.js

@@ -1,5 +1,5 @@
 import { trailingSlash, Tree } from "@weborigami/async-tree";
-import { evaluate, projectGlobals } from "@weborigami/language";
+import { evaluate, getGlobalsForTree } from "@weborigami/language";
 import debugTransform from "./debugTransform.js";
 
 const mapParentToResult = new WeakMap();
@@ -16,7 +16,7 @@ const mapParentToResult = new WeakMap();
  * counter to force reevaluation of the same expression.
  */
 export default async function oriEval(parent) {
-  const globals = await projectGlobals(parent);
+  const globals = getGlobalsForTree(parent);
   return async (key) => {
     const normalizedKey = trailingSlash.remove(key);
     let result = mapParentToResult.get(parent);

package/src/dev/dev.js

@@ -18,5 +18,6 @@ export { default as log } from "./log.js";
 export { default as serve } from "./serve.js";
 export { default as stdin } from "./stdin.js";
 export { default as svg } from "./svg.js";
+export { default as syscache } from "./syscache.js";
 export { default as version } from "./version.js";
 export { default as watch } from "./watch.js";

package/src/dev/explore.js

@@ -44,6 +44,7 @@ async function getScopeData(scope) {
 async function loadTemplate() {
   const folderPath = path.resolve(fileURLToPath(import.meta.url), "..");
   const folder = new OrigamiFileMap(folderPath);
+  await folder.initializeGlobals();
   const templateFile = await folder.get("explore.ori");
   const template = await Handlers.ori_handler.unpack(templateFile, {
     parent: folder,

package/src/dev/help.yaml

@@ -13,12 +13,12 @@ Dev:
     clear:
       args: (tree)
       description: Remove all values from the tree (alias of Tree.clear)
-    crawl:
-      args: (tree, base)
-      description: A tree of a site's discoverable resources
     copy:
       args: (source, target)
       description: Copy the source tree to the target
+    crawl:
+      args: (tree, base)
+      description: A tree of a site's discoverable resources
     debug:
       args: (tree)
       description: Add debug features to the tree
@@ -63,11 +63,20 @@ Origami:
     document:
       args: (text, [data])
       description: Create a document object with the text and data
+    domObject:
+      args: (dom)
+      description: Convert a DOM tree to a plain JavaScript object
     extension:
       description: Helpers for working with file extensions
     fetch:
       args: (url, options)
       description: Fetch a resource from a URL with support for extensions
+    hash:
+      args: (data)
+      description: A hex string hash of the data
+    htmlDom:
+      args: (html)
+      description: Parse HTML into a DOM tree
     htmlEscape:
       args: (text)
       description: Escape HTML entities in the text
@@ -79,9 +88,6 @@ Origami:
     inline:
       args: (text)
       description: Inline Origami expressions found in the text
-    htmlParse:
-      args: (html)
-      description: Parse HTML into a plain JavaScript object
     json:
       args: (obj)
       description: Render the object in JSON format
@@ -99,9 +105,9 @@ Origami:
       description: The outline structure of the markdown document
     naturalOrder:
       description: A comparison function for natural sort order
-    once:
-      args: (fn)
-      description: Run the function only once, return the same result
+    # once:
+    #   args: (fn)
+    #   description: Run the function only once, return the same result
     ori:
       args: (text)
       description: Evaluate the text as an Origami expression
@@ -110,6 +116,12 @@ Origami:
       description: POST the given data to the URL
     projectRoot:
       description: The root folder for the current Origami project
+    randomFrom:
+      args: (data)
+      description: Returns a random value based on the data
+    randomsFrom:
+      args: (data)
+      description: Returns a function to produce random values based on the data
     redirect:
       args: (url, options)
       description: Redirect to the given URL
@@ -139,12 +151,15 @@ Origami:
     toFunction:
       args: (obj)
       description: Coerce a tree or packed function definition to a function
+    tsv:
+      args: (tree)
+      description: Render the tree as a TSV file
     unpack:
       args: (buffer)
       description: Unpack the buffer into a usable form
-    xmlParse:
+    xmlDom:
       args: (xml)
-      description: Parse XML into a plain JavaScript object
+      description: Parse XML into a DOM tree
     yaml:
       args: (obj)
       description: Render the object in YAML format
@@ -193,6 +208,9 @@ Tree:
     clear:
       args: (map)
       description: Remove all values from the map
+    combine:
+      args: (tree1, tree2, combineFn)
+      description: Pairwise application of combineFn to the trees' values
     concat:
       args: (...trees)
       description: Merge trees, renumbering numeric keys

package/src/dev/syscache.js

@@ -0,0 +1,56 @@
+import { activeProjectRoot, systemCache, volatile } from "@weborigami/language";
+import path from "node:path";
+import * as YAMLModule from "yaml";
+
+// The "yaml" package doesn't seem to provide a default export that the browser can
+// recognize, so we have to handle two ways to accommodate Node and the browser.
+// @ts-ignore
+const YAML = YAMLModule.default ?? YAMLModule.YAML;
+
+export default function syscache() {
+  const projectRoot = activeProjectRoot.get();
+
+  /** @type {any} */
+  const entries = [...systemCache.entries()].map(([path, entry]) => {
+    const result = {};
+    if (entry.downstreams) {
+      result.downstreams = preferRelativePaths(projectRoot, entry.downstreams);
+    }
+    if (entry.upstreams) {
+      result.upstreams = preferRelativePaths(projectRoot, entry.upstreams);
+    }
+    return [preferRelativePath(projectRoot, path), result];
+  });
+
+  // Sort the entries by key
+  entries.sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
+
+  const result = volatile(new Map(entries));
+
+  // When served, render as YAML and preserve trailing slashes
+  Object.defineProperty(result, "pack", {
+    configurable: true,
+    enumerable: false,
+    get() {
+      return () => volatile(YAML.stringify(result));
+    },
+  });
+
+  return result;
+}
+
+function preferRelativePath(projectRoot, inputPath) {
+  if (!path.isAbsolute(inputPath)) {
+    return inputPath;
+  }
+  const prefix = `${projectRoot.path}${path.sep}`;
+  if (!inputPath.startsWith(prefix)) {
+    return inputPath;
+  }
+  const relativePath = inputPath.slice(prefix.length);
+  return relativePath;
+}
+
+function preferRelativePaths(projectRoot, paths) {
+  return Array.from(paths).map((path) => preferRelativePath(projectRoot, path));
+}

package/src/handlers/xml_handler.js

@@ -1,5 +1,5 @@
 import { symbols, toString } from "@weborigami/async-tree";
-import xmlParse from "../origami/xmlParse.js";
+import xmlParse from "../origami/xmlDom.js";
 
 export default {
   mediaType: "application/xml",

package/src/origami/{domNodeToObject.js → domObject.js}

@@ -1,17 +1,29 @@
+import { isUnpackable } from "@weborigami/async-tree";
+
 const ELEMENT_NODE = 1;
 const TEXT_NODE = 3;
 const CDATA_SECTION_NODE = 4;
 const DOCUMENT_NODE = 9;
 const DOCUMENT_FRAGMENT_NODE = 11;
 
-export default function domNodeToObject(node) {
+/**
+ * Given a DOM node, return a plain object representation of it.
+ */
+export default async function domObject(input) {
+  if (isUnpackable(input)) {
+    input = await input.unpack();
+  }
+  return nodeObject(input);
+}
+
+function nodeObject(node) {
   switch (node.nodeType) {
     case DOCUMENT_NODE:
       return {
         name: "#document",
         children: [...node.childNodes]
           .filter((child) => !isWhitespaceOnly(child))
-          .map(domNodeToObject),
+          .map(nodeObject),
       };
 
     case DOCUMENT_FRAGMENT_NODE:
@@ -19,7 +31,7 @@ export default function domNodeToObject(node) {
         name: "#document-fragment",
         children: [...node.childNodes]
           .filter((child) => !isWhitespaceOnly(child))
-          .map(domNodeToObject),
+          .map(nodeObject),
       };
 
     case ELEMENT_NODE: {
@@ -55,7 +67,7 @@ export default function domNodeToObject(node) {
           result.text = text;
         }
       } else if (relevantChildren.length > 0) {
-        result.children = relevantChildren.map(domNodeToObject);
+        result.children = relevantChildren.map(nodeObject);
       }
 
       return result;

package/src/origami/fetch.js

@@ -1,22 +1 @@
-import { args } from "@weborigami/async-tree";
-import { handleExtension } from "@weborigami/language";
-
-/**
- * Extend the JavaScript `fetch` function to implicity return an ArrayBuffer
- * with an unpack() method if the resource has a known file extension.
- */
-export default async function fetchBuiltin(resource, options, state) {
-  resource = args.string(resource, "Origami.fetch");
-  const response = await fetch(resource, options);
-  if (!response.ok) {
-    return undefined;
-  }
-
-  const value = await response.arrayBuffer();
-
-  const url = new URL(resource);
-  const key = url.pathname;
-
-  return handleExtension(value, key, state?.parent);
-}
-fetchBuiltin.needsState = true;
+export { fetchAndHandleExtension as default } from "@weborigami/language";

package/src/origami/hash.js

@@ -0,0 +1,17 @@
+import hashBytes from "../common/hashBytes.js";
+
+/**
+ * Given string or Uint8Array data, return a hex-encoded hash of that data.
+ *
+ * @typedef {import("@weborigami/async-tree").Stringlike} Stringlike
+ *
+ * @param {Uint8Array|Stringlike} data
+ */
+export default function hash(data) {
+  const bytes = hashBytes(data);
+  const text = Array.from(bytes)
+    .slice(0, 20) // Limit to first 20 bytes (160 bits) for a shorter hash string
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  return text;
+}

package/src/origami/htmlDom.js

@@ -0,0 +1,21 @@
+import { args } from "@weborigami/async-tree";
+import loadJsDom from "../common/loadJsDom.js";
+
+/**
+ * Return the DOM structure for the given HTML.
+ *
+ * @param {import("@weborigami/async-tree").Stringlike} html
+ */
+export default async function htmlDom(html) {
+  html = args.stringlike(html, "Origami.htmlDom");
+  const { JSDOM } = await loadJsDom();
+  let dom = JSDOM.fragment(html);
+  if (
+    (dom.nodeType === 9 || dom.nodeType === 11) &&
+    dom.children.length === 1
+  ) {
+    // Document or DocumentFragment with a single child: return the child
+    dom = dom.children[0];
+  }
+  return dom;
+}

package/src/origami/htmlParse.js

@@ -1,22 +1,15 @@
 import { args } from "@weborigami/async-tree";
-import loadJsDom from "../common/loadJsDom.js";
-import domNodeToObject from "./domNodeToObject.js";
+import htmlDom from "./htmlDom.js";
 
 /**
- * Return the DOM structure for the given HTML as a plain object.
+ * Return the DOM structure for the given HTML.
  *
  * @param {import("@weborigami/async-tree").Stringlike} html
  */
 export default async function htmlParse(html) {
+  console.warn("Origami.htmlParse is deprecated. Use Origami.htmlDom instead.");
+
   html = args.stringlike(html, "Origami.htmlParse");
-  const { JSDOM } = await loadJsDom();
-  const dom = JSDOM.fragment(html);
-  let object = domNodeToObject(dom);
-  if (
-    (object.name === "#document" || object.name === "#document-fragment") &&
-    object.children.length === 1
-  ) {
-    object = object.children[0];
-  }
-  return object;
+  const dom = await htmlDom(html);
+  return dom;
 }

package/src/origami/mdHtml.js

@@ -55,4 +55,5 @@ export default async function mdHtml(input) {
 
 mdHtml.key = (sourceValue, sourceKey) =>
   extension.replace(sourceKey, ".md", ".html");
+mdHtml.key.needsSourceValue = false;
 mdHtml.inverseKey = (resultKey) => extension.replace(resultKey, ".html", ".md");

package/src/origami/once.js

@@ -1,4 +1,4 @@
-import { args } from "@weborigami/async-tree";
+import { args, interop } from "@weborigami/async-tree";
 
 const fnPromiseMap = new Map();
 const codePromiseMap = new Map();
@@ -9,6 +9,9 @@ const codePromiseMap = new Map();
  * @param {Function} fn
  */
 export default async function once(fn) {
+  interop.warn(
+    `Now that Origami caches most results, Origami.once is no longer needed and will be removed in a future release. If you believe you have a need for it, please mention your use case in the Origami chat.`,
+  );
   fn = args.fn(fn, "Origami.once");
   const code = /** @type {any} */ (fn).code;
   if (code) {

package/src/origami/ori.js

@@ -1,5 +1,10 @@
-import { Tree, args, getRealmObjectPrototype } from "@weborigami/async-tree";
-import { compile, projectGlobals } from "@weborigami/language";
+import {
+  args,
+  assignPropertyDescriptors,
+  getRealmObjectPrototype,
+  Tree,
+} from "@weborigami/async-tree";
+import { compile, getGlobalsForTree } from "@weborigami/language";
 import { toYaml } from "../common/serialize.js";
 import * as dev from "../dev/dev.js";
 
@@ -17,18 +22,12 @@ export default async function ori(expression, options = {}) {
 
   expression = args.stringlike(expression, "Origami.ori");
 
-  // Add Dev builtins as top-level globals
-  const globals = {
-    ...(await projectGlobals(parent)),
-    ...dev,
-  };
+  // Add Dev builtins as top-level globals; avoid invoking getters
+  const globals = assignPropertyDescriptors({}, getGlobalsForTree(parent), dev);
 
-  // Compile the expression. Avoid caching scope references so that, e.g.,
-  // passing a function to the `watch` builtin will always look the current
-  // value of things in scope.
+  // Compile the expression
   const fn = compile.expression(expression, {
     globals,
-    enableCaching: false,
     mode: "shell",
     parent,
   });

package/src/origami/origami.js

@@ -3,7 +3,10 @@ export { default as help } from "../dev/help.js"; // Alias
 export { default as basename } from "./basename.js";
 export { default as csv } from "./csv.js";
 export { default as document } from "./document.js";
+export { default as domObject } from "./domObject.js";
 export { default as fetch } from "./fetch.js";
+export { default as hash } from "./hash.js";
+export { default as htmlDom } from "./htmlDom.js";
 export { default as htmlEscape } from "./htmlEscape.js";
 export { default as htmlParse } from "./htmlParse.js";
 export { default as format } from "./image/format.js";
@@ -21,8 +24,9 @@ export { default as once } from "./once.js";
 export { default as ori } from "./ori.js";
 export { default as pack } from "./pack.js";
 export { default as post } from "./post.js";
-export { default as project } from "./project.js";
 export { default as projectRoot } from "./projectRoot.js";
+export { default as randomFrom } from "./randomFrom.js";
+export { default as randomsFrom } from "./randomsFrom.js";
 export { default as redirect } from "./redirect.js";
 export { default as repeat } from "./repeat.js";
 export { default as rss } from "./rss.js";
@@ -34,6 +38,8 @@ export { default as static } from "./static.js";
 export { default as string } from "./string.js";
 export { default as tsv } from "./tsv.js";
 export { default as unpack } from "./unpack.js";
+export { default as volatile } from "./volatile.js";
+export { default as xmlDom } from "./xmlDom.js";
 export { default as xmlParse } from "./xmlParse.js";
 export { default as yaml } from "./yaml.js";
 export { default as yamlParse } from "./yamlParse.js";

package/src/origami/randomFrom.js

@@ -0,0 +1,15 @@
+import hashBytes from "../common/hashBytes.js";
+
+/**
+ * Given a block of seed data, derive a pseudo-random 32-bit integer.
+ *
+ * @typedef {import("@weborigami/async-tree").Stringlike} Stringlike
+ *
+ * @param {Uint8Array|Stringlike} data
+ * @return {number}
+ */
+export default function randomFrom(data) {
+  // Extract the first 32-bit integer from the hash to use as the random number
+  const hash = hashBytes(data);
+  return hash.readUInt32LE(0);
+}

package/src/origami/randomsFrom.js

@@ -0,0 +1,65 @@
+import hashBytes from "../common/hashBytes.js";
+
+/**
+ * Given a block of seed data, return a function that produces a sequence of
+ * pseudo-random 32-bit integers.
+ *
+ * @typedef {import("@weborigami/async-tree").Stringlike} Stringlike
+ *
+ * @param {Uint8Array|Stringlike} data
+ * @return {function(): number}
+ */
+export default function randomsFrom(data) {
+  const hash = hashBytes(data);
+
+  // Extract four 32-bit integers from the hash to use as the initial state of
+  // the pseudo-random number generator
+  const a = hash.readUInt32LE(0);
+  const b = hash.readUInt32LE(4);
+  const c = hash.readUInt32LE(8);
+  const d = hash.readUInt32LE(12);
+
+  const prng = xoshiro128ss(a, b, c, d);
+  return prng;
+}
+
+// Rotate left (circular left shift) for 32-bit integers
+function rotl(x, k) {
+  return ((x << k) | (x >>> (32 - k))) >>> 0;
+}
+
+/**
+ * Pseudo-random number generator based on the xoshiro128** algorithm. See
+ * the 256-bit variant: https://en.wikipedia.org/wiki/Xorshift#xoshiro256**
+ *
+ * Unlike a typical implementation, this directly returns a 32-bit integer
+ * instead of a float.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {function(): number}
+ */
+function xoshiro128ss(a, b, c, d) {
+  let s0 = a >>> 0;
+  let s1 = b >>> 0;
+  let s2 = c >>> 0;
+  let s3 = d >>> 0;
+
+  return function () {
+    const result = (rotl(Math.imul(s1, 5), 7) * 9) >>> 0;
+
+    const t = (s1 << 9) >>> 0;
+
+    s2 ^= s0;
+    s3 ^= s1;
+    s1 ^= s2;
+    s0 ^= s3;
+
+    s2 ^= t;
+    s3 = rotl(s3, 11);
+
+    return result;
+  };
+}

package/src/origami/volatile.js

@@ -0,0 +1 @@
+export { volatile as default } from "@weborigami/language";

package/src/origami/xmlDom.js

@@ -0,0 +1,32 @@
+import { args } from "@weborigami/async-tree";
+import loadJsDom from "../common/loadJsDom.js";
+
+let parser;
+
+/**
+ * Return the DOM for the given XML.
+ *
+ * @param {import("@weborigami/async-tree").Stringlike} xml
+ */
+export default async function xmlDom(xml) {
+  xml = args.stringlike(xml, "Origami.xmlDom");
+  const parser = await getParser();
+  let dom = parser.parseFromString(xml, "application/xml");
+  if (
+    (dom.nodeType === 9 || dom.nodeType === 11) &&
+    dom.children.length === 1
+  ) {
+    // Document or DocumentFragment with a single child: return the child
+    dom = dom.children[0];
+  }
+  return dom;
+}
+
+async function getParser() {
+  if (!parser) {
+    const { JSDOM } = await loadJsDom();
+    const dom = new JSDOM();
+    parser = new dom.window.DOMParser();
+  }
+  return parser;
+}

package/src/origami/xmlParse.js

@@ -1,33 +1,15 @@
 import { args } from "@weborigami/async-tree";
-import loadJsDom from "../common/loadJsDom.js";
-import domNodeToObject from "./domNodeToObject.js";
-
-let parser;
+import xmlDom from "./xmlDom.js";
 
 /**
- * Return the DOM for the given XML as a plain object.
+ * Return the DOM structure for the given XML.
  *
  * @param {import("@weborigami/async-tree").Stringlike} xml
  */
 export default async function xmlParse(xml) {
-  xml = args.stringlike(xml, "Origami.xmlParse");
-  const parser = await getParser();
-  const dom = parser.parseFromString(xml, "application/xml");
-  let object = domNodeToObject(dom);
-  if (
-    (object.name === "#document" || object.name === "#document-fragment") &&
-    object.children.length === 1
-  ) {
-    object = object.children[0];
-  }
-  return object;
-}
+  console.warn("Origami.xmlParse is deprecated. Use Origami.xmlDom instead.");
 
-async function getParser() {
-  if (!parser) {
-    const { JSDOM } = await loadJsDom();
-    const dom = new JSDOM();
-    parser = new dom.window.DOMParser();
-  }
-  return parser;
+  xml = args.stringlike(xml, "Origami.xmlParse");
+  const dom = await xmlDom(xml);
+  return dom;
 }