@weborigami/origami 0.0.49 → 0.0.51

package/src/builtins/@image/formatFn.js

@@ -0,0 +1,15 @@
+import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that transforms an input image to a different format.
+ *
+ * @this {import("@weborigami/types").AsyncTree|null}
+ * @param {keyof import("sharp").FormatEnum|import("sharp").AvailableFormatInfo}
+ * format
+ * @param {any} options
+ */
+export default function imageFormatFn(format, options) {
+  assertScopeIsDefined(this, "image/formatFn");
+  return (buffer) => sharp(buffer).toFormat(format, options).toBuffer();
+}

package/src/builtins/@image/resize.js

@@ -1,35 +1,14 @@
-import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import imageResizeFn from "./resizeFn.js";
 
 /**
  * Resize an image.
  *
  * @this {import("@weborigami/types").AsyncTree|null}
- *
- * @typedef {import("sharp").ResizeOptions} ResizeOptions
- *
- * @overload
- * @param {ResizeOptions} param1
- * @returns {(buffer: Buffer) => Promise<Buffer>}
- *
- * @overload
- * @param {Buffer} param1
- * @param {ResizeOptions} param2
- * @returns {Promise<Buffer>}
+ * @param {Buffer} buffer
+ * @param {import("sharp").ResizeOptions} options
  */
-export default function resize(param1, param2) {
-  // Identify which overload was used.
-  let buffer;
-  let options;
-  if (param2 === undefined) {
-    options = param1;
-  } else {
-    buffer = param1;
-    options = param2;
-  }
-
-  // Include `rotate()` to auto-rotate according to EXIF data.
-  const transform = (buffer) =>
-    sharp(buffer).rotate().resize(options).toBuffer();
-
-  return buffer ? transform(buffer) : transform;
+export default async function resize(buffer, options) {
+  assertScopeIsDefined(this, "image/resize");
+  return imageResizeFn.call(this, options)(buffer);
 }

package/src/builtins/@image/resizeFn.js

@@ -0,0 +1,14 @@
+import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that resizes an image.
+ *
+ * @this {import("@weborigami/types").AsyncTree|null}
+ * @param {import("sharp").ResizeOptions} options
+ */
+export default function imageResizeFn(options) {
+  assertScopeIsDefined(this, "image/resizeFn");
+  // Include `rotate()` to auto-rotate according to EXIF data.
+  return (buffer) => sharp(buffer).rotate().resize(options).toBuffer();
+}

package/src/builtins/@invoke.js

@@ -3,7 +3,7 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
 import builtins from "./@builtins.js";
 
 /**
- * Invoke the given function.
+ * Invoke the given text as an Origami function.
  *
  * This built-in exists to facilitate executing an Origami file as a script via
  * a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) directive.

package/src/builtins/@json.js

@@ -1,4 +1,5 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import { isUnpackable } from "@weborigami/async-tree";
 import * as serialize from "../common/serialize.js";
 import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
 
@@ -20,9 +21,12 @@ export default async function json(obj) {
   if (obj === undefined) {
     return undefined;
   }
+  if (isUnpackable(obj)) {
+    obj = await obj.unpack();
+  }
   const value = await serialize.toJsonValue(obj);
   return JSON.stringify(value, null, 2);
 }
 
 json.usage = "@json <obj>\tRender the object as text in JSON format";
-json.documentation = "https://weborigami.org/language/@json.html";
+json.documentation = "https://weborigami.org/builtins/@json.html";

package/src/builtins/@jsonParse.js

@@ -0,0 +1,9 @@
+import { toString } from "../common/utilities.js";
+
+export default async function jsonParse(input) {
+  const text = toString(input);
+  return text ? JSON.parse(text) : undefined;
+}
+
+jsonParse.usage = `@jsonParse <text>\tParse text as JSON`;
+jsonParse.documentation = "https://weborigami.org/builtins/@jsonParse.html";

package/src/builtins/{@count.js → @length.js}

@@ -8,11 +8,8 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @this {AsyncTree|null}
  * @param {Treelike} [treelike]
  */
-export default async function count(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@count");
+export default async function length(treelike) {
+  const tree = await getTreeArgument(this, arguments, treelike, "@length");
   const keys = Array.from(await tree.keys());
   return keys.length;
 }
-
-count.usage = `@count <treelike>\tReturn the number of keys in the tree`;
-count.documentation = "https://weborigami.org/cli/@tree.html#count";

package/src/builtins/@map.js

@@ -1,190 +1,19 @@
-import {
-  cachedKeyFunctions,
-  isPlainObject,
-  keyFunctionsForExtensions,
-  map,
-} from "@weborigami/async-tree";
-import { Scope } from "@weborigami/language";
-import addValueKeyToScope from "../common/addValueKeyToScope.js";
-import { toFunction } from "../common/utilities.js";
 import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import mapFn from "./@mapFn.js";
 
 /**
  * Map a hierarchical tree of keys and values to a new tree of keys and values.
  *
- * @typedef {import("@weborigami/async-tree").KeyFn} KeyFn
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  * @typedef {import("@weborigami/async-tree").ValueKeyFn} ValueKeyFn
- * @typedef {import("@weborigami/async-tree").TreeTransform} TreeTransform
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- *
- * @typedef {{ deep?: boolean, description?: string, extension?: string,
- * extensions?: string, inverseKey?: KeyFn, key?: ValueKeyFn, keyMap?:
- * ValueKeyFn, needsSourceValue?: boolean, value?: ValueKeyFn, valueMap?:
- * ValueKeyFn }} MapOptionsDictionary
- *
- * @typedef {ValueKeyFn|MapOptionsDictionary} OptionsOrValueFn
- *
- * @overload
- * @param {Treelike} source
- * @param {OptionsOrValueFn} instructions
- * @returns {AsyncTree}
- *
- * @overload
- * @param {OptionsOrValueFn} instructions
- * @returns {TreeTransform}
+ * @typedef {import("./map.d.ts").TreeMapOptions} TreeMapOptions
  *
  * @this {AsyncTree|null}
- * @param {Treelike|OptionsOrValueFn} param1
- * @param {OptionsOrValueFn} [param2]
+ * @param {Treelike} source
+ * @param {ValueKeyFn|TreeMapOptions} operation
  */
-export default function treeMap(param1, param2) {
+export default function map(source, operation) {
   assertScopeIsDefined(this, "map");
-
-  // Identify whether the map instructions are in the first parameter or the
-  // second. If present, identify the function to apply to values.
-
-  /** @type {Treelike|undefined} */
-  let source;
-  /** @type {OptionsOrValueFn} */
-  let instructions;
-  /** @type {ValueKeyFn|undefined} */
-  let valueFn;
-
-  if (arguments.length === 0) {
-    throw new TypeError(
-      `@map: You must give @map a function or a dictionary of options.`
-    );
-  } else if (!param1) {
-    throw new TypeError(`@map: The first argument was undefined.`);
-  } else if (arguments.length === 1) {
-    // One argument
-    // @ts-ignore
-    instructions = param1;
-  } else if (param2 === undefined) {
-    throw new TypeError(`@map: The second argument was undefined.`);
-  } else {
-    // Two arguments
-    source = param1;
-    instructions = param2;
-  }
-
-  // Identify whether the map instructions take the form of a value function or
-  // a dictionary of options.
-  /** @type {MapOptionsDictionary} */
-  let options;
-  if (isPlainObject(instructions)) {
-    // @ts-ignore
-    options = instructions;
-    valueFn = options?.value ?? options?.valueMap;
-  } else if (
-    typeof instructions === "function" ||
-    typeof (/** @type {any} */ (instructions)?.unpack) === "function"
-  ) {
-    valueFn = instructions;
-    options = {};
-  } else {
-    throw new TypeError(
-      `@map: You must specify a value function or options dictionary.`
-    );
-  }
-
-  let { deep, description, inverseKey, needsSourceValue } = options;
-  let extension = options.extension ?? options.extensions;
-  let keyFn = options.keyMap ?? options.key;
-
-  description ??= `@map ${extension ?? ""}`;
-
-  if (extension && (keyFn || inverseKey)) {
-    throw new TypeError(
-      `@map: You can't specify extensions and also a key or inverseKey function`
-    );
-  }
-
-  const baseScope = Scope.getScope(this);
-
-  // Extend the value function to include the value and key in scope.
-  let extendedValueFn;
-  if (valueFn) {
-    const resolvedValueFn = toFunction(valueFn);
-    extendedValueFn = function (sourceValue, sourceKey, tree) {
-      const scope = addValueKeyToScope(baseScope, sourceValue, sourceKey);
-      return resolvedValueFn.call(scope, sourceValue, sourceKey, tree);
-    };
-  }
-
-  // Extend the key function to include the value and key in scope.
-  let extendedKeyFn;
-  let extendedInverseKeyFn;
-  if (extension) {
-    let { resultExtension, sourceExtension } = parseExtensions(extension);
-    const keyFns = keyFunctionsForExtensions({
-      resultExtension,
-      sourceExtension,
-    });
-    extendedKeyFn = keyFns.key;
-    extendedInverseKeyFn = keyFns.inverseKey;
-  } else if (keyFn) {
-    const resolvedKeyFn = toFunction(keyFn);
-    async function scopedKeyFn(sourceKey, tree) {
-      const sourceValue = await tree.get(sourceKey);
-      const scope = addValueKeyToScope(baseScope, sourceValue, sourceKey);
-      const resultKey = await resolvedKeyFn.call(
-        scope,
-        sourceValue,
-        sourceKey,
-        tree
-      );
-      return resultKey;
-    }
-    const keyFns = cachedKeyFunctions(scopedKeyFn);
-    extendedKeyFn = keyFns.key;
-    extendedInverseKeyFn = keyFns.inverseKey;
-  } else {
-    // Use sidecar keyFn/inverseKey functions if the valueFn defines them.
-    extendedKeyFn = /** @type {any} */ (valueFn)?.key;
-    extendedInverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
-  }
-
-  const transform = function mapTreelike(treelike) {
-    return map({
-      deep,
-      description,
-      inverseKey: extendedInverseKeyFn,
-      key: extendedKeyFn,
-      needsSourceValue,
-      value: extendedValueFn,
-    })(treelike);
-  };
-
-  return source ? transform(source) : transform;
-}
-
-/**
- * Given a string specifying an extension or a mapping of one extension to another,
- * return the source and result extensions.
- *
- * Syntax:
- *   foo
- *   foo→bar      Unicode Rightwards Arrow
- *   foo->bar     hyphen and greater-than sign
- *
- * @param {string} specifier
- */
-function parseExtensions(specifier) {
-  const lowercase = specifier?.toLowerCase() ?? "";
-  const extensionRegex =
-    /^\.?(?<sourceExtension>\S*)(?:\s*(→|->)\s*)\.?(?<extension>\S+)$/;
-  let resultExtension;
-  let sourceExtension;
-  const match = lowercase.match(extensionRegex);
-  if (match?.groups) {
-    // foo→bar
-    ({ extension: resultExtension, sourceExtension } = match.groups);
-  } else {
-    // foo
-    resultExtension = lowercase;
-    sourceExtension = lowercase;
-  }
-  return { resultExtension, sourceExtension };
+  return mapFn.call(this, operation)(source);
 }

package/src/builtins/@mapFn.js

@@ -0,0 +1,145 @@
+import {
+  cachedKeyFunctions,
+  isPlainObject,
+  keyFunctionsForExtensions,
+  mapFn,
+} from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { toFunction } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that transforms a tree of keys and values to a new tree of
+ * keys and values.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").ValueKeyFn} ValueKeyFn
+ * @typedef {import("./map.d.ts").TreeMapOptions} TreeMapOptions
+ *
+ * @this {AsyncTree|null}
+ * @param {ValueKeyFn|TreeMapOptions} operation
+ */
+export default function mapFnBuiltin(operation) {
+  assertScopeIsDefined(this, "map");
+  const scope = this;
+
+  // Identify whether the map instructions take the form of a value function or
+  // a dictionary of options.
+  /** @type {TreeMapOptions} */
+  let options;
+  /** @type {ValueKeyFn|undefined} */
+  let valueFn;
+  if (isPlainObject(operation)) {
+    // @ts-ignore
+    options = operation;
+    if (`value` in options && !options.value) {
+      throw new TypeError(`@mapFn: The value function is not defined.`);
+    }
+    valueFn = options?.value;
+  } else if (
+    typeof operation === "function" ||
+    typeof (/** @type {any} */ (operation)?.unpack) === "function"
+  ) {
+    valueFn = operation;
+    options = {};
+  } else {
+    throw new TypeError(
+      `@mapFn: You must specify a value function or options dictionary as the first parameter.`
+    );
+  }
+
+  const { deep, extension, needsSourceValue } = options;
+  const description = options.description ?? `@mapFn ${extension ?? ""}`;
+  const keyFn = options.key;
+  const inverseKeyFn = options.inverseKey;
+
+  if (extension && (keyFn || inverseKeyFn)) {
+    throw new TypeError(
+      `@mapFn: You can't specify extensions and also a key or inverseKey function`
+    );
+  }
+
+  let extendedValueFn;
+  if (valueFn) {
+    const resolvedValueFn = toFunction(valueFn);
+    // Have the value function run in this scope.
+    extendedValueFn = resolvedValueFn.bind(scope);
+  }
+
+  // Extend the value function to run in scope.
+  let extendedKeyFn;
+  let extendedInverseKeyFn;
+  if (extension) {
+    let { resultExtension, sourceExtension } = parseExtensions(extension);
+    const keyFns = keyFunctionsForExtensions({
+      resultExtension,
+      sourceExtension,
+    });
+    extendedKeyFn = keyFns.key;
+    extendedInverseKeyFn = keyFns.inverseKey;
+  } else if (keyFn) {
+    const resolvedKeyFn = toFunction(keyFn);
+    async function scopedKeyFn(sourceKey, tree) {
+      const sourceValue = await tree.get(sourceKey);
+      const resultKey = await resolvedKeyFn.call(
+        scope,
+        sourceValue,
+        sourceKey,
+        tree
+      );
+      return resultKey;
+    }
+    const keyFns = cachedKeyFunctions(scopedKeyFn);
+    extendedKeyFn = keyFns.key;
+    extendedInverseKeyFn = keyFns.inverseKey;
+  } else {
+    // Use sidecar keyFn/inverseKey functions if the valueFn defines them.
+    extendedKeyFn = /** @type {any} */ (valueFn)?.key;
+    extendedInverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
+  }
+
+  const fn = mapFn({
+    deep,
+    description,
+    inverseKey: extendedInverseKeyFn,
+    key: extendedKeyFn,
+    needsSourceValue,
+    value: extendedValueFn,
+  });
+
+  return (treelike) => {
+    const mapped = fn(treelike);
+    const scoped = Scope.treeWithScope(mapped, scope);
+    return scoped;
+  };
+}
+
+/**
+ * Given a string specifying an extension or a mapping of one extension to another,
+ * return the source and result extensions.
+ *
+ * Syntax:
+ *   foo
+ *   foo→bar      Unicode Rightwards Arrow
+ *   foo->bar     hyphen and greater-than sign
+ *
+ * @param {string} specifier
+ */
+function parseExtensions(specifier) {
+  const lowercase = specifier?.toLowerCase() ?? "";
+  const extensionRegex =
+    /^\.?(?<sourceExtension>\S*)(?:\s*(→|->)\s*)\.?(?<extension>\S+)$/;
+  let resultExtension;
+  let sourceExtension;
+  const match = lowercase.match(extensionRegex);
+  if (match?.groups) {
+    // foo→bar
+    ({ extension: resultExtension, sourceExtension } = match.groups);
+  } else {
+    // foo
+    resultExtension = lowercase;
+    sourceExtension = lowercase;
+  }
+  return { resultExtension, sourceExtension };
+}

package/src/builtins/@mdHtml.js

@@ -26,6 +26,8 @@ marked.use(
 );
 
 /**
+ * Transform markdown to HTML.
+ *
  * @typedef {import("@weborigami/async-tree").StringLike} StringLike
  * @typedef {import("@weborigami/async-tree").Unpackable<StringLike>} UnpackableStringlike
  *

package/src/builtins/@mdTree.js

@@ -0,0 +1,69 @@
+import { toString } from "../common/utilities.js";
+
+/**
+ * Returns the tree structure of a markdown document.
+ *
+ * @typedef {import("@weborigami/async-tree").StringLike} StringLike
+ * @typedef {import("@weborigami/async-tree").Unpackable<StringLike>}
+ * UnpackableStringlike
+ *
+ * @this {import("@weborigami/types").AsyncTree|null|void}
+ * @param {StringLike|UnpackableStringlike} input
+ */
+export default function mdStructure(input) {
+  const markdown = toString(input);
+  if (markdown === null) {
+    throw new Error("No markdown text provided.");
+  }
+
+  // The document acts as an entry for heading level zero. All level one
+  // headings will end up as its children.
+  const document = {};
+  const activeHeadings = [document];
+
+  // Split the text by lines that contain markdown headings.
+  const lines = markdown.split("\n");
+  lines.forEach((line) => {
+    const match = line.match(/^(?<levelMarkers>#{1,6})\s(?<heading>.*)$/);
+    if (!match?.groups) {
+      return;
+    }
+    const { levelMarkers, heading } = match.groups;
+    const level = levelMarkers.length;
+
+    // If we've gone up a level (or more), pop completed entries off the stack.
+    while (activeHeadings.length > level) {
+      activeHeadings.pop();
+    }
+
+    // If we've skipped a level (or more), add intermediate entries using
+    // symbols to avoid name collisions.
+    while (activeHeadings.length < level) {
+      const entry = {};
+      const parentEntry = activeHeadings[activeHeadings.length - 1];
+      parentEntry[Symbol()] = entry;
+      activeHeadings.push(entry);
+    }
+
+    // Add a new entry to the list of children under construction.
+    const entry = {};
+    const parentEntry = activeHeadings[activeHeadings.length - 1];
+    parentEntry[heading] = entry;
+    activeHeadings.push(entry);
+  });
+
+  return pruneEmptyObjects(document) ?? {};
+}
+
+// Replace empty objects in the tree with nulls.
+function pruneEmptyObjects(tree) {
+  const keys = [...Object.keys(tree), ...Object.getOwnPropertySymbols(tree)];
+  if (keys.length === 0) {
+    return null;
+  }
+  const result = {};
+  for (const key of keys) {
+    result[key] = pruneEmptyObjects(tree[key]);
+  }
+  return result;
+}

package/src/builtins/@merge.js

@@ -33,7 +33,7 @@ export default async function treeMerge(...trees) {
 
   // If all trees are plain objects, return a plain object.
   if (unpacked.every((tree) => isPlainObject(tree))) {
-    return Object.assign({}, ...unpacked);
+    return mergeObjects(...unpacked);
   }
 
   // If a tree can take a scope, give it one that includes the other trees and
@@ -55,5 +55,25 @@ export default async function treeMerge(...trees) {
   return result;
 }
 
+/**
+ * Merge the indicated plain objects. If a key is present in multiple objects,
+ * the value from the first object is used.
+ *
+ * This is similar to calling Object.assign() with the objects in reverse order,
+ * but we want to ensure the keys end up in the same order they're encountered
+ * in the objects.
+ *
+ * @param  {...any} objects
+ */
+function mergeObjects(...objects) {
+  const result = {};
+  for (const obj of objects) {
+    for (const key of Object.keys(obj)) {
+      result[key] ??= obj[key];
+    }
+  }
+  return result;
+}
+
 treeMerge.usage = `@merge <...trees>\tMerge the given trees`;
 treeMerge.documentation = "https://weborigami.org/cli/builtins.html#@merge";

package/src/builtins/@naturalOrder.js

@@ -0,0 +1 @@
+export { naturalOrder as default } from "@weborigami/async-tree";

package/src/builtins/@paginate.js

@@ -0,0 +1,18 @@
+import getTreeArgument from "../misc/getTreeArgument.js";
+import paginateFn from "./@paginateFn.js";
+
+/**
+ * Return a new grouping of the treelike's values into chunks of the specified
+ * size.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ * @param {number} [size=10]
+ */
+export default async function paginate(treelike, size = 10) {
+  const tree = await getTreeArgument(this, arguments, treelike, "@count");
+  return paginateFn.call(this, size)(tree);
+}

package/src/builtins/@paginateFn.js

@@ -0,0 +1,61 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+
+/**
+ * Return a new grouping of the treelike's values into "pages" of the specified
+ * size.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {number} [size=10]
+ */
+export default function paginateFn(size = 10) {
+  const scope = this;
+  /**
+   * @param {Treelike} [treelike]
+   */
+  return async function (treelike) {
+    const tree = Tree.from(treelike);
+    const keys = Array.from(await tree.keys());
+    const pageCount = Math.ceil(keys.length / size);
+
+    const result = {
+      async get(pageKey) {
+        // Note: page numbers are 1-based.
+        const pageNumber = Number(pageKey);
+        if (Number.isNaN(pageNumber)) {
+          return undefined;
+        }
+        const nextPage = pageNumber + 1 <= pageCount ? pageNumber + 1 : null;
+        const previousPage = pageNumber - 1 >= 1 ? pageNumber - 1 : null;
+        const items = {};
+        for (
+          let index = (pageNumber - 1) * size;
+          index < Math.min(keys.length, pageNumber * size);
+          index++
+        ) {
+          const key = keys[index];
+          items[key] = await tree.get(keys[index]);
+        }
+
+        return {
+          items,
+          nextPage,
+          pageCount,
+          pageNumber,
+          previousPage,
+        };
+      },
+
+      async keys() {
+        // Return an array from 1..totalPages
+        return Array.from({ length: pageCount }, (_, index) => index + 1);
+      },
+    };
+
+    const scoped = Scope.treeWithScope(result, scope);
+    return scoped;
+  };
+}