@weborigami/origami 0.0.46 → 0.0.48

package/src/builtins/css_handler.js

@@ -0,0 +1,7 @@
+// .css files use the .txt loader
+import fileTypeText from "./txt_handler.js";
+
+export default {
+  ...fileTypeText,
+  mediaType: "text/css",
+};

package/src/builtins/htm_handler.js

@@ -0,0 +1,2 @@
+// .htm is a synonynm for .html
+export { default } from "./html_handler.js";

package/src/builtins/html_handler.js

@@ -0,0 +1,7 @@
+// .html files use the .txt loader
+import fileTypeText from "./txt_handler.js";
+
+export default {
+  ...fileTypeText,
+  mediaType: "text/html",
+};

package/src/builtins/jpeg_handler.js

@@ -0,0 +1,58 @@
+import exifParser from "exif-parser";
+
+const exifDateTags = [
+  "ModifyDate",
+  "MDPrepDate",
+  "DateTimeOriginal",
+  "CreateDate",
+  "PreviewDateTime",
+  "GPSDateStamp",
+];
+
+/**
+ * A JPEG file with possible Exif metadata
+ */
+export default {
+  mediaType: "image/jpeg",
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  async unpack(packed, options) {
+    const parser = exifParser.create(packed);
+    parser.enableTagNames(true);
+    parser.enableSimpleValues(true);
+    const parsed = await parser.parse();
+
+    // The exif-parser `enableSimpleValues` option should convert dates to
+    // JavaScript Date objects, but that doesn't seem to work. Ensure dates are
+    // Date objects.
+    const exif = parsed.tags;
+    for (const tag of exifDateTags) {
+      if (typeof exif[tag] === "number") {
+        exif[tag] = new Date(exif[tag] * 1000);
+      }
+    }
+
+    const result = {
+      height: parsed.imageSize.height,
+      width: parsed.imageSize.width,
+      exif,
+    };
+
+    // Promote some Exif properties to the top level.
+    const tagsToPromote = {
+      ImageDescription: "caption",
+      ModifyDate: "modified",
+      Orientation: "orientation",
+    };
+    for (const [tag, key] of Object.entries(tagsToPromote)) {
+      if (exif[tag] !== undefined) {
+        result[key] = exif[tag];
+      }
+    }
+
+    // Add aspect ratio for use with `aspect-ratio` CSS.
+    result.aspectRatio = result.width / result.height;
+
+    return result;
+  },
+};

package/src/builtins/jpg_handler.js

@@ -0,0 +1,2 @@
+// .jpg is a synonym for .jpeg
+export { default } from "./jpeg_handler.js";

package/src/builtins/js_handler.js

@@ -0,0 +1,20 @@
+import processUnpackedContent from "../common/processUnpackedContent.js";
+
+/**
+ * A JavaScript file
+ *
+ * Unpacking a JavaScript file returns its default export, or its set of exports
+ * if there is more than one.
+ */
+export default {
+  mediaType: "application/javascript",
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const { key, parent } = options;
+    if (parent && "import" in parent) {
+      const content = await /** @type {any} */ (parent).import?.(key);
+      return processUnpackedContent(content, parent);
+    }
+  },
+};

package/src/builtins/json_handler.js

@@ -0,0 +1,19 @@
+import * as utilities from "../common/utilities.js";
+
+/**
+ * A JSON file
+ *
+ * Unpacking a JSON file returns the parsed data.
+ */
+export default {
+  mediaType: "application/json",
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  unpack(packed) {
+    const json = utilities.toString(packed);
+    if (!json) {
+      throw new Error("Tried to parse something as JSON but it wasn't text.");
+    }
+    return JSON.parse(json);
+  },
+};

package/src/builtins/md_handler.js

@@ -0,0 +1,7 @@
+// .md files use the .txt loader
+import fileTypeText from "./txt_handler.js";
+
+export default {
+  ...fileTypeText,
+  mediaType: "text/markdown",
+};

package/src/builtins/mjs_handler.js

@@ -0,0 +1,2 @@
+// .mjs is a synonynm for .js
+export { default } from "./js_handler.js";

package/src/builtins/ori_handler.js

@@ -0,0 +1,48 @@
+import { symbols } from "@weborigami/async-tree";
+import { Scope, compile } from "@weborigami/language";
+import processUnpackedContent from "../common/processUnpackedContent.js";
+import * as utilities from "../common/utilities.js";
+import builtins from "./@builtins.js";
+
+/**
+ * An Origami expression file
+ *
+ * Unpacking an Origami file returns the result of evaluating the expression.
+ */
+export default {
+  mediaType: "text/plain",
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const attachedData = options.attachedData;
+    const parent =
+      options.parent ??
+      /** @type {any} */ (packed).parent ??
+      /** @type {any} */ (packed)[symbols.parent];
+
+    // Construct an object to represent the source code.
+    const sourceName = options.key;
+    let url;
+    if (sourceName && parent?.url) {
+      let parentHref = parent.url.href;
+      if (!parentHref.endsWith("/")) {
+        parentHref += "/";
+      }
+      url = new URL(sourceName, parentHref);
+    }
+
+    const source = {
+      text: utilities.toString(packed),
+      name: options.key,
+      url,
+    };
+
+    // Compile the source code as an Origami expression and evaluate it.
+    const compiler = options.compiler ?? compile.expression;
+    const fn = compiler(source);
+    const parentScope = parent ? Scope.getScope(parent) : builtins;
+    let content = await fn.call(parentScope);
+
+    return processUnpackedContent(content, parent, attachedData);
+  },
+};

package/src/builtins/txt_handler.js

@@ -0,0 +1,78 @@
+import { isPacked, symbols } from "@weborigami/async-tree";
+import { evaluateYaml, toYaml } from "../common/serialize.js";
+import * as utilities from "../common/utilities.js";
+
+/**
+ * A text file with possible front matter
+ *
+ * The unpacking process will parse out any YAML or JSON front matter and attach
+ * it to the document as data. The first line of the text must be "---",
+ * followed by a block of JSON or YAML, followed by another line of "---". Any
+ * lines following will be treated as the document text.
+ *
+ * If there is no front matter, the document will be treated as plain text and
+ * returned as a String object.
+ *
+ * If there is front matter, any Origami expressions in the front matter will be
+ * evaluated. The result will be a plain JavaScript object with the evaluated
+ * data and a `@text` property containing the document text.
+ */
+export default {
+  mediaType: "text/plain",
+
+  /**
+   * If the input is already in some packed format, it will be returned as is.
+   *
+   * Otherwise, the properties of the object will be formatted as YAML. If the
+   * object has a `@text` property, that will be used as the body of the text
+   * document; otherwise, an empty string will be used.
+   *
+   * @param {any} object
+   * @returns {Promise<import("@weborigami/async-tree").Packed>}
+   */
+  async pack(object) {
+    if (isPacked(object)) {
+      return object;
+    } else if (!object || typeof object !== "object") {
+      throw new TypeError("The input to pack must be a JavaScript object.");
+    }
+
+    const text = object["@text"] ?? "";
+
+    /** @type {any} */
+    const dataWithoutText = Object.assign({}, object);
+    delete dataWithoutText["@text"];
+    if (Object.keys(dataWithoutText).length > 0) {
+      const frontMatter = (await toYaml(dataWithoutText)).trimEnd();
+      return `---\n${frontMatter}\n---\n${text}`;
+    } else {
+      return text;
+    }
+  },
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const parent = options.parent ?? null;
+    const text = utilities.toString(packed);
+    if (text === null) {
+      throw new Error("Tried to treat something as text but it wasn't text.");
+    }
+
+    const regex =
+      /^(---\r?\n(?<frontText>[\s\S]*?\r?\n?)---\r?\n)(?<body>[\s\S]*$)/;
+    const match = regex.exec(text);
+    let unpacked;
+    if (match) {
+      // Document object with front matter
+      const { body, frontText } = /** @type {any} */ (match.groups);
+      const frontData = await evaluateYaml(frontText, parent);
+      unpacked = Object.assign({}, frontData, { "@text": body });
+    } else {
+      // Plain text
+      unpacked = new String(text);
+    }
+
+    unpacked[symbols.parent] = parent;
+    return unpacked;
+  },
+};

package/src/builtins/wasm_handler.js

@@ -0,0 +1,17 @@
+import processUnpackedContent from "../common/processUnpackedContent.js";
+
+/**
+ * A WebAssembly module
+ *
+ * Unpacking a WebAssembly module returns its exports.
+ */
+export default {
+  mediaType: "application/wasm",
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const wasmModule = await WebAssembly.instantiate(packed);
+    // @ts-ignore TypeScript thinks wasmModule is already an Instance.
+    return processUnpackedContent(wasmModule.instance.exports, options.parent);
+  },
+};

package/src/builtins/xhtml_handler.js

@@ -0,0 +1,2 @@
+// .xhtml is a synonynm for .html
+export { default } from "./html_handler.js";

package/src/builtins/yaml_handler.js

@@ -0,0 +1,29 @@
+import * as YAMLModule from "yaml";
+import processUnpackedContent from "../common/processUnpackedContent.js";
+import { evaluateYaml } from "../common/serialize.js";
+import * as utilities from "../common/utilities.js";
+
+// See notes at serialize.js
+// @ts-ignore
+const YAML = YAMLModule.default ?? YAMLModule.YAML;
+
+/**
+ * A YAML file
+ *
+ * Unpacking a YAML file returns the parsed data.
+ *
+ */
+export default {
+  mediaType: "application/yaml",
+
+  /** @type {import("@weborigami/language").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const parent = options.parent ?? null;
+    const yaml = utilities.toString(packed);
+    if (!yaml) {
+      throw new Error("Tried to parse something as YAML but it wasn't text.");
+    }
+    const data = await evaluateYaml(yaml, options.parent);
+    return processUnpackedContent(data, parent);
+  },
+};

package/src/builtins/yml_handler.js

@@ -0,0 +1,2 @@
+// .yml is a synonym for .yaml
+export { default } from "./yaml_handler.js";

package/src/common/ExplorableSiteTransform.js

@@ -59,11 +59,15 @@ export default function ExplorableSiteTransform(Base) {
         const original = value.unpack.bind(value);
         value.unpack = async () => {
           const content = await original();
-          if (!Tree.isTreelike(content)) {
+          if (!Tree.isTraversable(content)) {
             return content;
           }
           /** @type {any} */
           let tree = Tree.from(content);
+          if (!tree.parent && !tree.scope) {
+            const scope = Scope.getScope(this);
+            tree = Scope.treeWithScope(tree, scope);
+          }
           tree = transformObject(ExplorableSiteTransform, tree);
           return tree;
         };

package/src/common/addValueKeyToScope.js

@@ -1,3 +1,4 @@
+import { ObjectTree } from "@weborigami/async-tree";
 import { Scope } from "@weborigami/language";
 
 /**
@@ -14,9 +15,9 @@ import { Scope } from "@weborigami/language";
  */
 export default function addValueKeyToScope(scope, value, key) {
   // Add the key and value to the scope as ambients.
-  const ambients = {
+  const ambients = new ObjectTree({
     "@key": key,
     _: value,
-  };
+  });
   return new Scope(ambients, scope);
 }

package/src/common/documentObject.js

@@ -0,0 +1,33 @@
+import { isPlainObject } from "@weborigami/async-tree";
+import txtHandler from "../builtins/txt_handler.js";
+
+/**
+ * In Origami, a text document object is any object with a `@text` property and
+ * a pack() method that formats that object as text with YAML front matter. This
+ * function is a helper for constructing such text document objects.
+ *
+ * @typedef {import("@weborigami/async-tree").StringLike} StringLike
+ * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
+ *
+ * @param {StringLike|PlainObject} input
+ * @param {any} [data]
+ */
+export default function documentObject(input, data) {
+  let text;
+  let inputData;
+  if (isPlainObject(input)) {
+    text = input["@text"];
+    inputData = input;
+  } else {
+    text = String(input);
+    inputData = null;
+  }
+  const base = {
+    pack() {
+      return txtHandler.pack(this);
+    },
+  };
+  const result = Object.create(base);
+  Object.assign(result, inputData, data, { "@text": text });
+  return result;
+}

package/src/common/serialize.d.ts

@@ -5,4 +5,5 @@ export function evaluateYaml(text: string, parent?: AsyncTree|null): Promise<Jso
 export function parseYaml(text: string): JsonValue|AsyncTree;
 export function toJson(obj: JsonValue | AsyncTree): Promise<string>;
 export function toJsonValue(obj: any): Promise<JsonValue>;
+export function toValue(obj: any, jsonValuesOnly?: boolean): Promise<JsonValue>;
 export function toYaml(obj: JsonValue | AsyncTree): Promise<string>;

package/src/common/serialize.js

@@ -5,7 +5,12 @@
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  */
 
-import { Tree, isPlainObject, isStringLike } from "@weborigami/async-tree";
+import {
+  Tree,
+  isPlainObject,
+  isStringLike,
+  isUnpackable,
+} from "@weborigami/async-tree";
 import { OrigamiTree } from "@weborigami/language";
 import * as YAMLModule from "yaml";
 import yamlOrigamiTag from "../misc/yamlOrigamiTag.js";
@@ -90,40 +95,76 @@ export async function toJson(obj) {
 }
 
 /**
- * Convert the given object to a corresponding JSON value that can be serialized
- * as JSON or YAML.
+ * Convert the given object to a corresponding JSON value that can be
+ * represented as JSON or YAML.
  *
- * If the object is already a JSON value, it is returned as is.
+ * @param {any} object
+ * @returns {Promise<JsonValue>}
+ */
+export async function toJsonValue(object) {
+  return toValue(object, true);
+}
+
+/**
+ * Convert the given input to the plainest possible JavaScript value. This
+ * helper is intended for functions that want to accept an argument from the ori
+ * CLI, which could a string, a file buffer, an ArrayBuffer from a URL, or some
+ * other kind of JavaScript object.
  *
- * If the object implements the `pack()` method, that method's result will be
- * returned.
+ * If the input implements the `unpack()` method, the input will be unpacked and
+ * before processing.
  *
- * If the object is treelike, it will be converted to a plain JavaScript
- * object, recursively traversing the tree and converting all values to native
- * types.
+ * If the input is treelike, it will be converted to a plain JavaScript object,
+ * recursively traversing the tree and converting all values to plain types.
  *
- * If the object has a `valueOf()` or `toString()` method, that method's result
- * will be returned.
+ * If the input is stringlike, its text will be returned.
  *
- * @param {any} object
- * @returns {Promise<JsonValue>}
+ * If the input is a Buffer or ArrayBuffer, it will be interpreted as UTF-8
+ * text.
+ *
+ * If the input has a custom class instance, its public properties will be
+ * returned as a plain object.
+ *
+ * The `jsonValuesOnly` parameter can be set to `true` to ensure that the
+ * returned value can be represented as JSON. If the input can't be represented
+ * as JSON, an error is thrown.
+ *
+ * @param {any} input
+ * @param {boolean} [jsonValuesOnly]
+ * @returns {Promise<any>}
  */
-export async function toJsonValue(object) {
-  if (isJsonValue(object)) {
-    return object;
-  } else if (object && typeof object.pack === "function") {
-    return object.pack();
-  } else if (isStringLike(object) && !(object instanceof Array)) {
-    return String(object);
-  } else if (Tree.isTreelike(object)) {
-    const mapped = await Tree.map(object, (value) => toJsonValue(value));
+export async function toValue(input, jsonValuesOnly = false) {
+  if (input instanceof Promise) {
+    // Resolve promise before processing.
+    return toValue(await input, jsonValuesOnly);
+  } else if (isJsonValue(input)) {
+    return input;
+  } else if (typeof input !== "object") {
+    if (jsonValuesOnly) {
+      throw new TypeError(`Couldn't serialize value to JSON: ${input}`);
+    } else {
+      return input;
+    }
+  } else if (isUnpackable(input)) {
+    // Unpack first, then convert to JSON value.
+    const unpacked = await input.unpack();
+    return toValue(unpacked);
+  } else if (isStringLike(input) && !(input instanceof Array)) {
+    return String(input);
+  } else if (Tree.isTreelike(input)) {
+    const mapped = await Tree.map(input, (value) => toValue(value));
     return Tree.plain(mapped);
-  } else if (object instanceof ArrayBuffer || object instanceof TypedArray) {
-    // Serialize data as UTF-8.
-    return textDecoder.decode(object);
+  } else if (input instanceof ArrayBuffer || input instanceof TypedArray) {
+    // Interpret input as UTF-8 text.
+    return textDecoder.decode(input);
+  } else {
+    // Some other kind of class instance; return its public properties.
+    const plain = {};
+    for (const [key, value] of Object.entries(input)) {
+      plain[key] = await toValue(value);
+    }
+    return plain;
   }
-
-  throw new TypeError("Couldn't serialize object");
 }
 
 /**

package/src/common/utilities.js

@@ -1,4 +1,9 @@
-import { Tree, isPlainObject, isStringLike } from "@weborigami/async-tree";
+import {
+  Tree,
+  isPlainObject,
+  isStringLike,
+  isUnpackable,
+} from "@weborigami/async-tree";
 
 const textDecoder = new TextDecoder();
 const TypedArray = Object.getPrototypeOf(Uint8Array);
@@ -57,16 +62,13 @@ export function toFunction(obj) {
   if (typeof obj === "function") {
     // Return a function as is.
     return obj;
-  } else if (
-    typeof obj === "object" &&
-    typeof (/** @type {any} */ (obj)?.unpack) === "function"
-  ) {
+  } else if (isUnpackable(obj)) {
     // Extract the contents of the object and convert that to a function.
     let fn;
     /** @this {any} */
     return async function (...args) {
       if (!fn) {
-        const content = await /** @type {any} */ (obj).unpack();
+        const content = await obj.unpack();
         fn = toFunction(content);
       }
       return fn.call(this, ...args);
@@ -100,7 +102,7 @@ export function toString(object) {
   if (isPlainObject(object) && "@text" in object) {
     return object["@text"];
   } else if (object instanceof ArrayBuffer || object instanceof TypedArray) {
-    // Serialize data as UTF-8.
+    // Treat the buffer as UTF-8 text.
     const decoded = textDecoder.decode(object);
     // If the result has non-printable characters, it's probably not a string.
     return hasNonPrintableCharacters(decoded) ? null : decoded;

package/src/misc/getTreeArgument.js

@@ -1,5 +1,6 @@
-import { Tree } from "@weborigami/async-tree";
+import { Tree, isUnpackable } from "@weborigami/async-tree";
 import { isTreelike } from "@weborigami/async-tree/src/Tree.js";
+import { Scope } from "@weborigami/language";
 import assertScopeIsDefined from "./assertScopeIsDefined.js";
 
 /**
@@ -29,8 +30,17 @@ export default async function getTreeArgument(
   assertScopeIsDefined(scope);
 
   if (treelike !== undefined) {
+    if (isUnpackable(treelike)) {
+      treelike = await treelike.unpack();
+    }
     if (isTreelike(treelike)) {
-      return Tree.from(treelike);
+      let tree = Tree.from(treelike);
+      // If the tree was created from a treelike object and does not yet have a
+      // parent or scope, put it in the current scope.
+      if (!tree.parent && !(/** @type {any} */ (tree).scope)) {
+        tree = Scope.treeWithScope(tree, scope);
+      }
+      return tree;
     }
     throw new Error(
       `${methodName}: The first argument must be a tree, like an array, object, or files.`

package/src/server/constructResponse.js

@@ -1,6 +1,7 @@
 import {
   SiteTree,
   Tree,
+  isPacked,
   isPlainObject,
   isStringLike,
 } from "@weborigami/async-tree";
@@ -30,8 +31,16 @@ export default async function constructResponse(request, resource) {
 
   // 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;
+
+  let mediaType;
+  if (resource.mediaType) {
+    // Resource indicates its own media type.
+    mediaType = resource.mediaType;
+  } else {
+    // Infer expected media type from file extension on request URL.
+    const extension = extname(url.pathname).toLowerCase();
+    mediaType = extension ? mediaTypeForExtension[extension] : undefined;
+  }
 
   if (
     mediaType === undefined &&
@@ -50,12 +59,16 @@ export default async function constructResponse(request, resource) {
     });
   }
 
-  // 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 (!isPacked(resource) && typeof resource.pack === "function") {
+    resource = await resource.pack();
+  }
+
   if (
     (mediaType === "application/json" || mediaType === "text/yaml") &&
     !isStringLike(resource)
   ) {
+    // 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.
     const tree = Tree.from(resource);
     resource =
       mediaType === "text/yaml"
@@ -92,7 +105,7 @@ export default async function constructResponse(request, resource) {
 
   // 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;
+  const validResponse = isPacked(body);
   if (!validResponse) {
     const typeName = body?.constructor?.name ?? typeof body;
     console.error(

package/src/server/server.js

@@ -1,4 +1,4 @@
-import { ObjectTree, Tree, keysFromPath } from "@weborigami/async-tree";
+import { DeepObjectTree, Tree, keysFromPath } from "@weborigami/async-tree";
 import { Scope, formatError } from "@weborigami/language";
 import { ServerResponse } from "node:http";
 import constructResponse from "./constructResponse.js";
@@ -50,15 +50,16 @@ function extendTreeScopeWithParams(tree, url) {
     return tree;
   }
 
-  const paramTree = new ObjectTree({
+  const paramTree = new DeepObjectTree({
     "@params": params,
   });
 
   // Create a new scope that includes search parameter tree.
-  const newScope = new Scope(paramTree, tree.parent);
+  const scope = Scope.getScope(tree);
+  const extendedScope = new Scope(paramTree, scope);
 
   // Create a new tree that extends the prototype chain of the supplied tree.
-  const extendedTree = Scope.treeWithScope(tree, newScope);
+  const extendedTree = Scope.treeWithScope(tree, extendedScope);
 
   return extendedTree;
 }

package/src/builtins/@loaders/css.js

@@ -1,2 +0,0 @@
-// .css files use the .txt loader
-export { default } from "./txt.js";