@weborigami/origami 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -13,22 +13,22 @@
   "main": "./main.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "22.7.4",
-    "typescript": "5.6.2"
+    "@types/node": "22.10.2",
+    "typescript": "5.7.2"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.2.2",
-    "@weborigami/language": "0.2.2",
-    "@weborigami/types": "0.2.2",
+    "@weborigami/async-tree": "0.2.3",
+    "@weborigami/language": "0.2.3",
+    "@weborigami/types": "0.2.3",
     "exif-parser": "0.1.12",
     "graphviz-wasm": "3.0.2",
-    "highlight.js": "11.10.0",
-    "marked": "14.1.2",
-    "marked-gfm-heading-id": "4.1.0",
-    "marked-highlight": "2.1.4",
-    "marked-smartypants": "1.1.8",
+    "highlight.js": "11.11.0",
+    "marked": "15.0.4",
+    "marked-gfm-heading-id": "4.1.1",
+    "marked-highlight": "2.2.1",
+    "marked-smartypants": "1.1.9",
     "sharp": "0.33.5",
-    "yaml": "2.5.1"
+    "yaml": "2.6.1"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/common/processUnpackedContent.js

@@ -16,9 +16,8 @@ export default function processUnpackedContent(content, parent) {
     // Bind the function to the parent as the `this` context.
     const target = parent ?? builtinsTree;
     const result = content.bind(target);
-    if (content.code) {
-      result.code = content.code;
-    }
+    // Copy over any properties that were attached to the function
+    Object.assign(result, content);
     return result;
   } else if (Tree.isAsyncTree(content) && !content.parent) {
     const result = Object.create(content);

package/src/common/serialize.d.ts

@@ -2,6 +2,6 @@ import type { AsyncTree } from "@weborigami/types";
 import type { JsonValue } from "../../index.ts";
 
 export function evaluateYaml(text: string, parent?: AsyncTree|null): Promise<JsonValue>;
-export function parseYaml(text: string): JsonValue|AsyncTree;
+export function parseYaml(text: string): JsonValue;
 export function toJson(obj: JsonValue | AsyncTree): Promise<string>;
 export function toYaml(obj: JsonValue | AsyncTree): Promise<string>;

package/src/common/serialize.js

@@ -30,7 +30,7 @@ export async function evaluateYaml(text, parent) {
 
 /**
  * @param {string} text
- * @returns {JsonValue|AsyncTree}
+ * @returns {JsonValue}
  */
 export function parseYaml(text) {
   return YAML.parse(text);

package/src/handlers/oridocument.handler.js

@@ -1,7 +1,14 @@
-import { symbols } from "@weborigami/async-tree";
+import {
+  extension,
+  ObjectTree,
+  symbols,
+  trailingSlash,
+} from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
-import * as utilities from "../common/utilities.js";
+import { parseYaml } from "../common/serialize.js";
+import { toString } from "../common/utilities.js";
 import { processUnpackedContent } from "../internal.js";
+import parseFrontMatter from "./parseFrontMatter.js";
 
 /**
  * An Origami template document: a plain text file that contains Origami
@@ -15,29 +22,107 @@ export default {
     const parent =
       options.parent ??
       /** @type {any} */ (packed).parent ??
-      /** @type {any} */ (packed)[symbols.parent];
+      /** @type {any} */ (packed)[symbols.parent] ??
+      null;
 
-    // Construct an object to represent the source code.
-    const sourceName = options.key;
+    // Unpack as a text document
+    const unpacked = toString(packed);
+
+    // See if we can construct a URL to use in error messages
+    const key = options.key;
     let url;
-    if (sourceName && parent?.url) {
+    if (key && parent?.url) {
       let parentHref = parent.url.href;
       if (!parentHref.endsWith("/")) {
         parentHref += "/";
       }
-      url = new URL(sourceName, parentHref);
+      url = new URL(key, parentHref);
+    }
+
+    // Determine the data (if present) and text content
+    let text;
+    let frontData = null;
+    let frontSource = null;
+    let extendedParent = parent;
+    const parsed = parseFrontMatter(unpacked);
+    if (!parsed) {
+      text = unpacked;
+    } else {
+      const { body, frontText, isOrigami } = parsed;
+      if (isOrigami) {
+        // Origami front matter
+        frontSource = { name: key, text: frontText, url };
+      } else {
+        // YAML front matter
+        frontData = parseYaml(frontText);
+        if (typeof frontData !== "object") {
+          throw new TypeError(`YAML or JSON front matter must be an object`);
+        }
+        extendedParent = new ObjectTree(frontData);
+        extendedParent.parent = parent;
+      }
+      text = body;
     }
 
-    const source = {
-      text: utilities.toString(packed),
-      name: options.key,
-      url,
-    };
+    // Construct an object to represent the source code
+    const bodySource = { name: key, text, url };
 
-    // Compile the text as an Origami template document.
-    const templateDefineFn = compile.templateDocument(source);
-    const templateFn = await templateDefineFn.call(parent);
+    // Compile the source as an Origami template document
+    const scopeCaching = frontSource ? false : true;
+    const defineTemplateFn = compile.templateDocument(bodySource, {
+      scopeCaching,
+    });
 
-    return processUnpackedContent(templateFn, parent);
+    // Determine the result of the template
+    let result;
+    if (frontSource) {
+      // Result is the evaluated front source
+      const frontFn = compile.expression(frontSource, {
+        macros: {
+          "@template": defineTemplateFn.code,
+        },
+      });
+      result = await frontFn.call(parent);
+    } else {
+      const templateFn = await defineTemplateFn.call(extendedParent);
+      if (frontData) {
+        // Result is a function that adds the front data to the template result
+        result = async (input) => {
+          const text = await templateFn.call(extendedParent, input);
+          const object = {
+            ...frontData,
+            "@text": text,
+          };
+          object[symbols.parent] = extendedParent;
+          return object;
+        };
+      } else {
+        // Result is a function that calls the body template
+        result = templateFn;
+      }
+    }
+
+    const resultExtension = key ? extension.extname(key) : null;
+    if (resultExtension && Object.isExtensible(result)) {
+      // Add sidecar function so this template can be used in a map.
+      result.key = addExtension(resultExtension);
+    }
+
+    return processUnpackedContent(result, parent);
   },
 };
+
+// Return a function that adds the given extension
+function addExtension(resultExtension) {
+  return (sourceKey) => {
+    if (sourceKey === undefined) {
+      return undefined;
+    }
+    const normalizedKey = trailingSlash.remove(sourceKey);
+    const sourceExtension = extension.extname(normalizedKey);
+    const resultKey = sourceExtension
+      ? extension.replace(normalizedKey, sourceExtension, resultExtension)
+      : normalizedKey + resultExtension;
+    return resultKey;
+  };
+}

package/src/handlers/parseFrontMatter.js

@@ -0,0 +1,21 @@
+export default function parseFrontMatter(text) {
+  const regex =
+    /^(---\r?\n(?<frontText>[\s\S]*?\r?\n?)---\r?\n)(?<body>[\s\S]*$)/;
+  const match = regex.exec(text);
+  if (!match?.groups) {
+    return null;
+  }
+  const isOrigami = detectOrigami(match.groups.frontText);
+  return {
+    body: match.groups.body,
+    frontText: match.groups.frontText,
+    isOrigami,
+  };
+}
+
+function detectOrigami(text) {
+  // Find first character that's not whitespace, alphanumeric, or underscore
+  const first = text.match(/[^A-Za-z0-9_ \t\n\r]/)?.[0];
+  const origamiMarkers = ["(", ".", "/", "{"];
+  return origamiMarkers.includes(first);
+}

package/src/handlers/txt.handler.js

@@ -1,6 +1,8 @@
 import { isPacked, symbols } from "@weborigami/async-tree";
+import { compile } from "@weborigami/language";
 import { parseYaml, toYaml } from "../common/serialize.js";
-import * as utilities from "../common/utilities.js";
+import { toString } from "../common/utilities.js";
+import parseFrontMatter from "./parseFrontMatter.js";
 
 /**
  * A text file with possible front matter
@@ -51,21 +53,25 @@ export default {
   },
 
   /** @type {import("@weborigami/language").UnpackFunction} */
-  unpack(packed, options = {}) {
+  async unpack(packed, options = {}) {
     const parent = options.parent ?? null;
-    const text = utilities.toString(packed);
+    const text = toString(packed);
     if (text === null) {
-      throw new Error("Tried to treat something as text but it wasn't text.");
+      throw new Error("Tried to treat a file 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);
+    const parsed = parseFrontMatter(text);
     let unpacked;
-    if (match) {
+    if (parsed) {
       // Document object with front matter
-      const { body, frontText } = /** @type {any} */ (match.groups);
-      const frontData = parseYaml(frontText);
+      const { body, frontText, isOrigami } = parsed;
+      let frontData;
+      if (isOrigami) {
+        const compiled = compile.expression(frontText.trim());
+        frontData = await compiled.call(parent);
+      } else {
+        frontData = parseYaml(frontText);
+      }
       unpacked = Object.assign({}, frontData, { "@text": body });
     } else {
       // Plain text

package/src/help/help.js

@@ -50,7 +50,7 @@ async function commandDescription(commandHelp, namespace, command) {
     "",
     formatCommandDescription(commandHelp, namespace, command),
     "",
-    `For more information: https://weborigami.org/builtins/${url}`,
+    `For more information: https://weborigami.org/builtins/${url}\n`,
   ];
   return text.join("\n");
 }
@@ -82,7 +82,7 @@ async function namespaceCommands(namespaceHelp, namespace) {
   }
 
   const url = namespaceHelp.collection ? `${namespace}.html` : `${namespace}/`;
-  text.push(`For more information: https://weborigami.org/builtins/${url}`);
+  text.push(`For more information: https://weborigami.org/builtins/${url}\n`);
   return text.join("\n");
 }
 
@@ -97,7 +97,7 @@ async function namespaceDescriptions(helpData) {
     }
   }
   text.push(
-    `\nType "ori help:<namespace>" for more or visit https://weborigami.org/builtins`
+    `\nType "ori help:<namespace>" for more or visit https://weborigami.org/builtins\n`
   );
   return text.join("\n");
 }

package/src/text/inline.js

@@ -1,9 +1,12 @@
-import { isUnpackable, symbols } from "@weborigami/async-tree";
-import { compile } from "@weborigami/language";
+import {
+  isUnpackable,
+  ObjectTree,
+  symbols,
+  toString,
+} from "@weborigami/async-tree";
 import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import documentObject from "../common/documentObject.js";
-import { toString } from "../common/utilities.js";
-import { oriHandler } from "../internal.js";
+import { oridocumentHandler } from "../internal.js";
 
 /**
  * Inline any Origami expressions found inside ${...} placeholders in the input
@@ -29,10 +32,19 @@ export default async function inline(input) {
   }
 
   const parent =
-    /** @type {any} */ (input).parent ?? input[symbols.parent] ?? this;
-  const templateFn = await oriHandler.unpack(origami, {
-    compiler: compile.templateDocument,
-    parent,
+    /** @type {any} */ (input).parent ??
+    /** @type {any} */ (input)[symbols.parent] ??
+    this;
+
+  let extendedParent = parent;
+  if (inputIsDocument) {
+    extendedParent = new ObjectTree(input);
+    extendedParent.parent = parent;
+  }
+
+  // @ts-ignore
+  const templateFn = await oridocumentHandler.unpack(input, {
+    parent: extendedParent,
   });
 
   const inputData = inputIsDocument ? input : null;

package/src/text/mdHtml.js

@@ -11,6 +11,7 @@ import origamiHighlightDefinition from "./origamiHighlightDefinition.js";
 highlight.registerLanguage("ori", origamiHighlightDefinition);
 
 marked.use(
+  // @ts-ignore
   markedGfmHeadingId(),
   markedHighlight({
     highlight(code, lang) {

package/src/text/text.js

@@ -1,4 +1,4 @@
+export { taggedTemplateIndent as indent } from "@weborigami/language";
 export { default as document } from "./document.js";
-export { default as indent } from "./indent.js";
 export { default as inline } from "./inline.js";
 export { default as mdHtml } from "./mdHtml.js";

package/src/tree/fromFn.js

@@ -1,4 +1,4 @@
-import { FunctionTree } from "@weborigami/async-tree";
+import { FunctionTree, isUnpackable } from "@weborigami/async-tree";
 import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { toFunction } from "../common/utilities.js";
 
@@ -20,6 +20,9 @@ export default async function fromFn(invocable, keys = []) {
     );
   }
   const fn = toFunction(invocable);
+  if (isUnpackable(keys)) {
+    keys = await keys.unpack();
+  }
   const tree = new FunctionTree(fn, keys);
   tree.parent = this;
   return tree;

package/src/tree/map.d.ts

@@ -1,4 +1,4 @@
-import { TreeMapOptions as AsyncTreeMapOptions, Treelike, TreeTransform, ValueKeyFn } from "@weborigami/async-tree";
+import { TreeMapOptions as AsyncTreeMapOptions, Treelike, ValueKeyFn } from "@weborigami/async-tree";
 import { AsyncTree } from "@weborigami/types";
 
 /* Add more properties to TreeMapOptions */
@@ -8,6 +8,4 @@ type TreeMapOptions = AsyncTreeMapOptions &{
   needsSourceValue?: boolean;
 };
 
-export default function treeMap(options: ValueKeyFn | TreeMapOptions): TreeTransform;
 export default function treeMap(treelike: Treelike, options: ValueKeyFn | TreeMapOptions): AsyncTree;
-export default function treeMap(param1: Treelike | ValueKeyFn | TreeMapOptions, param2?: ValueKeyFn | TreeMapOptions): AsyncTree | TreeTransform;

package/src/tree/map.js

@@ -1,6 +1,7 @@
 import {
   cachedKeyFunctions,
   isPlainObject,
+  isUnpackable,
   keyFunctionsForExtensions,
   map as mapTransform,
 } from "@weborigami/async-tree";
@@ -25,7 +26,11 @@ export default async function map(treelike, operation) {
   // The tree in which the map operation happens
   const context = this;
 
+  if (isUnpackable(operation)) {
+    operation = await operation.unpack();
+  }
   const options = extendedOptions(context, operation);
+
   const mapped = mapTransform(source, options);
   mapped.parent = context;
   return mapped;
@@ -66,8 +71,8 @@ function extendedOptions(context, operation) {
 
   const { deep, extension, needsSourceValue } = options;
   const description = options.description ?? `map ${extension ?? ""}`;
-  const keyFn = options.key;
-  const inverseKeyFn = options.inverseKey;
+  let keyFn = options.key;
+  let inverseKeyFn = options.inverseKey;
 
   if (extension && (keyFn || inverseKeyFn)) {
     throw new TypeError(
@@ -75,47 +80,60 @@ function extendedOptions(context, operation) {
     );
   }
 
-  let extendedValueFn;
   if (valueFn) {
-    const resolvedValueFn = toFunction(valueFn);
-    // Have the value function run in this tree.
-    extendedValueFn = resolvedValueFn.bind(context);
+    // @ts-ignore
+    valueFn = toFunction(valueFn);
+    // By default, run the value function in the context of this tree so that
+    // Origami builtins can be used as value functions.
+    // @ts-ignore
+    const bound = valueFn.bind(context);
+    // @ts-ignore
+    Object.assign(bound, valueFn);
+    valueFn = bound;
   }
 
-  // Extend the key functions to run in this tree.
-  let extendedKeyFn;
-  let extendedInverseKeyFn;
   if (extension) {
+    // Generate key/inverseKey functions from the extension
     let { resultExtension, sourceExtension } = parseExtensions(extension);
     const keyFns = keyFunctionsForExtensions({
       resultExtension,
       sourceExtension,
     });
-    extendedKeyFn = keyFns.key;
-    extendedInverseKeyFn = keyFns.inverseKey;
+    keyFn = keyFns.key;
+    inverseKeyFn = keyFns.inverseKey;
   } else if (keyFn) {
-    const resolvedKeyFn = toFunction(keyFn);
-    async function keyWithValueFn(sourceKey, sourceTree) {
-      const sourceValue = await sourceTree.get(sourceKey);
-      const resultKey = await resolvedKeyFn(sourceValue, sourceKey, sourceTree);
-      return resultKey;
-    }
-    const keyFns = cachedKeyFunctions(keyWithValueFn, deep);
-    extendedKeyFn = keyFns.key;
-    extendedInverseKeyFn = keyFns.inverseKey;
+    // Extend the key function to include a value parameter
+    keyFn = extendKeyFn(keyFn);
   } else {
-    // Use sidecar keyFn/inverseKey functions if the valueFn defines them.
-    extendedKeyFn = /** @type {any} */ (valueFn)?.key;
-    extendedInverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
+    // Use sidecar key/inverseKey functions if the valueFn defines them
+    keyFn = /** @type {any} */ (valueFn)?.key;
+    inverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
+  }
+
+  if (keyFn && !inverseKeyFn) {
+    // Only keyFn was provided, so we need to generate the inverseKeyFn
+    const keyFns = cachedKeyFunctions(keyFn, deep);
+    keyFn = keyFns.key;
+    inverseKeyFn = keyFns.inverseKey;
   }
 
   return {
     deep,
     description,
-    inverseKey: extendedInverseKeyFn,
-    key: extendedKeyFn,
+    inverseKey: inverseKeyFn,
+    key: keyFn,
     needsSourceValue,
-    value: extendedValueFn,
+    value: valueFn,
+  };
+}
+
+// Extend the key function to include a value parameter
+function extendKeyFn(keyFn) {
+  keyFn = toFunction(keyFn);
+  return async function keyWithValueFn(sourceKey, sourceTree) {
+    const sourceValue = await sourceTree.get(sourceKey);
+    const resultKey = await keyFn(sourceValue, sourceKey, sourceTree);
+    return resultKey;
   };
 }
 

package/src/text/indent.js

@@ -1,115 +0,0 @@
-const lastLineWhitespaceRegex = /\n(?<indent>[ \t]*)$/;
-
-const mapStringsToModifications = new Map();
-
-/**
- * Normalize indentation in a tagged template string.
- *
- * @param {TemplateStringsArray} strings
- * @param  {...any} values
- * @returns {string}
- */
-export default function indent(strings, ...values) {
-  let modified = mapStringsToModifications.get(strings);
-  if (!modified) {
-    modified = modifyStrings(strings);
-    mapStringsToModifications.set(strings, modified);
-  }
-  const { blockIndentations, strings: modifiedStrings } = modified;
-  return joinBlocks(modifiedStrings, values, blockIndentations);
-}
-
-// Join strings and values, applying the given block indentation to the lines of
-// values for block placholders.
-function joinBlocks(strings, values, blockIndentations) {
-  let result = strings[0];
-  for (let i = 0; i < values.length; i++) {
-    let text = values[i];
-    if (text) {
-      const blockIndentation = blockIndentations[i];
-      if (blockIndentation) {
-        const lines = text.split("\n");
-        text = "";
-        if (lines.at(-1) === "") {
-          // Drop empty last line
-          lines.pop();
-        }
-        for (let line of lines) {
-          text += blockIndentation + line + "\n";
-        }
-      }
-      result += text;
-    }
-    result += strings[i + 1];
-  }
-  return result;
-}
-
-// Given an array of template boilerplate strings, return an object { modified,
-// blockIndentations } where `strings` is the array of strings with indentation
-// removed, and `blockIndentations` is an array of indentation strings for each
-// block placeholder.
-function modifyStrings(strings) {
-  // Phase one: Identify the indentation based on the first real line of the
-  // first string (skipping the initial newline), and remove this indentation
-  // from all lines of all strings.
-  let indent;
-  if (strings.length > 0 && strings[0].startsWith("\n")) {
-    // Look for indenttation
-    const firstLineWhitespaceRegex = /^\n(?<indent>[ \t]*)/;
-    const match = strings[0].match(firstLineWhitespaceRegex);
-    indent = match?.groups.indent;
-  }
-
-  // Determine the modified strings. If this invoked as a JS tagged template
-  // literal, the `strings` argument will be an odd array-ish object that we'll
-  // want to convert to a real array.
-  let modified;
-  if (indent) {
-    // De-indent the strings.
-    const indentationRegex = new RegExp(`\n${indent}`, "g");
-    // The `replaceAll` also converts strings to a real array.
-    modified = strings.map((string) =>
-      string.replaceAll(indentationRegex, "\n")
-    );
-    // Remove indentation from last line of last string
-    modified[modified.length - 1] = modified
-      .at(-1)
-      .replace(lastLineWhitespaceRegex, "\n");
-  } else {
-    // No indentation; just copy the strings so we have a real array
-    modified = strings.slice();
-  }
-
-  // Phase two: Identify any block placholders, identify and remove their
-  // preceding indentation, and remove the following newline. Work backward from
-  // the end towards the start because we're modifying the strings in place and
-  // our pattern matching won't work going forward from start to end.
-  let blockIndentations = [];
-  for (let i = modified.length - 2; i >= 0; i--) {
-    // Get the modified before and after substitution with index `i`
-    const beforeString = modified[i];
-    const afterString = modified[i + 1];
-    const match = beforeString.match(lastLineWhitespaceRegex);
-    if (match && afterString.startsWith("\n")) {
-      // The substitution between these strings is a block substitution
-      let blockIndentation = match.groups.indent;
-      blockIndentations[i] = blockIndentation;
-      // Trim the before and after strings
-      if (blockIndentation) {
-        modified[i] = beforeString.slice(0, -blockIndentation.length);
-      }
-      modified[i + 1] = afterString.slice(1);
-    }
-  }
-
-  // Remove newline from start of first string *after* removing indentation.
-  if (modified[0].startsWith("\n")) {
-    modified[0] = modified[0].slice(1);
-  }
-
-  return {
-    blockIndentations,
-    strings: modified,
-  };
-}