@weborigami/origami 0.0.48 → 0.0.50

package/exports/buildExports.js

@@ -103,11 +103,11 @@ function exportStatements(src) {
   const withPaths = transformObject(PathTransform, src);
 
   // Map each source file to an export statement.
-  const mapped = map({
+  const mapped = map(withPaths, {
     deep: true,
     value: exportStatementForCode,
     ...keyFunctionsForExtensions({ sourceExtension: "js" }),
-  })(withPaths);
+  });
 
   return mapped;
 }

package/exports/exports.js

@@ -1,15 +1,24 @@
 // This file is generated by running buildExports.js -- do not edit by hand.
-export { default as apply } from "../src/builtins/@apply.js";
-export { default as arrows } from "../src/builtins/@arrows.js";
+export { default as addNextPrevious } from "../src/builtins/@addNextPrevious.js";
+export { default as arrowsMap } from "../src/builtins/@arrowsMap.js";
 export { default as basename } from "../src/builtins/@basename.js";
 export { default as builtins } from "../src/builtins/@builtins.js";
 export { default as cache } from "../src/builtins/@cache.js";
+export { default as changes } from "../src/builtins/@changes.js";
+export { default as clean } from "../src/builtins/@clean.js";
 export { default as concat } from "../src/builtins/@concat.js";
 export { default as config } from "../src/builtins/@config.js";
+export { default as constructor } from "../src/builtins/@constructor.js";
 export { default as copy } from "../src/builtins/@copy.js";
 export { default as count } from "../src/builtins/@count.js";
 export { default as crawl } from "../src/builtins/@crawl.js";
 export { default as debug } from "../src/builtins/@debug.js";
+export { default as deepMap } from "../src/builtins/@deepMap.js";
+export { default as deepMapFn } from "../src/builtins/@deepMapFn.js";
+export { default as deepMerge } from "../src/builtins/@deepMerge.js";
+export { default as deepTake } from "../src/builtins/@deepTake.js";
+export { default as deepTakeFn } from "../src/builtins/@deepTakeFn.js";
+export { default as deepValues } from "../src/builtins/@deepValues.js";
 export { default as defineds } from "../src/builtins/@defineds.js";
 export { default as document } from "../src/builtins/@document.js";
 export { default as equals } from "../src/builtins/@equals.js";
@@ -21,30 +30,34 @@ export { default as filter } from "../src/builtins/@filter.js";
 export { default as first } from "../src/builtins/@first.js";
 export { default as fnTree } from "../src/builtins/@fnTree.js";
 export { default as globs } from "../src/builtins/@globs.js";
-export { default as groupBy } from "../src/builtins/@groupBy.js";
+export { default as group } from "../src/builtins/@group.js";
+export { default as groupFn } from "../src/builtins/@groupFn.js";
 export { default as help } from "../src/builtins/@help.js";
 export { default as http } from "../src/builtins/@http.js";
 export { default as https } from "../src/builtins/@https.js";
 export { default as if } from "../src/builtins/@if.js";
 export { default as imageFormat } from "../src/builtins/@image/format.js";
+export { default as imageFormatFn } from "../src/builtins/@image/formatFn.js";
 export { default as imageResize } from "../src/builtins/@image/resize.js";
+export { default as imageResizeFn } from "../src/builtins/@image/resizeFn.js";
 export { default as index } from "../src/builtins/@index.js";
 export { default as inherited } from "../src/builtins/@inherited.js";
 export { default as inline } from "../src/builtins/@inline.js";
 export { default as inners } from "../src/builtins/@inners.js";
 export { default as invoke } from "../src/builtins/@invoke.js";
-export { default as isAsyncTree } from "../src/builtins/@isAsyncTree.js";
 export { default as js } from "../src/builtins/@js.js";
 export { default as json } from "../src/builtins/@json.js";
+export { default as jsonParse } from "../src/builtins/@jsonParse.js";
 export { default as keys } from "../src/builtins/@keys.js";
 export { default as keysJson } from "../src/builtins/@keysJson.js";
 export { default as map } from "../src/builtins/@map.js";
-export { default as mapDeep } from "../src/builtins/@mapDeep.js";
+export { default as mapFn } from "../src/builtins/@mapFn.js";
 export { default as match } from "../src/builtins/@match.js";
 export { default as mdHtml } from "../src/builtins/@mdHtml.js";
+export { default as mdTree } from "../src/builtins/@mdTree.js";
 export { default as merge } from "../src/builtins/@merge.js";
-export { default as mergeDeep } from "../src/builtins/@mergeDeep.js";
 export { default as mkdir } from "../src/builtins/@mkdir.js";
+export * from "../src/builtins/@naturalOrder.js";
 export { default as node } from "../src/builtins/@node.js";
 export { default as not } from "../src/builtins/@not.js";
 export { default as once } from "../src/builtins/@once.js";
@@ -52,14 +65,16 @@ export { default as or } from "../src/builtins/@or.js";
 export { default as ori } from "../src/builtins/@ori.js";
 export { default as pack } from "../src/builtins/@pack.js";
 export { default as package } from "../src/builtins/@package.js";
+export { default as paginate } from "../src/builtins/@paginate.js";
+export { default as paginateFn } from "../src/builtins/@paginateFn.js";
 export { default as parent } from "../src/builtins/@parent.js";
-export { default as parseJson } from "../src/builtins/@parse/json.js";
-export { default as parseYaml } from "../src/builtins/@parse/yaml.js";
 export { default as paths } from "../src/builtins/@paths.js";
 export { default as perf } from "../src/builtins/@perf.js";
 export { default as plain } from "../src/builtins/@plain.js";
 export { default as project } from "../src/builtins/@project.js";
 export { default as redirect } from "../src/builtins/@redirect.js";
+export { default as regexParse } from "../src/builtins/@regexParse.js";
+export { default as regexParseFn } from "../src/builtins/@regexParseFn.js";
 export { default as repeat } from "../src/builtins/@repeat.js";
 export { default as reverse } from "../src/builtins/@reverse.js";
 export { default as rss } from "../src/builtins/@rss.js";
@@ -72,23 +87,24 @@ export { default as setDeep } from "../src/builtins/@setDeep.js";
 export { default as shell } from "../src/builtins/@shell.js";
 export { default as shuffle } from "../src/builtins/@shuffle.js";
 export { default as sitemap } from "../src/builtins/@sitemap.js";
+export { default as slug } from "../src/builtins/@slug.js";
 export { default as sort } from "../src/builtins/@sort.js";
-export { default as sortBy } from "../src/builtins/@sortBy.js";
+export { default as sortFn } from "../src/builtins/@sortFn.js";
 export { default as static } from "../src/builtins/@static.js";
 export { default as stdin } from "../src/builtins/@stdin.js";
 export { default as string } from "../src/builtins/@string.js";
 export { default as svg } from "../src/builtins/@svg.js";
 export { default as table } from "../src/builtins/@table.js";
 export { default as take } from "../src/builtins/@take.js";
-export { default as tree } from "../src/builtins/@tree.js";
+export { default as takeFn } from "../src/builtins/@takeFn.js";
+export * from "../src/builtins/@tree.js";
 export { default as treeHttp } from "../src/builtins/@treeHttp.js";
 export { default as treeHttps } from "../src/builtins/@treeHttps.js";
 export { default as unpack } from "../src/builtins/@unpack.js";
 export { default as values } from "../src/builtins/@values.js";
-export { default as valuesDeep } from "../src/builtins/@valuesDeep.js";
 export { default as watch } from "../src/builtins/@watch.js";
-export { default as with } from "../src/builtins/@with.js";
 export { default as yaml } from "../src/builtins/@yaml.js";
+export { default as yamlParse } from "../src/builtins/@yamlParse.js";
 export { default as homeFiles } from "../src/builtins/~.js";
 export { default as csshandler } from "../src/builtins/css_handler.js";
 export { default as htmhandler } from "../src/builtins/htm_handler.js";
@@ -108,7 +124,7 @@ export { default as ymlhandler } from "../src/builtins/yml_handler.js";
 export { default as defaultModuleExport } from "../src/cli/defaultModuleExport.js";
 export { default as showUsage } from "../src/cli/showUsage.js";
 export { default as addValueKeyToScope } from "../src/common/addValueKeyToScope.js";
-export { default as arrowFunctionsMap } from "../src/common/arrowFunctionsMap.js";
+export { default as arrowsMapFn } from "../src/common/arrowsMapFn.js";
 export { default as CommandModulesTransform } from "../src/common/CommandModulesTransform.js";
 export { default as ConstantTree } from "../src/common/ConstantTree.js";
 export { default as documentObject } from "../src/common/documentObject.js";

package/index.ts

@@ -4,7 +4,6 @@
  */
 
 import { Treelike, Unpackable } from "@weborigami/async-tree";
-import { AsyncTree } from "@weborigami/types";
 
 /**
  * A class constructor is an object with a `new` method that returns an
@@ -21,5 +20,3 @@ export interface JsonObject {
 export type JsonValue = boolean | number | string | Date | JsonObject | JsonValue[] | null;
 
 export type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
-
-export type TreelikeTransform = (value: Treelike) => AsyncTree;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.0.48",
+  "version": "0.0.50",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -13,22 +13,22 @@
   "main": "./exports/exports.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "20.11.27",
-    "typescript": "5.4.2"
+    "@types/node": "20.12.7",
+    "typescript": "5.4.5"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.0.48",
-    "@weborigami/language": "0.0.48",
-    "@weborigami/types": "0.0.48",
+    "@weborigami/async-tree": "0.0.50",
+    "@weborigami/language": "0.0.50",
+    "@weborigami/types": "0.0.50",
     "exif-parser": "0.1.12",
-    "graphviz-wasm": "3.0.1",
+    "graphviz-wasm": "3.0.2",
     "highlight.js": "11.9.0",
-    "marked": "12.0.1",
+    "marked": "12.0.2",
     "marked-gfm-heading-id": "3.1.3",
     "marked-highlight": "2.1.1",
     "marked-smartypants": "1.1.6",
-    "sharp": "0.33.2",
-    "yaml": "2.4.1"
+    "sharp": "0.33.3",
+    "yaml": "2.4.2"
   },
   "scripts": {
     "build": "ori exports/buildExports.js src > exports/exports.js",

package/src/builtins/@addNextPrevious.js

@@ -0,0 +1,58 @@
+import { Tree } from "@weborigami/async-tree";
+import getTreeArgument from "../misc/getTreeArgument.js";
+
+/**
+ * Add nextKey/previousKey properties to values.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {import("@weborigami/async-tree").Treelike} treelike
+ */
+export default async function addNextPrevious(treelike) {
+  const tree = await getTreeArgument(this, arguments, treelike, "@sequence");
+  let keys;
+  return Object.create(tree, {
+    get: {
+      value: async (key) => {
+        let value = await tree.get(key);
+
+        if (value === undefined) {
+          return undefined;
+        } else if (Tree.isTreelike(value)) {
+          value = await Tree.plain(value);
+        } else if (typeof value === "object") {
+          // Clone value to avoid modifying the original object.
+          value = { ...value };
+        } else if (typeof value === "string") {
+          // Upgrade text nodes to objects.
+          value = { "@text": value };
+        } else {
+          // Upgrade other scalar types to objects.
+          value = { "@data": value };
+        }
+
+        if (keys === undefined) {
+          keys = Array.from(await tree.keys());
+        }
+        const index = keys.indexOf(key);
+        if (index === -1) {
+          // Key is supported but not published in `keys`
+          return value;
+        }
+
+        // Extend value with nextKey/previousKey properties.
+        const nextKey = keys[index + 1];
+        if (nextKey) {
+          value.nextKey = nextKey;
+        }
+        const previousKey = keys[index - 1];
+        if (previousKey) {
+          value.previousKey = previousKey;
+        }
+        return value;
+      },
+      writable: true,
+    },
+  });
+}

package/src/builtins/{@arrows.js → @arrowsMap.js}

@@ -1,5 +1,5 @@
 import { Scope, functionResultsMap } from "@weborigami/language";
-import arrowFunctionsMap from "../common/arrowFunctionsMap.js";
+import arrowsMapFn from "../common/arrowsMapFn.js";
 import { keySymbol } from "../common/utilities.js";
 import getTreeArgument from "../misc/getTreeArgument.js";
 import builtins from "./@builtins.js";
@@ -12,14 +12,14 @@ import builtins from "./@builtins.js";
  * @this {AsyncTree|null}
  * @param {Treelike} [treelike]
  */
-export default async function arrows(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@arrows");
-  const mapped = functionResultsMap(arrowFunctionsMap()(tree));
+export default async function arrowsMap(treelike) {
+  const tree = await getTreeArgument(this, arguments, treelike, "arrowsMap");
+  const mapped = functionResultsMap(arrowsMapFn()(tree));
   const scope = this ?? builtins;
   const scoped = Scope.treeWithScope(mapped, scope);
-  scoped[keySymbol] = "@arrows";
+  scoped[keySymbol] = "@arrowsMap";
   return scoped;
 }
 
-arrows.usage = `@arrows <obj>\tInterpret arrow keys in the tree as function calls`;
-arrows.documentation = "https://weborigami.org/language/@arrows.html";
+arrowsMap.usage = `@arrowsMap <obj>\tInterpret arrow keys in the tree as function calls`;
+arrowsMap.documentation = "https://weborigami.org/language/@arrowsMap.html";

package/src/builtins/@changes.js

@@ -0,0 +1,46 @@
+import { Tree } from "@weborigami/async-tree";
+
+// Given an old tree and a new tree, return a tree of changes indicated
+// by the values: "added", "changed", or "deleted".
+export default async function changes(oldTreelike, newTreelike) {
+  const oldTree = Tree.from(oldTreelike);
+  const newTree = Tree.from(newTreelike);
+
+  const oldKeys = Array.from(await oldTree.keys());
+  const newKeys = Array.from(await newTree.keys());
+
+  const result = {};
+
+  for (const key of oldKeys) {
+    if (!newKeys.includes(key)) {
+      result[key] = "deleted";
+      continue;
+    }
+
+    const oldValue = await oldTree.get(key);
+    const newValue = await newTree.get(key);
+
+    if (Tree.isAsyncTree(oldValue) && Tree.isAsyncTree(newValue)) {
+      const treeChanges = await changes(oldValue, newValue);
+      if (Object.keys(treeChanges).length > 0) {
+        result[key] = treeChanges;
+      }
+    } else if (oldValue?.toString && newValue?.toString) {
+      const oldText = oldValue.toString();
+      const newText = newValue.toString();
+      if (oldText !== newText) {
+        result[key] = "changed";
+      }
+    } else {
+      result[key] = "changed";
+    }
+  }
+
+  for (const key of newKeys) {
+    if (!oldKeys.includes(key)) {
+      result[key] = "added";
+    }
+  }
+
+  return result;
+}

package/src/builtins/@clean.js

@@ -0,0 +1,19 @@
+import { Tree } from "@weborigami/async-tree";
+import getTreeArgument from "../misc/getTreeArgument.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {import("@weborigami/async-tree").Treelike} treelike
+ */
+export default async function clean(treelike) {
+  const tree = await getTreeArgument(this, arguments, treelike, "@sequence");
+  if (!Tree.isAsyncMutableTree(tree)) {
+    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));
+  await Promise.all(promises);
+  return tree;
+}

package/src/builtins/@constructor.js

@@ -0,0 +1,17 @@
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param  {...any} keys
+ */
+export default function constructor(...keys) {
+  assertScopeIsDefined(this, "constructor");
+  const scope = this;
+  if (!scope) {
+    throw new Error("@constructor requires a non-null scope.");
+  }
+  return ops.constructor.call(scope, ...keys);
+}

package/src/builtins/@crawl.js

@@ -1,9 +1,9 @@
 import {
   DeepObjectTree,
   Tree,
+  deepMerge,
   isPlainObject,
   keysFromPath,
-  mergeDeep,
 } from "@weborigami/async-tree";
 import { InvokeFunctionsTransform, Scope, extname } from "@weborigami/language";
 import * as utilities from "../common/utilities.js";
@@ -93,7 +93,7 @@ export default async function crawl(treelike, baseHref) {
   // for something already, that's better than a function that will get that
   // value.
   /** @type {AsyncTree} */
-  let result = mergeDeep(
+  let result = deepMerge(
     new DeepObjectTree(cache),
     new (InvokeFunctionsTransform(DeepObjectTree))(resources)
   );

package/src/builtins/@debug.js

@@ -1,4 +1,4 @@
-import { Tree, isPlainObject } from "@weborigami/async-tree";
+import { Tree } from "@weborigami/async-tree";
 import { Scope } from "@weborigami/language";
 import ExplorableSiteTransform from "../common/ExplorableSiteTransform.js";
 import { isTransformApplied, transformObject } from "../common/utilities.js";
@@ -19,12 +19,13 @@ export default async function debug(treelike) {
   // apply its own scope to the tree.
   let tree = await getTreeArgument(this, arguments, treelike, "@debug");
 
+  if (!isTransformApplied(DebugTransform, tree)) {
+    tree = transformObject(DebugTransform, tree);
+  }
   if (!isTransformApplied(ExplorableSiteTransform, tree)) {
     tree = transformObject(ExplorableSiteTransform, tree);
   }
 
-  tree = transformObject(DebugTransform, tree);
-
   return tree;
 }
 
@@ -36,20 +37,19 @@ function DebugTransform(Base) {
   return class Debug extends OriCommandTransform(Base) {
     async get(key) {
       let value = await super.get(key);
+      const scope = Scope.getScope(this);
 
-      // Since this transform is for diagnostic purposes, cast arrays
-      // or plain objects to trees so we can debug them too.
-      if (value instanceof Array || isPlainObject(value)) {
+      // Since this transform is for diagnostic purposes, cast any treelike
+      // result to a tree so we can debug the result too.
+      if (Tree.isTreelike(value)) {
         value = Tree.from(value);
-      }
-
-      // Ensure debug transforms are applied to explorable results.
-      if (Tree.isAsyncTree(value)) {
-        value = transformObject(ExplorableSiteTransform, value);
-        value = transformObject(DebugTransform, value);
-      }
-
-      if (value?.unpack) {
+        if (!value.parent && !value.scope) {
+          value = Scope.treeWithScope(value, scope);
+        }
+        if (!isTransformApplied(DebugTransform, value)) {
+          value = transformObject(DebugTransform, value);
+        }
+      } else if (value?.unpack) {
         // If the value isn't a tree, but has a tree attached via an `unpack`
         // method, wrap the unpack method to provide debug support for it.
         const original = value.unpack.bind(value);
@@ -61,13 +61,11 @@ function DebugTransform(Base) {
           /** @type {any} */
           let tree = Tree.from(content);
           if (!tree.parent && !tree.scope) {
-            const scope = Scope.getScope(this);
             tree = Scope.treeWithScope(tree, scope);
           }
-          if (!isTransformApplied(ExplorableSiteTransform, tree)) {
-            tree = transformObject(ExplorableSiteTransform, tree);
+          if (!isTransformApplied(DebugTransform, tree)) {
+            tree = transformObject(DebugTransform, tree);
           }
-          tree = transformObject(DebugTransform, tree);
           return tree;
         };
       }

package/src/builtins/@deepMap.js

@@ -0,0 +1,19 @@
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import deepMapFn from "./@deepMapFn.js";
+
+/**
+ * Shorthand for calling `@map` with `deep: true` option.
+ *
+ * @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 {Treelike} source
+ * @param {ValueKeyFn|TreeMapOptions} operation
+ */
+export default function deepMap(source, operation) {
+  assertScopeIsDefined(this, "deepMap");
+  return deepMapFn.call(this, operation)(source);
+}

package/src/builtins/@deepMapFn.js

@@ -0,0 +1,25 @@
+import { isPlainObject } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import mapFn from "./@mapFn.js";
+
+/**
+ * Shorthand for calling `@mapFn` with `deep: true` option.
+ *
+ * @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 deepMapFn(operation) {
+  assertScopeIsDefined(this, "deepMap");
+  /** @type {TreeMapOptions} */
+  const options = isPlainObject(operation)
+    ? // Dictionary
+      { ...operation, deep: true }
+    : // Function
+      { deep: true, value: operation };
+  return mapFn.call(this, options);
+}

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

@@ -1,4 +1,4 @@
-import { mergeDeep } from "@weborigami/async-tree";
+import { deepMerge } from "@weborigami/async-tree";
 import { Scope } from "@weborigami/language";
 import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
 
@@ -10,8 +10,8 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @this {AsyncTree|null}
  * @param {Treelike[]} trees
  */
-export default async function treeMergeDeep(...trees) {
-  assertScopeIsDefined(this, "mergeDeep");
+export default async function treedeepMerge(...trees) {
+  assertScopeIsDefined(this, "deepMerge");
   // Filter out null or undefined trees.
   const filtered = trees.filter((tree) => tree);
 
@@ -30,7 +30,7 @@ export default async function treeMergeDeep(...trees) {
   });
 
   // Merge the trees.
-  const result = mergeDeep(...scopedTrees);
+  const result = deepMerge(...scopedTrees);
 
   // Give the overall mixed tree a scope that includes the component trees and
   // the current scope.
@@ -39,6 +39,6 @@ export default async function treeMergeDeep(...trees) {
   return result;
 }
 
-treeMergeDeep.usage = `@mergeDeep <...trees>\tMerge the given trees deeply`;
-treeMergeDeep.documentation =
-  "https://weborigami.org/cli/builtins.html#mergeDeep";
+treedeepMerge.usage = `@deepMerge <...trees>\tMerge the given trees deeply`;
+treedeepMerge.documentation =
+  "https://weborigami.org/cli/builtins.html#deepMerge";

package/src/builtins/@deepTake.js

@@ -0,0 +1,21 @@
+import getTreeArgument from "../misc/getTreeArgument.js";
+import deepTakeFn from "./@deepTakeFn.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} n
+ */
+export default async function deepTake(treelike, n) {
+  const tree = await getTreeArgument(this, arguments, treelike, "@deepTake");
+  return deepTakeFn.call(this, n)(tree);
+}
+
+deepTake.usage = `@deepTake tree, n\tReturn the first n values from the deep tree`;
+deepTake.documentation = "https://weborigami.org/builtins/deepTake.html";

package/src/builtins/@deepTakeFn.js

@@ -0,0 +1,22 @@
+import { deepTakeFn } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Returns a function that traverses a tree deeply and returns the values of the
+ * first `count` keys.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {number} count
+ */
+export default function deepTakeFnBuiltin(count) {
+  assertScopeIsDefined(this, "deepTakeFn");
+  const scope = this;
+  return async (treelike) => {
+    const taken = await deepTakeFn(count)(treelike);
+    const scoped = Scope.treeWithScope(taken, scope);
+    return scoped;
+  };
+}

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

@@ -1,4 +1,4 @@
-import { Tree } from "@weborigami/async-tree";
+import { deepValues } from "@weborigami/async-tree";
 import getTreeArgument from "../misc/getTreeArgument.js";
 
 /**
@@ -6,14 +6,15 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
  * @this {AsyncTree|null}
  * @param {Treelike} [treelike]
  */
-export default async function valuesDeep(treelike) {
+export default async function deepValuesBuiltin(treelike) {
   const tree = await getTreeArgument(this, arguments, treelike, "@valuesDeep");
-  return Tree.mapReduce(tree, null, async (values) => values.flat());
+  return deepValues(tree);
 }
 
-valuesDeep.usage = `@valuesDeep <tree>\tThe in-order tree values as a flat array`;
-valuesDeep.documentation =
+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/@document.js

@@ -8,9 +8,8 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  * @this {AsyncTree|null}
  * @param {StringLike} text
  * @param {any} [data]
- * @returns
  */
-export default function documentBuiltin(text, data) {
+export default async function documentBuiltin(text, data) {
   assertScopeIsDefined(this, "document");
   return documentObject(text, data);
 }

package/src/builtins/@files.js

@@ -1,4 +1,5 @@
 import { OrigamiFiles, Scope } from "@weborigami/language";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
@@ -11,7 +12,19 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
  */
 export default async function files(...keys) {
   assertScopeIsDefined(this, "files");
-  const resolved = path.resolve(process.cwd(), ...keys);
+
+  // If path begins with `~`, treat it relative to the home directory.
+  // Otherwise, treat it relative to the current working directory.
+  let relativePath = keys.join(path.sep);
+  let basePath;
+  if (relativePath.startsWith("~")) {
+    basePath = os.homedir();
+    relativePath = relativePath.slice(2);
+  } else {
+    basePath = process.cwd();
+  }
+  const resolved = path.resolve(basePath, relativePath);
+
   /** @type {AsyncTree} */
   let result = new OrigamiFiles(resolved);
   result = Scope.treeWithScope(result, this);