@weborigami/origami 0.5.4 → 0.5.5

package/index.ts

@@ -3,16 +3,12 @@
  * tool to confirm our code is type safe.
  */
 
-import { Treelike, Unpackable } from "@weborigami/async-tree";
-
 /**
  * A class constructor is an object with a `new` method that returns an
  * instance of the indicated type.
  */
 export type Constructor<T> = new (...args: any[]) => T;
 
-export type Invocable = Function | Unpackable<Function|Treelike> | Treelike;
-
 export interface JsonObject {
   [key: string]: JsonValue;
 }

package/main.js

@@ -1,6 +1,5 @@
 export { default as documentObject } from "./src/common/documentObject.js";
 export { toString } from "./src/common/utilities.js";
-export * from "./src/dev/dev.js";
 export { default as handlerBuiltins } from "./src/handlers/handlerBuiltins.js";
 export * from "./src/handlers/handlers.js";
 export * from "./src/origami/origami.js";
@@ -8,5 +7,23 @@ export { default as origamiHighlightDefinition } from "./src/origami/origamiHigh
 export { default as package } from "./src/protocols/package.js";
 export * from "./src/server/server.js";
 
-// TODO: Remove once these async-tree owns sole copy of all tree builtins
-export * from "./src/tree/tree.js";
+// Export only those dev exports that aren't tree exports
+export {
+  audit,
+  breakpoint,
+  changes,
+  code,
+  copy,
+  crawl,
+  debug,
+  explore,
+  help,
+  indexPage,
+  log,
+  serve,
+  stdin,
+  svg,
+  version,
+  watch,
+  yaml,
+} from "./src/dev/dev.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -17,10 +17,10 @@
     "typescript": "5.9.2"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.5.4",
+    "@weborigami/async-tree": "0.5.5",
     "@weborigami/json-feed-to-rss": "1.0.0",
-    "@weborigami/language": "0.5.4",
-    "@weborigami/types": "0.5.4",
+    "@weborigami/language": "0.5.5",
+    "@weborigami/types": "0.5.5",
     "css-tree": "3.1.0",
     "exif-parser": "0.1.12",
     "graphviz-wasm": "3.0.2",

package/src/builtinsProgram.js

@@ -1,4 +1,4 @@
-import { deepText, indent, json, text } from "@weborigami/async-tree";
+import { Tree } from "@weborigami/async-tree";
 import { jsGlobals } from "@weborigami/language";
 import * as dev from "./dev/dev.js";
 import help from "./dev/help.js";
@@ -12,20 +12,11 @@ import httpstree from "./protocols/httpstree.js";
 import httptree from "./protocols/httptree.js";
 import node from "./protocols/node.js";
 import packageNamespace from "./protocols/package.js";
-import * as tree from "./tree/tree.js";
 
 let builtins;
 
 export default function builtinsProgram() {
   if (!builtins) {
-    const Tree = {
-      ...tree,
-      deepText,
-      indent,
-      json,
-      text,
-    };
-
     const Protocol = {
       explore,
       files,

package/src/common/documentObject.js

@@ -4,10 +4,10 @@ import { isPlainObject, isUnpackable, toString } from "@weborigami/async-tree";
  * In Origami, a text document object is any object with a `_body` property.
  * This function is a helper for constructing such text document objects.
  *
- * @typedef {import("@weborigami/async-tree").StringLike} StringLike
+ * @typedef {import("@weborigami/async-tree").Stringlike} Stringlike
  * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
  *
- * @param {StringLike|PlainObject} input
+ * @param {Stringlike|PlainObject} input
  * @param {any} [data]
  */
 export default async function documentObject(input, data) {

package/src/common/loadJsDom.js

@@ -0,0 +1,13 @@
+let promise;
+
+/**
+ * Lazy-load the jsdom library.
+ *
+ * Statically loading jsdom is slightly annoying. It's a large library that's
+ * rarely used. It also executes non-trivial code at load time. That includes a
+ * runtime test that (always?) throws an exception, which complicates debugging.
+ */
+export default async function loadJsDom() {
+  promise ??= await import("jsdom");
+  return promise;
+}

package/src/common/utilities.d.ts

@@ -2,6 +2,5 @@
 export function getDescriptor(object: any): string;
 export function hasNonPrintableCharacters(text: string): boolean;
 export function isTransformApplied(Transform: Function, object: any): boolean;
-export function toFunction(object: any): Function;
 export function toString(object: any): string|null;
 export function transformObject(Transform: Function, object: any): any;

package/src/common/utilities.js

@@ -1,8 +1,6 @@
 import {
-  Tree,
   toString as asyncTreeToString,
   isPlainObject,
-  isUnpackable,
   trailingSlash,
 } from "@weborigami/async-tree";
 import { symbols } from "@weborigami/language";
@@ -52,40 +50,6 @@ export function isTransformApplied(Transform, obj) {
   return false;
 }
 
-/**
- * Convert the given object to a function.
- *
- * @typedef {import("../../index.ts").Invocable} Invocable
- * @param {any} obj
- * @returns {Function|null}
- */
-export function toFunction(obj) {
-  if (typeof obj === "function") {
-    // Return a function as is.
-    return obj;
-  } else if (isUnpackable(obj)) {
-    // Extract the contents of the object and convert that to a function.
-    let fnPromise;
-    /** @this {any} */
-    return async function (...args) {
-      if (!fnPromise) {
-        // unpack() may return a function or a promise for a function; normalize
-        // to a promise for a function
-        const unpackPromise = Promise.resolve(obj.unpack());
-        fnPromise = unpackPromise.then((content) => toFunction(content));
-      }
-      const fn = await fnPromise;
-      return fn.call(this, ...args);
-    };
-  } else if (Tree.isTreelike(obj)) {
-    // Return a function that invokes the tree's getter.
-    return Tree.toFunction(obj);
-  } else {
-    // Not a function
-    return null;
-  }
-}
-
 /**
  * Extend the async-tree toString method: objects that have a `_body` property
  * will return the value of that property as a string.

package/src/dev/ExplorableSiteTransform.js

@@ -48,7 +48,6 @@ export default function ExplorableSiteTransform(Base) {
         // If the value isn't a tree, but has a tree attached via an `unpack`
         // method, wrap the unpack method to add this transform.
         const original = value.unpack.bind(value);
-        const parent = this;
         value.unpack = async () => {
           const content = await original();
           // See function notes at @debug
@@ -57,9 +56,6 @@ export default function ExplorableSiteTransform(Base) {
           }
           /** @type {any} */
           let tree = Tree.from(content);
-          if (!tree.parent) {
-            tree.parent = parent;
-          }
           if (!isTransformApplied(ExplorableSiteTransform, tree)) {
             tree = transformObject(ExplorableSiteTransform, tree);
           }

package/src/dev/changes.js

@@ -1,4 +1,4 @@
-import { trailingSlash, Tree } from "@weborigami/async-tree";
+import { getTreeArgument, trailingSlash, Tree } from "@weborigami/async-tree";
 
 /**
  * Given an old tree and a new tree, return a tree of changes indicated
@@ -6,13 +6,18 @@ import { trailingSlash, Tree } from "@weborigami/async-tree";
  *
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  *
- * @this {import("@weborigami/types").AsyncTree|null}
  * @param {Treelike} oldTreelike
  * @param {Treelike} newTreelike
  */
 export default async function changes(oldTreelike, newTreelike) {
-  const oldTree = Tree.from(oldTreelike, { deep: true, parent: this });
-  const newTree = Tree.from(newTreelike, { deep: true, parent: this });
+  const oldTree = await getTreeArgument(oldTreelike, "changes", {
+    deep: true,
+    position: 0,
+  });
+  const newTree = await getTreeArgument(newTreelike, "changes", {
+    deep: true,
+    position: 1,
+  });
 
   const oldKeys = Array.from(await oldTree.keys());
   const newKeys = Array.from(await newTree.keys());
@@ -34,7 +39,7 @@ export default async function changes(oldTreelike, newTreelike) {
     const newValue = await newTree.get(oldKey);
 
     if (Tree.isAsyncTree(oldValue) && Tree.isAsyncTree(newValue)) {
-      const treeChanges = await changes.call(this, oldValue, newValue);
+      const treeChanges = await changes(oldValue, newValue);
       if (treeChanges && Object.keys(treeChanges).length > 0) {
         result ??= {};
         result[oldKey] = treeChanges;

package/src/dev/code.js

@@ -1,17 +1,12 @@
 import { toString } from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
-import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
- * @this {AsyncTree|null}
- * @param {import("@weborigami/async-tree").StringLike} input
+ * @param {import("@weborigami/async-tree").Stringlike} input
  */
 export default async function code(input) {
-  if (input === undefined) {
-    input = await getTreeArgument(this, arguments, input, "code");
-  }
   if (input === undefined) {
     return undefined;
   }

package/src/dev/copy.js

@@ -1,22 +1,18 @@
-import { Tree } from "@weborigami/async-tree";
+import { getTreeArgument, Tree } from "@weborigami/async-tree";
 import { formatError } from "@weborigami/language";
 import process, { stdout } from "node:process";
-import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { transformObject } from "../common/utilities.js";
-import setDeep from "../tree/setDeep.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  *
- * @this {AsyncTree|null}
  * @param {Treelike} source
  * @param {Treelike} target
  */
 export default async function copy(source, target) {
-  assertTreeIsDefined(this, "copy");
-  const sourceTree = Tree.from(source, { parent: this });
-  /** @type {any} */ let targetTree = Tree.from(target, { parent: this });
+  const sourceTree = await getTreeArgument(source, "copy", { position: 0 });
+  let targetTree = await getTreeArgument(target, "copy", { position: 1 });
 
   if (stdout.isTTY) {
     targetTree = transformObject(ProgressTransform, targetTree);
@@ -25,7 +21,7 @@ export default async function copy(source, target) {
     countCopied = 0;
   }
 
-  await setDeep.call(this, targetTree, sourceTree);
+  await Tree.assign(targetTree, sourceTree);
 
   if (stdout.isTTY) {
     process.stdout.clearLine(0);

package/src/dev/crawler/audit.js

@@ -1,5 +1,9 @@
-import { pathFromKeys, symbols, Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../../common/getTreeArgument.js";
+import {
+  getTreeArgument,
+  pathFromKeys,
+  symbols,
+  Tree,
+} from "@weborigami/async-tree";
 import crawlResources from "./crawlResources.js";
 import { getBaseUrl } from "./utilities.js";
 
@@ -10,12 +14,11 @@ import { getBaseUrl } from "./utilities.js";
  * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  *
- * @this {AsyncTree|null}
  * @param {Treelike} treelike
  * @param {string} [baseHref]
  */
 export default async function audit(treelike, baseHref) {
-  const tree = await getTreeArgument(this, arguments, treelike, "audit");
+  const tree = await getTreeArgument(treelike, "audit");
   const baseUrl = getBaseUrl(baseHref, treelike);
 
   let errors = {};
@@ -73,13 +76,10 @@ export default async function audit(treelike, baseHref) {
     return undefined;
   }
 
-  Object.defineProperty(errors, symbols.parent, {
-    enumerable: false,
-    value: this,
-  });
   Object.defineProperty(errors, symbols.deep, {
     enumerable: false,
     value: true,
   });
+
   return errors;
 }

package/src/dev/crawler/crawl.js

@@ -1,11 +1,10 @@
 import {
   DeepObjectTree,
   Tree,
-  deepMerge,
+  getTreeArgument,
   keysFromPath,
 } from "@weborigami/async-tree";
 import { InvokeFunctionsTransform } from "@weborigami/language";
-import getTreeArgument from "../../common/getTreeArgument.js";
 import crawlResources from "./crawlResources.js";
 import { addValueToObject, getBaseUrl } from "./utilities.js";
 
@@ -20,13 +19,12 @@ import { addValueToObject, getBaseUrl } from "./utilities.js";
  * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  *
- * @this {AsyncTree|null}
  * @param {Treelike} treelike
  * @param {string} [baseHref]
  * @returns {Promise<AsyncTree>}
  */
 export default async function crawlBuiltin(treelike, baseHref) {
-  const tree = await getTreeArgument(this, arguments, treelike, "crawl");
+  const tree = await getTreeArgument(treelike, "crawl");
   const baseUrl = getBaseUrl(baseHref, treelike);
 
   const cache = {};
@@ -55,7 +53,7 @@ export default async function crawlBuiltin(treelike, baseHref) {
   // Merge the cache on top of the resources tree. If we have an actual value
   // for something already, that's better than a function that will get that
   // value.
-  const result = deepMerge(
+  const result = Tree.deepMerge(
     new DeepObjectTree(cache),
     new (InvokeFunctionsTransform(DeepObjectTree))(resources)
   );

package/src/dev/crawler/findPaths.js

@@ -41,15 +41,21 @@ function filterPaths(paths, baseUrl, localPath) {
  * Given a value retrieved from a site using a given key (name), determine what
  * kind of file it is and, based on that, find the paths it references.
  */
-export default function findPaths(value, key, baseUrl, localPath) {
+export default async function findPaths(value, key, baseUrl, localPath) {
   const text = toString(value);
+  if (text === null) {
+    return {
+      crawlablePaths: [],
+      resourcePaths: [],
+    };
+  }
 
   // We guess the value is HTML is if its key has an .html extension or
   // doesn't have an extension, or the value starts with `<`.
   const ext = key ? extension.extname(key).toLowerCase() : "";
   let foundPaths;
   if (ext === ".html" || ext === ".htm" || ext === ".xhtml") {
-    foundPaths = pathsInHtml(text);
+    foundPaths = await pathsInHtml(text);
   } else if (ext === ".css") {
     foundPaths = pathsInCss(text);
   } else if (ext === ".js") {
@@ -62,7 +68,7 @@ export default function findPaths(value, key, baseUrl, localPath) {
     foundPaths = pathsInSitemap(text);
   } else if (ext === "" && text?.trim().startsWith("<")) {
     // Probably HTML
-    foundPaths = pathsInHtml(text);
+    foundPaths = await pathsInHtml(text);
   } else {
     // Doesn't have an extension we want to process
     return {

package/src/dev/crawler/pathsInHtml.js

@@ -1,9 +1,10 @@
-import { JSDOM, VirtualConsole } from "jsdom";
+import loadJsDom from "../../common/loadJsDom.js";
 import pathsInCss from "./pathsInCss.js";
 import pathsInJs from "./pathsInJs.js";
 import { addHref } from "./utilities.js";
 
-export default function pathsInHtml(html) {
+export default async function pathsInHtml(html) {
+  const { JSDOM, VirtualConsole } = await loadJsDom();
   const paths = {
     /** @type {string[]} */
     crawlablePaths: [],
@@ -153,7 +154,7 @@ export default function pathsInHtml(html) {
   while ((match = noframesRegex.exec(html))) {
     const noframesHtml = match.groups?.html;
     if (noframesHtml) {
-      const noframesPaths = pathsInHtml(noframesHtml);
+      const noframesPaths = await pathsInHtml(noframesHtml);
       paths.crawlablePaths.push(...noframesPaths.crawlablePaths);
       paths.resourcePaths.push(...noframesPaths.resourcePaths);
     }

package/src/dev/debug.js

@@ -1,5 +1,4 @@
-import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../common/getTreeArgument.js";
+import { getTreeArgument, Tree } from "@weborigami/async-tree";
 import { isTransformApplied, transformObject } from "../common/utilities.js";
 import ExplorableSiteTransform from "./ExplorableSiteTransform.js";
 import OriCommandTransform from "./OriCommandTransform.js";
@@ -10,13 +9,11 @@ import OriCommandTransform from "./OriCommandTransform.js";
  * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  *
- * @this {AsyncTree|null}
- * @param {Treelike} [treelike]
+ * @param {Treelike} treelike
+ * @returns {Promise<AsyncTree>}
  */
 export default async function debug(treelike) {
-  // The debug command leaves the tree's existing scope intact; it does not
-  // apply its own scope to the tree.
-  let tree = await getTreeArgument(this, arguments, treelike, "debug");
+  let tree = await getTreeArgument(treelike, "debug");
 
   if (!isTransformApplied(DebugTransform, tree)) {
     tree = transformObject(DebugTransform, tree);

package/src/dev/dev.js

@@ -1,7 +1,9 @@
+import { Tree } from "@weborigami/async-tree";
+export const clear = Tree.clear;
+export const keys = Tree.keys;
+
 export { default as indexPage } from "../origami/indexPage.js";
 export { default as yaml } from "../origami/yaml.js";
-export { default as clear } from "../tree/clear.js";
-export { default as keys } from "../tree/keys.js";
 export { default as breakpoint } from "./breakpoint.js";
 export { default as changes } from "./changes.js";
 export { default as code } from "./code.js";

package/src/dev/explore.js

@@ -1,5 +1,5 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
-import { Tree, scope } from "@weborigami/async-tree";
+import { Tree } from "@weborigami/async-tree";
 import { OrigamiFiles } from "@weborigami/language";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -29,7 +29,7 @@ export default async function explore(...keys) {
     if (!debugTree) {
       return undefined;
     }
-    const debugScope = scope(debugTree);
+    const debugScope = await Tree.scope(debugTree);
     // HACK: reproduce logic of ExplorableSiteTransform that turns a trailing
     // slash into index.html. Calling `debug` applies that transform and the
     // transform should handle that logic, but unfortunately the `traverse`
@@ -41,7 +41,8 @@ export default async function explore(...keys) {
     result = await Tree.traverse(debugScope, ...keys);
   } else {
     // Return the Explore page for the current scope.
-    const data = await getScopeData(scope(tree));
+    const scope = await Tree.scope(tree);
+    const data = await getScopeData(scope);
     templatePromise ??= loadTemplate();
     const template = await templatePromise;
     const text = await template.call(this, data);

package/src/dev/help.js

@@ -2,18 +2,14 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "url";
 import YAML from "yaml";
-import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import version from "./version.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
- * @this {AsyncTree|null}
  * @param {string} [key]
  */
 export default async function help(key) {
-  assertTreeIsDefined(this, "help");
-
   const helpFilename = path.resolve(
     fileURLToPath(import.meta.url),
     "../help.yaml"

package/src/dev/help.yaml

@@ -175,12 +175,12 @@ Tree:
     cache:
       args: (tree, [cache])
       description: Caches values from the tree
+    calendar:
+      args: (options)
+      description: Return a tree structure for years/months/days
     clear:
       args: (tree)
       description: Remove all values from the tree
-    concat:
-      args: (...objs)
-      description: Concatenate text and/or trees of text
     constant:
       args: (value)
       description: Return a deep tree with a single constant value
@@ -202,9 +202,9 @@ Tree:
     deepValues:
       args: (tree)
       description: The in-order leaf values of the tree
-    defineds:
-      args: (tree)
-      description: Only the defined values of the tree
+    delete:
+      args: (tree, key)
+      description: Delete the value for the key from tree
     entries:
       args: (tree)
       description: The tree's [key, value] pairs
@@ -220,9 +220,6 @@ Tree:
     from:
       args: (object, options)
       description: Create a tree from an object
-    fromFn:
-      args: (fn, [keys])
-      description: A tree defined by a value function
     globKeys:
       args: (patterns)
       description: A tree whose keys can include glob wildcard patterns
@@ -233,6 +230,7 @@ Tree:
       args: (tree, key)
       description: True if key exists in tree
     indent:
+      args: "`…`"
       description: Tagged template literal for normalizing indentation
     inners:
       args: (tree)
@@ -262,7 +260,7 @@ Tree:
       args: (tree, options)
       description: Create a new tree by mapping keys and/or values
     mapReduce:
-      args: (tree, valueFn, reduceFn)
+      args: (tree, mapFn, reduceFn)
       description: Map values and reduce them
     mask:
       args: (source, mask)
@@ -288,9 +286,6 @@ Tree:
     regExpKeys:
       args: (tree)
       description: A tree whose keys are regular expression strings
-    remove:
-      args: (tree, key)
-      description: Remove the value for the key from tree
     reverse:
       args: (tree)
       description: Reverse the order of the tree's keys
@@ -309,6 +304,9 @@ Tree:
     take:
       args: (tree, n)
       description: The first n values in the tree
+    text:
+      args: "`…`"
+      description: Tagged template literal for rendering trees
     traverse:
       args: (tree, ...keys)
       description: Return the value at the path of keys
@@ -321,3 +319,6 @@ Tree:
     values:
       args: (tree)
       description: The tree's values
+    withKeys:
+      args: (tree, keys)
+      description: Use the given keys for the tree

package/src/dev/log.js

@@ -4,12 +4,11 @@ import yaml from "../origami/yaml.js";
  * Log the first argument to the console as a side effect and return the second
  * argument. If no second argument is provided, return the first argument.
  *
- * @this {import("@weborigami/types").AsyncTree|null}
  * @param {any} object
  * @param {any} [result]
  */
 export default async function log(result, object = result) {
-  let text = object !== undefined ? await yaml.call(this, object) : "undefined";
+  let text = object !== undefined ? await yaml.call(null, object) : "undefined";
   text = text?.trim();
   console.log(text);
   return result;

package/src/dev/serve.js

@@ -1,13 +1,10 @@
-import { Tree } from "@weborigami/async-tree";
+import { getTreeArgument } from "@weborigami/async-tree";
 import http from "node:http";
 import { createServer } from "node:net";
 import process from "node:process";
-import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { isTransformApplied, transformObject } from "../common/utilities.js";
 import { requestListener } from "../server/server.js";
-import debug from "./debug.js";
 import ExplorableSiteTransform from "./ExplorableSiteTransform.js";
-import watch from "./watch.js";
 
 const defaultPort = 5000;
 
@@ -19,22 +16,12 @@ const defaultPort = 5000;
  *
  * @param {Treelike} treelike
  * @param {number} [port]
- * @this {AsyncTree|null}
  */
 export default async function serve(treelike, port) {
-  assertTreeIsDefined(this, "serve");
-  let tree;
-  if (treelike) {
-    tree = Tree.from(treelike, { parent: this });
-    if (!isTransformApplied(ExplorableSiteTransform, tree)) {
-      tree = transformObject(ExplorableSiteTransform, tree);
-    }
-  } else if (arguments.length === 0) {
-    // By default, watch the default tree and add default pages.
-    const withDefaults = await debug.call(this);
-    tree = await watch.call(this, withDefaults);
-  } else {
-    throw new Error("serve: no tree was provided to serve");
+  let tree = await getTreeArgument(treelike, "serve");
+
+  if (!isTransformApplied(ExplorableSiteTransform, tree)) {
+    tree = transformObject(ExplorableSiteTransform, tree);
   }
 
   if (port === undefined) {