@weborigami/origami 0.0.73 → 0.2.0

package/main.js

@@ -0,0 +1,12 @@
+export * from "./src/calc/calc.js";
+export { default as documentObject } from "./src/common/documentObject.js";
+export { toString } from "./src/common/utilities.js";
+export * from "./src/dev/dev.js";
+export * from "./src/handlers/handlerExports.js";
+export * from "./src/handlers/handlers.js";
+export * from "./src/image/image.js";
+export { builtinsTree } from "./src/internal.js";
+export * from "./src/origami/origami.js";
+export * from "./src/site/site.js";
+export * from "./src/text/text.js";
+export * from "./src/tree/tree.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/origami",
-  "version": "0.0.73",
+  "version": "0.2.0",
   "description": "Web Origami language, CLI, framework, and server",
   "type": "module",
   "repository": {
@@ -10,16 +10,16 @@
   "bin": {
     "ori": "src/cli/cli.js"
   },
-  "main": "./exports/exports.js",
+  "main": "./main.js",
   "types": "./index.ts",
   "devDependencies": {
     "@types/node": "22.7.4",
     "typescript": "5.6.2"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.0.73",
-    "@weborigami/language": "0.0.73",
-    "@weborigami/types": "0.0.73",
+    "@weborigami/async-tree": "0.2.0",
+    "@weborigami/language": "0.2.0",
+    "@weborigami/types": "0.2.0",
     "exif-parser": "0.1.12",
     "graphviz-wasm": "3.0.2",
     "highlight.js": "11.10.0",
@@ -31,8 +31,6 @@
     "yaml": "2.5.1"
   },
   "scripts": {
-    "build": "ori exports/buildExports.js src > exports/exports.js",
-    "prepublishOnly": "npm run build",
     "test": "node --test --test-reporter=spec",
     "typecheck": "node node_modules/typescript/bin/tsc"
   }

package/src/builtins.js

@@ -0,0 +1,62 @@
+import * as calc from "./calc/calc.js";
+import deprecated from "./deprecated.js";
+import * as dev from "./dev/dev.js";
+import * as handlers from "./handlers/handlers.js";
+import help from "./help/help.js";
+import * as image from "./image/image.js";
+import js from "./js.js";
+import node from "./node.js";
+import * as origami from "./origami/origami.js";
+import explore from "./protocols/explore.js";
+import files from "./protocols/files.js";
+import http from "./protocols/http.js";
+import https from "./protocols/https.js";
+import httpstree from "./protocols/httpstree.js";
+import httptree from "./protocols/httptree.js";
+import inherited from "./protocols/inherited.js";
+import instantiate from "./protocols/new.js";
+import packageNamespace from "./protocols/package.js";
+import scope from "./protocols/scope.js";
+import * as site from "./site/site.js";
+import * as text from "./text/text.js";
+import * as tree from "./tree/tree.js";
+
+/** @type {any} */
+export default {
+  "calc:": adjustReservedWords(calc),
+  "dev:": dev,
+  "explore:": explore,
+  "files:": files,
+  "help:": help,
+  "http:": http,
+  "https:": https,
+  "httpstree:": httpstree,
+  "httptree:": httptree,
+  "image:": image,
+  "inherited:": inherited,
+  "js:": js,
+  "new:": instantiate,
+  "node:": node,
+  "origami:": origami,
+  "package:": packageNamespace,
+  "scope:": scope,
+  "site:": adjustReservedWords(site),
+  "text:": text,
+  "tree:": tree,
+
+  // Some builtins need to be exposed at top level
+  ...handlers.default,
+
+  // Deprecated builtins
+  ...deprecated,
+};
+
+// Handle cases where a builtin name conflicts with a JS reserved word
+function adjustReservedWords(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const name = value.key ?? key;
+    result[name] = value;
+  }
+  return result;
+}

package/src/builtinsTree.js

@@ -0,0 +1,36 @@
+import { trailingSlash } from "@weborigami/async-tree";
+import builtins from "./builtins.js";
+
+const expanded = { ...builtins };
+
+// For all builtins like `tree:keys`, add a shorthand `keys`.
+for (const [key, value] of Object.entries(expanded)) {
+  const isNamespace = key.endsWith(":");
+  if (isNamespace) {
+    for (const [subKey, subValue] of Object.entries(value)) {
+      // HACK: Skip description keys until we can make them all non-enumerable.
+      if (subKey === "description") {
+        continue;
+      }
+      if (subKey in expanded) {
+        throw new Error(`Internal Origami error: Duplicate key: ${subKey}`);
+      }
+      expanded[subKey] = subValue;
+    }
+  }
+}
+
+// We create our own tree instead of using ObjectTree, since that binds the
+// functions would be bound to the object. We want to leave them unbound.
+class BuiltinsTree {
+  async get(key) {
+    const normalizedKey = trailingSlash.remove(key);
+    return expanded[normalizedKey];
+  }
+
+  async keys() {
+    return Object.keys(expanded);
+  }
+}
+
+export default new BuiltinsTree();

package/src/calc/calc.js

@@ -0,0 +1,71 @@
+import { Tree } from "@weborigami/async-tree";
+import assertTreeIsDefined from "../common/assertTreeIsDefined.js";
+
+export function add(...args) {
+  const numbers = args.map((arg) => Number(arg));
+  return numbers.reduce((acc, val) => acc + val, 0);
+}
+
+export function and(...args) {
+  console.warn(`Warning: "and" is deprecated. Use the "&&" operator instead.`);
+  return args.every((arg) => arg);
+}
+
+export function divide(a, b) {
+  return Number(a) / Number(b);
+}
+
+export function equals(a, b) {
+  console.warn(
+    `Warning: "equals" is deprecated. Use the "===" operator instead.`
+  );
+  return a === b;
+}
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {any} value
+ * @param {any} trueResult
+ * @param {any} [falseResult]
+ */
+export async function ifBuiltin(value, trueResult, falseResult) {
+  console.warn(
+    `Warning: "if" is deprecated. Use the conditional "a ? b : c" operator instead.`
+  );
+
+  assertTreeIsDefined(this, "calc:if");
+  let condition = await value;
+  if (Tree.isAsyncTree(condition)) {
+    const keys = Array.from(await condition.keys());
+    condition = keys.length > 0;
+  }
+
+  // 0 is true, null/undefined/false is false
+  let result = condition || condition === 0 ? trueResult : falseResult;
+  if (typeof result === "function") {
+    result = await result.call(this);
+  }
+  return result;
+}
+ifBuiltin.key = "if";
+
+export function multiply(...args) {
+  const numbers = args.map((arg) => Number(arg));
+  return numbers.reduce((acc, val) => acc * val, 1);
+}
+
+export function not(value) {
+  console.warn(`Warning: "not" is deprecated. Use the "!" operator instead.`);
+  return !value;
+}
+
+export function or(...args) {
+  console.warn(`Warning: "or" is deprecated. Use the "||" operator instead.`);
+  return args.find((arg) => arg);
+}
+
+export function subtract(a, b) {
+  return Number(a) - Number(b);
+}

package/src/cli/cli.js

@@ -4,9 +4,9 @@ import { Tree } from "@weborigami/async-tree";
 import { formatError } from "@weborigami/language";
 import path from "node:path";
 import process, { stdout } from "node:process";
-import ori from "../builtins/@ori.js";
-import project from "../builtins/@project.js";
-import showUsage from "./showUsage.js";
+import help from "../help/help.js";
+import ori from "../origami/ori.js";
+import project from "../origami/project.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
@@ -20,7 +20,8 @@ async function main(...args) {
   if (!expression) {
     // HACK: the config is the parent of the project tree.
     const config = projectTree.parent;
-    await showUsage(config);
+    const usage = await help.call(config);
+    console.log(usage);
     return;
   }
 
@@ -30,6 +31,7 @@ async function main(...args) {
   const tree = await Tree.traversePath(projectTree, relative);
 
   const result = await ori.call(tree, expression);
+
   if (result !== undefined) {
     const output =
       result instanceof ArrayBuffer

package/src/{misc → common}/assertTreeIsDefined.js

@@ -1,5 +1,8 @@
+import { Tree } from "@weborigami/async-tree";
+
 export default function assertTreeIsDefined(tree, methodName) {
-  if (tree === undefined) {
+  const isValid = tree === null || Tree.isAsyncTree(tree);
+  if (!isValid) {
     throw new Error(
       `${methodName} must be called with a tree target. If you don't want to pass a tree, invoke with: ${methodName}.call(null)`
     );

package/src/common/constructHref.js

@@ -0,0 +1,20 @@
+import { pathFromKeys } from "@weborigami/async-tree";
+
+/**
+ * Given a protocol, a host, and a list of keys, construct an href.
+ *
+ * @param {string} protocol
+ * @param {string} host
+ * @param  {string[]} keys
+ */
+export default function constructHref(protocol, host, ...keys) {
+  const path = pathFromKeys(keys);
+  let href = [host, path].join("/");
+  if (!href.startsWith(protocol)) {
+    if (!href.startsWith("//")) {
+      href = `//${href}`;
+    }
+    href = `${protocol}${href}`;
+  }
+  return href;
+}

package/src/common/constructSiteTree.js

@@ -0,0 +1,34 @@
+import { trailingSlash } from "@weborigami/async-tree";
+import { HandleExtensionsTransform } from "@weborigami/language";
+import constructHref from "./constructHref.js";
+
+/**
+ * Given a protocol, a host, and a list of keys, construct an href.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {string} protocol
+ * @param {import("../../index.ts").Constructor<AsyncTree>} treeClass
+ * @param {AsyncTree|null} parent
+ * @param {string} host
+ * @param  {string[]} keys
+ */
+export default function constructSiteTree(
+  protocol,
+  treeClass,
+  parent,
+  host,
+  ...keys
+) {
+  // If the last key doesn't end in a slash, remove it for now.
+  let lastKey;
+  if (keys.length > 0 && keys.at(-1) && !trailingSlash.has(keys.at(-1))) {
+    lastKey = keys.pop();
+  }
+
+  const href = constructHref(protocol, host, ...keys);
+  let result = new (HandleExtensionsTransform(treeClass))(href);
+  result.parent = parent;
+
+  return lastKey ? result.get(lastKey) : result;
+}

package/src/common/fetchAndHandleExtension.js

@@ -0,0 +1,26 @@
+import { handleExtension } from "@weborigami/language";
+
+/**
+ * Fetch the resource at the given href.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {string} href
+ */
+export default async function fetchAndHandleExtension(href) {
+  const response = await fetch(href);
+  if (!response.ok) {
+    return undefined;
+  }
+  let buffer = await response.arrayBuffer();
+
+  // Attach any loader defined for the file type.
+  const url = new URL(href);
+  const filename = url.pathname.split("/").pop();
+  if (this && filename) {
+    buffer = await handleExtension(this, buffer, filename);
+  }
+
+  return buffer;
+}

package/src/{misc → common}/getTreeArgument.js

@@ -25,7 +25,7 @@ export default async function getTreeArgument(
   args,
   treelike,
   methodName,
-  deep = false
+  deep
 ) {
   assertTreeIsDefined(parent, methodName);
 
@@ -34,16 +34,22 @@ export default async function getTreeArgument(
       treelike = await treelike.unpack();
     }
     if (Tree.isTreelike(treelike)) {
-      let tree = Tree.from(treelike, { deep });
+      const options = deep !== undefined ? { deep } : undefined;
+      let tree = Tree.from(treelike, options);
       // If the tree was created from a treelike object and does not yet have a
       // parent, make the current tree its parent.
-      if (!tree.parent) {
+      if (!tree.parent && parent !== undefined) {
+        if (parent !== null && !Tree.isAsyncTree(parent)) {
+          throw new Error(
+            `The parent argument passed to ${methodName} must be a tree.`
+          );
+        }
         tree.parent = parent;
       }
       return tree;
     }
     throw new Error(
-      `${methodName}: The first argument must be a tree, like an array, object, or files.`
+      `The first argument to ${methodName} must be a tree, like an array, object, or files.`
     );
   }
 
@@ -57,5 +63,5 @@ export default async function getTreeArgument(
     return parent;
   }
 
-  throw new Error(`${methodName}: The first argument was undefined.`);
+  throw new Error(`The first argument to ${methodName} was undefined.`);
 }

package/src/common/processUnpackedContent.js

@@ -1,5 +1,5 @@
 import { symbols, Tree } from "@weborigami/async-tree";
-import builtins from "../builtins/@builtins.js";
+import { builtinsTree } from "../internal.js";
 
 /**
  * Perform any necessary post-processing on the unpacked content of a file. This
@@ -9,21 +9,12 @@ import builtins from "../builtins/@builtins.js";
  *
  * @param {any} content
  * @param {AsyncTree|null} parent
- * @param {any} [attachedData]
  * @returns
  */
-export default function processUnpackedContent(content, parent, attachedData) {
+export default function processUnpackedContent(content, parent) {
   if (typeof content === "function") {
-    // Bind the function to a target that's the attached data (if it exists) or
-    // the parent.
-    const base = parent ?? builtins;
-    let target;
-    if (attachedData) {
-      target = Tree.from(attachedData);
-      target.parent = base;
-    } else {
-      target = base;
-    }
+    // Bind the function to the parent as the `this` context.
+    const target = parent ?? builtinsTree;
     const result = content.bind(target);
     if (content.code) {
       result.code = content.code;

package/src/common/utilities.d.ts

@@ -1,8 +1,7 @@
 
-export const keySymbol: unique symbol;
+export function getDescriptor(object: any): string;
 export function hasNonPrintableCharacters(text: string): boolean;
 export function isTransformApplied(Transform: Function, object: any): boolean;
-export function replaceExtension(key: string, sourceExtension: string, resultExtension: string): string;
 export function toFunction(object: any): Function;
 export function toString(object: any): string|null;
 export function transformObject(Transform: Function, object: any): any;

package/src/common/utilities.js

@@ -5,6 +5,27 @@ import {
   isUnpackable,
   trailingSlash,
 } from "@weborigami/async-tree";
+import { symbols } from "@weborigami/language";
+import { basename } from "node:path";
+
+// For a given tree, return some user-friendly descriptor
+export function getDescriptor(tree) {
+  if ("path" in tree) {
+    return trailingSlash.add(basename(tree.path));
+  }
+
+  const source = tree[symbols.sourceSymbol];
+  if (source) {
+    // If the source looks like an identifier, use that.
+    // TODO: Use real identifier parsing.
+    const identifierRegex = /^[A-Za-z0-9_\-\.]+\/?$/;
+    if (identifierRegex.test(source)) {
+      return trailingSlash.add(source);
+    }
+  }
+
+  return null;
+}
 
 // Return true if the text appears to contain non-printable binary characters;
 // used to infer whether a file is binary or text.
@@ -31,40 +52,12 @@ export function isTransformApplied(Transform, obj) {
   return false;
 }
 
-export const keySymbol = Symbol("key");
-
-/**
- * If the given key ends in the source extension (which will generally include a
- * period), replace that extension with the result extension (which again should
- * generally include a period). Otherwise, return the key as is.
- *
- * If the key ends in a trailing slash, that will be preserved in the result.
- *
- * @param {string} key
- * @param {string} sourceExtension
- * @param {string} resultExtension
- */
-export function replaceExtension(key, sourceExtension, resultExtension) {
-  if (!key) {
-    return undefined;
-  }
-
-  const normalizedKey = trailingSlash.remove(key);
-  if (!normalizedKey.endsWith(sourceExtension)) {
-    return normalizedKey;
-  }
-
-  const replaced =
-    normalizedKey.slice(0, -sourceExtension.length) + resultExtension;
-  return trailingSlash.toggle(replaced, trailingSlash.has(key));
-}
-
 /**
  * Convert the given object to a function.
  *
  * @typedef {import("../../index.ts").Invocable} Invocable
  * @param {any} obj
- * @returns {Function}
+ * @returns {Function|null}
  */
 export function toFunction(obj) {
   if (typeof obj === "function") {
@@ -88,8 +81,8 @@ export function toFunction(obj) {
     // Return a function that invokes the tree's getter.
     return Tree.toFunction(obj);
   } else {
-    // Return a constant function.
-    return () => obj;
+    // Not a function
+    return null;
   }
 }
 

package/src/deprecated.js

@@ -0,0 +1,140 @@
+import { Tree } from "@weborigami/async-tree";
+import * as calc from "./calc/calc.js";
+import * as dev from "./dev/dev.js";
+import * as image from "./image/image.js";
+import js from "./js.js";
+import node from "./node.js";
+import * as origami from "./origami/origami.js";
+import files from "./protocols/files.js";
+import * as site from "./site/site.js";
+import * as text from "./text/text.js";
+import * as tree from "./tree/tree.js";
+
+const warningsDisplayedForKeys = new Set();
+
+export function command(namespace, newKey, oldKey, fn) {
+  const wrappedFn = function (...args) {
+    const keys = newKey
+      ? `"${namespace}${newKey}" or just "${newKey}"`
+      : `"${namespace}"`;
+    if (!warningsDisplayedForKeys.has(oldKey)) {
+      console.warn(
+        `ori: Warning: "${oldKey}" is deprecated. Use ${keys} instead.`
+      );
+      warningsDisplayedForKeys.add(oldKey);
+    }
+    return fn instanceof Function
+      ? // @ts-ignore
+        fn.call(this, ...args)
+      : Tree.traverseOrThrow(fn, ...args);
+  };
+  if (fn.key) {
+    wrappedFn.key = fn.key;
+  }
+  if (fn.inverseKey) {
+    wrappedFn.inverseKey = fn.inverseKey;
+  }
+  return wrappedFn;
+}
+
+export function commands(namespace, object) {
+  const deprecatedEntries = Object.entries(object).map(([key, fn]) => [
+    `@${fn.key ?? key}`,
+    command(namespace, fn.key ?? key, `@${fn.key ?? key}`, fn),
+  ]);
+  return Object.fromEntries(deprecatedEntries);
+}
+
+export default {
+  ...commands("calc:", calc),
+  ...commands("dev:", dev),
+  "@false": command("js:", "false", "@false", js.false),
+  "@fetch": command("js:", "fetch", "@fetch", js.fetch),
+  "@files": command("files:", null, "@files/", files),
+  "@image": command("image:", null, "@image/", image),
+  "@js": command("js:", null, "@js/", js),
+  "@math": command("calc:", null, "@math/", calc),
+  "@mdHtml": command("text:", "mdHtml", "@mdHtml", text.mdHtml),
+  "@node": command("node:", null, "@node/", node),
+  ...commands("origami:", origami),
+  ...commands("site:", site),
+  ...commands("text:", text),
+  ...commands("tree:", tree),
+  "@tree": command("tree:", null, "@tree/", Tree),
+  "@true": command("js:", "true", "@true", js.true),
+
+  // Renamed commands
+  "@clean": command("tree:", "clear", "@clean", tree.clear),
+
+  // Deprecated commands
+  "@deepTakeFn": command(
+    "tree:",
+    "deepTake",
+    "@deepTakeFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.deepTake.call(this, treelike, options);
+      }
+  ),
+  "@deepMapFn": command(
+    "tree:",
+    "deepMap",
+    "@deepMapFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.deepMap.call(this, treelike, options);
+      }
+  ),
+  "@groupFn": command(
+    "tree:",
+    "group",
+    "@groupFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.group.call(this, treelike, options);
+      }
+  ),
+  "@mapFn": command(
+    "tree:",
+    "map",
+    "@mapFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.map.call(this, treelike, options);
+      }
+  ),
+  "@paginateFn": command(
+    "tree:",
+    "paginate",
+    "@paginateFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.paginate.call(this, treelike, options);
+      }
+  ),
+  "@sortFn": command(
+    "tree:",
+    "sort",
+    "@sortFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.sort.call(this, treelike, options);
+      }
+  ),
+  "@takeFn": command(
+    "tree:",
+    "take",
+    "@takeFn",
+    (options) =>
+      /** @this {any} */
+      function (treelike) {
+        return tree.take.call(this, treelike, options);
+      }
+  ),
+};

package/src/{common → dev}/ExplorableSiteTransform.js

@@ -1,6 +1,6 @@
 import { Tree, jsonKeys } from "@weborigami/async-tree";
-import index from "../builtins/@index.js";
 import { isTransformApplied, transformObject } from "../common/utilities.js";
+import index from "../site/index.js";
 
 /**
  * Wraps a tree (typically a SiteTree) to turn a standard site into an

package/src/{misc → dev}/OriCommandTransform.js

@@ -1,5 +1,5 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
-import ori from "../builtins/@ori.js";
+import ori from "../origami/ori.js";
 
 /**
  * Add support for commands prefixed with `!`.
@@ -7,7 +7,7 @@ import ori from "../builtins/@ori.js";
  * E.g., asking this tree for `!yaml` will invoke the yaml() builtin function
  * in the context of this tree.
  *
- * @typedef {import("../../index.js").Constructor<AsyncTree>} AsyncTreeConstructor
+ * @typedef {import("../../index.ts").Constructor<AsyncTree>} AsyncTreeConstructor
  * @param {AsyncTreeConstructor} Base
  */
 export default function OriCommandTransform(Base) {