@weborigami/async-tree 0.5.7 → 0.6.0

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,73 @@ 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();
+  get(year) {
+    year = parseInt(trailingSlash.remove(year));
+    return this.inRange(year)
+      ? monthsForYearMap(year, this.start, this.end, this.valueFn)
+      : undefined;
   }
-  if (end.month === undefined) {
-    end.month = end.year ? 12 : today.getMonth() + 1;
+
+  inRange(year) {
+    return year >= this.start.year && year <= this.end.year;
   }
-  if (end.year === undefined) {
-    end.year = today.getFullYear();
+
+  keys() {
+    return Array.from(
+      { length: this.end.year - this.start.year + 1 },
+      (_, i) => this.start.year + i
+    )[Symbol.iterator]();
   }
 
-  return yearsTree(start, end, valueFn);
+  trailingSlashKeys = false;
 }
 
 function dateParts(date) {
@@ -64,9 +97,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 +134,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 +177,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,30 @@
+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]();
+  }
+
+  get trailingSlashKeys() {
+    return true;
+  }
+}

package/src/drivers/DeepObjectMap.js

@@ -0,0 +1,27 @@
+import isMap from "../operations/isMap.js";
+import isPlainObject from "../utilities/isPlainObject.js";
+import ObjectMap from "./ObjectMap.js";
+
+export default class DeepObjectMap extends ObjectMap {
+  // Implement delete (and set) to keep the Map read-write
+  delete(key) {
+    return super.delete(key);
+  }
+
+  get(key) {
+    let value = super.get(key);
+    if (value instanceof Array || isPlainObject(value)) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+    return value;
+  }
+
+  isSubtree(value) {
+    return value instanceof Array || isPlainObject(value) || isMap(value);
+  }
+
+  // See delete()
+  set(key, value) {
+    return super.set(key, value);
+  }
+}

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,245 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { hiddenFileNames } from "../constants.js";
+import from from "../operations/from.js";
+import isMaplike from "../operations/isMaplike.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);
+  }
+
+  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);
+
+    let stats;
+    try {
+      stats = fs.statSync(filePath);
+    } catch (/** @type {any} */ error) {
+      if (error.code === "ENOENT" /* File not found */) {
+        return undefined;
+      }
+      throw error;
+    }
+
+    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 baseKey = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, baseKey);
+
+    // Ensure this directory exists.
+    const dirname = path.dirname(destPath);
+    fs.mkdirSync(dirname, { recursive: true });
+
+    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 if (value === /** @type {any} */ (this.constructor).EMPTY) {
+      clearDirectory(destPath, this);
+    } else if (isMaplike(value)) {
+      writeDirectory(value, destPath, this);
+    } else {
+      const typeName = value?.constructor?.name ?? "unknown";
+      throw new TypeError(
+        `Cannot write a value of type ${typeName} as ${stringKey}`
+      );
+    }
+
+    return this;
+  }
+
+  get trailingSlashKeys() {
+    return true;
+  }
+}
+
+// Create the indicated directory.
+function clearDirectory(destPath, parent) {
+  const destTree = Reflect.construct(parent.constructor, [destPath]);
+
+  // Ensure the directory exists.
+  fs.mkdirSync(destPath, { recursive: true });
+
+  // Clear any existing files
+  destTree.clear();
+
+  return destTree;
+}
+
+/**
+ * Treat value as a subtree and write it out as a subdirectory.
+ *
+ * @param {import("../../index.ts").Maplike} value
+ */
+function writeDirectory(value, destPath, parent) {
+  // Since value is Maplike, result will be a Map
+  /** @type {Map} */
+  // @ts-ignore
+  const valueMap = from(value);
+  const destTree = clearDirectory(destPath, parent);
+
+  // Write out the subtree.
+  for (const key of valueMap.keys()) {
+    const childValue = valueMap.get(key);
+    destTree.set(key, childValue);
+  }
+}
+
+// Write a value to a file.
+function writeFile(value, destPath) {
+  // Write out the value as the contents of a file.
+  try {
+    fs.writeFileSync(destPath, value);
+  } catch (/** @type {any} */ error) {
+    if (error.code === "EISDIR" /* Is a directory */) {
+      throw new Error(
+        `Tried to overwrite a directory with a single file: ${destPath}`
+      );
+    }
+  }
+}

package/src/drivers/{FunctionTree.js → FunctionMap.js}

@@ -1,20 +1,14 @@
 import setParent from "../utilities/setParent.js";
+import SyncMap from "./SyncMap.js";
 
-/**
- * A tree defined by a function and an optional domain.
- *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @implements {AsyncTree}
- */
-export default class FunctionTree {
-  /**
-   * @param {function} fn the key->value function
-   * @param {Iterable<any>} [domain] optional domain of the function
-   */
+export default class FunctionMap extends SyncMap {
   constructor(fn, domain = []) {
+    if (typeof fn !== "function") {
+      throw new TypeError("FunctionMap: first argument must be a function");
+    }
+    super();
     this.fn = fn;
     this.domain = domain;
-    this.parent = null;
   }
 
   /**
@@ -22,25 +16,28 @@ export default class FunctionTree {
    *
    * @param {any} key
    */
-  async get(key) {
-    const value =
+  get(key) {
+    let value =
       this.fn.length <= 1
         ? // Function takes no arguments, one argument, or a variable number of
           // arguments: invoke it.
-          await this.fn(key)
+          this.fn(key)
         : // Bind the key to the first parameter. Subsequent get calls will
           // eventually bind all parameters until only one remains. At that point,
           // the above condition will apply and the function will be invoked.
           Reflect.construct(this.constructor, [this.fn.bind(null, key)]);
-    setParent(value, this);
+    if (value instanceof Promise) {
+      value = value.then((v) => {
+        setParent(v, this);
+        return v;
+      });
+    } else {
+      setParent(value, this);
+    }
     return value;
   }
 
-  /**
-   * Enumerates the function's domain (if defined) as the tree's keys. If no domain
-   * was defined, this returns an empty iterator.
-   */
-  async keys() {
-    return this.domain;
+  keys() {
+    return this.domain[Symbol.iterator]();
   }
 }