@weborigami/async-tree 0.5.1 → 0.5.2

package/index.ts

@@ -20,6 +20,7 @@ export type HasString = {
  * an HTTP response via response.write, or readily converted to such a form.
  */
 export type Packed = (ArrayBuffer | Buffer | ReadableStream | string | String | TypedArray) & {
+  parent?: AsyncTree|null;
   unpack?(): Promise<any>;
 };
 
@@ -70,4 +71,9 @@ export type Unpackable<T> = {
   unpack(): Promise<T>
 };
 
+/**
+ * A function that converts a value from a persistent form into a live value.
+ */
+export type UnpackFunction = (input: Packed, options?: any) => any;
+
 export type ValueKeyFn = (value: any, key: any, innerTree: AsyncTree) => any;

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "dependencies": {
-    "@weborigami/types": "0.5.1"
+    "@weborigami/types": "0.5.2"
   },
   "devDependencies": {
     "@types/node": "24.3.0",

package/src/Tree.d.ts

@@ -13,7 +13,7 @@ export function isTraversable(obj: any): boolean;
 export function isTreelike(obj: any): obj is Treelike;
 export function map(tree: Treelike, options: TreeMapOptions|ValueKeyFn): AsyncTree;
 export function mapReduce(tree: Treelike, mapFn: ValueKeyFn | null, reduceFn: ReduceFn): Promise<any>;
-export function paths(tree: Treelike, base?: string): string[];
+export function paths(tree: Treelike, options?: { assumeSlashes?: boolean, base?: string }): string[];
 export function plain(tree: Treelike): Promise<PlainObject>;
 export function root(tree: Treelike): AsyncTree;
 export function remove(AsyncTree: AsyncMutableTree, key: any): Promise<boolean>;

package/src/Tree.js

@@ -291,18 +291,41 @@ export async function mapReduce(treelike, valueFn, reduceFn) {
 /**
  * Returns slash-separated paths for all values in the tree.
  *
+ * The `base` argument is prepended to all paths.
+ *
+ * If `assumeSlashes` is true, then keys are assumed to have trailing slashes to
+ * indicate subtrees. The default value of this option is false.
+ *
  * @param {Treelike} treelike
- * @param {string?} base
+ * @param {{ assumeSlashes?: boolean, base?: string }} options
  */
-export async function paths(treelike, base = "") {
+export async function paths(treelike, options = {}) {
   const tree = from(treelike);
+  const base = options.base ?? "";
+  const assumeSlashes = options.assumeSlashes ?? false;
   const result = [];
   for (const key of await tree.keys()) {
     const separator = trailingSlash.has(base) ? "" : "/";
     const valuePath = base ? `${base}${separator}${key}` : key;
-    const value = await tree.get(key);
-    if (await isAsyncTree(value)) {
-      const subPaths = await paths(value, valuePath);
+    let isSubtree;
+    let value;
+    if (assumeSlashes) {
+      // Subtree needs to have a trailing slash
+      isSubtree = trailingSlash.has(key);
+      if (isSubtree) {
+        // We'll need the value to recurse
+        value = await tree.get(key);
+      }
+    } else {
+      // Get value and check
+      value = await tree.get(key);
+    }
+    if (value) {
+      // If we got the value we can check if it's a subtree
+      isSubtree = isAsyncTree(value);
+    }
+    if (isSubtree) {
+      const subPaths = await paths(value, { assumeSlashes, base: valuePath });
       result.push(...subPaths);
     } else {
       result.push(valuePath);

package/src/utilities.d.ts

@@ -4,6 +4,7 @@ import { Packed, PlainObject, StringLike } from "../index.ts";
 export function assertIsTreelike(object: any, operation: string, position?: number): void;
 export function box(value: any): any;
 export function castArrayLike(keys: any[], values: any[]): any;
+export function getParent(object: any, options?: any): AsyncTree|null;
 export function getRealmObjectPrototype(object: any): any;
 export const hiddenFileNames: string[];
 export function isPacked(obj: any): obj is Packed;

package/src/utilities.js

@@ -87,6 +87,36 @@ export function castArrayLike(keys, values) {
     : Object.fromEntries(keys.map((key, i) => [key, values[i]]));
 }
 
+/**
+ * Return a suitable parent for the packed file.
+ *
+ * This is intended to be called by unpack functions.
+ *
+ * @param {any} packed
+ * @param {any} [options]
+ * @returns {AsyncTree|null}
+ */
+export function getParent(packed, options = {}) {
+  // Prefer parent set on options
+  if (options?.parent) {
+    return options.parent;
+  }
+
+  // If the packed object has a `parent` property, use that. Exception: Node
+  // Buffer objects have a `parent` property that we ignore.
+  if (packed.parent && !(packed instanceof Buffer)) {
+    return packed.parent;
+  }
+
+  // If the packed object has a parent symbol, use that.
+  if (packed[symbols.parent]) {
+    return packed[symbols.parent];
+  }
+
+  // Otherwise, return null.
+  return null;
+}
+
 /**
  * Return the Object prototype at the root of the object's prototype chain.
  *

package/test/Tree.test.js

@@ -232,6 +232,27 @@ describe("Tree", () => {
     assert.deepEqual(await Tree.paths(tree), ["a", "b", "c/d", "c/e"]);
   });
 
+  test("paths can focus just on keys with trailing slashes", async () => {
+    const tree = new ObjectTree({
+      a: 1,
+      b: 2,
+      // This is a shallow ObjectTree, so `c` won't have a trailing slash
+      c: {
+        d: 3,
+      },
+      // Explicitly include a trailing slash to signal a subtree
+      "d/": new ObjectTree({
+        e: 4,
+      }),
+    });
+    assert.deepEqual(await Tree.paths(tree, { assumeSlashes: true }), [
+      "a",
+      "b",
+      "c",
+      "d/e",
+    ]);
+  });
+
   test("plain() produces a plain object version of a tree", async () => {
     const tree = new ObjectTree({
       a: 1,