@weborigami/origami 0.5.8 → 0.6.1

package/src/dev/help.yaml

@@ -167,8 +167,8 @@ Tree:
   description: Work with trees of files and data
   commands:
     addNextPrevious:
-      args: (tree)
-      description: Add next/previous fields to the tree's values
+      args: (map)
+      description: Add next/previous fields to the map's values
     assign:
       args: (target, source)
       description: Apply key/values from source to target
@@ -178,9 +178,12 @@ Tree:
     calendar:
       args: (options)
       description: Return a tree structure for years/months/days
+    child:
+      args: (tree, key)
+      description: Returns the indicated child node, creating it if necessary
     clear:
-      args: (tree)
-      description: Remove all values from the tree
+      args: (map)
+      description: Remove all values from the map
     constant:
       args: (value)
       description: Return a deep tree with a single constant value
@@ -203,68 +206,68 @@ Tree:
       args: (tree)
       description: The in-order leaf values of the tree
     delete:
-      args: (tree, key)
-      description: Delete the value for the key from tree
+      args: (map, key)
+      description: Delete the value for the key from map
     entries:
-      args: (tree)
-      description: The tree's [key, value] pairs
+      args: (map)
+      description: The map's [key, value] pairs
     filter:
-      args: (source, options)
-      description: Filter the source tree
+      args: (tree, options)
+      description: Filter a tree by a condition
     first:
-      args: (tree)
-      description: The first value in the tree
+      args: (map)
+      description: The first value in the map
     forEach:
-      args: (tree, fn)
+      args: (map, fn)
       description: Apply fn to each (value, key)
     from:
       args: (object, options)
-      description: Create a tree from an object
+      description: Create a map from an object
     globKeys:
       args: (patterns)
       description: A tree whose keys can include glob wildcard patterns
     groupBy:
-      args: (tree, fn)
-      description: A new tree with values grouped by the function
+      args: (map, fn)
+      description: A new map with values grouped by the function
     has:
-      args: (tree, key)
-      description: True if key exists in tree
+      args: (map, key)
+      description: True if key exists in map
     indent:
       args: "`…`"
       description: Tagged template literal for normalizing indentation
     inners:
       args: (tree)
       description: The tree's interior nodes
-    isAsyncMutableTree:
+    invokeFunctions:
+      args: (map)
+      description: Getting a map value invokes it if it's a function
+    isMap:
       args: (object)
-      description: True if object is an async mutable tree
-    isAsyncTree:
+      description: True if object is a map
+    isMaplike:
       args: (object)
-      description: True if object is an async tree
+      description: True if object can be coerced to a tree
+    isReadOnlyMap:
+      args: (object)
+      description: True if object is a read-only map
     isTraversable:
       args: (object)
       description: True if object is traversable
-    isTreelike:
-      args: (object)
-      description: True if object can be coerced to a tree
     json:
       args: (tree)
       description: Render the tree in JSON format
     keys:
-      args: (tree)
-      description: The keys of the tree
-    length:
-      args: (tree)
-      description: The tree's size (number of keys)
+      args: (map)
+      description: The keys of the map
     map:
-      args: (tree, options)
-      description: Create a new tree by mapping keys and/or values
+      args: (source, options)
+      description: Create a new map by transforming keys and/or values
     mapExtension:
-      args: (tree, ext, options)
-      description: Map extensions and values
+      args: (source, ext, options)
+      description: Create a new map by transforming extensions
     mapReduce:
       args: (tree, mapFn, reduceFn)
-      description: Map values and reduce them
+      description: Map the keys and/or values in a tree and reduce them
     mask:
       args: (source, mask)
       description: Return the source tree with only the keys in the mask
@@ -272,11 +275,11 @@ Tree:
       args: (pattern, fn, [keys])
       description: Matches simple patterns or regular expressions
     merge:
-      args: (...trees)
-      description: Return a new tree merging the given trees
+      args: (...maps)
+      description: Return a new tree merging the given maps
     paginate:
-      args: (tree, [n])
-      description: Group the tree's values into fixed-size sets
+      args: (map, [n])
+      description: Group the map's values into fixed-size sets
     parent:
       args: (tree)
       description: The parent of the given tree node
@@ -286,27 +289,39 @@ Tree:
     plain:
       args: (tree)
       description: Render the tree as a plain JavaScript object
+    reduce:
+      args: (tree, reduceFn)
+      description: Reduce the tree to a single value
     regExpKeys:
       args: (tree)
       description: A tree whose keys are regular expression strings
     reverse:
-      args: (tree)
-      description: Reverse the order of the tree's keys
+      args: (map)
+      description: Reverse the order of the map's keys
     root:
       args: (tree)
       description: The root node of the given tree
-    setDeep:
-      args: (target, source)
-      description: Applies the source tree to the target
-    shuffle:
+    scope:
       args: (tree)
-      description: Shuffle the keys of the tree
+      description: A merged view of the tree and its ancestors
+    set:
+      args: (map, key, value)
+      description: Set the value for the key in the map
+    shuffle:
+      args: (map)
+      description: Shuffle the keys of the map
+    size:
+      args: (map)
+      description: The map's size (number of keys)
     sort:
-      args: (tree, options)
-      description: A new tree with its keys sorted
+      args: (map, options)
+      description: A new map with its keys sorted
+    sync:
+      args: (tree)
+      description: Awaits all asynchronous values in the tree
     take:
-      args: (tree, n)
-      description: The first n values in the tree
+      args: (map, n)
+      description: The first n values in the map
     text:
       args: "`…`"
       description: Tagged template literal for rendering trees
@@ -320,8 +335,8 @@ Tree:
       args: (tree, path)
       description: Traverse a slash-separated path
     values:
-      args: (tree)
-      description: The tree's values
+      args: (map)
+      description: The map's values
     withKeys:
-      args: (tree, keys)
-      description: Use the given keys for the tree
+      args: (map, keys)
+      description: Use the given keys for the map

package/src/dev/serve.js

@@ -11,14 +11,13 @@ const defaultPort = 5000;
 /**
  * Start a local web server for the indicated tree.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {number} [port]
  */
-export default async function serve(treelike, port) {
-  let tree = await getTreeArgument(treelike, "serve");
+export default async function serve(maplike, port) {
+  let tree = await getTreeArgument(maplike, "serve");
 
   if (!isTransformApplied(ExplorableSiteTransform, tree)) {
     tree = transformObject(ExplorableSiteTransform, tree);

package/src/dev/svg.js

@@ -8,19 +8,18 @@ let graphvizLoaded = false;
 /**
  * Render a tree visually in SVG format.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {PlainObject} [options]
  */
-export default async function svg(treelike, options = {}) {
+export default async function svg(maplike, options = {}) {
   if (!graphvizLoaded) {
     await graphviz.loadWASM();
     graphvizLoaded = true;
   }
-  const tree = await getTreeArgument(treelike, "svg", { deep: true });
+  const tree = await getTreeArgument(maplike, "svg", { deep: true });
   const dotText = await dot(tree, options);
   if (dotText === undefined) {
     return undefined;

package/src/dev/treeDot.js

@@ -12,14 +12,14 @@ import { getDescriptor } from "../common/utilities.js";
 /**
  * Render a tree in DOT format.
  *
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {PlainObject} [options]
  */
-export default async function dot(treelike, options = {}) {
-  const tree = await getTreeArgument(treelike, "treeDot", { deep: true });
+export default async function dot(maplike, options = {}) {
+  const tree = await getTreeArgument(maplike, "treeDot", { deep: true });
   const rootLabel = getDescriptor(tree) ?? "";
   const treeArcs = await statements(tree, "", rootLabel, options);
   return `digraph g {
@@ -48,7 +48,7 @@ async function statements(tree, nodePath, nodeLabel, options) {
 
   // Draw edges and collect labels for the nodes they lead to.
   let nodes = new Map();
-  for (const key of await tree.keys()) {
+  for (const key of await Tree.keys(tree)) {
     const destPath = nodePath ? `${trailingSlash.add(nodePath)}${key}` : key;
     const labelUrl = createLinks ? `; labelURL="${destPath}"` : "";
     const arc = `  "${nodePath}" -> "${destPath}" [label="${key}"${labelUrl}];`;
@@ -67,7 +67,7 @@ async function statements(tree, nodePath, nodeLabel, options) {
     }
 
     const expandable =
-      value instanceof Array || isPlainObject(value) || Tree.isAsyncTree(value);
+      value instanceof Array || isPlainObject(value) || Tree.isMap(value);
     if (expandable) {
       const subtree = Tree.from(value);
       const subStatements = await statements(subtree, destPath, null, options);

package/src/dev/watch.js

@@ -1,19 +1,19 @@
-import { constant, getTreeArgument, Tree } from "@weborigami/async-tree";
+import { ConstantMap, getTreeArgument, Tree } from "@weborigami/async-tree";
 import { formatError, moduleCache } from "@weborigami/language";
 
 /**
  * Let a tree (e.g., of files) respond to changes.
  *
+ * @typedef {import("@weborigami/async-tree").AsyncMap} AsyncMap
  * @typedef {import("@weborigami/async-tree").Invocable} Invocable
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {Invocable} [fn]
- * @returns {Promise<AsyncTree>}
+ * @returns {Promise<Map|AsyncMap>}
  */
-export default async function watch(treelike, fn) {
-  const container = await getTreeArgument(treelike, "watch");
+export default async function watch(maplike, fn) {
+  const container = await getTreeArgument(maplike, "watch");
 
   // Watch the indicated tree.
   await /** @type {any} */ (container).watch?.();
@@ -58,7 +58,7 @@ async function evaluateTree(parent, fn) {
     message = `Warning: watch expression did not return a tree`;
   }
   console.warn(message);
-  tree = constant(message);
+  tree = new ConstantMap(message);
   return tree;
 }
 

package/src/origami/csv.js

@@ -3,7 +3,7 @@ import { isUnpackable, toPlainValue } from "@weborigami/async-tree";
 /**
  * Render the object as text in CSV format.
  *
- * The object should a treelike object such as an array. The output will include
+ * The object should a maplike object such as an array. The output will include
  * a header row with field names taken from the first item in the tree/array.
  *
  * @param {any} object

package/src/origami/document.js

@@ -1,7 +1,6 @@
 import documentObject from "../common/documentObject.js";
 
 /**
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Stringlike} Stringlike
  *
  * @param {Stringlike} text

package/src/origami/indexPage.js

@@ -1,21 +1,20 @@
-import { getTreeArgument } from "@weborigami/async-tree";
+import { getTreeArgument, Tree } from "@weborigami/async-tree";
 import { getDescriptor } from "../common/utilities.js";
 
 /**
  * Return a default index.html page for the current tree.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {string} [basePath]
  */
-export default async function indexPage(treelike, basePath) {
-  const tree = await getTreeArgument(treelike, "svg");
-  const keys = Array.from(await tree.keys());
+export default async function indexPage(maplike, basePath) {
+  const tree = await getTreeArgument(maplike, "svg");
+  const treeKeys = await Tree.keys(tree);
 
   // Skip system-ish files that start with a period. Also skip `index.html`.
-  const filtered = keys.filter(
+  const filtered = treeKeys.filter(
     (key) => !(key.startsWith?.(".") || key === "index.html")
   );
 

package/src/origami/inline.js

@@ -6,7 +6,6 @@ import documentObject from "../common/documentObject.js";
  * Inline any Origami expressions found inside ${...} placeholders in the input
  * text.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @param {any} input
  */

package/src/origami/json.js

@@ -3,7 +3,6 @@ import { isUnpackable, toPlainValue } from "@weborigami/async-tree";
 /**
  * Render the given object in JSON format.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @param {any} [obj]
  */

package/src/origami/jsonKeys.js

@@ -1,36 +1,49 @@
-import { Tree, getTreeArgument, jsonKeys } from "@weborigami/async-tree";
+import {
+  AsyncMap,
+  Tree,
+  getTreeArgument,
+  jsonKeys,
+} from "@weborigami/async-tree";
 
 /**
  * Expose .keys.json for a tree.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  *
- * @param {Treelike} treelike
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function jsonKeysBuiltin(treelike) {
-  const tree = await getTreeArgument(treelike, "jsonKeys");
-  return jsonKeysTree(tree);
+export default async function jsonKeysBuiltin(maplike) {
+  const source = await getTreeArgument(maplike, "jsonKeys");
+  return jsonKeysMap(source);
 }
 
-function jsonKeysTree(tree) {
-  return Object.assign(Object.create(tree), {
+function jsonKeysMap(source) {
+  const result = Object.assign(new AsyncMap(), {
+    description: "jsonKeys",
+
     async get(key) {
-      let value = await tree.get(key);
+      let value = await source.get(key);
       if (value === undefined && key === ".keys.json") {
         value = await jsonKeys.stringify(this);
-      } else if (Tree.isTreelike(value)) {
-        const subtree = Tree.from(value, { deep: true, parent: this });
-        value = jsonKeysTree(subtree);
+      } else if (Tree.isMaplike(value)) {
+        const subtree = Tree.from(value, { deep: true, parent: result });
+        value = jsonKeysMap(subtree);
       }
       return value;
     },
 
-    async keys() {
-      const keys = new Set(await tree.keys());
-      keys.add(".keys.json");
-      return keys;
+    async *keys() {
+      const treeKeys = new Set(await Tree.keys(source));
+      treeKeys.add(".keys.json");
+      yield* treeKeys;
+    },
+
+    source: source,
+
+    get trailingSlashKeys() {
+      return source.trailingSlashKeys;
     },
   });
+  return result;
 }

package/src/origami/once.js

@@ -4,7 +4,6 @@ const codePromiseMap = new Map();
 /**
  * Evaluate the given function only once and cache the result.
  *
- * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @param {Function} fn
  */

package/src/origami/ori.js

@@ -15,7 +15,6 @@ const TypedArray = Object.getPrototypeOf(Uint8Array);
  * Parse an Origami expression, evaluate it in the context of a tree (provided
  * by `this`), and return the result as text.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @param {string} expression
  */
@@ -49,6 +48,17 @@ export default async function ori(expression, options = {}) {
   // Execute
   let result = await fn();
 
+  // if (result === undefined) {
+  //   // Was the code a path traversal?
+  //   const wasTraversal =
+  //     fn.code[0] === ops.unpack ||
+  //     (fn.code[0] instanceof Array && fn.code[0][0] === ops.scope);
+  //   if (wasTraversal) {
+  //     // Yes, probably an error
+  //     console.warn(`ori: warning: undefined ${highlightError(expression)}`);
+  //   }
+  // }
+
   // If result was a function, execute it.
   if (typeof result === "function") {
     result = await result();
@@ -90,8 +100,8 @@ async function format(result) {
     text = result;
   }
 
-  // If the result is treelike, attach it to the text output.
-  if (Tree.isTreelike(result)) {
+  // If the result is maplike, attach it to the text output.
+  if (Tree.isMaplike(result)) {
     if (typeof text === "string") {
       // @ts-ignore
       text = new String(text);

package/src/origami/pack.js

@@ -1,5 +1,4 @@
 /**
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @param {any} obj
  */

package/src/origami/post.js

@@ -18,7 +18,7 @@ export default async function post(url, data) {
   if (isUnpackable(data)) {
     data = await data.unpack();
   }
-  if (Tree.isTreelike(data)) {
+  if (Tree.isMaplike(data)) {
     const value = await toPlainValue(data);
     body = JSON.stringify(value);
     headers = {

package/src/origami/rss.js

@@ -2,10 +2,9 @@ import { getTreeArgument, Tree } from "@weborigami/async-tree";
 import jsonFeedToRss from "@weborigami/json-feed-to-rss";
 
 /**
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  *
- * @param {Treelike} jsonFeed
+ * @param {Maplike} jsonFeed
  * @param {any} options
  */
 export default async function rss(jsonFeed, options = {}) {

package/src/origami/sitemap.js

@@ -11,32 +11,22 @@ const templateText = `(urls) => \`<?xml version="1.0" encoding="UTF-8"?>
 `;
 
 /**
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
  *
- * @param {Treelike} treelike
- * @param {{ assumeSlashes?: boolean, base?: string }} options
+ * @param {Maplike} maplike
+ * @param {{ base?: string }} options
  * @returns {Promise<string>}
  */
-export default async function sitemap(treelike, options = {}) {
-  const tree = await getTreeArgument(treelike, "sitemap");
+export default async function sitemap(maplike, options = {}) {
+  const tree = await getTreeArgument(maplike, "sitemap");
 
   // We're only interested in keys that end in .html or with no extension.
-  function test(key) {
-    return key.endsWith?.(".html") || !key.includes?.(".");
-  }
-  const filterTree = {
-    async keys() {
-      const keys = Array.from(await tree.keys());
-      return keys.filter((key) => test(key));
-    },
+  const filtered = await Tree.filter(
+    tree,
+    (value, key) => key.endsWith?.(".html") || !key.includes?.(".")
+  );
 
-    async get(key) {
-      return test(key) ? tree.get(key) : undefined;
-    },
-  };
-
-  const treePaths = await Tree.paths(filterTree, options);
+  const treePaths = await Tree.paths(filtered, options);
 
   // For simplicity, we assume that HTML pages will end in .html.
   // If the page is named index.html, we remove index.html from