@weborigami/origami 0.0.35

package/src/common/CommandModulesTransform.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+
+/**
+ * This mixin can be used to turn a collection of .js modules in a folder into a collection
+ * of commands. For every module `foo.js`, the tree will expose a key `foo` with the value
+ * of the module's export(s).
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Constructor<AsyncTree & { import: function }>} BaseConstructor
+ * @param {BaseConstructor} Base
+ */
+export default function CommandsModulesTransform(Base) {
+  return class CommandModules extends Base {
+    async get(key) {
+      const value = await super.get(key);
+      if (value !== undefined) {
+        return value;
+      }
+
+      // See if we have a JS module for the requested key.
+      if (key === undefined || key.endsWith?.(".js")) {
+        return undefined;
+      }
+
+      const moduleKey = `${key}.js`;
+      return this.import?.(moduleKey);
+    }
+
+    async keys() {
+      const keys = [...(await super.keys())];
+      // If we find a key like "foo.js", then return "foo" as the key.
+      return keys.map((key) =>
+        key.endsWith(".js") ? path.basename(key, ".js") : key
+      );
+    }
+  };
+}

package/src/common/ConstantTree.js

@@ -0,0 +1,17 @@
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class ConstantTree {
+  constructor(value) {
+    this.value = value;
+  }
+
+  async get(key) {
+    return this.value;
+  }
+
+  async keys() {
+    return [];
+  }
+}

package/src/common/ExplorableSiteTransform.d.ts

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

package/src/common/ExplorableSiteTransform.js

@@ -0,0 +1,77 @@
+import { Tree, keysJson } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import index from "../builtins/@index.js";
+import { isTransformApplied, transformObject } from "../common/utilities.js";
+
+/**
+ * Wraps a tree (typically a SiteTree) to turn a standard site into an
+ * explorable site.
+ *
+ * An explorable site follows three conventions:
+ * 1. if route /foo has any resources beneath it (/foo/bar.jpg), then /foo
+ *    redirects to /foo/
+ * 2. /foo/ is a synonym for foo/index.html
+ * 3. /foo/.keys.json returns the public keys below foo/
+ *
+ * The first convention is handled by the Tree Origami server. This transform
+ * handles the second and third conventions.
+ *
+ * As a convenience, this transform also provides a default index.html page if
+ * the tree doesn't define one.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Constructor<AsyncTree>} AsyncTreeConstructor
+ * @param {AsyncTreeConstructor} Base
+ */
+export default function ExplorableSiteTransform(Base) {
+  return class ExplorableSite extends Base {
+    async get(key) {
+      // The empty string key represents "index.html".
+      if (key === "") {
+        key = "index.html";
+      }
+
+      // Ask the tree if it has the key.
+      let value = await super.get(key);
+
+      if (value === undefined) {
+        // The tree doesn't have the key; try the defaults.
+        const scope = Scope.getScope(this);
+        if (key === "index.html") {
+          value = await index.call(scope, this);
+        } else if (key === ".keys.json") {
+          value = await keysJson.stringify(this);
+        }
+      }
+
+      // Ensure this transform is applied to any explorable result. This lets
+      // the user browse into data and explorable trees of types other than the
+      // current class.
+      if (
+        Tree.isAsyncTree(value) &&
+        !isTransformApplied(ExplorableSiteTransform, value)
+      ) {
+        value = transformObject(ExplorableSiteTransform, value);
+      }
+
+      if (value?.unpack) {
+        // If the value isn't a tree, but has a tree attached via a `unpack`
+        // method, wrap the unpack method to add this transform.
+        const original = value.unpack.bind(value);
+        value.unpack = async () => {
+          const content = await original();
+          if (!Tree.isTreelike(content)) {
+            return content;
+          }
+          /** @type {any} */
+          let tree = Tree.from(content);
+          if (!isTransformApplied(ExplorableSiteTransform, tree)) {
+            tree = transformObject(ExplorableSiteTransform, tree);
+          }
+          return tree;
+        };
+      }
+      return value;
+    }
+  };
+}

package/src/common/FilterTree.js

@@ -0,0 +1,60 @@
+import { Tree } from "@weborigami/async-tree";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class FilterTree {
+  constructor(tree, filter) {
+    this.tree = Tree.from(tree);
+    this.filter = Tree.from(filter);
+  }
+
+  async get(key) {
+    let value = await this.tree.get(key);
+
+    let filterValue = await this.filter.get(key);
+    if (!Tree.isAsyncTree(value)) {
+      if (filterValue === undefined) {
+        value = undefined;
+      } else if (Tree.isAsyncTree(filterValue)) {
+        value = undefined;
+      }
+    } else if (Tree.isAsyncTree(filterValue)) {
+      // Wrap value with corresponding filter.
+      value = Reflect.construct(this.constructor, [value, filterValue]);
+    }
+
+    return value;
+  }
+
+  async keys() {
+    const keys = new Set();
+
+    // Enumerate all keys in the tree that can be found in the filter tree.
+    for (const key of await this.tree.keys()) {
+      const filterValue = await this.filter.get(key);
+      const isFilterValueTree = Tree.isAsyncTree(filterValue);
+      // If the filter value is a tree, the corresponding value in the tree
+      // must be a tree too.
+      const match =
+        (!isFilterValueTree && filterValue) ||
+        (isFilterValueTree && (await Tree.isKeyForSubtree(this.tree, key)));
+      if (match) {
+        keys.add(key);
+      }
+    }
+
+    // Also include any keys in the filter that are found in the tree. This
+    // lets the filter "pull" values from a tree that, e.g., is defined by a
+    // function without an explicit domain.
+    for (const key of await this.filter.keys()) {
+      const value = await this.tree.get(key);
+      if (value !== undefined) {
+        keys.add(key);
+      }
+    }
+
+    return keys;
+  }
+}

package/src/common/GlobTree.js

@@ -0,0 +1,67 @@
+import { ObjectTree, Tree, merge } from "@weborigami/async-tree";
+
+const globstar = "**";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class GlobTree {
+  constructor(globs) {
+    this.globs = Tree.from(globs);
+  }
+
+  async get(key) {
+    if (typeof key !== "string") {
+      return undefined;
+    }
+    let value = await matchGlobs(this.globs, key);
+    if (Tree.isAsyncTree(value)) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+    return value;
+  }
+
+  async keys() {
+    return this.globs.keys();
+  }
+}
+
+function matchGlob(glob, text) {
+  // Convert the glob to a regular expression
+  const regexText = glob
+    // Escape special regex characters
+    .replace(/[+?^${}()|\[\]\\]/g, "\\$&")
+    // Replace the glob wildcards with regex wildcards
+    .replace(/\*/g, ".+")
+    .replace(/\?/g, ".");
+  const regex = new RegExp(`^${regexText}$`);
+  return regex.test(text);
+}
+
+async function matchGlobs(globs, text) {
+  let value;
+  for (const glob of await globs.keys()) {
+    if (typeof glob !== "string") {
+      continue;
+    } else if (glob !== globstar && matchGlob(glob, text)) {
+      value = await globs.get(glob);
+      if (value !== undefined) {
+        break;
+      }
+    }
+  }
+
+  const globstarGlobs = await globs.get(globstar);
+  if (globstarGlobs) {
+    const globstarTree = new ObjectTree({ [globstar]: globstarGlobs });
+    if (value === undefined) {
+      const globstarValue = await matchGlobs(globstarGlobs, text);
+      value = globstarValue !== undefined ? globstarValue : globstarTree;
+    } else if (Tree.isAsyncTree(value)) {
+      value = merge(value, globstarTree);
+    }
+  }
+
+  return value;
+}

package/src/common/ShuffleTransform.js

@@ -0,0 +1,29 @@
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Constructor<AsyncTree>} AsyncTreeConstructor
+ * @param {AsyncTreeConstructor} Base
+ */
+export default function ShuffleTransform(Base) {
+  return class Shuffle extends Base {
+    async keys() {
+      const keys = Array.from(await super.keys());
+      shuffle(keys);
+      return keys;
+    }
+  };
+}
+
+/*
+ * Shuffle an array.
+ *
+ * Performs a Fisher-Yates shuffle. From http://sedition.com/perl/javascript-fy.html
+ */
+function shuffle(array) {
+  var i = array.length;
+  while (--i >= 0) {
+    var j = Math.floor(Math.random() * (i + 1));
+    var temp = array[i];
+    array[i] = array[j];
+    array[j] = temp;
+  }
+}

package/src/common/TextDocument.js

@@ -0,0 +1,57 @@
+import { isStringLike } from "@weborigami/async-tree";
+import { toYaml } from "./serialize.js";
+import * as utilities from "./utilities.js";
+
+/**
+ * A text document is any object with a `@text` property and a `toString()`
+ * method that returns that text. This class is a helper for constructing such
+ * text documents.
+ */
+export default class TextDocument {
+  /**
+   * The `input` parameter can be anything that can be converted to a string.
+   * The optional `data` parameter can be any object; if the object is a plain
+   * object, its properties will be copied to the new document; otherwise, that
+   * parameter is ignored.
+   *
+   * @typedef {import("@weborigami/types").AsyncTree|null} AsyncTree
+   *
+   * @param {any} [data]
+   * @param {AsyncTree} [parent]
+   */
+  constructor(data, parent) {
+    Object.assign(this, data);
+    if (parent) {
+      this[utilities.parentSymbol] = parent;
+    }
+  }
+
+  static from(input, parent) {
+    if (input["@text"]) {
+      return input;
+    } else if (isStringLike(input)) {
+      const text = utilities.toString(input);
+      return new TextDocument({ "@text": text }, parent);
+    }
+  }
+
+  /**
+   * Render the text and data as a document with YAML front matter.
+   */
+  async pack() {
+    const text = this["@text"];
+    /** @type {any} */
+    const dataWithoutText = Object.assign({}, this);
+    delete dataWithoutText["@text"];
+    if (Object.keys(dataWithoutText).length > 0) {
+      const frontMatter = (await toYaml(dataWithoutText)).trimEnd();
+      return `---\n${frontMatter}\n---\n${text}`;
+    } else {
+      return text;
+    }
+  }
+
+  toString() {
+    return this["@text"];
+  }
+}

package/src/common/addValueKeyToScope.js

@@ -0,0 +1,30 @@
+import { Scope } from "@weborigami/language";
+
+/**
+ * A number of transforms accept functions that can accept a single value. This
+ * helper adds the value and key to the scope as ambients.
+ *
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.js").Invocable} Invocable
+ *
+ * @param {AsyncTree|null} scope
+ * @param {any} value
+ * @param {any} key
+ * @param {string} [valueName]
+ * @param {string} [keyName]
+ */
+export default function addValueKeyToScope(
+  scope,
+  value,
+  key,
+  valueName = "_",
+  keyName = "@key"
+) {
+  // Add the key and value to the scope as ambients.
+  const ambients = {
+    [keyName]: key,
+    [valueName]: value,
+  };
+  return new Scope(ambients, scope);
+}

package/src/common/arrowFunctionsMap.js

@@ -0,0 +1,35 @@
+import { cachedKeyMaps, map } from "@weborigami/async-tree";
+import { toFunction } from "./utilities.js";
+
+export default function arrowFunctionsMap() {
+  const deep = true;
+  return map({
+    deep,
+    description: "arrowFunctions",
+    valueMap,
+    ...cachedKeyMaps(keyMap, deep),
+  });
+}
+
+function keyMap(sourceKey, tree) {
+  return parseArrowKey(sourceKey) ?? sourceKey;
+}
+
+// If the key is of the form "lhs←rhs", return "lhs".
+// Whitespace between the lhs and the arrow is ignored.
+function parseArrowKey(sourceKey) {
+  const regex = /^(?<lhs>.+?)\s*←.+$/;
+  const match = sourceKey.match(regex);
+  return match?.groups.lhs;
+}
+
+function valueMap(sourceValue, sourceKey, tree) {
+  let resultValue;
+  if (parseArrowKey(sourceKey)) {
+    // Treat the value as a function to be invoked.
+    resultValue = toFunction(sourceValue);
+  } else {
+    resultValue = sourceValue;
+  }
+  return resultValue;
+}

package/src/common/processUnpackedContent.js

@@ -0,0 +1,39 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import builtins from "../builtins/@builtins.js";
+
+/**
+ * Perform any necessary post-processing on the unpacked content of a file. This
+ * lets treat the contents of various file types consistently.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {any} content
+ * @param {AsyncTree|null} parent
+ * @param {any} [attachedData]
+ * @returns
+ */
+export default function processUnpackedContent(content, parent, attachedData) {
+  if (typeof content === "function") {
+    // Wrap the function such to add ambients to the scope.
+    const fn = content;
+
+    // Use the parent's scope, adding any attached data.
+    const parentScope = parent ? Scope.getScope(parent) : builtins;
+    const extendedScope = new Scope(attachedData, parentScope);
+
+    /** @this {AsyncTree|null} */
+    async function extendScope(input, ...rest) {
+      return fn.call(extendedScope, input, ...rest);
+    }
+
+    extendScope.code = fn.code;
+    return extendScope;
+  } else if (Tree.isAsyncTree(content)) {
+    const result = Object.create(content);
+    result.parent = parent;
+    return result;
+  } else {
+    return content;
+  }
+}

package/src/common/serialize.d.ts

@@ -0,0 +1,8 @@
+import type { AsyncTree } from "@weborigami/types";
+import type { JsonValue } from "../../index.ts";
+
+export function evaluateYaml(text: string, parent?: AsyncTree|null): Promise<JsonValue>;
+export function parseYaml(text: string): JsonValue|AsyncTree;
+export function toJson(obj: JsonValue | AsyncTree): Promise<string>;
+export function toJsonValue(obj: any): Promise<JsonValue>;
+export function toYaml(obj: JsonValue | AsyncTree): Promise<string>;

package/src/common/serialize.js

@@ -0,0 +1,138 @@
+/**
+ * @typedef {import("../../index.ts").JsonValue} JsonValue
+ * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ */
+
+import { Tree, isPlainObject, isStringLike } from "@weborigami/async-tree";
+import { OrigamiTree } from "@weborigami/language";
+import * as YAMLModule from "yaml";
+import yamlOrigamiTag from "../misc/yamlOrigamiTag.js";
+
+const textDecoder = new TextDecoder();
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
+// The "yaml" package doesn't seem to provide a default export that the browser can
+// recognize, so we have to handle two ways to accommodate Node and the browser.
+// @ts-ignore
+const YAML = YAMLModule.default ?? YAMLModule.YAML;
+
+/**
+ *
+ * @param {string} text
+ * @param {AsyncTree|null} [parent]
+ */
+export async function evaluateYaml(text, parent) {
+  const data = parseYaml(String(text));
+  if (Tree.isAsyncTree(data)) {
+    data.parent = parent;
+    return Tree.plain(data);
+  } else {
+    return data;
+  }
+}
+
+/**
+ * @param {any} obj
+ * @returns {obj is JsonValue}
+ */
+function isJsonValue(obj) {
+  const t = typeof obj;
+  return (
+    t === "boolean" ||
+    t === "number" ||
+    t === "string" ||
+    obj instanceof Date ||
+    obj === null
+  );
+}
+
+// Return true if the given object has any functions in it.
+function objectContainsFunctions(obj) {
+  for (const key in obj) {
+    const value = obj[key];
+    if (typeof value === "function") {
+      return true;
+    } else if (isPlainObject(value)) {
+      const valueContainsExpression = objectContainsFunctions(value);
+      if (valueContainsExpression) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} text
+ * @returns {JsonValue|AsyncTree}
+ */
+export function parseYaml(text) {
+  const data = YAML.parse(text, {
+    customTags: [yamlOrigamiTag],
+  });
+  if (objectContainsFunctions(data)) {
+    return new OrigamiTree(data);
+  } else {
+    return data;
+  }
+}
+
+/**
+ * Serializes an object as a JSON string.
+ *
+ * @param {any} obj
+ */
+export async function toJson(obj) {
+  const serializable = await toJsonValue(obj);
+  return JSON.stringify(serializable, null, 2);
+}
+
+/**
+ * Convert the given object to a corresponding JSON value that can be serialized
+ * as JSON or YAML.
+ *
+ * If the object is already a JSON value, it is returned as is.
+ *
+ * If the object implements the `pack()` method, that method's result will be
+ * returned.
+ *
+ * If the object is treelike, it will be converted to a plain JavaScript
+ * object, recursively traversing the tree and converting all values to native
+ * types.
+ *
+ * If the object has a `valueOf()` or `toString()` method, that method's result
+ * will be returned.
+ *
+ * @param {any} object
+ * @returns {Promise<JsonValue>}
+ */
+export async function toJsonValue(object) {
+  if (isJsonValue(object)) {
+    return object;
+  } else if (object && typeof object.pack === "function") {
+    return object.pack();
+  } else if (isStringLike(object) && !(object instanceof Array)) {
+    return String(object);
+  } else if (Tree.isTreelike(object)) {
+    const mapped = await Tree.map(object, (value) => toJsonValue(value));
+    return Tree.plain(mapped);
+  } else if (object instanceof ArrayBuffer || object instanceof TypedArray) {
+    // Serialize data as UTF-8.
+    return textDecoder.decode(object);
+  }
+
+  throw new TypeError("Couldn't serialize object");
+}
+
+/**
+ * Serializes an object as a JSON string.
+ *
+ * @param {any} obj
+ * @returns {Promise<string>}
+ */
+export async function toYaml(obj) {
+  const serializable = await toJsonValue(obj);
+  return YAML.stringify(serializable);
+}

package/src/common/utilities.d.ts

@@ -0,0 +1,7 @@
+
+export const keySymbol: unique symbol;
+export const parentSymbol: unique symbol;
+export function isTransformApplied(Transform: Function, object: any): boolean;
+export function toFunction(object: any): Function;
+export function toString(object: any): string|null;
+export function transformObject(Transform: Function, object: any): any;