@weborigami/origami 0.0.41 → 0.0.42

package/src/builtins/{@tree/take.js → @take.js}

@@ -1,5 +1,5 @@
 import { Scope } from "@weborigami/language";
-import getTreeArgument from "../../misc/getTreeArgument.js";
+import getTreeArgument from "../misc/getTreeArgument.js";
 
 /**
  * Given a tree, take the first n items from it.
@@ -11,7 +11,7 @@ import getTreeArgument from "../../misc/getTreeArgument.js";
  * @param {number} n
  */
 export default async function take(treelike, n) {
-  const tree = await getTreeArgument(this, arguments, treelike);
+  const tree = await getTreeArgument(this, arguments, treelike, "@take");
 
   /** @type {AsyncTree} */
   let takeTree = {
@@ -30,5 +30,5 @@ export default async function take(treelike, n) {
   return takeTree;
 }
 
-take.usage = `take tree, n\tReturn the first n items from tree`;
+take.usage = `@take tree, n\tReturn the first n items from tree`;
 take.documentation = "https://weborigami.org/cli/builtins.html#take";

package/src/builtins/{@tree/from.js → @tree.js}

@@ -1,5 +1,5 @@
 import { Scope } from "@weborigami/language";
-import getTreeArgument from "../../misc/getTreeArgument.js";
+import getTreeArgument from "../misc/getTreeArgument.js";
 
 /**
  * Cast the indicated treelike to a tree.
@@ -10,10 +10,10 @@ import getTreeArgument from "../../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function tree(treelike) {
-  let tree = await getTreeArgument(this, arguments, treelike);
+  let tree = await getTreeArgument(this, arguments, treelike, "@tree");
   tree = Scope.treeWithScope(tree, this);
   return tree;
 }
 
-tree.usage = `from <treelike>\tConvert JSON, YAML, function, or plain object to a tree`;
+tree.usage = `@tree <treelike>\tConvert JSON, YAML, function, or plain object to a tree`;
 tree.documentation = "https://weborigami.org/cli/builtins.html#tree";

package/src/builtins/@treeHttp.js

@@ -11,7 +11,7 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @param  {...string|Symbol} keys
  */
 export default function treeHttp(host, ...keys) {
-  assertScopeIsDefined(this);
+  assertScopeIsDefined(this, "treeHttp");
   return ops.treeHttp.call(this, host, ...keys);
 }
 

package/src/builtins/@treeHttps.js

@@ -11,7 +11,7 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @param  {...string|Symbol} keys
  */
 export default function treeHttps(host, ...keys) {
-  assertScopeIsDefined(this);
+  assertScopeIsDefined(this, "treeHttps");
   return ops.treeHttps.call(this, host, ...keys);
 }
 

package/src/builtins/@unpack.js

@@ -8,6 +8,6 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @returns
  */
 export default function unpack(obj) {
-  assertScopeIsDefined(this);
+  assertScopeIsDefined(this, "unpack");
   return obj?.unpack?.();
 }

package/src/builtins/{@tree/values.js → @values.js}

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../../misc/getTreeArgument.js";
+import getTreeArgument from "../misc/getTreeArgument.js";
 
 /**
  * Return the interior nodes of the tree.
@@ -10,9 +10,9 @@ import getTreeArgument from "../../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function values(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike);
+  const tree = await getTreeArgument(this, arguments, treelike, "@values");
   return Tree.values(tree);
 }
 
-values.usage = `values <tree>\tThe top-level values in the tree`;
+values.usage = `@values <tree>\tThe top-level values in the tree`;
 values.documentation = "https://weborigami.org/cli/builtins.html#values";

package/src/builtins/{@tree/valuesDeep.js → @valuesDeep.js}

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../../misc/getTreeArgument.js";
+import getTreeArgument from "../misc/getTreeArgument.js";
 
 /**
  * Return the in-order exterior values of a tree as a flat array.
@@ -10,10 +10,10 @@ import getTreeArgument from "../../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function valuesDeep(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike);
+  const tree = await getTreeArgument(this, arguments, treelike, "@valuesDeep");
   return Tree.mapReduce(tree, null, async (values) => values.flat());
 }
 
-valuesDeep.usage = `valuesDeep <tree>\tThe in-order tree values as a flat array`;
+valuesDeep.usage = `@valuesDeep <tree>\tThe in-order tree values as a flat array`;
 valuesDeep.documentation =
   "https://weborigami.org/cli/builtins.html#valuesDeep";

package/src/builtins/@watch.js

@@ -16,7 +16,7 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  */
 export default async function watch(treelike, fn) {
   /** @type {any} */
-  const container = await getTreeArgument(this, arguments, treelike);
+  const container = await getTreeArgument(this, arguments, treelike, "@watch");
 
   // Watch the indicated tree.
   await /** @type {any} */ (container).watch?.();

package/src/builtins/@with.js

@@ -14,7 +14,7 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @param  {Invocable} invocable
  */
 export default function withTree(treelike, invocable) {
-  assertScopeIsDefined(this);
+  assertScopeIsDefined(this, "with");
   const tree = Tree.from(treelike);
   const fn = toFunction(invocable);
   const scope = new Scope(tree, this);

package/src/builtins/@yaml.js

@@ -10,7 +10,7 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @param {any} [obj]
  */
 export default async function toYaml(obj) {
-  assertScopeIsDefined(this);
+  assertScopeIsDefined(this, "yaml");
   // A fragment of the logic from getTreeArgument.js
   if (arguments.length > 0 && obj === undefined) {
     throw new Error(

package/src/builtins/{@tree/map.d.ts → map.d.ts}

@@ -1,6 +1,6 @@
 import { KeyFn, Treelike, ValueKeyFn } from "@weborigami/async-tree";
 import { AsyncTree } from "@weborigami/types";
-import { TreelikeTransform } from "../../../index.ts";
+import { TreelikeTransform } from "../../index.ts";
 
 type TreeMapOptions = {
   deep?: boolean;

package/src/cli/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { ObjectTree, Tree } from "@weborigami/async-tree";
-import { Scope } from "@weborigami/language";
+import { Scope, formatError } from "@weborigami/language";
 import path from "node:path";
 import process, { stdout } from "node:process";
 import ori from "../builtins/@ori.js";
@@ -75,19 +75,6 @@ while (args[0] === "") {
 try {
   await main(...args);
 } catch (/** @type {any} */ error) {
-  // Work up to the root cause, displaying intermediate messages as we go up.
-  if (!error.cause && !error.stack) {
-    console.error(error.message);
-  } else {
-    while (error.cause) {
-      console.error(error.message);
-      error = error.cause;
-    }
-  }
-  if (error.stack) {
-    // Display stack trace for root cause, under the theory that that's the most
-    // useful place to look for the problem.
-    console.error(error.stack);
-  }
+  console.error(formatError(error));
   process.exitCode = 1;
 }

package/src/common/ExplorableSiteTransform.js

@@ -37,10 +37,12 @@ export default function ExplorableSiteTransform(Base) {
       if (value === undefined) {
         // The tree doesn't have the key; try the defaults.
         const scope = Scope.getScope(this);
-        if (key === "index.html") {
-          value = await index.call(scope, this);
-        } else if (key === ".keys.json") {
-          value = await keysJson.stringify(this);
+        if (scope) {
+          if (key === "index.html") {
+            value = await index.call(scope, this);
+          } else if (key === ".keys.json") {
+            value = await keysJson.stringify(this);
+          }
         }
       }
 

package/src/misc/assertScopeIsDefined.js

@@ -1,7 +1,7 @@
-export default function assertScopeIsDefined(scope) {
+export default function assertScopeIsDefined(scope, methodName) {
   if (scope === undefined) {
     throw new Error(
-      "Tree methods must be called a scope. If you don't want to pass a scope, invoke with: <methodName>.call(null)"
+      `${methodName} must be called with a scope. If you don't want to pass a scope, invoke with: ${methodName}.call(null)`
     );
   }
 }

package/src/misc/getTreeArgument.js

@@ -1,4 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
+import { isTreelike } from "@weborigami/async-tree/src/Tree.js";
 import assertScopeIsDefined from "./assertScopeIsDefined.js";
 
 /**
@@ -16,26 +17,35 @@ import assertScopeIsDefined from "./assertScopeIsDefined.js";
  * @param {AsyncTree|null} scope
  * @param {IArguments} args
  * @param {Treelike|undefined} treelike
+ * @param {string} methodName
  * @returns {Promise<AsyncTree>}
  */
-export default async function getTreeArgument(scope, args, treelike) {
+export default async function getTreeArgument(
+  scope,
+  args,
+  treelike,
+  methodName
+) {
   assertScopeIsDefined(scope);
 
   if (treelike !== undefined) {
-    return Tree.from(treelike);
+    if (isTreelike(treelike)) {
+      return Tree.from(treelike);
+    }
+    throw new Error(
+      `${methodName}: The first argument must be a tree, like an array, object, or files.`
+    );
   }
 
   if (args.length === 0) {
     if (!scope) {
       // Should never happen because assertScopeIsDefined throws an exception.
       throw new Error(
-        "An Origami tree function was called with no tree argument and no scope."
+        `${methodName} was called with no tree argument and no scope.`
       );
     }
     return scope.get("@current");
   }
 
-  throw new Error(
-    "An Origami tree function was called with an initial argument, but its value is undefined."
-  );
+  throw new Error(`${methodName}: The first argument was undefined.`);
 }

package/src/{builtins/@tree/dot.js → misc/treeDot.js}

@@ -1,11 +1,7 @@
 import { Tree, isPlainObject, isStringLike } from "@weborigami/async-tree";
 import { extname } from "@weborigami/language";
-import * as serialize from "../../common/serialize.js";
-import {
-  hasNonPrintableCharacters,
-  keySymbol,
-} from "../../common/utilities.js";
-import getTreeArgument from "../../misc/getTreeArgument.js";
+import * as serialize from "../common/serialize.js";
+import { hasNonPrintableCharacters, keySymbol } from "../common/utilities.js";
 
 /**
  * Render a tree in DOT format.
@@ -19,7 +15,7 @@ import getTreeArgument from "../../misc/getTreeArgument.js";
  * @param {PlainObject} [options]
  */
 export default async function dot(treelike, options = {}) {
-  const tree = await getTreeArgument(this, arguments, treelike);
+  const tree = Tree.from(treelike);
   const rootLabel = tree[keySymbol] ?? "";
   const treeArcs = await statements(tree, "", rootLabel, options);
   return `digraph g {

package/src/server/constructResponse.js

@@ -0,0 +1,126 @@
+import {
+  SiteTree,
+  Tree,
+  isPlainObject,
+  isStringLike,
+} from "@weborigami/async-tree";
+import { extname } from "@weborigami/language";
+import * as serialize from "../common/serialize.js";
+import { toString } from "../common/utilities.js";
+import { mediaTypeForExtension } from "./mediaTypes.js";
+
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
+/**
+ * Given a resource that was returned from a route, construct an appropriate
+ * HTTP Response indicating what should be sent to the client. Return null
+ * if the resource is not a valid response.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {any} resource
+ * @returns {Promise<Response|null>}
+ */
+export default async function constructResponse(request, resource) {
+  if (resource instanceof Response) {
+    // Already a Response, return as is.
+    return resource;
+  } else if (!resource) {
+    return null;
+  }
+
+  // Determine media type, what data we'll send, and encoding.
+  const url = new URL(request.url ?? "", `https://${request.headers.host}`);
+  const extension = extname(url.pathname).toLowerCase();
+  let mediaType = extension ? mediaTypeForExtension[extension] : undefined;
+
+  if (
+    mediaType === undefined &&
+    !url.pathname.endsWith("/") &&
+    (Tree.isAsyncTree(resource) ||
+      isPlainObject(resource) ||
+      resource instanceof Array)
+  ) {
+    // Redirect to an index page for the result.
+    const Location = `${request.url}/`;
+    return new Response("ok", {
+      headers: {
+        Location,
+      },
+      status: 307,
+    });
+  }
+
+  // If the request is for a JSON or YAML result, and the resource we got
+  // isn't yet a string or Buffer, convert the resource to JSON or YAML now.
+  if (
+    (mediaType === "application/json" || mediaType === "text/yaml") &&
+    !isStringLike(resource)
+  ) {
+    const tree = Tree.from(resource);
+    resource =
+      mediaType === "text/yaml"
+        ? await serialize.toYaml(tree)
+        : await serialize.toJson(tree);
+  } else if (
+    mediaType === undefined &&
+    (isPlainObject(resource) || resource instanceof Array)
+  ) {
+    // The resource is data, try showing it as YAML.
+    const tree = Tree.from(resource);
+    resource = await serialize.toYaml(tree);
+    mediaType = "text/yaml";
+  }
+
+  let body;
+  if (mediaType) {
+    body = SiteTree.mediaTypeIsText(mediaType) ? toString(resource) : resource;
+  } else {
+    body = textOrObject(resource);
+    // Infer media type.
+    mediaType =
+      typeof body !== "string"
+        ? "application/octet-stream"
+        : body.trimStart().startsWith("<")
+        ? "text/html"
+        : "text/plain";
+  }
+
+  // Assume text is encoded in UTF-8.
+  if (SiteTree.mediaTypeIsText(mediaType)) {
+    mediaType += "; charset=utf-8";
+  }
+
+  // If we didn't get back some kind of data that response.write() accepts,
+  // assume it was an error.
+  const validResponse = typeof body === "string" || body instanceof TypedArray;
+  if (!validResponse) {
+    const typeName = body?.constructor?.name ?? typeof body;
+    console.error(
+      `A served tree must return a string or a TypedArray (such as a Buffer) but returned an instance of ${typeName}.`
+    );
+    return null;
+  }
+
+  return new Response(body, {
+    headers: {
+      "Content-Type": mediaType,
+    },
+  });
+}
+
+/**
+ * Convert to a string if we can, but leave objects that convert to something
+ * like "[object Object]" alone.
+ *
+ * @param {any} object
+ */
+function textOrObject(object) {
+  if (object instanceof ArrayBuffer) {
+    // Convert to Buffer.
+    return Buffer.from(object);
+  } else if (object instanceof TypedArray) {
+    // Return typed arrays as is.
+    return object;
+  }
+  return toString(object);
+}

package/src/server/mediaTypes.js

@@ -79,19 +79,3 @@ export const mediaTypeForExtension = {
   ".yaml": "text/yaml", // Not official
   ".zip": "application/zip",
 };
-
-export const mediaTypeIsText = {
-  "application/json": true,
-  "application/ld+json": true,
-  "application/vnd.oasis.opendocument.text": true,
-  "application/x-httpd-php": true,
-  "application/x-sh": true,
-  "application/xhtml+xml": true,
-  "text/css": true,
-  "text/csv": true,
-  "text/html": true,
-  "text/javascript": true,
-  "text/plain": true,
-  "text/yaml": true,
-  "text/yml": true,
-};

package/src/server/server.js

@@ -1,16 +1,41 @@
-import {
-  ObjectTree,
-  Tree,
-  isPlainObject,
-  isStringLike,
-  keysFromPath,
-} from "@weborigami/async-tree";
-import { Scope, extname } from "@weborigami/language";
-import * as serialize from "../common/serialize.js";
-import { toString } from "../common/utilities.js";
-import { mediaTypeForExtension, mediaTypeIsText } from "./mediaTypes.js";
+import { ObjectTree, Tree, keysFromPath } from "@weborigami/async-tree";
+import { Scope, formatError } from "@weborigami/language";
+import { ServerResponse } from "node:http";
+import constructResponse from "./constructResponse.js";
 
-const TypedArray = Object.getPrototypeOf(Uint8Array);
+/**
+ * Copy a constructed response to a ServerResponse. Return true if the response
+ * was successfully copied, and false if there was a problem.
+ *
+ * @param {Response} constructed
+ * @param {ServerResponse} response
+ */
+async function copyResponse(constructed, response) {
+  response.statusCode = constructed.status;
+  response.statusMessage = constructed.statusText;
+
+  for (const [key, value] of constructed.headers) {
+    response.setHeader(key, value);
+  }
+
+  if (constructed.body) {
+    try {
+      // Write the response body to the ServerResponse.
+      const reader = constructed.body.getReader();
+      let { done, value } = await reader.read();
+      while (!done) {
+        response.write(value);
+        ({ done, value } = await reader.read());
+      }
+      response.end();
+    } catch (/** @type {any} */ error) {
+      console.error(error.message);
+      return false;
+    }
+  }
+
+  return true;
+}
 
 // Extend the tree's scope with the URL's search parameters.
 function extendTreeScopeWithParams(tree, url) {
@@ -38,21 +63,16 @@ function extendTreeScopeWithParams(tree, url) {
   return extendedTree;
 }
 
-// Asynchronous tree router as Express middleware.
-export function treeRouter(tree) {
-  // Return a router for the tree source.
-  return async function (request, response, next) {
-    const handled = await handleRequest(request, response, tree);
-    if (!handled) {
-      // Module not found, let next middleware function try.
-      next();
-    }
-  };
-}
-
+/**
+ * Handle a client request.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {ServerResponse} response
+ * @param {import("@weborigami/types").AsyncTree} tree
+ */
 export async function handleRequest(request, response, tree) {
   // For parsing purposes, we assume HTTPS -- it doesn't affect parsing.
-  const url = new URL(request.url, `https://${request.headers.host}`);
+  const url = new URL(request.url ?? "", `https://${request.headers.host}`);
   const keys = keysFromUrl(url);
 
   const extendedTree =
@@ -73,93 +93,15 @@ export async function handleRequest(request, response, tree) {
     return true;
   }
 
-  let mediaType;
-
-  if (!resource) {
-    return false;
-  }
-
-  // Determine media type, what data we'll send, and encoding.
-  const extension = extname(url.pathname).toLowerCase();
-  mediaType = extension ? mediaTypeForExtension[extension] : undefined;
-
-  if (
-    mediaType === undefined &&
-    !request.url.endsWith("/") &&
-    (Tree.isAsyncTree(resource) ||
-      isPlainObject(resource) ||
-      resource instanceof Array)
-  ) {
-    // Redirect to an index page for the result.
-    // Redirect to the root of the tree.
-    const Location = `${request.url}/`;
-    response.writeHead(307, { Location });
-    response.end("ok");
-    return true;
-  }
-
-  // If the request is for a JSON or YAML result, and the resource we got
-  // isn't yet a string or Buffer, convert the resource to JSON or YAML now.
-  if (
-    (mediaType === "application/json" || mediaType === "text/yaml") &&
-    !isStringLike(resource)
-  ) {
-    const tree = Tree.from(resource);
-    resource =
-      mediaType === "text/yaml"
-        ? await serialize.toYaml(tree)
-        : await serialize.toJson(tree);
-  } else if (
-    mediaType === undefined &&
-    (isPlainObject(resource) || resource instanceof Array)
-  ) {
-    // The resource is data, try showing it as YAML.
-    const tree = Tree.from(resource);
-    resource = await serialize.toYaml(tree);
-    mediaType = "text/yaml";
-  }
-
-  let data;
-  if (mediaType) {
-    data = mediaTypeIsText[mediaType] ? toString(resource) : resource;
-  } else {
-    data = textOrObject(resource);
-  }
-
-  if (!mediaType) {
-    // Can't identify media type; infer default type.
-    mediaType =
-      typeof data !== "string"
-        ? "application/octet-stream"
-        : data.trimStart().startsWith("<")
-        ? "text/html"
-        : "text/plain";
-  }
-  const encoding = mediaTypeIsText[mediaType] ? "utf-8" : undefined;
-
-  // If we didn't get back some kind of data that response.write() accepts,
-  // assume it was an error.
-  const validResponse = typeof data === "string" || data instanceof TypedArray;
-
-  if (!validResponse) {
-    const typeName = data?.constructor?.name ?? typeof data;
-    console.error(
-      `A served tree must return a string or a TypedArray (such as a Buffer) but returned an instance of ${typeName}.`
-    );
-    return false;
-  }
-
-  response.writeHead(200, {
-    "Content-Type": mediaType,
-  });
-  try {
-    response.end(data, encoding);
-  } catch (/** @type {any} */ error) {
-    console.error(error.message);
+  // Construct the response.
+  const constructed = await constructResponse(request, resource);
+  if (!constructed) {
     return false;
   }
 
-  return true;
+  // Copy the construct response to the ServerResponse and return true if
+  // the response was valid.
+  return copyResponse(constructed, response);
 }
 
 function keysFromUrl(url) {
@@ -211,16 +153,7 @@ export function requestListener(treelike) {
  * the console.
  */
 function respondWithError(response, error) {
-  let message = "";
-  // Work up to the root cause, displaying intermediate messages as we go up.
-  while (error.cause) {
-    message += error.message + `\n`;
-    error = error.cause;
-  }
-  if (error.name) {
-    message += `${error.name}: `;
-  }
-  message += error.message;
+  let message = formatError(error);
   // Prevent HTML in the error message from being interpreted as HTML.
   message = message.replace(/</g, "&lt;").replace(/>/g, "&gt;");
   const html = `<!DOCTYPE html>
@@ -241,16 +174,14 @@ ${message}
   console.error(message);
 }
 
-/**
- * Convert to a string if we can, but leave objects that convert to something
- * like "[object Object]" alone.
- *
- * @param {any} object
- */
-function textOrObject(object) {
-  // Return buffers and typed arrays as is.
-  if (object instanceof ArrayBuffer || object instanceof TypedArray) {
-    return object;
-  }
-  return toString(object);
+// Asynchronous tree router as Express middleware.
+export function treeRouter(tree) {
+  // Return a router for the tree source.
+  return async function (request, response, next) {
+    const handled = await handleRequest(request, response, tree);
+    if (!handled) {
+      // Module not found, let next middleware function try.
+      next();
+    }
+  };
 }