@weborigami/async-tree 0.5.4 → 0.5.6

package/src/utilities/isPlainObject.js

@@ -0,0 +1,29 @@
+import getRealmObjectPrototype from "./getRealmObjectPrototype.js";
+
+/**
+ * Return true if the object is a plain JavaScript object created by `{}`,
+ * `new Object()`, or `Object.create(null)`.
+ *
+ * This function also considers object-like things with no prototype (like a
+ * `Module`) as plain objects.
+ *
+ * @typedef {import("../../index.ts").PlainObject} PlainObject
+ *
+ * @param {any} obj
+ * @returns {obj is PlainObject}
+ */
+export default function isPlainObject(obj) {
+  // From https://stackoverflow.com/q/51722354/76472
+  if (typeof obj !== "object" || obj === null) {
+    return false;
+  }
+
+  // We treat object-like things with no prototype (like a Module) as plain
+  // objects.
+  if (Object.getPrototypeOf(obj) === null) {
+    return true;
+  }
+
+  // Do we inherit directly from Object in this realm?
+  return Object.getPrototypeOf(obj) === getRealmObjectPrototype(obj);
+}

package/src/utilities/isPrimitive.js

@@ -0,0 +1,13 @@
+/**
+ * Return true if the value is a primitive JavaScript value.
+ *
+ * @param {any} value
+ */
+export default function isPrimitive(value) {
+  // Check for null first, since typeof null === "object".
+  if (value === null) {
+    return true;
+  }
+  const type = typeof value;
+  return type !== "object" && type !== "function";
+}

package/src/utilities/isStringlike.js

@@ -0,0 +1,25 @@
+import getRealmObjectPrototype from "./getRealmObjectPrototype.js";
+
+/**
+ * Return true if the object is a string or object with a non-trival `toString`
+ * method.
+ *
+ * @typedef {import("../../index.ts").Stringlike} Stringlike
+ *
+ * @param {any} obj
+ * @returns {obj is Stringlike}
+ */
+export default function isStringlike(obj) {
+  if (typeof obj === "string") {
+    return true;
+  } else if (obj?.toString === undefined) {
+    return false;
+  } else if (obj.toString === getRealmObjectPrototype(obj)?.toString) {
+    // The stupid Object.prototype.toString implementation always returns
+    // "[object Object]", so if that's the only toString method the object has,
+    // we return false.
+    return false;
+  } else {
+    return true;
+  }
+}

package/src/utilities/isUnpackable.js

@@ -0,0 +1,13 @@
+import isPacked from "./isPacked.js";
+
+/**
+ * @typedef {import("../../index.ts").Unpackable} Unpackable
+ *
+ * @param {any} obj
+ * @returns {obj is Unpackable}
+ */
+export default function isUnpackable(obj) {
+  return (
+    isPacked(obj) && typeof (/** @type {any} */ (obj).unpack) === "function"
+  );
+}

package/src/utilities/keysFromPath.js

@@ -0,0 +1,34 @@
+import * as trailingSlash from "../trailingSlash.js";
+
+/**
+ * Given a path like "/foo/bar/baz", return an array of keys like ["foo/",
+ * "bar/", "baz"].
+ *
+ * Leading slashes are ignored. Consecutive slashes will be ignored. Trailing
+ * slashes are preserved.
+ *
+ * @param {string} pathname
+ */
+export default function keysFromPath(pathname) {
+  // Split the path at each slash
+  let keys = pathname.split("/");
+  if (keys[0] === "") {
+    // The path begins with a slash; drop that part.
+    keys.shift();
+  }
+  if (keys.at(-1) === "") {
+    // The path ends with a slash; drop that part.
+    keys.pop();
+  }
+  // Drop any empty keys
+  keys = keys.filter((key) => key !== "");
+  // Add the trailing slash back to all keys but the last
+  for (let i = 0; i < keys.length - 1; i++) {
+    keys[i] += "/";
+  }
+  // Add trailing slash to last key if path ended with a slash
+  if (keys.length > 0 && trailingSlash.has(pathname)) {
+    keys[keys.length - 1] += "/";
+  }
+  return keys;
+}

package/src/utilities/naturalOrder.js

@@ -0,0 +1,9 @@
+/**
+ * Compare two strings using [natural sort
+ * order](https://en.wikipedia.org/wiki/Natural_sort_order).
+ */
+const naturalOrder = new Intl.Collator(undefined, {
+  numeric: true,
+}).compare;
+
+export default naturalOrder;

package/src/utilities/pathFromKeys.js

@@ -0,0 +1,18 @@
+import * as trailingSlash from "../trailingSlash.js";
+
+/**
+ * Return a slash-separated path for the given keys.
+ *
+ * This takes care to avoid adding consecutive slashes if they keys themselves
+ * already have trailing slashes.
+ *
+ * @param {string[]} keys
+ */
+export default function pathFromKeys(keys) {
+  // Ensure there's a slash between all keys. If the last key has a trailing
+  // slash, leave it there.
+  const normalized = keys.map((key, index) =>
+    index < keys.length - 1 ? trailingSlash.add(key) : key
+  );
+  return normalized.join("");
+}

package/src/utilities/setParent.js

@@ -0,0 +1,38 @@
+import isAsyncTree from "../operations/isAsyncTree.js";
+import * as symbols from "../symbols.js";
+
+/**
+ * If the child object doesn't have a parent yet, set it to the indicated
+ * parent. If the child is an AsyncTree, set the `parent` property. Otherwise,
+ * set the `symbols.parent` property.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {*} child
+ * @param {AsyncTree|null} parent
+ */
+export default function setParent(child, parent) {
+  if (isAsyncTree(child)) {
+    // Value is a subtree; set its parent to this tree.
+    if (!child.parent) {
+      child.parent = parent;
+    }
+  } else if (Object.isExtensible(child) && !child[symbols.parent]) {
+    try {
+      // Add parent reference as a symbol to avoid polluting the object. This
+      // reference will be used if the object is later used as a tree. We set
+      // `enumerable` to false even thought this makes no practical difference
+      // (symbols are never enumerated) because it can provide a hint in the
+      // debugger that the property is for internal use.
+      Object.defineProperty(child, symbols.parent, {
+        configurable: true,
+        enumerable: false,
+        value: parent,
+        writable: true,
+      });
+    } catch (error) {
+      // Ignore exceptions. Some esoteric objects don't allow adding properties.
+      // We can still treat them as trees, but they won't have a parent.
+    }
+  }
+}

package/src/utilities/toFunction.js

@@ -0,0 +1,40 @@
+import from from "../operations/from.js";
+import isTreelike from "../operations/isTreelike.js";
+import isUnpackable from "./isUnpackable.js";
+
+/**
+ * Convert the given object to a function.
+ *
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @param {Invocable} obj
+ * @returns {Function|null}
+ */
+export default function toFunction(obj) {
+  if (typeof obj === "function") {
+    // Return a function as is.
+    return obj;
+  } else if (isUnpackable(obj)) {
+    // Extract the contents of the object and convert that to a function.
+    let fnPromise;
+    return async function (...args) {
+      if (!fnPromise) {
+        // unpack() may return a function or a promise for a function; normalize
+        // to a promise for a function
+        const unpackPromise = Promise.resolve(
+          /** @type {any} */ (obj).unpack()
+        );
+        fnPromise = unpackPromise.then((content) => toFunction(content));
+      }
+      const fn = await fnPromise;
+      return fn(...args);
+    };
+  } else if (isTreelike(obj)) {
+    // Return a function that invokes the tree's getter.
+    const tree = from(obj);
+    return tree.get.bind(tree);
+  } else {
+    // Not a function
+    return null;
+  }
+}

package/src/utilities/toPlainValue.js

@@ -0,0 +1,95 @@
+import ObjectTree from "../drivers/ObjectTree.js";
+import isTreelike from "../operations/isTreelike.js";
+import mapReduce from "../operations/mapReduce.js";
+import * as trailingSlash from "../trailingSlash.js";
+import castArraylike from "./castArraylike.js";
+import isPrimitive from "./isPrimitive.js";
+import isStringlike from "./isStringlike.js";
+import toString from "./toString.js";
+import TypedArray from "./TypedArray.js";
+
+/**
+ * Convert the given input to the plainest possible JavaScript value. This
+ * helper is intended for functions that want to accept an argument from the ori
+ * CLI, which could a string, a stream of data, or some other kind of JavaScript
+ * object.
+ *
+ * If the input is a function, it will be invoked and its result will be
+ * processed.
+ *
+ * If the input is a promise, it will be resolved and its result will be
+ * processed.
+ *
+ * If the input is treelike, it will be converted to a plain JavaScript object,
+ * recursively traversing the tree and converting all values to plain types.
+ *
+ * If the input is stringlike, its text will be returned.
+ *
+ * If the input is a ArrayBuffer or typed array, it will be interpreted as UTF-8
+ * text if it does not contain unprintable characters. If it does, it will be
+ * returned as a base64-encoded string.
+ *
+ * If the input has a custom class instance, its public properties will be
+ * returned as a plain object.
+ *
+ * @param {any} input
+ * @returns {Promise<any>}
+ */
+export default async function toPlainValue(input) {
+  if (input instanceof Function) {
+    // Invoke function
+    input = input();
+  }
+  if (input instanceof Promise) {
+    // Resolve promise
+    input = await input;
+  }
+
+  if (isPrimitive(input) || input instanceof Date) {
+    return input;
+  } else if (isTreelike(input)) {
+    // Recursively convert tree to plain object.
+    return mapReduce(input, toPlainValue, (values, keys, tree) => {
+      // Special case for an empty tree: if based on array, return array.
+      if (tree instanceof ObjectTree && keys.length === 0) {
+        return /** @type {any} */ (tree).object instanceof Array ? [] : {};
+      }
+      // Normalize slashes in keys.
+      keys = keys.map(trailingSlash.remove);
+      return castArraylike(keys, values);
+    });
+  } else if (input instanceof ArrayBuffer || input instanceof TypedArray) {
+    // Try to interpret the buffer as UTF-8 text, otherwise use base64.
+    const text = toString(input);
+    if (text !== null) {
+      return text;
+    } else {
+      return toBase64(input);
+    }
+  } else if (isStringlike(input)) {
+    return toString(input);
+  } else {
+    // Some other kind of class instance; return its public properties.
+    const plain = {};
+    for (const [key, value] of Object.entries(input)) {
+      plain[key] = await toPlainValue(value);
+    }
+    return plain;
+  }
+}
+
+function toBase64(object) {
+  if (typeof Buffer !== "undefined") {
+    // Node.js environment
+    return Buffer.from(object).toString("base64");
+  } else {
+    // Browser environment
+    let binary = "";
+    const bytes = new Uint8Array(object);
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+  }
+}

package/src/utilities/toString.js

@@ -0,0 +1,37 @@
+import isPrimitive from "./isPrimitive.js";
+import isStringlike from "./isStringlike.js";
+import TypedArray from "./TypedArray.js";
+
+const textDecoder = new TextDecoder();
+
+/**
+ * Return a string form of the object, handling cases not generally handled by
+ * the standard JavaScript `toString()` method:
+ *
+ * 1. If the object is an ArrayBuffer or TypedArray, decode the array as UTF-8.
+ * 2. If the object is otherwise a plain JavaScript object with the useless
+ *    default toString() method, return null instead of "[object Object]". In
+ *    practice, it's generally more useful to have this method fail than to
+ *    return a useless string.
+ * 3. If the object is a defined primitive value, return the result of
+ *    String(object).
+ *
+ * Otherwise return null.
+ *
+ * @param {any} object
+ * @returns {string|null}
+ */
+export default function toString(object) {
+  if (object instanceof ArrayBuffer || object instanceof TypedArray) {
+    // Treat the buffer as UTF-8 text.
+    const decoded = textDecoder.decode(object);
+    // If the result appears to contain non-printable characters, it's probably not a string.
+    // https://stackoverflow.com/a/1677660/76472
+    const hasNonPrintableCharacters = /[\x00-\x08\x0E-\x1F]/.test(decoded);
+    return hasNonPrintableCharacters ? null : decoded;
+  } else if (isStringlike(object) || (object !== null && isPrimitive(object))) {
+    return String(object);
+  } else {
+    return null;
+  }
+}

package/test/drivers/ExplorableSiteTree.test.js

@@ -77,7 +77,7 @@ describe("ExplorableSiteTree", () => {
   test("can convert a site to a plain object", async () => {
     const fixture = new ExplorableSiteTree(mockHost);
     // Convert buffers to strings.
-    const strings = Tree.map(fixture, {
+    const strings = await Tree.map(fixture, {
       deep: true,
       value: (value) => textDecoder.decode(value),
     });

package/test/drivers/FileTree.test.js

@@ -132,7 +132,7 @@ describe("FileTree", async () => {
 
     // Read them back in.
     const actualFiles = await tempFiles.get("folder");
-    const strings = Tree.map(actualFiles, {
+    const strings = await Tree.map(actualFiles, {
       deep: true,
       value: (buffer) => textDecoder.decode(buffer),
     });

package/test/drivers/calendarTree.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import calendar from "../../src/drivers/calendarTree.js";
-import { toPlainValue } from "../../src/utilities.js";
+import toPlainValue from "../../src/utilities/toPlainValue.js";
 
 describe("calendarTree", () => {
   test("without a start or end, returns a tree for today", async () => {

package/test/jsonKeys.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import { DeepObjectTree } from "../src/internal.js";
+import DeepObjectTree from "../src/drivers/DeepObjectTree.js";
 import * as jsonKeys from "../src/jsonKeys.js";
 
 describe("jsonKeys", () => {

package/test/operations/assign.test.js

@@ -0,0 +1,54 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import DeepObjectTree from "../../src/drivers/DeepObjectTree.js";
+import ObjectTree from "../../src/drivers/ObjectTree.js";
+import assign from "../../src/operations/assign.js";
+import plain from "../../src/operations/plain.js";
+
+describe("assign", () => {
+  test("assign applies one tree to another", async () => {
+    const target = new DeepObjectTree({
+      a: 1,
+      b: 2,
+      more: {
+        d: 3,
+      },
+    });
+
+    const source = new DeepObjectTree({
+      a: 4, // Overwrite existing value
+      b: undefined, // Delete
+      c: 5, // Add
+      more: {
+        // Should leave existing `more` keys alone.
+        e: 6, // Add
+      },
+      // Add new subtree
+      extra: {
+        f: 7,
+      },
+    });
+
+    // Apply changes.
+    const result = await assign(target, source);
+
+    assert.equal(result, target);
+    assert.deepEqual(await plain(target), {
+      a: 4,
+      c: 5,
+      more: {
+        d: 3,
+        e: 6,
+      },
+      extra: {
+        f: 7,
+      },
+    });
+  });
+
+  test("assign() can apply updates to an array", async () => {
+    const target = new ObjectTree(["a", "b", "c"]);
+    await assign(target, ["d", "e"]);
+    assert.deepEqual(await plain(target), ["d", "e", "c"]);
+  });
+});

package/test/operations/cache.test.js

@@ -6,7 +6,7 @@ import cache from "../../src/operations/cache.js";
 describe("cache", () => {
   test("caches reads of values from one tree into another", async () => {
     const objectCache = new ObjectTree({});
-    const fixture = cache(
+    const fixture = await cache(
       new DeepObjectTree({
         a: 1,
         b: 2,

package/test/operations/cachedKeyFunctions.test.js

@@ -12,7 +12,7 @@ describe("cachedKeyFunctions", () => {
     });
 
     let callCount = 0;
-    const addUnderscore = async (sourceKey, tree) => {
+    const addUnderscore = async (sourceValue, sourceKey, tree) => {
       callCount++;
       return `_${sourceKey}`;
     };
@@ -26,15 +26,15 @@ describe("cachedKeyFunctions", () => {
     assert.equal(await inverseKey("_b", tree), "b"); // Cache miss
     assert.equal(callCount, 2);
 
-    assert.equal(await key("a", tree), "_a");
-    assert.equal(await key("a", tree), "_a");
-    assert.equal(await key("b", tree), "_b");
+    assert.equal(await key(null, "a", tree), "_a");
+    assert.equal(await key(null, "a", tree), "_a");
+    assert.equal(await key(null, "b", tree), "_b");
     assert.equal(callCount, 2);
 
     // `c` isn't in tree, so we should get undefined.
     assert.equal(await inverseKey("_c", tree), undefined);
     // But key mapping is still possible.
-    assert.equal(await key("c", tree), "_c");
+    assert.equal(await key(null, "c", tree), "_c");
     // And now we have a cache hit.
     assert.equal(await inverseKey("_c", tree), "c");
     assert.equal(callCount, 3);
@@ -49,7 +49,7 @@ describe("cachedKeyFunctions", () => {
     });
 
     let callCount = 0;
-    const addUnderscore = async (sourceKey, tree) => {
+    const addUnderscore = async (sourceValue, sourceKey, tree) => {
       callCount++;
       return `_${sourceKey}`;
     };
@@ -66,12 +66,12 @@ describe("cachedKeyFunctions", () => {
     assert.equal(await inverseKey("b/", tree), "b/");
     assert.equal(callCount, 1);
 
-    assert.equal(await key("a", tree), "_a");
-    assert.equal(await key("a", tree), "_a");
+    assert.equal(await key(null, "a", tree), "_a");
+    assert.equal(await key(null, "a", tree), "_a");
     assert.equal(callCount, 1);
 
-    assert.equal(await key("b/", tree), "b/");
-    assert.equal(await key("b", tree), "b");
+    assert.equal(await key(null, "b/", tree), "b/");
+    assert.equal(await key(null, "b", tree), "b");
     assert.equal(callCount, 1);
   });
 
@@ -79,11 +79,11 @@ describe("cachedKeyFunctions", () => {
     const tree = new ObjectTree({
       a: "letter a",
     });
-    const addUnderscore = async (sourceKey) => `_${sourceKey}`;
+    const addUnderscore = async (sourceValue, sourceKey) => `_${sourceKey}`;
     const { inverseKey, key } = cachedKeyFunctions(addUnderscore);
 
-    assert.equal(await key("a/", tree), "_a/");
-    assert.equal(await key("a", tree), "_a");
+    assert.equal(await key(null, "a/", tree), "_a/");
+    assert.equal(await key(null, "a", tree), "_a");
 
     assert.equal(await inverseKey("_a/", tree), "a/");
     assert.equal(await inverseKey("_a", tree), "a");
@@ -93,14 +93,14 @@ describe("cachedKeyFunctions", () => {
     const tree = new ObjectTree({
       a: "letter a",
     });
-    const addUnderscoreAndSlash = async (sourceKey) =>
+    const addUnderscoreAndSlash = async (sourceValue, sourceKey) =>
       `_${trailingSlash.remove(sourceKey)}/`;
     const { inverseKey, key } = cachedKeyFunctions(addUnderscoreAndSlash);
 
     assert.equal(await inverseKey("_a/", tree), "a");
     assert.equal(await inverseKey("_a", tree), "a");
 
-    assert.equal(await key("a", tree), "_a/");
-    assert.equal(await key("a/", tree), "_a/");
+    assert.equal(await key(null, "a", tree), "_a/");
+    assert.equal(await key(null, "a/", tree), "_a/");
   });
 });

package/test/operations/clear.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import FileTree from "../../src/drivers/FileTree.js";
+import { ObjectTree, Tree } from "../../src/internal.js";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const tempDirectory = path.join(dirname, "fixtures/temp");
+
+describe("clear", () => {
+  test("unsets all public keys in an object tree", async () => {
+    const tree = new ObjectTree({ a: 1, b: 2, c: 3 });
+    await Tree.clear(tree);
+    assert.deepEqual(await Tree.plain(tree), {});
+  });
+
+  test("unsets all public keys in a file tree", async () => {
+    // Create a temp directory with some files
+    await fs.mkdir(tempDirectory, { recursive: true });
+    await fs.writeFile(path.join(tempDirectory, "a"), "1");
+    await fs.writeFile(path.join(tempDirectory, "b"), "2");
+
+    const tree = new FileTree(tempDirectory);
+    await Tree.clear(tree);
+
+    const files = await fs.readdir(tempDirectory);
+    assert.deepEqual(files, []);
+
+    // Remove temp directory
+    await fs.rm(tempDirectory, { recursive: true });
+  });
+});

package/test/operations/deepMerge.test.js

@@ -1,11 +1,11 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { DeepObjectTree, Tree } from "../../src/internal.js";
-import mergeDeep from "../../src/operations/deepMerge.js";
+import deepMerge from "../../src/operations/deepMerge.js";
 
 describe("mergeDeep", () => {
   test("can merge deep", async () => {
-    const fixture = mergeDeep(
+    const fixture = deepMerge(
       new DeepObjectTree({
         a: {
           b: 0, // Will be obscured by `b` below
@@ -34,9 +34,5 @@ describe("mergeDeep", () => {
         f: 4,
       },
     });
-
-    // Parent of a subvalue is the merged tree
-    const a = await fixture.get("a");
-    assert.equal(a.parent, fixture);
   });
 });

package/test/operations/deepReverse.test.js

@@ -12,7 +12,7 @@ describe("deepReverse", () => {
         d: 3,
       },
     };
-    const reversed = deepReverse.call(null, tree);
+    const reversed = await deepReverse(tree);
     assert.deepEqual(await Tree.plain(reversed), {
       b: {
         d: 3,

package/test/operations/delete.test.js

@@ -0,0 +1,20 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectTree from "../../src/drivers/ObjectTree.js";
+import { default as del } from "../../src/operations/delete.js";
+import plain from "../../src/operations/plain.js";
+
+describe("delete", () => {
+  test("removes a value", async () => {
+    const fixture = new ObjectTree({
+      "Alice.md": "Hello, **Alice**.",
+      "Bob.md": "Hello, **Bob**.",
+      "Carol.md": "Hello, **Carol**.",
+    });
+    await del(fixture, "Alice.md");
+    assert.deepEqual(await plain(fixture), {
+      "Bob.md": "Hello, **Bob**.",
+      "Carol.md": "Hello, **Carol**.",
+    });
+  });
+});

package/test/operations/entries.test.js

@@ -0,0 +1,18 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import entries from "../../src/operations/entries.js";
+
+describe("entries", () => {
+  test("entries() returns the [key, value] pairs", async () => {
+    const fixture = {
+      "Alice.md": "Hello, **Alice**.",
+      "Bob.md": "Hello, **Bob**.",
+      "Carol.md": "Hello, **Carol**.",
+    };
+    assert.deepEqual(Array.from(await entries(fixture)), [
+      ["Alice.md", "Hello, **Alice**."],
+      ["Bob.md", "Hello, **Bob**."],
+      ["Carol.md", "Hello, **Carol**."],
+    ]);
+  });
+});