@weborigami/origami 0.0.72 → 0.1.0

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

@@ -1,4 +1,4 @@
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Return the number of keys in the tree.
@@ -9,7 +9,7 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function length(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@length");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:length");
   const keys = Array.from(await tree.keys());
   return keys.length;
 }

package/src/{builtins → tree}/map.d.ts

@@ -1,14 +1,11 @@
-import { KeyFn, Treelike, TreeTransform, ValueKeyFn } from "@weborigami/async-tree";
+import { TreeMapOptions as AsyncTreeMapOptions, Treelike, TreeTransform, ValueKeyFn } from "@weborigami/async-tree";
 import { AsyncTree } from "@weborigami/types";
 
-type TreeMapOptions = {
-  deep?: boolean;
+/* Add more properties to TreeMapOptions */
+type TreeMapOptions = AsyncTreeMapOptions &{
   description?: string;
   extension?: string;
-  inverseKey?: KeyFn;
-  key?: ValueKeyFn;
   needsSourceValue?: boolean;
-  value?: ValueKeyFn;
 };
 
 export default function treeMap(options: ValueKeyFn | TreeMapOptions): TreeTransform;

package/src/tree/map.js

@@ -0,0 +1,154 @@
+import {
+  cachedKeyFunctions,
+  isPlainObject,
+  keyFunctionsForExtensions,
+  map as mapTransform,
+} from "@weborigami/async-tree";
+import getTreeArgument from "../common/getTreeArgument.js";
+import { toFunction } from "../common/utilities.js";
+
+/**
+ * Map a hierarchical 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.js").TreeMapOptions} TreeMapOptions
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {ValueKeyFn|TreeMapOptions} operation
+ */
+export default async function map(treelike, operation) {
+  // The tree we're going to map
+  const source = await getTreeArgument(this, arguments, treelike, "tree:map");
+  // The tree in which the map operation happens
+  const context = this;
+
+  const options = extendedOptions(context, operation);
+  const mapped = mapTransform(source, options);
+  mapped.parent = context;
+  return mapped;
+}
+
+/**
+ * Return a function that transforms a tree of keys and values to a new tree of
+ * keys and values.
+ *
+ * @param {AsyncTree|null} context
+ * @param {ValueKeyFn|TreeMapOptions} operation
+ */
+function extendedOptions(context, operation) {
+  // 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(`map: 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(
+      `map: You must specify a value function or options dictionary as the first parameter.`
+    );
+  }
+
+  const { deep, extension, needsSourceValue } = options;
+  const description = options.description ?? `map ${extension ?? ""}`;
+  const keyFn = options.key;
+  const inverseKeyFn = options.inverseKey;
+
+  if (extension && (keyFn || inverseKeyFn)) {
+    throw new TypeError(
+      `map: 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 tree.
+    extendedValueFn = resolvedValueFn.bind(context);
+  }
+
+  // Extend the key functions to run in this tree.
+  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 keyWithValueFn(sourceKey, sourceTree) {
+      const sourceValue = await sourceTree.get(sourceKey);
+      const resultKey = await resolvedKeyFn(sourceValue, sourceKey, sourceTree);
+      return resultKey;
+    }
+    const keyFns = cachedKeyFunctions(keyWithValueFn, deep);
+    extendedKeyFn = keyFns.key;
+    extendedInverseKeyFn = keyFns.inverseKey;
+  } else {
+    // Use sidecar keyFn/inverseKey functions if the valueFn defines them.
+    extendedKeyFn = /** @type {any} */ (valueFn)?.key;
+    extendedInverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
+  }
+
+  return {
+    deep,
+    description,
+    inverseKey: extendedInverseKeyFn,
+    key: extendedKeyFn,
+    needsSourceValue,
+    value: extendedValueFn,
+  };
+}
+
+/**
+ * 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*(?<resultExtension>\.?\S*))|(?<extension>\.?\S*)$/;
+  const match = lowercase.match(extensionRegex);
+  if (!match) {
+    // Shouldn't happen because the regex is exhaustive.
+    throw new Error(`map: Invalid extension specifier "${specifier}".`);
+  }
+  // @ts-ignore
+  const { extension, resultExtension, sourceExtension } = match.groups;
+  if (extension) {
+    // foo
+    return {
+      resultExtension: extension,
+      sourceExtension: extension,
+    };
+  } else {
+    // foo→bar
+    return { resultExtension, sourceExtension };
+  }
+}

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

@@ -2,10 +2,10 @@ import {
   cachedKeyFunctions,
   isPlainObject,
   keyFunctionsForExtensions,
-  mapFn,
+  map,
 } from "@weborigami/async-tree";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 import { toFunction } from "../common/utilities.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
 
 /**
  * Return a function that transforms a tree of keys and values to a new tree of
@@ -14,7 +14,7 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @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
+ * @typedef {import("./map.js").TreeMapOptions} TreeMapOptions
  *
  * @this {AsyncTree|null}
  * @param {ValueKeyFn|TreeMapOptions} operation
@@ -100,17 +100,25 @@ export default function mapFnBuiltin(operation) {
     extendedInverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
   }
 
-  const fn = mapFn({
+  // const fn = mapFn({
+  //   deep,
+  //   description,
+  //   inverseKey: extendedInverseKeyFn,
+  //   key: extendedKeyFn,
+  //   needsSourceValue,
+  //   value: extendedValueFn,
+  // });
+  const temp = {
     deep,
     description,
     inverseKey: extendedInverseKeyFn,
     key: extendedKeyFn,
     needsSourceValue,
     value: extendedValueFn,
-  });
+  };
 
   return (treelike) => {
-    const mapped = fn(treelike);
+    const mapped = map(treelike, temp);
     mapped.parent = tree;
     return mapped;
   };

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

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Return a tree with the indicated keys (if provided).
@@ -24,7 +24,7 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @param {Treelike} [keys]
  */
 export default function match(pattern, resultFn, keys = []) {
-  assertTreeIsDefined(this, "match");
+  assertTreeIsDefined(this, "tree:match");
   let regex;
   if (typeof pattern === "string") {
     // Convert the simple pattern format into a regular expression.
@@ -77,6 +77,3 @@ export default function match(pattern, resultFn, keys = []) {
 
   return result;
 }
-
-match.usage = `@match <pattern>, <fn>, [<keys>]\tMatches simple patterns or regular expressions`;
-match.documentation = "https://weborigami.org/language/@match.html";

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

@@ -1,5 +1,5 @@
 import { isPlainObject, isUnpackable, merge } from "@weborigami/async-tree";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
 
 /**
  * Create a tree that's the result of merging the given trees.
@@ -11,7 +11,7 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * @param {(Treelike|null)[]} trees
  */
 export default async function treeMerge(...trees) {
-  assertTreeIsDefined(this, "merge");
+  assertTreeIsDefined(this, "tree:merge");
 
   // Filter out null or undefined trees.
   /** @type {Treelike[]}
@@ -39,6 +39,3 @@ export default async function treeMerge(...trees) {
   const result = merge(...unpacked);
   return result;
 }
-
-treeMerge.usage = `@merge <...trees>\tMerge the given trees`;
-treeMerge.documentation = "https://weborigami.org/cli/builtins.html#@merge";

package/src/tree/paginate.js

@@ -0,0 +1,61 @@
+import getTreeArgument from "../common/getTreeArgument.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,
+    "tree:paginate"
+  );
+
+  const keys = Array.from(await tree.keys());
+  const pageCount = Math.ceil(keys.length / size);
+
+  const paginated = {
+    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);
+    },
+  };
+
+  paginated.parent = this;
+  return paginated;
+}

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

@@ -1,4 +1,4 @@
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Returns the parent of the current tree.
@@ -10,9 +10,6 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function parent(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@parent");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:parent");
   return tree.parent;
 }
-
-parent.usage = `@parent\tThe parent of the current tree`;
-parent.documentation = "https://weborigami.org/cli/builtins.html#parent";

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

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Return the interior nodes of the tree.
@@ -10,9 +10,6 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function plain(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@plain");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:plain");
   return Tree.plain(tree);
 }
-
-plain.usage = `@plain <tree>\tA plain JavaScript object representation of the tree`;
-plain.documentation = "https://weborigami.org/cli/builtins.html#plain";

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

@@ -1,5 +1,5 @@
 import { reverse } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Reverse the order of the top-level keys in the tree.
@@ -11,10 +11,7 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function reverseBuiltin(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@reverse");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:reverse");
   const reversed = reverse(tree);
   return reversed;
 }
-
-reverseBuiltin.usage = `@reverse <tree>\tReverses the order of the tree's top-level keys`;
-reverseBuiltin.documentation = "https://weborigami.org/builtins/@reverse.html";

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

@@ -47,6 +47,3 @@ async function applyUpdateForKey(source, target, key) {
   // 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://weborigami.org/cli/builtins.html#setDeep";

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

@@ -1,9 +1,6 @@
-import {
-  default as ShuffleTransform,
-  shuffle,
-} from "../common/ShuffleTransform.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 import { transformObject } from "../common/utilities.js";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import { default as ShuffleTransform, shuffle } from "./ShuffleTransform.js";
 
 /**
  * Return a new tree with the original's keys shuffled
@@ -26,9 +23,6 @@ export default async function shuffleTree(treelike) {
     shuffle(array);
     return array;
   }
-  const tree = await getTreeArgument(this, arguments, treelike, "@shuffle");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:shuffle");
   return transformObject(ShuffleTransform, tree);
 }
-
-shuffleTree.usage = `@shuffle <tree>\tReturn a new tree with the original's keys shuffled`;
-shuffleTree.documentation = "https://weborigami.org/cli/builtins.html#shuffle";

package/src/{builtins/@sortFn.js → tree/sort.js}

@@ -1,10 +1,9 @@
-import { sortFn } from "@weborigami/async-tree";
+import { sort as sortTransform } from "@weborigami/async-tree";
+import getTreeArgument from "../common/getTreeArgument.js";
 import { toFunction } from "../common/utilities.js";
-import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
 
 /**
- * Return a transform function that sorts a tree's keys using a comparison
- * function.
+ * Return a new tree with the original's keys sorted.
  *
  * If the `options` include a `sortKey` function, that will be invoked for each
  * key in the tree to produce a sort key. If no `sortKey` function is provided,
@@ -14,16 +13,17 @@ import assertTreeIsDefined from "../misc/assertTreeIsDefined.js";
  * sort keys.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  * @typedef {import("@weborigami/async-tree").ValueKeyFn} ValueKeyFn
  * @typedef {{ compare?: (a: any, b: any) => number, sortKey?: ValueKeyFn }}
  * SortOptions
  *
  * @this {AsyncTree|null}
- * @param {ValueKeyFn|SortOptions} [options]
+ * @param {Treelike} [treelike]
+ * @param {SortOptions|ValueKeyFn} [options]
  */
-export default function sortFnBuiltin(options) {
-  assertTreeIsDefined(this, "sortFn");
-  const parent = this;
+export default async function sortBuiltin(treelike, options) {
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:sort");
 
   if (typeof options === "function") {
     // Take the function as the `sortKey` option
@@ -34,6 +34,7 @@ export default function sortFnBuiltin(options) {
   let extendedSortKeyFn;
   if (options?.sortKey) {
     const originalSortKey = toFunction(options?.sortKey);
+    const parent = this;
     extendedSortKeyFn = async (key, tree) => {
       const value = await tree.get(key);
       const sortKey = await originalSortKey.call(parent, value, key);
@@ -41,17 +42,11 @@ export default function sortFnBuiltin(options) {
     };
   }
 
-  const fn = sortFn({
+  const sorted = await sortTransform(tree, {
     compare,
     sortKey: extendedSortKeyFn,
   });
 
-  return (treelike) => {
-    const sorted = fn(treelike);
-    sorted.parent = parent;
-    return sorted;
-  };
+  sorted.parent = this;
+  return sorted;
 }
-
-sortFnBuiltin.usage = `@sortFn [sortFn]\tReturn a function that sorts a tree`;
-sortFnBuiltin.documentation = "https://weborigami.org/builtins/@sortFn.html";

package/src/tree/take.js

@@ -0,0 +1,19 @@
+import { take as takeTransform } from "@weborigami/async-tree";
+import getTreeArgument from "../common/getTreeArgument.js";
+
+/**
+ * Given a tree, take the first n items from it.
+ *
+ * @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 take(treelike, count) {
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:take");
+  const taken = await takeTransform(tree, count);
+  taken.parent = this;
+  return taken;
+}

package/src/tree/tree.js

@@ -0,0 +1,49 @@
+import { Tree } from "@weborigami/async-tree";
+export { default as addNextPrevious } from "./addNextPrevious.js";
+export { default as cache } from "./cache.js";
+export { default as calendar } from "./calendar.js";
+export { default as clear } from "./clear.js";
+export { default as concat } from "./concat.js";
+export { default as copy } from "./copy.js";
+export { default as deepMap } from "./deepMap.js";
+export { default as deepMerge } from "./deepMerge.js";
+export { default as deepReverse } from "./deepReverse.js";
+export { default as deepTake } from "./deepTake.js";
+export { default as deepValues } from "./deepValues.js";
+export { default as defineds } from "./defineds.js";
+export { default as filter } from "./filter.js";
+export { default as first } from "./first.js";
+export { default as fromFn } from "./fromFn.js";
+export { default as globs } from "./globs.js";
+export { default as group } from "./group.js";
+export { default as inners } from "./inners.js";
+export { default as keys } from "./keys.js";
+export { default as length } from "./length.js";
+export { default as map } from "./map.js";
+export { default as match } from "./match.js";
+export { default as merge } from "./merge.js";
+export { default as paginate } from "./paginate.js";
+export { default as parent } from "./parent.js";
+export { default as plain } from "./plain.js";
+export { default as reverse } from "./reverse.js";
+export { default as setDeep } from "./setDeep.js";
+export { default as shuffle } from "./shuffle.js";
+export { default as sort } from "./sort.js";
+export { default as take } from "./take.js";
+export { default as values } from "./values.js";
+
+export const assign = Tree.assign;
+export const entries = Tree.entries;
+export const forEach = Tree.forEach;
+export const from = Tree.from;
+export const has = Tree.has;
+export const isAsyncMutableTree = Tree.isAsyncMutableTree;
+export const isAsyncTree = Tree.isAsyncTree;
+export const isTraversable = Tree.isTraversable;
+export const isTreelike = Tree.isTreelike;
+export const mapReduce = Tree.mapReduce;
+export const paths = Tree.paths;
+export const remove = Tree.remove;
+export const traverse = Tree.traverse;
+export const traverseOrThrow = Tree.traverseOrThrow;
+export const traversePath = Tree.traversePath;

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

@@ -1,5 +1,5 @@
 import { Tree } from "@weborigami/async-tree";
-import getTreeArgument from "../misc/getTreeArgument.js";
+import getTreeArgument from "../common/getTreeArgument.js";
 
 /**
  * Return the interior nodes of the tree.
@@ -10,9 +10,6 @@ import getTreeArgument from "../misc/getTreeArgument.js";
  * @param {Treelike} [treelike]
  */
 export default async function values(treelike) {
-  const tree = await getTreeArgument(this, arguments, treelike, "@values");
+  const tree = await getTreeArgument(this, arguments, treelike, "tree:values");
   return Tree.values(tree);
 }
-
-values.usage = `@values <tree>\tThe top-level values in the tree`;
-values.documentation = "https://weborigami.org/cli/builtins.html#values";

package/exports/PathTransform.d.ts

@@ -1,5 +0,0 @@
-import type { Mixin } from "@weborigami/language";
-
-declare const PathTransform: Mixin<{}>;
-
-export default PathTransform;

package/exports/PathTransform.js

@@ -1,20 +0,0 @@
-import { trailingSlash } from "@weborigami/async-tree";
-
-export default function PathTransform(Base) {
-  return class Path extends Base {
-    async get(key) {
-      let value = await super.get(key);
-      if (typeof value === "object" && value !== null) {
-        // @ts-ignore
-        const path = this[PathTransform.pathKey]
-          ? // @ts-ignore
-            `${trailingSlash.add(this[PathTransform.pathKey])}${key}`
-          : key;
-        value[PathTransform.pathKey] = path;
-      }
-      return value;
-    }
-  };
-}
-
-PathTransform.pathKey = Symbol("path");