@weborigami/origami 0.0.73 → 0.2.0

package/src/{builtins/@sitemap.js → site/sitemap.js}

@@ -1,12 +1,11 @@
 import { Tree } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
-import getTreeArgument from "../misc/getTreeArgument.js";
-import builtins from "./@builtins.js";
-import fileTypeOrigami from "./ori.handler.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
+import getTreeArgument from "../common/getTreeArgument.js";
+import { builtinsTree, oriHandler } from "../internal.js";
 
 const templateText = `(urls) => \`<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-\${ @map(urls, (url) => \`  <url>
+\${ map(urls, (url) => \`  <url>
     <loc>\${ url }</loc>
   </url>
 \`) }</urlset>
@@ -21,8 +20,8 @@ const templateText = `(urls) => \`<?xml version="1.0" encoding="UTF-8"?>
  * @param {string} [baseHref ]
  */
 export default async function sitemap(treelike, baseHref = "") {
-  assertTreeIsDefined(this, "sitemap");
-  const tree = await getTreeArgument(this, arguments, treelike, "@sitemap");
+  assertTreeIsDefined(this, "site:sitemap");
+  const tree = await getTreeArgument(this, arguments, treelike, "site:sitemap");
 
   // We're only interested in keys that end in .html or with no extension.
   function test(key) {
@@ -48,11 +47,8 @@ export default async function sitemap(treelike, baseHref = "") {
     .filter((path) => path.endsWith(".html"))
     .map((path) => (path.endsWith("index.html") ? path.slice(0, -10) : path));
 
-  const templateFn = await fileTypeOrigami.unpack(templateText);
-  const target = this ?? builtins;
+  const templateFn = await oriHandler.unpack(templateText);
+  const target = this ?? builtinsTree;
   const templateResult = await templateFn.call(target, htmlPaths);
   return String(templateResult);
 }
-
-sitemap.usage = `@sitemap <tree>\tGenerate a sitemap for a tree`;
-sitemap.documentation = "https://weborigami.org/cli/builtins.html#@sitemap";

package/src/{builtins/@static.js → site/static.js}

@@ -1,7 +1,7 @@
 import { Tree, jsonKeys } from "@weborigami/async-tree";
+import getTreeArgument from "../common/getTreeArgument.js";
 import { transformObject } from "../common/utilities.js";
-import getTreeArgument from "../misc/getTreeArgument.js";
-import index from "./@index.js";
+import index from "./index.js";
 
 /**
  * Expose common static keys (index.html, .keys.json) for a tree.
@@ -11,13 +11,16 @@ import index from "./@index.js";
  * @this {AsyncTree|null}
  * @param {Treelike} treelike
  */
-export default async function staticTree(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@static");
+export default async function staticBuiltin(treelike) {
+  const tree = await getTreeArgument(this, arguments, treelike, "site:static");
   const result = transformObject(StaticTransform, tree);
   result.parent = this;
   return result;
 }
 
+// The name we'll register as a builtin
+staticBuiltin.key = "static";
+
 function StaticTransform(Base) {
   return class Static extends Base {
     async get(key) {
@@ -41,6 +44,3 @@ function StaticTransform(Base) {
     }
   };
 }
-
-staticTree.usage = `@static <tree>\tAdd keys for generating common static files`;
-staticTree.documentation = "https://weborigami.org/cli/builtins.html#static";

package/src/{builtins/@document.js → text/document.js}

@@ -1,5 +1,5 @@
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import documentObject from "../common/documentObject.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
@@ -10,6 +10,6 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @param {any} [data]
  */
 export default async function documentBuiltin(text, data) {
-  assertTreeIsDefined(this, "document");
+  assertTreeIsDefined(this, "text:document");
   return documentObject(text, data);
 }

package/src/{builtins/@inline.js → text/inline.js}

@@ -1,9 +1,9 @@
 import { isUnpackable, symbols } from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import documentObject from "../common/documentObject.js";
 import { toString } from "../common/utilities.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
-import fileTypeOrigami from "./ori.handler.js";
+import { oriHandler } from "../internal.js";
 
 /**
  * Inline any Origami expressions found inside ${...} placeholders in the input
@@ -16,7 +16,7 @@ import fileTypeOrigami from "./ori.handler.js";
  * @param {StringLike} input
  */
 export default async function inline(input) {
-  assertTreeIsDefined(this, "inline");
+  assertTreeIsDefined(this, "text:inline");
 
   // Get the input text and any attached front matter.
   if (isUnpackable(input)) {
@@ -24,24 +24,21 @@ export default async function inline(input) {
   }
   const inputIsDocument = input["@text"] !== undefined;
   const origami = inputIsDocument ? input["@text"] : toString(input);
+  if (origami === null) {
+    return undefined;
+  }
 
   const parent =
     /** @type {any} */ (input).parent ?? input[symbols.parent] ?? this;
-
-  // If the input document is a plain object, include it in scope for the
-  // evaluated expression.
-  const inputData = inputIsDocument ? input : null;
-
-  const templateFn = await fileTypeOrigami.unpack(origami, {
-    attachedData: inputData,
+  const templateFn = await oriHandler.unpack(origami, {
     compiler: compile.templateDocument,
     parent,
   });
+
+  const inputData = inputIsDocument ? input : null;
   const templateResult = await templateFn(inputData);
+
   return inputIsDocument
     ? documentObject(templateResult, inputData)
     : templateResult;
 }
-
-inline.usage = `@inline <text>\tInline Origami expressions found in the text`;
-inline.documentation = "https://weborigami.org/language/@inline.html";

package/src/{builtins/@mdHtml.js → text/mdHtml.js}

@@ -1,12 +1,12 @@
-import { isUnpackable } from "@weborigami/async-tree";
+import { extension, isUnpackable } from "@weborigami/async-tree";
 import highlight from "highlight.js";
 import { marked } from "marked";
 import { gfmHeadingId as markedGfmHeadingId } from "marked-gfm-heading-id";
 import { markedHighlight } from "marked-highlight";
 import { markedSmartypants } from "marked-smartypants";
 import documentObject from "../common/documentObject.js";
-import { replaceExtension, toString } from "../common/utilities.js";
-import origamiHighlightDefinition from "../misc/origamiHighlightDefinition.js";
+import { toString } from "../common/utilities.js";
+import origamiHighlightDefinition from "./origamiHighlightDefinition.js";
 
 highlight.registerLanguage("ori", origamiHighlightDefinition);
 
@@ -39,7 +39,7 @@ marked.use(
  */
 export default async function mdHtml(input) {
   if (input == null) {
-    const error = new TypeError("@mdHtml: The input is not defined.");
+    const error = new TypeError("mdHtml: The input is not defined.");
     /** @type {any} */ (error).position = 0;
     throw error;
   }
@@ -49,14 +49,11 @@ export default async function mdHtml(input) {
   const inputIsDocument = input["@text"] !== undefined;
   const markdown = toString(input);
   if (markdown === null) {
-    throw new Error("@mdHtml: The provided input couldn't be treated as text.");
+    throw new Error("mdHtml: The provided input couldn't be treated as text.");
   }
   const html = marked(markdown);
   return inputIsDocument ? documentObject(html, input) : html;
 }
 
-mdHtml.key = (sourceKey) => replaceExtension(sourceKey, ".md", ".html");
-mdHtml.inverseKey = (resultKey) => replaceExtension(resultKey, ".html", ".md");
-
-mdHtml.usage = `@mdHtml <markdown>\tRender the markdown text as HTML`;
-mdHtml.documentation = "https://weborigami.org/language/@mdHtml.html";
+mdHtml.key = (sourceKey) => extension.replace(sourceKey, ".md", ".html");
+mdHtml.inverseKey = (resultKey) => extension.replace(resultKey, ".html", ".md");

package/src/text/origamiHighlightDefinition.js

@@ -0,0 +1,57 @@
+/**
+ * Origami language definition for highlight.js
+ */
+export default function origamiHighlightDefinition(hljs) {
+  return {
+    name: "Origami",
+    contains: [
+      hljs.C_LINE_COMMENT_MODE,
+      hljs.C_BLOCK_COMMENT_MODE,
+      hljs.C_NUMBER_MODE,
+      hljs.APOS_STRING_MODE,
+      hljs.QUOTE_STRING_MODE,
+      hljs.BACKSLASH_ESCAPE,
+      {
+        // Backtick template strings
+        className: "string",
+        begin: "`",
+        end: "`",
+        contains: [
+          hljs.BACKSLASH_ESCAPE,
+          {
+            className: "subst",
+            begin: "\\$\\{",
+            end: "\\}",
+            contains: [hljs.C_NUMBER_MODE, hljs.QUOTE_STRING_MODE],
+          },
+        ],
+      },
+      {
+        // Treat namespaces as keywords
+        className: "keyword",
+        begin:
+          /\b(calc|dev|explore|files|http|https|httpstree|httptree|image|inherited|js|new|node|origami|package|scope|site|text|tree):\b/,
+      },
+      {
+        // Treat identifier containing a period before an open paren or backtick as a variable
+        className: "variable",
+        begin:
+          /\b[^(){}\[\]<>\-=,/:\`"'«»\\ →⇒\t\n\r]+\.[^(){}\[\]<>\?!&\|\-=,/:\`"'«»\\ →⇒\t\n\r]+(?=(\(|\`))\b/,
+      },
+      {
+        className: "built_in",
+        // Treat shorthands before open paren or backtick as a builtin
+        begin: /\b[A-Za-z][A-Za-z0-9]*(?=(\(|\`))\b/,
+      },
+      {
+        // Treat remaining identifiers as variables
+        className: "variable",
+        begin: /\b[^(){}\[\]<>\?!&\|\-=,/:\`"'«»\\ →⇒\t\n\r]+\b/,
+      },
+      {
+        className: "operator",
+        begin: /===|!==|==|!=|=>|⇒|->|→|=|\.\.\.|…|&&|\|\||!|\?\?/,
+      },
+    ],
+  };
+}

package/src/text/text.js

@@ -0,0 +1,4 @@
+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/{builtins/@addNextPrevious.js → tree/addNextPrevious.js}

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Add nextKey/previousKey properties to values.
@@ -10,7 +10,12 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {import("@weborigami/async-tree").Treelike} treelike
  */
 export default async function addNextPrevious(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@sequence");
+  const tree = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "tree:addNextPrevious"
+  );
   let keys;
   return Object.create(tree, {
     get: {

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

@@ -1,5 +1,5 @@
 import { Tree, cache } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Caches tree values in a storable cache.
@@ -17,7 +17,7 @@ export default async function cacheBuiltin(
   cacheTreelike,
   filterTreelike
 ) {
-  assertTreeIsDefined(this, "cache");
+  assertTreeIsDefined(this, "tree:cache");
   /** @type {any} */
   const cacheTree = cacheTreelike
     ? Tree.from(cacheTreelike, { parent: this })
@@ -25,6 +25,3 @@ export default async function cacheBuiltin(
   const result = cache(sourceTreelike, cacheTree, filterTreelike);
   return result;
 }
-
-cacheBuiltin.usage = `@cache/tree tree, [cache], [filter]\tCaches tree values`;
-cacheBuiltin.documentation = "https://weborigami.org/cli/builtins.html#@cache";

package/src/{builtins/@clean.js → tree/clear.js}

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
@@ -7,10 +7,10 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @this {AsyncTree|null}
  * @param {import("@weborigami/async-tree").Treelike} treelike
  */
-export default async function clean(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@clean");
+export default async function clear(treelike) {
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:clear");
   if (!Tree.isAsyncMutableTree(tree)) {
-    throw new TypeError("@clean: the given tree is read-only.");
+    throw new TypeError("clean: the given tree is read-only.");
   }
   const keys = Array.from(await tree.keys());
   const promises = keys.map((key) => tree.set(key, undefined));

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

@@ -1,6 +1,6 @@
 import { Tree } from "@weborigami/async-tree";
 import { ops } from "@weborigami/language";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Concatenate the text content of objects or trees.
@@ -11,10 +11,7 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @param {any[]} args
  */
 export default async function concat(...args) {
-  assertTreeIsDefined(this, "concat");
+  assertTreeIsDefined(this, "tree:concat");
   const tree = args.length === 0 ? this : Tree.from(args, { parent: this });
   return ops.concat.call(this, tree);
 }
-
-concat.usage = `@concat <...objs>\tConcatenate text and/or trees of text`;
-concat.documentation = "https://weborigami.org/cli/@tree.html#concat";

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

@@ -1,9 +1,9 @@
 import { 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 assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
-import setDeep from "./@setDeep.js";
+import setDeep from "./setDeep.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
@@ -14,8 +14,7 @@ import setDeep from "./@setDeep.js";
  * @param {Treelike} target
  */
 export default async function copy(source, target) {
-  assertTreeIsDefined(this, "copy");
-  // const start = performance.now();
+  assertTreeIsDefined(this, "tree:copy");
   const sourceTree = Tree.from(source, { parent: this });
   /** @type {any} */ let targetTree = Tree.from(target, { parent: this });
 
@@ -35,9 +34,6 @@ export default async function copy(source, target) {
     countFiles = null;
     countCopied = null;
   }
-
-  // const end = performance.now();
-  // console.log(`copy time in ms: ${end - start}`);
 }
 
 let countFiles;
@@ -67,6 +63,3 @@ function ProgressTransform(Base) {
     }
   };
 }
-
-copy.usage = `@copy <source>, <target>\tCopies the source tree to the target`;
-copy.documentation = "https://weborigami.org/language/@copy.html";

package/src/{builtins/@deepMapFn.js → tree/deepMap.js}

@@ -1,9 +1,9 @@
 import { isPlainObject } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
-import mapFn from "./@mapFn.js";
+import getTreeArgument from "../common/getTreeArgument.js";
+import map from "./map.js";
 
 /**
- * Shorthand for calling `@mapFn` with `deep: true` option.
+ * Shorthand for calling `map` with `deep: true` option.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
@@ -11,15 +11,22 @@ import mapFn from "./@mapFn.js";
  * @typedef {import("./map.d.ts").TreeMapOptions} TreeMapOptions
  *
  * @this {AsyncTree|null}
+ * @param {Treelike} treelike
  * @param {ValueKeyFn|TreeMapOptions} operation
  */
-export default function deepMapFn(operation) {
-  assertTreeIsDefined(this, "deepMap");
+export default async function deepMap(treelike, operation) {
+  const tree = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "tree:deepMap",
+    true
+  );
   /** @type {TreeMapOptions} */
   const options = isPlainObject(operation)
     ? // Dictionary
       { ...operation, deep: true }
     : // Function
       { deep: true, value: operation };
-  return mapFn.call(this, options);
+  return map.call(this, tree, options);
 }

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

@@ -1,5 +1,5 @@
 import { deepMerge } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Create a tree that's the result of deep merging the given trees.
@@ -9,8 +9,9 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @this {AsyncTree|null}
  * @param {Treelike[]} trees
  */
-export default async function treedeepMerge(...trees) {
-  assertTreeIsDefined(this, "deepMerge");
+export default async function treeDeepMerge(...trees) {
+  assertTreeIsDefined(this, "tree:deepMerge");
+
   // Filter out null or undefined trees.
   const filtered = trees.filter((tree) => tree);
 
@@ -23,7 +24,3 @@ export default async function treedeepMerge(...trees) {
   const result = deepMerge(...filtered);
   return result;
 }
-
-treedeepMerge.usage = `@deepMerge <...trees>\tMerge the given trees deeply`;
-treedeepMerge.documentation =
-  "https://weborigami.org/cli/builtins.html#deepMerge";

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

@@ -1,5 +1,5 @@
 import { deepReverse } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Reverse the order of keys at all levels of the tree.
@@ -11,7 +11,13 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function deepReverseBuiltin(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@deepReverse");
+  const tree = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "tree:deepReverse",
+    true
+  );
   const reversed = deepReverse(tree);
   return reversed;
 }

package/src/tree/deepTake.js

@@ -0,0 +1,26 @@
+import { deepTake as deepTakeTransform } from "@weborigami/async-tree";
+import getTreeArgument from "../common/getTreeArgument.js";
+
+/**
+ * Returns a function that traverses a tree deeply and returns the values of the
+ * first `count` keys.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {number} count
+ */
+export default async function deepTake(treelike, count) {
+  const tree = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "tree:deepTake",
+    true
+  );
+  const taken = await deepTakeTransform(tree, count);
+  taken.parent = this;
+  return taken;
+}

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

@@ -1,5 +1,5 @@
 import { deepValues } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Return the in-order exterior values of a tree as a flat array.
@@ -15,12 +15,8 @@ export default async function deepValuesBuiltin(treelike) {
     this,
     arguments,
     treelike,
-    "@valuesDeep",
+    "tree:deepValues",
     true
   );
   return deepValues(tree);
 }
-
-deepValuesBuiltin.usage = `@valuesDeep <tree>\tThe in-order tree values as a flat array`;
-deepValuesBuiltin.documentation =
-  "https://weborigami.org/cli/builtins.html#valuesDeep";

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

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Return only the defined (not `undefined`) values in the tree.
@@ -11,7 +11,12 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} treelike
  */
 export default async function defineds(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@defineds");
+  const tree = await getTreeArgument(
+    this,
+    arguments,
+    treelike,
+    "tree:defineds"
+  );
 
   const result = await Tree.mapReduce(tree, null, async (values, keys) => {
     const object = {};

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

@@ -1,6 +1,6 @@
 import { Tree } from "@weborigami/async-tree";
-import FilterTree from "../common/FilterTree.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
+import FilterTree from "./FilterTree.js";
 
 /**
  * Apply a filter to a tree.
@@ -12,13 +12,10 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @param {Treelike} filterTreelike
  */
 export default async function filter(sourceTreelike, filterTreelike) {
-  assertTreeIsDefined(this, "filter");
+  assertTreeIsDefined(this, "tree:filter");
   const sourceTree = Tree.from(sourceTreelike, { parent: this });
   const filterTree = Tree.from(filterTreelike, { deep: true, parent: this });
   const result = new FilterTree(sourceTree, filterTree);
   result.parent = this;
   return result;
 }
-
-filter.usage = `@filter <tree>, <filter>\tOnly returns values whose keys match the filter`;
-filter.documentation = "https://weborigami.org/language/@filter.html";

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

@@ -1,4 +1,4 @@
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Return the first value in the tree.
@@ -9,7 +9,7 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function first(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@first");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:first");
   for (const key of await tree.keys()) {
     // Just return first value immediately.
     const value = await tree.get(key);
@@ -17,6 +17,3 @@ export default async function first(treelike) {
   }
   return undefined;
 }
-
-first.usage = `@first <tree>\tReturns the first value in the tree.`;
-first.documentation = "https://weborigami.org/cli/builtins.html#first";

package/src/{builtins/@fnTree.js → tree/fromFn.js}

@@ -1,6 +1,6 @@
 import { FunctionTree } from "@weborigami/async-tree";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { toFunction } from "../common/utilities.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
 
 /**
  * Create a tree from a function and a set of keys.
@@ -12,8 +12,8 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @this {AsyncTree|null}
  * @param {Invocable} [invocable]
  */
-export default async function fnTree(invocable, keys = []) {
-  assertTreeIsDefined(this, "fnTree");
+export default async function fromFn(invocable, keys = []) {
+  assertTreeIsDefined(this, "tree:fromFn");
   if (invocable === undefined) {
     throw new Error(
       "An Origami function was called with an initial argument, but its value is undefined."
@@ -24,6 +24,3 @@ export default async function fnTree(invocable, keys = []) {
   tree.parent = this;
   return tree;
 }
-
-fnTree.usage = `@fnTree <fn>, [<keys>]\tCreate a tree from a function and a set of keys`;
-fnTree.documentation = "https://weborigami.org/cli/tree.html#fn";

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

@@ -1,5 +1,5 @@
-import GlobTree from "../common/GlobTree.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
+import GlobTree from "./GlobTree.js";
 
 /**
  * Define a tree whose keys are globs.
@@ -11,10 +11,7 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @this {AsyncTree|null}
  */
 export default async function globs(tree) {
-  assertTreeIsDefined(this, "globs");
+  assertTreeIsDefined(this, "tree:globs");
   const result = new GlobTree(tree);
   return result;
 }
-
-globs.usage = `@globs <patterns>\tDefine a tree whose keys can include wildcard globs`;
-globs.documentation = "https://weborigami.org/language/@globs.html";

package/src/tree/group.js

@@ -0,0 +1,26 @@
+import { group as groupTransform } from "@weborigami/async-tree";
+import getTreeArgument from "../common/getTreeArgument.js";
+import { toFunction } from "../common/utilities.js";
+
+/**
+ * Map a tree to a new tree with the values from the original tree grouped by
+ * the given function.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {import("@weborigami/async-tree").Treelike} treelike
+ * @param {import("../../index.ts").Invocable} groupKey
+ */
+export default async function groupBuiltin(treelike, groupKey) {
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:group");
+
+  const groupKeyFn = toFunction(groupKey);
+  // Have the group key function run in this tree.
+  const extendedGroupKeyFn = groupKeyFn.bind(tree);
+
+  // @ts-ignore
+  const grouped = await groupTransform(tree, extendedGroupKeyFn);
+  grouped.parent = tree;
+  return grouped;
+}