@weborigami/async-tree 0.5.8 → 0.6.1

package/src/drivers/{BrowserFileTree.js → BrowserFileMap.js}

@@ -1,24 +1,21 @@
 import { hiddenFileNames } from "../constants.js";
-import assign from "../operations/assign.js";
-import isTreelike from "../operations/isTreelike.js";
+import isMap from "../operations/isMap.js";
 import * as trailingSlash from "../trailingSlash.js";
 import isStringlike from "../utilities/isStringlike.js";
 import naturalOrder from "../utilities/naturalOrder.js";
 import setParent from "../utilities/setParent.js";
+import AsyncMap from "./AsyncMap.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
 /**
- * A tree of files backed by a browser-hosted file system such as the standard
+ * A map of files backed by a browser-hosted file system such as the standard
  * Origin Private File System or the (as of October 2023) experimental File
  * System Access API.
- *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
- * @implements {AsyncMutableTree}
  */
-export default class BrowserFileTree {
+export default class BrowserFileMap extends AsyncMap {
   /**
-   * Construct a tree of files backed by a browser-hosted file system.
+   * Construct a map of files backed by a browser-hosted file system.
    *
    * The directory handle can be obtained via any of the [methods that return a
    * FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle).
@@ -28,11 +25,50 @@ export default class BrowserFileTree {
    * @param {FileSystemDirectoryHandle} [directoryHandle]
    */
   constructor(directoryHandle) {
-    /** @type {FileSystemDirectoryHandle}
-     * @ts-ignore */
+    super();
     this.directory = directoryHandle;
   }
 
+  async child(key) {
+    const normalized = trailingSlash.remove(key);
+    let result = await this.get(normalized);
+
+    // If child is already a map we can use it as is
+    if (!isMap(result)) {
+      // Create subfolder
+      const directory = await this.getDirectory();
+      if (result) {
+        // Delete existing file with same name
+        await directory.removeEntry(normalized);
+      }
+      const subfolderHandle = await directory.getDirectoryHandle(normalized, {
+        create: true,
+      });
+      result = Reflect.construct(this.constructor, [subfolderHandle]);
+      setParent(result, this);
+    }
+
+    return result;
+  }
+
+  async delete(key) {
+    const normalized = trailingSlash.remove(key);
+    const directory = await this.getDirectory();
+
+    // Delete file.
+    try {
+      await directory.removeEntry(normalized);
+    } catch (error) {
+      // If the file didn't exist, ignore the error.
+      if (error instanceof DOMException && error.name === "NotFoundError") {
+        return false;
+      }
+      throw error;
+    }
+
+    return true;
+  }
+
   async get(key) {
     if (key == null) {
       // Reject nullish key.
@@ -90,15 +126,15 @@ export default class BrowserFileTree {
     return this.directory;
   }
 
-  async keys() {
+  async *keys() {
     const directory = await this.getDirectory();
     let keys = [];
     // @ts-ignore
     for await (const entryKey of directory.keys()) {
       // Check if the entry is a subfolder
-      const baseKey = trailingSlash.remove(entryKey);
+      const normalized = trailingSlash.remove(entryKey);
       const subfolderHandle = await directory
-        .getDirectoryHandle(baseKey)
+        .getDirectoryHandle(normalized)
         .catch(() => null);
       const isSubfolder = subfolderHandle !== null;
 
@@ -110,28 +146,13 @@ export default class BrowserFileTree {
     keys = keys.filter((key) => !hiddenFileNames.includes(key));
     keys.sort(naturalOrder);
 
-    return keys;
+    yield* keys;
   }
 
   async set(key, value) {
-    const baseKey = trailingSlash.remove(key);
+    const normalized = trailingSlash.remove(key);
     const directory = await this.getDirectory();
 
-    if (value === undefined) {
-      // Delete file.
-      try {
-        await directory.removeEntry(baseKey);
-      } catch (error) {
-        // If the file didn't exist, ignore the error.
-        if (
-          !(error instanceof DOMException && error.name === "NotFoundError")
-        ) {
-          throw error;
-        }
-      }
-      return this;
-    }
-
     // Treat null value as empty string; will create an empty file.
     if (value === null) {
       value = "";
@@ -152,19 +173,12 @@ export default class BrowserFileTree {
 
     if (isWriteable) {
       // Write file.
-      const fileHandle = await directory.getFileHandle(baseKey, {
+      const fileHandle = await directory.getFileHandle(normalized, {
         create: true,
       });
       const writable = await fileHandle.createWritable();
       await writable.write(value);
       await writable.close();
-    } else if (isTreelike(value)) {
-      // Treat value as a tree and write it out as a subdirectory.
-      const subdirectory = await directory.getDirectoryHandle(baseKey, {
-        create: true,
-      });
-      const destTree = Reflect.construct(this.constructor, [subdirectory]);
-      await assign(destTree, value);
     } else {
       const typeName = value?.constructor?.name ?? "unknown";
       throw new TypeError(`Cannot write a value of type ${typeName} as ${key}`);
@@ -172,4 +186,6 @@ export default class BrowserFileTree {
 
     return this;
   }
+
+  trailingSlashKeys = true;
 }

package/src/drivers/{calendarTree.js → CalendarMap.js}

@@ -1,4 +1,5 @@
 import * as trailingSlash from "../trailingSlash.js";
+import SyncMap from "./SyncMap.js";
 
 /**
  * Return a tree of years, months, and days from a start date to an end date.
@@ -14,41 +15,71 @@ import * as trailingSlash from "../trailingSlash.js";
  *
  * @typedef {string|undefined} CalendarOptionsDate
  * @typedef {( year: string, month: string, day: string ) => any} CalendarOptionsFn
+ * @typedef {{ year: number, month: number, day: number}} CalendarDateParts}
+ *
  * @param {{ end?: CalendarOptionsDate, start?: CalendarOptionsDate, value: CalendarOptionsFn }} options
  */
-export default function calendarTree(options) {
-  const start = dateParts(options.start);
-  const end = dateParts(options.end);
-  const valueFn = options.value;
-
-  // Fill in the missing parts of the start and end dates.
-  const today = new Date();
-
-  if (start.day === undefined) {
-    start.day = start.year ? 1 : today.getDate();
-  }
-  if (start.month === undefined) {
-    start.month = start.year ? 1 : today.getMonth() + 1;
-  }
-  if (start.year === undefined) {
-    start.year = today.getFullYear();
+export default class CalendarMap extends SyncMap {
+  constructor(options = {}) {
+    super();
+
+    /** @type {CalendarDateParts} */
+    // @ts-ignore
+    const start = dateParts(options.start);
+    /** @type {CalendarDateParts} */
+    // @ts-ignore
+    const end = dateParts(options.end);
+    const valueFn = options.value;
+
+    // Fill in the missing parts of the start and end dates.
+    const today = new Date();
+
+    if (start.day === undefined) {
+      start.day = start.year ? 1 : today.getDate();
+    }
+    if (start.month === undefined) {
+      start.month = start.year ? 1 : today.getMonth() + 1;
+    }
+    if (start.year === undefined) {
+      start.year = today.getFullYear();
+    }
+
+    if (end.day === undefined) {
+      end.day = end.month
+        ? daysInMonth(end.year, end.month)
+        : end.year
+        ? 31 // Last day of December
+        : today.getDate();
+    }
+    if (end.month === undefined) {
+      end.month = end.year ? 12 : today.getMonth() + 1;
+    }
+    if (end.year === undefined) {
+      end.year = today.getFullYear();
+    }
+
+    this.start = start;
+    this.end = end;
+    this.valueFn = valueFn ?? defaultValueFn;
   }
 
-  if (end.day === undefined) {
-    end.day = end.month
-      ? daysInMonth(end.year, end.month)
-      : end.year
-      ? 31 // Last day of December
-      : today.getDate();
-  }
-  if (end.month === undefined) {
-    end.month = end.year ? 12 : today.getMonth() + 1;
+  get(year) {
+    year = parseInt(trailingSlash.remove(year));
+    return this.inRange(year)
+      ? monthsForYearMap(year, this.start, this.end, this.valueFn)
+      : undefined;
   }
-  if (end.year === undefined) {
-    end.year = today.getFullYear();
+
+  inRange(year) {
+    return year >= this.start.year && year <= this.end.year;
   }
 
-  return yearsTree(start, end, valueFn);
+  keys() {
+    return Array.from(
+      { length: this.end.year - this.start.year + 1 },
+      (_, i) => this.start.year + i
+    )[Symbol.iterator]();
+  }
 }
 
 function dateParts(date) {
@@ -64,9 +95,9 @@ function dateParts(date) {
   return { year, month, day };
 }
 
-function daysForMonthTree(year, month, start, end, valueFn) {
-  return {
-    async get(day) {
+function daysForMonthMap(year, month, start, end, valueFn) {
+  return Object.assign(new SyncMap(), {
+    get(day) {
       day = parseInt(trailingSlash.remove(day));
       return this.inRange(day)
         ? valueFn(year.toString(), twoDigits(month), twoDigits(day))
@@ -101,28 +132,34 @@ function daysForMonthTree(year, month, start, end, valueFn) {
       }
     },
 
-    async keys() {
+    *keys() {
       const days = Array.from(
         { length: daysInMonth(year, month) },
         (_, i) => i + 1
       );
-      return days
+      yield* days
         .filter((day) => this.inRange(day))
         .map((day) => twoDigits(day));
     },
-  };
+
+    trailingSlashKeys: false,
+  });
 }
 
 function daysInMonth(year, month) {
   return new Date(year, month, 0).getDate();
 }
 
-function monthsForYearTree(year, start, end, valueFn) {
-  return {
-    async get(month) {
+function defaultValueFn(year, month, day) {
+  return `${year}-${month}-${day}`;
+}
+
+function monthsForYearMap(year, start, end, valueFn) {
+  return Object.assign(new SyncMap(), {
+    get(month) {
       month = parseInt(trailingSlash.remove(month));
       return this.inRange(month)
-        ? daysForMonthTree(year, month, start, end, valueFn)
+        ? daysForMonthMap(year, month, start, end, valueFn)
         : undefined;
     },
 
@@ -138,37 +175,17 @@ function monthsForYearTree(year, start, end, valueFn) {
       }
     },
 
-    async keys() {
+    *keys() {
       const months = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
-      return months
+      yield* months
         .filter((month) => this.inRange(month))
         .map((month) => twoDigits(month));
     },
-  };
+
+    trailingSlashKeys: false,
+  });
 }
 
 function twoDigits(number) {
   return number.toString().padStart(2, "0");
 }
-
-function yearsTree(start, end, valueFn) {
-  return {
-    async get(year) {
-      year = parseInt(trailingSlash.remove(year));
-      return this.inRange(year)
-        ? monthsForYearTree(year, start, end, valueFn)
-        : undefined;
-    },
-
-    inRange(year) {
-      return year >= start.year && year <= end.year;
-    },
-
-    async keys() {
-      return Array.from(
-        { length: end.year - start.year + 1 },
-        (_, i) => start.year + i
-      );
-    },
-  };
-}

package/src/drivers/ConstantMap.js

@@ -0,0 +1,28 @@
+import * as trailingSlash from "../trailingSlash.js";
+import SyncMap from "./SyncMap.js";
+
+/**
+ * A tree that returns a constant value for any key. If the key ends with a
+ * slash, then the same type of subtree is returned.
+ *
+ * @param {any} constant
+ * @returns {SyncMap}
+ */
+export default class ConstantTree extends SyncMap {
+  constructor(constant) {
+    super();
+    this.constant = constant;
+  }
+
+  get(key) {
+    return trailingSlash.has(key)
+      ? new ConstantTree(this.constant)
+      : this.constant;
+  }
+
+  keys() {
+    return [][Symbol.iterator]();
+  }
+
+  trailingSlashKeys = true;
+}

package/src/drivers/{ExplorableSiteTree.js → ExplorableSiteMap.js}

@@ -1,11 +1,11 @@
-import SiteTree from "./SiteTree.js";
+import SiteMap from "./SiteMap.js";
 
 /**
- * A [SiteTree](SiteTree.html) that implements the [JSON Keys](jsonKeys.html)
+ * A [SiteMap](SiteMap.html) that implements the [JSON Keys](jsonKeys.html)
  * protocol. This enables a `keys()` method that can return the keys of a site
  * route even though such a mechanism is not built into the HTTP protocol.
  */
-export default class ExplorableSiteTree extends SiteTree {
+export default class ExplorableSiteMap extends SiteMap {
   /**
    * @param {string} href
    */
@@ -24,12 +24,12 @@ export default class ExplorableSiteTree extends SiteTree {
       .then((response) => (response.ok ? response.text() : null))
       .then((text) => {
         try {
-          return text ? JSON.parse(text) : null;
+          return text ? JSON.parse(text) : [];
         } catch (error) {
           // Got a response, but it's not JSON. Most likely the site doesn't
           // actually have a .keys.json file, and is returning a Not Found page,
           // but hasn't set the correct 404 status code.
-          return null;
+          return [];
         }
       });
     return this.serverKeysPromise;
@@ -39,9 +39,9 @@ export default class ExplorableSiteTree extends SiteTree {
    * Returns the keys of the site route. For this to work, the route must have a
    * `.keys.json` file that contains a JSON array of string keys.
    */
-  async keys() {
+  async *keys() {
     const serverKeys = await this.getServerKeys();
-    return serverKeys ?? [];
+    yield* serverKeys;
   }
 
   processResponse(response) {

package/src/drivers/FileMap.js

@@ -0,0 +1,238 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { hiddenFileNames } from "../constants.js";
+import * as trailingSlash from "../trailingSlash.js";
+import isPacked from "../utilities/isPacked.js";
+import isStringlike from "../utilities/isStringlike.js";
+import naturalOrder from "../utilities/naturalOrder.js";
+import setParent from "../utilities/setParent.js";
+import SyncMap from "./SyncMap.js";
+
+/**
+ * A file system folder as a Map.
+ *
+ * File values are returned as Uint8Array instances. The underlying Node fs API
+ * returns file contents as instances of the Node-specific Buffer class, but
+ * that class has some incompatible method implementations; see
+ * https://nodejs.org/api/buffer.html#buffers-and-typedarrays. For greater
+ * compatibility, files are returned as standard Uint8Array instances instead.
+ */
+export default class FileMap extends SyncMap {
+  constructor(location) {
+    if (location instanceof URL) {
+      location = location.href;
+    } else if (
+      !(
+        typeof location === "string" ||
+        /** @type {any} */ (location) instanceof String
+      )
+    ) {
+      throw new TypeError("FileMap constructor needs a string or URL");
+    }
+
+    super();
+    this.dirname = location.startsWith("file://")
+      ? fileURLToPath(location)
+      : path.resolve(process.cwd(), location);
+  }
+
+  // Return the (possibly new) subdirectory with the given key.
+  child(key) {
+    const stringKey = key != null ? String(key) : "";
+    const baseKey = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, baseKey);
+    const destTree = Reflect.construct(this.constructor, [destPath]);
+
+    const stats = getStats(destPath);
+    if (stats === null || !stats.isDirectory()) {
+      if (stats !== null) {
+        // File with the same name exists; delete it.
+        fs.rmSync(destPath);
+      }
+      // Ensure the directory exists.
+      fs.mkdirSync(destPath, { recursive: true });
+    }
+
+    return destTree;
+  }
+
+  delete(key) {
+    if (key === "" || key == null) {
+      // Can't have a file with no name or a nullish name
+      throw new Error("delete: key was empty or nullish");
+    }
+
+    // What file or directory are we going to delete?
+    const stringKey = key != null ? String(key) : "";
+    const baseKey = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, baseKey);
+
+    try {
+      fs.rmSync(destPath, { recursive: true });
+      return true;
+    } catch (/** @type {any} */ error) {
+      if (error.code === "ENOENT") {
+        return false; // File or directory didn't exist
+      }
+      throw error;
+    }
+  }
+
+  get(key) {
+    if (key == null) {
+      // Reject nullish key
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
+    }
+    if (key === "") {
+      // Can't have a file with no name
+      return undefined;
+    }
+
+    key = trailingSlash.remove(key); // normalize key
+    const filePath = path.resolve(this.dirname, key);
+
+    const stats = getStats(filePath);
+    if (stats === null) {
+      return undefined; // File or directory doesn't exist
+    }
+
+    let value;
+    if (stats.isDirectory()) {
+      // Return subdirectory as an instance of this class
+      value = Reflect.construct(this.constructor, [filePath]);
+    } else {
+      // Return file contents as a standard Uint8Array
+      const buffer = fs.readFileSync(filePath);
+      value = Uint8Array.from(buffer);
+    }
+
+    value.parent =
+      key === ".."
+        ? // Special case: ".." parent is the grandparent (if it exists)
+          this.parent?.parent
+        : this;
+    setParent(value, this);
+
+    return value;
+  }
+
+  keys() {
+    let dirEntries;
+    try {
+      dirEntries = fs.readdirSync(this.dirname, { withFileTypes: true });
+    } catch (/** @type {any} */ error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+      // Directory doesn't exist yet; treat as empty
+      dirEntries = [];
+    }
+
+    // Add slashes to directory names.
+    let names = dirEntries.map((dirEntry) =>
+      trailingSlash.toggle(dirEntry.name, dirEntry.isDirectory())
+    );
+
+    // Filter out unhelpful file names.
+    names = names.filter((name) => !hiddenFileNames.includes(name));
+
+    // Node fs.readdir sort order appears to be unreliable; see, e.g.,
+    // https://github.com/nodejs/node/issues/3232.
+    names.sort(naturalOrder);
+
+    return names[Symbol.iterator]();
+  }
+
+  get path() {
+    return this.dirname;
+  }
+
+  set(key, value) {
+    // Where are we going to write this value?
+    const stringKey = key != null ? String(key) : "";
+    const normalized = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, normalized);
+
+    // Ensure this directory exists.
+    const dirname = path.dirname(destPath);
+    fs.mkdirSync(dirname, { recursive: true });
+
+    if (value === undefined) {
+      // Special case: undefined value is equivalent to delete()
+      this.delete(normalized);
+      return this;
+    }
+
+    if (typeof value === "function") {
+      // Invoke function; write out the result.
+      value = value();
+    }
+
+    let packed = false;
+    if (value === null) {
+      // Treat null value as empty string; will create an empty file.
+      value = "";
+      packed = true;
+    } else if (value instanceof ArrayBuffer) {
+      // Convert ArrayBuffer to Uint8Array, which Node.js can write directly.
+      value = new Uint8Array(value);
+      packed = true;
+    } else if (!(value instanceof String) && isPacked(value)) {
+      // As of Node 22, fs.writeFile is incredibly slow for large String
+      // instances. Instead of treating a String instance as a Packed value, we
+      // want to consider it as a stringlike below. That will convert it to a
+      // primitive string before writing — which is orders of magnitude faster.
+      packed = true;
+    } else if (typeof value.pack === "function") {
+      // Pack the value for writing.
+      value = value.pack();
+      packed = true;
+    } else if (isStringlike(value)) {
+      // Value has a meaningful `toString` method, use that.
+      value = String(value);
+      packed = true;
+    }
+
+    if (packed) {
+      writeFile(value, destPath);
+    } else {
+      const typeName = value?.constructor?.name ?? "unknown";
+      throw new TypeError(
+        `Cannot write a value of type ${typeName} as ${stringKey}`
+      );
+    }
+
+    return this;
+  }
+
+  trailingSlashKeys = true;
+}
+
+// Return stats for the path, or null if it doesn't exist.
+function getStats(filePath) {
+  let stats;
+  try {
+    stats = fs.statSync(filePath);
+  } catch (/** @type {any} */ error) {
+    if (error.code === "ENOENT" /* File not found */) {
+      return null;
+    }
+    throw error;
+  }
+  return stats;
+}
+
+// Write a value to a file.
+function writeFile(value, destPath) {
+  // If path exists and it's a directory, delete the directory first.
+  const stats = getStats(destPath);
+  if (stats !== null && stats.isDirectory()) {
+    fs.rmSync(destPath, { recursive: true });
+  }
+
+  // Write out the value as the contents of a file.
+  fs.writeFileSync(destPath, value);
+}