@weborigami/origami 0.0.35

package/src/builtins/@tree/fromYaml.js

@@ -0,0 +1,24 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import * as serialize from "../../common/serialize.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").StringLike} StringLike
+ *
+ * @param {StringLike} text
+ * @this {AsyncTree|null}
+ */
+export default async function fromYaml(text) {
+  assertScopeIsDefined(this);
+  let result = text ? serialize.parseYaml(String(text)) : undefined;
+  if (this && Tree.isAsyncTree(result)) {
+    result = Scope.treeWithScope(result, this);
+  }
+  return result;
+}
+
+fromYaml.usage = `fromYaml <text>\tParse text as YAML`;
+fromYaml.documentation = "https://graphorigami.org/cli/builtins.html#fromYaml";

package/src/builtins/@tree/groupBy.js

@@ -0,0 +1,39 @@
+import { Tree, groupBy } 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";
+
+/**
+ * Return a new tree with the values from the original tree in groups.
+ * The groups are determined by the given function.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {Invocable} groupKeyFn
+ */
+export default async function groupByBuiltin(treelike, groupKeyFn) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  const tree = Tree.from(treelike);
+
+  const fn = toFunction(groupKeyFn);
+  const baseScope = Scope.getScope(this);
+  async function extendedGroupKeyFn(value, key, tree) {
+    const scope = addValueKeyToScope(baseScope, value, key);
+    const sortKey = await fn.call(scope, value, key);
+    return sortKey;
+  }
+
+  const grouped = await groupBy(extendedGroupKeyFn)(tree);
+  const scoped = Scope.treeWithScope(grouped, this);
+  return scoped;
+}
+
+groupByBuiltin.usage = `groupBy <tree>, [groupKeyFn]\tReturn a new tree with the original's values grouped`;
+groupByBuiltin.documentation =
+  "https://graphorigami.org/cli/builtins.html#@group";

package/src/builtins/@tree/inners.js

@@ -0,0 +1,44 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the source nodes of the tree: the nodes with children.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function inners(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+
+  /** @type {AsyncTree} */
+  let result = {
+    async get(key) {
+      const value = await tree.get(key);
+      return Tree.isAsyncTree(value) ? inners.call(this, value) : undefined;
+    },
+
+    async keys() {
+      const subtreeKeys = [];
+      for (const key of await tree.keys()) {
+        if (await Tree.isKeyForSubtree(tree, key)) {
+          subtreeKeys.push(key);
+        }
+      }
+      return subtreeKeys;
+    },
+  };
+
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+inners.usage = `inners <tree>\tThe source nodes of the tree`;
+inners.documentation = "https://graphorigami.org/cli/builtins.html#inners";

package/src/builtins/@tree/isAsyncTree.js

@@ -0,0 +1,17 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+
+import { Tree } from "@weborigami/async-tree";
+
+/**
+ * Return true if the value is an async tree.
+ *
+ * @this {AsyncTree|null}
+ * @param {any} value
+ */
+export default function isAsyncTree(value) {
+  return Tree.isAsyncTree(value);
+}
+
+isAsyncTree.usage = `@tree/isAsyncTree <value>\tReturn true for an async tree`;
+isAsyncTree.documentation =
+  "https://graphorigami.org/cli/builtins.html#isAsyncTree";

package/src/builtins/@tree/keys.js

@@ -0,0 +1,24 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the top-level keys in the tree as an array.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function keys(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  const keys = await tree.keys();
+  return Array.from(keys);
+}
+
+keys.usage = `keys <tree>\tThe top-level keys in the tree`;
+keys.documentation = "https://graphorigami.org/cli/builtins.html#keys";

package/src/builtins/@tree/keysJson.js

@@ -0,0 +1,44 @@
+import { Tree, keysJson } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { transformObject } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Expose .keys.json for a tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ */
+export default async function treeKeysJson(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  let result = transformObject(KeysJsonTransform, tree);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+function KeysJsonTransform(Base) {
+  return class Static extends Base {
+    async get(key) {
+      let value = await super.get(key);
+      if (value === undefined && key === ".keys.json") {
+        value = await keysJson.stringify(this);
+      } else if (Tree.isAsyncTree(value)) {
+        value = transformObject(KeysJsonTransform, value);
+      }
+      return value;
+    }
+
+    async keys() {
+      const keys = new Set(await super.keys());
+      keys.add(".keys.json");
+      return keys;
+    }
+  };
+}

package/src/builtins/@tree/map.d.ts

@@ -0,0 +1,19 @@
+import { KeyFn, Treelike, ValueKeyFn } from "@weborigami/async-tree";
+import { AsyncTree } from "@weborigami/types";
+import { TreelikeTransform } from "../../../index.ts";
+
+type TreeMapOptions = {
+  deep?: boolean;
+  description?: string;
+  extensions?: string;
+  inverseKeyMap?: KeyFn;
+  keyMap?: ValueKeyFn;
+  keyName?: string;
+  valueMap?: ValueKeyFn;
+  valueName?: string
+};
+
+export default function treeMap(valueMap: ValueKeyFn): TreelikeTransform;
+export default function treeMap(options: TreeMapOptions): TreelikeTransform;
+export default function treeMap(treelike: Treelike, valueMap: ValueKeyFn): AsyncTree;
+export default function treeMap(treelike: Treelike, options: TreeMapOptions): AsyncTree;

package/src/builtins/@tree/merge.js

@@ -0,0 +1,47 @@
+import { merge } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Create a tree that's the result of merging the given trees.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {(Treelike|null)[]} trees
+ */
+export default async function treeMerge(...trees) {
+  assertScopeIsDefined(this);
+
+  // Filter out null or undefined trees.
+  /** @type {Treelike[]}
+   * @ts-ignore */
+  const filtered = trees.filter((tree) => tree);
+
+  if (filtered.length === 1) {
+    // Only one tree, no need to merge.
+    return filtered[0];
+  }
+
+  // If a tree can take a scope, give it one that includes the other trees and
+  // the current scope.
+  const scopedTrees = filtered.map((tree) => {
+    const otherTrees = filtered.filter((g) => g !== tree);
+    const scope = new Scope(...otherTrees, this);
+    // Each tree will be included first in its own scope.
+    return Scope.treeWithScope(tree, scope);
+  });
+
+  // Merge the trees.
+  const result = merge(...scopedTrees);
+
+  // Give the overall mixed tree a scope that includes the component trees and
+  // the current scope.
+  /** @type {any} */ (result).scope = new Scope(result, this);
+
+  return result;
+}
+
+treeMerge.usage = `@merge <...trees>\tMerge the given trees`;
+treeMerge.documentation = "https://graphorigami.org/cli/builtins.html#@merge";

package/src/builtins/@tree/mergeDeep.js

@@ -0,0 +1,44 @@
+import { mergeDeep } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Create a tree that's the result of deep merging the given trees.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike[]} trees
+ */
+export default async function treeMergeDeep(...trees) {
+  assertScopeIsDefined(this);
+  // Filter out null or undefined trees.
+  const filtered = trees.filter((tree) => tree);
+
+  if (filtered.length === 1) {
+    // Only one tree, no need to merge.
+    return filtered[0];
+  }
+
+  // If a tree can take a scope, give it one that includes the other trees and
+  // the current scope.
+  const scopedTrees = filtered.map((tree) => {
+    const otherTrees = filtered.filter((g) => g !== tree);
+    const scope = new Scope(...otherTrees, this);
+    // Each tree will be included first in its own scope.
+    return Scope.treeWithScope(tree, scope);
+  });
+
+  // Merge the trees.
+  const result = mergeDeep(...scopedTrees);
+
+  // Give the overall mixed tree a scope that includes the component trees and
+  // the current scope.
+  /** @type {any} */ (result).scope = new Scope(result, this);
+
+  return result;
+}
+
+treeMergeDeep.usage = `mergeDeep <...trees>\tMerge the given trees deeply`;
+treeMergeDeep.documentation =
+  "https://graphorigami.org/cli/builtins.html#mergeDeep";

package/src/builtins/@tree/nextKey.js

@@ -0,0 +1,29 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Returns the key after the indicated key.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {any} key
+ */
+export default async function nextKey(treelike, key) {
+  assertScopeIsDefined(this);
+  const tree = Tree.from(treelike);
+  let returnNextKey = false;
+  for (const treeKey of await tree.keys()) {
+    if (returnNextKey) {
+      return treeKey;
+    }
+    if (treeKey === key) {
+      returnNextKey = true;
+    }
+  }
+  return undefined;
+}
+
+nextKey.usage = `nextKey <tree>, <key>\tReturns the key after the indicated key`;
+nextKey.documentation = "https://graphorigami.org/cli/builtins.html#nextKey";

package/src/builtins/@tree/parent.js

@@ -0,0 +1,24 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Returns the parent of the current tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function parent(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  return tree.parent;
+}
+
+parent.usage = `parent\tThe parent of the current tree`;
+parent.documentation = "https://graphorigami.org/cli/builtins.html#parent";

package/src/builtins/@tree/paths.js

@@ -0,0 +1,35 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return an array of paths to the values in the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ * @param {string} [prefix]
+ */
+export default async function paths(treelike, prefix = "") {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const result = [];
+  const tree = Tree.from(treelike);
+  for (const key of await tree.keys()) {
+    const valuePath = prefix ? `${prefix}/${key}` : key;
+    const value = await tree.get(key);
+    if (await Tree.isAsyncTree(value)) {
+      const subPaths = await paths.call(this, value, valuePath);
+      result.push(...subPaths);
+    } else {
+      result.push(valuePath);
+    }
+  }
+  return result;
+}
+
+paths.usage = `paths(tree)\tReturn an array of paths to the values in the tree`;

package/src/builtins/@tree/plain.js

@@ -0,0 +1,22 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the interior nodes of the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function plain(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  return Tree.plain(treelike);
+}
+
+plain.usage = `plain <tree>\tA plain JavaScript object representation of the tree`;
+plain.documentation = "https://graphorigami.org/cli/builtins.html#plain";

package/src/builtins/@tree/previousKey.js

@@ -0,0 +1,29 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Returns the key before the indicated key.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @param {any} key
+ * @this {AsyncTree|null}
+ */
+export default async function previousKey(treelike, key) {
+  assertScopeIsDefined(this);
+  const tree = Tree.from(treelike);
+  let previousKey = undefined;
+  for (const treeKey of await tree.keys()) {
+    if (treeKey === key) {
+      return previousKey;
+    }
+    previousKey = treeKey;
+  }
+  return undefined;
+}
+
+previousKey.usage = `previousKey <tree>, <key>\tReturns the key before the indicated key`;
+previousKey.documentation =
+  "https://graphorigami.org/cli/builtins.html#previousKey";

package/src/builtins/@tree/reverse.js

@@ -0,0 +1,51 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Reverse the order of the top-level keys in the tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ * @param {PlainObject} [options]
+ */
+export default async function reverse(treelike, options = {}) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const scope = this;
+  const tree = Tree.from(treelike);
+  const deep = options.deep ?? false;
+
+  /** @type {AsyncTree} */
+  let reversed = {
+    async get(key) {
+      let value = await tree.get(key);
+
+      if (deep && Tree.isAsyncTree(value)) {
+        value = reverse.call(scope, value, options);
+      }
+
+      return value;
+    },
+
+    async keys() {
+      const keys = Array.from(await tree.keys());
+      keys.reverse();
+      return keys;
+    },
+  };
+
+  reversed = Scope.treeWithScope(reversed, this);
+
+  return reversed;
+}
+
+reverse.usage = `reverse <tree>\tReverses the order of the tree's top-level keys`;
+reverse.documentation = "https://graphorigami.org/cli/builtins.html#reverse";

package/src/builtins/@tree/setDeep.js

@@ -0,0 +1,45 @@
+import { Tree } from "@weborigami/async-tree";
+
+export default async function setDeep(target, source) {
+  const targetTree = Tree.from(target);
+  const sourceTree = Tree.from(source);
+  await applyUpdates(sourceTree, targetTree);
+}
+
+// Apply all updates from the source to the target.
+async function applyUpdates(source, target) {
+  // Fire off requests to update all keys, then wait for all of them to finish.
+  const promises = [];
+  for (const key of await source.keys()) {
+    const updateKeyPromise = applyUpdateForKey(source, target, key);
+    promises.push(updateKeyPromise);
+  }
+  await Promise.all(promises);
+
+  // HACK: Transforms like KeysTransform that maintain caches will need to
+  // recalculate things now that updates have been applied. This should be an
+  // automatic part of calling set() -- but triggering those changes inside
+  // set() produces cases where set() and get() calls can be interleaved. The
+  // atomicity of set() needs to be reconsidered. For now, we work around the
+  // problem by triggering `onChange` after the updates have been applied.
+  target.onChange?.();
+}
+
+// Copy the value for the given key from the source to the target.
+async function applyUpdateForKey(source, target, key) {
+  const sourceValue = await source.get(key);
+  if (Tree.isAsyncTree(sourceValue)) {
+    const targetValue = await target.get(key);
+    if (Tree.isAsyncTree(targetValue)) {
+      // Both source and target are async dictionaries; recurse.
+      await applyUpdates(sourceValue, targetValue);
+      return;
+    }
+  }
+
+  // Copy the value from the source to the target.
+  await target.set(key, sourceValue);
+}
+
+setDeep.usage = `setDeep <target>, <source>\tApplies the source tree to the target`;
+setDeep.documentation = "https://graphorigami.org/cli/builtins.html#setDeep";

package/src/builtins/@tree/shuffle.js

@@ -0,0 +1,31 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import ShuffleTransform from "../../common/ShuffleTransform.js";
+import { transformObject } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a new tree with the original's keys shuffled
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function shuffle(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+
+  /** @type {AsyncTree} */
+  let shuffled = transformObject(ShuffleTransform, tree);
+  shuffled = Scope.treeWithScope(shuffled, this);
+  return shuffled;
+}
+
+shuffle.usage = `shuffle <tree>\tReturn a new tree with the original's keys shuffled`;
+shuffle.documentation = "https://graphorigami.org/cli/builtins.html#shuffle";

package/src/builtins/@tree/sitemap.js

@@ -0,0 +1,59 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import builtins from "../@builtins.js";
+import unpackOrigamiTemplate from "../@loaders/orit.js";
+import paths from "./paths.js";
+
+const templateText = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+{{ @map(=\`
+  <url>
+    <loc>{{ _ }}</loc>
+  </url>
+\`)(_) }}
+</urlset>
+`;
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {string} [baseHref ]
+ */
+export default async function sitemap(treelike, baseHref = "") {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  const tree = Tree.from(treelike);
+
+  // We're only interested in keys that end in .html or with no extension.
+  function test(key) {
+    return key.endsWith?.(".html") || !key.includes?.(".");
+  }
+  const filterTree = {
+    async keys() {
+      const keys = Array.from(await tree.keys());
+      return keys.filter((key) => test(key));
+    },
+
+    async get(key) {
+      return test(key) ? tree.get(key) : undefined;
+    },
+  };
+
+  const treePaths = await paths.call(this, filterTree, baseHref);
+
+  // For simplicity, we assume that HTML pages will end in .html.
+  // If the page is named index.html, we remove index.html from
+  // the path.
+  const htmlPaths = treePaths
+    .filter((path) => path.endsWith(".html"))
+    .map((path) => (path.endsWith("index.html") ? path.slice(0, -10) : path));
+
+  const templateFn = await unpackOrigamiTemplate(templateText);
+  const templateResult = await templateFn.call(builtins, htmlPaths);
+  return String(templateResult);
+}
+
+sitemap.usage = `@sitemap <tree>\tGenerate a sitemap for a tree`;
+sitemap.documentation = "https://graphorigami.org/cli/builtins.html#@sitemap";

package/src/builtins/@tree/sort.js

@@ -0,0 +1,25 @@
+import { Tree, sortNatural } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a new tree with the original's keys sorted in natural sort order.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function sort(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  const tree = Tree.from(treelike);
+  const sorted = sortNatural()(tree);
+  const scoped = Scope.treeWithScope(sorted, this);
+  return scoped;
+}
+
+sort.usage = `sort <tree>\tReturn a new tree with the original's keys sorted`;
+sort.documentation = "https://graphorigami.org/cli/builtins.html#@sort";