path-class 0.12.1 → 0.13.0

package/src/Path.ts

@@ -1,3 +1,4 @@
+import { createReadStream } from "node:fs";
 import {
   appendFile,
   chmod,
@@ -19,6 +20,7 @@ import {
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 import { cwd } from "node:process";
+import { createInterface } from "node:readline/promises";
 import { Readable } from "node:stream";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
@@ -34,6 +36,7 @@ import type {
   readFileType,
   statType,
 } from "./modifiedNodeTypes";
+import { stringifyIfPath } from "./stringifyfIfPath";
 
 // Note that (non-static) functions in this file are defined using `function(…)
 // { … }` rather than arrow functions, specifically because we want `this` to
@@ -74,6 +77,30 @@ export function resolutionPrefix(pathString: string): ResolutionPrefix {
   return ResolutionPrefix.Bare;
 }
 
+const DEFAULT_TEMP_PREFIX = "js-temp-";
+const DEFAULT_TEMP_FILE_NAME = "file";
+
+function preserveRelativeResolutionPrefix(
+  pathString: string,
+  from: string,
+): string {
+  if (
+    resolutionPrefix(from) === ResolutionPrefix.Relative &&
+    resolutionPrefix(pathString) !== ResolutionPrefix.Relative
+  ) {
+    // We don't have to handle the case of `"."`, as it already starts with `"."`
+    return `./${pathString}`;
+  }
+  return pathString;
+}
+
+function joinPreservingRelativeResolutionPrefix(
+  base: string,
+  relative: string[],
+): string {
+  return preserveRelativeResolutionPrefix(join(base, ...relative), base);
+}
+
 export class Path {
   // @ts-expect-error ts(2564): False positive. https://github.com/microsoft/TypeScript/issues/32194
   #path: string;
@@ -85,6 +112,27 @@ export class Path {
     this.#setNormalizedPath(s);
   }
 
+  static #pathlikeToString(path: string | URL | Path): string {
+    if (path instanceof Path) {
+      return path.#path;
+    }
+    if (path instanceof URL) {
+      return fileURLToPath(path);
+    }
+    if (typeof path === "string") {
+      // TODO: allow turning off this heuristic?
+      if (path.startsWith("file:///")) {
+        return fileURLToPath(path);
+      }
+      return path;
+    }
+    throw new Error("Invalid path");
+  }
+
+  // Preserves the `ResolutionPrefix` status when possible.
+  #setNormalizedPath(path: string): void {
+    this.#path = joinPreservingRelativeResolutionPrefix(path, []);
+  }
   static fromString(s: string): Path {
     if (typeof s !== "string") {
       throw new Error(
@@ -124,31 +172,80 @@ export class Path {
     return new Path(new URL(Path.#pathlikeToString(path), baseURL));
   }
 
-  static #pathlikeToString(path: string | URL | Path): string {
-    if (path instanceof Path) {
-      return path.#path;
+  /**
+   * Convenience function. The following are equivalent:
+   *
+   *     B.resolve(A);
+   *     Path.resolve(A, B);
+   *
+   */
+  resolve(path: string | URL | Path): Path {
+    return Path.resolve(path, this);
+  }
+
+  /**
+   * Computes the relative path from an ancestor (this) to another path.
+   *
+   * - If the path is a descendant *or is the same path*, this returns a
+   *   relative path. Call {@link Path.asBare `.asBare()`} on the output if
+   *   needed.
+   * - The output is `null` unless the input paths are:
+   *   - Both absolute paths.
+   *   - Both relative paths. Resolve the paths before passing to this function
+   *     if needed.
+   * - Trailing slashes:
+   *   - By default, the ancestor path must have a trailing slash for the
+   *     function to be called. Pass `{ requireTrailingSlashForAncestor: false
+   *     }` if needed. Note that recombining the ancestor path with the output
+   *     using {@link Path.prototype.resolve `.resolve(…)` } does not result in
+   *     the original input path if the ancestor path did not have a trailing
+   *     slash.
+   *   - For the descendant/same path check, trailing slashes are ignored. In
+   *     particular, if the ancestor path has a trailing slash and the
+   *     descendant path is the same path without a trailing slash, this is
+   *     still considered to be the same path.
+   *   - The output has trailing slash if and only if:
+   *       - the input descendant does, or
+   *       - the output is the absolute path `/`.
+   */
+  descendantRelativePath(
+    potentialDescendant: string | URL | Path,
+    options?: { requireTrailingSlashForAncestor: boolean },
+  ): Path | null {
+    const requireTrailingSlashForAncestor =
+      options?.requireTrailingSlashForAncestor ?? true;
+    if (requireTrailingSlashForAncestor && !this.hasTrailingSlash()) {
+      throw new Error(
+        "Ancestor must have a trailing slash. Pass `{ requireTrailingSlashForAncestor: false }` if needed.",
+      );
     }
-    if (path instanceof URL) {
-      return fileURLToPath(path);
+
+    const other = new Path(potentialDescendant);
+    if (this.isAbsolutePath() !== other.isAbsolutePath()) {
+      return null;
     }
-    if (typeof path === "string") {
-      // TODO: allow turning off this heuristic?
-      if (path.startsWith("file:///")) {
-        return fileURLToPath(path);
+
+    // Leading slashes are okay, as they will result in a `""` component for
+    // absolute paths (and we don't compare absolute paths to relative paths.)
+    const thisParts = this.toggleTrailingSlash(false).#path.split("/");
+    const otherParts = other.toggleTrailingSlash(false).#path.split("/");
+
+    if (otherParts.length < thisParts.length) {
+      return null;
+    }
+    for (let i = 0; i < thisParts.length; i++) {
+      console.log(i, thisParts[i], otherParts[i]);
+      if (thisParts[i] !== otherParts[i]) {
+        return null;
       }
-      return path;
     }
-    throw new Error("Invalid path");
+    return new Path("./")
+      .join(...otherParts.slice(thisParts.length))
+      .toggleTrailingSlash(other.hasTrailingSlash());
   }
 
-  // Preserves the `ResolutionPrefix` status when possible.
-  #setNormalizedPath(path: string): void {
-    const prefix = resolutionPrefix(path);
-    this.#path = join(path);
-    if (prefix === ResolutionPrefix.Relative && !this.#path.startsWith(".")) {
-      // We don't have to handle the case of `"."`, as it already starts with `"."`
-      this.#path = `./${this.#path}`;
-    }
+  unresolve(path: string | URL | Path): Path {
+    return Path.resolve(path, this);
   }
 
   isAbsolutePath(): boolean {
@@ -235,7 +332,9 @@ export class Path {
       }
       return s;
     });
-    return new Path(join(this.#path, ...segmentStrings));
+    return new Path(
+      joinPreservingRelativeResolutionPrefix(this.#path, segmentStrings),
+    );
   }
 
   /**
@@ -494,7 +593,47 @@ export class Path {
    * */
   static async makeTempDir(prefix?: string): Promise<AsyncDisposablePath> {
     return new AsyncDisposablePath(
-      await mkdtemp(new Path(tmpdir()).join(prefix ?? "js-temp-").toString()),
+      await mkdtemp(
+        new Path(tmpdir()).join(prefix ?? DEFAULT_TEMP_PREFIX).toString(),
+      ),
+    );
+  }
+
+  /**
+   * Return a path:
+   *
+   * - whose parent dir is a temp dir that *has* been created, but
+   * - which has itself not yet been created.
+   *
+   * Note that this path can actually also be used to create dir, but it is most
+   * convenient to get a path for a temporary file that can be written to, while
+   * having a disposal implementation that cleans everything up:
+   *
+   *     await using tempFile = await Path.tempFilePath({ basename: "foo.txt" });
+   *     await tempFile.write("hello world!");
+   *     // …
+   *
+   * Note that that the following are equivalent when *not* using `await using`:
+   *
+   *     await Path.tempFilePath({ basename: "foo.txt" });
+   *     (await Path.makeTempDir()).join("file.txt");
+   *
+   * However, it is recommended to use `await using` to ensure cleanup.
+   */
+  static async tempFilePath(options: {
+    tempDirPrefix?: string;
+    basename?: string | Path;
+  }): Promise<AsyncDisposablePath> {
+    const tempDir = new Path(
+      await mkdtemp(
+        new Path(tmpdir())
+          .join(options?.tempDirPrefix ?? DEFAULT_TEMP_PREFIX)
+          .toString(),
+      ),
+    );
+    return new AsyncDisposablePath(
+      tempDir.join(options?.basename ?? DEFAULT_TEMP_FILE_NAME),
+      { disposePathInstead: tempDir },
     );
   }
 
@@ -524,6 +663,18 @@ export class Path {
     return readFile(this.#path, "utf-8");
   }
 
+  /**
+   * Yields one line from the text of the line at a time.
+   *
+   * This uses streams, so it can be considerably more efficient than calling e.g. `.split("\n")` on the output of {@link readText `.readText()`}.
+   *
+   * Note that this function does not have a `.readLinesSync()` counterpart.
+   */
+  async *readLines(): AsyncIterable<string> {
+    const stream = createReadStream(this.#path, "utf-8");
+    yield* createInterface({ input: stream, terminal: false });
+  }
+
   /**
    * Reads JSON from the given file and parses it. No validation is performed
    * (beyond JSON parsing).
@@ -697,25 +848,22 @@ export class Path {
 }
 
 export class AsyncDisposablePath extends Path {
-  async [Symbol.asyncDispose]() {
-    await this.rm_rf();
+  #options?: { disposePathInstead: Path };
+  constructor(
+    path: ConstructorParameters<typeof Path>[0],
+    options?: { disposePathInstead: Path | string },
+  ) {
+    super(path);
+    if (options) {
+      this.#options = {
+        disposePathInstead: new Path(options.disposePathInstead),
+      };
+    }
   }
-}
 
-/**
- * This function is useful to serialize any `Path`s in a structure to pass on to
- * functions that do not know about the `Path` class, e.g.
- *
- *     function process(args: (string | Path)[]) {
- *       const argsAsStrings = args.map(stringifyIfPath);
- *     }
- *
- */
-export function stringifyIfPath<T>(value: T | Path): T | string {
-  if (value instanceof Path) {
-    return value.toString();
-  }
-  return value;
+  async [Symbol.asyncDispose]() {
+    await (this.#options?.disposePathInstead ?? this).rm_rf();
+  }
 }
 
 export function mustNotHaveTrailingSlash(path: Path): void {
@@ -725,8 +873,3 @@ export function mustNotHaveTrailingSlash(path: Path): void {
     );
   }
 }
-
-const tmp = await Path.makeTempDir();
-(await tmp.join("foo.json").write("foo")).rename(
-  tmp.join("sdfsD", "sdfsdfsdf", "sdfsdf.json"),
-);

package/src/index.ts

@@ -2,5 +2,6 @@ export {
   AsyncDisposablePath,
   Path,
   ResolutionPrefix,
-  stringifyIfPath,
 } from "./Path";
+
+export { stringifyIfPath } from "./stringifyfIfPath";

package/src/stringifyIfPath.test.ts

@@ -0,0 +1,9 @@
+import { expect, test } from "bun:test";
+import { Path } from "./Path";
+import { stringifyIfPath } from "./stringifyfIfPath";
+
+test.concurrent(".stringifyIfPath(…)", async () => {
+  expect(stringifyIfPath(Path.homedir)).toBe("/mock/home/dir");
+  expect(stringifyIfPath("/mock/home/dir")).toBe("/mock/home/dir");
+  expect(stringifyIfPath(4)).toBe(4);
+});

package/src/stringifyfIfPath.ts

@@ -0,0 +1,17 @@
+import { Path } from "./Path";
+
+/**
+ * This function is useful to serialize any `Path`s in a structure to pass on to
+ * functions that do not know about the `Path` class, e.g.
+ *
+ *     function process(args: (string | Path)[]) {
+ *       const argsAsStrings = args.map(stringifyIfPath);
+ *     }
+ *
+ */
+export function stringifyIfPath<T>(value: Exclude<T, Path> | Path): T | string {
+  if (value instanceof Path) {
+    return value.toString();
+  }
+  return value;
+}