path-class 0.6.0 → 0.7.0

package/src/{index.test.ts → Path.test.ts}

@@ -1,7 +1,7 @@
 import { expect, spyOn, test } from "bun:test";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { Path } from ".";
+import { Path, stringifyIfPath } from "./Path";
 
 test("constructor", async () => {
   expect(new Path("foo").path).toEqual("foo");
@@ -63,7 +63,7 @@ test("normalize", async () => {
   expect(new Path("//absolute////bar").path).toEqual("/absolute/bar");
 });
 
-test("join", async () => {
+test(".join(…)", async () => {
   expect(new Path("foo").join("bar").path).toEqual("foo/bar");
   expect(new Path("foo/bar").join("bath", "kitchen/sink").path).toEqual(
     "foo/bar/bath/kitchen/sink",
@@ -161,14 +161,14 @@ test(".existsAsDir()", async () => {
   expect(await filePath.existsAsDir()).toBe(false);
 });
 
-test("mkdir (un-nested)", async () => {
+test(".mkdir(…) (un-nested)", async () => {
   const dir = (await Path.makeTempDir()).join("mkdir-test");
   expect(await dir.exists()).toBe(false);
   await dir.mkdir();
   expect(await dir.exists()).toBe(true);
 });
 
-test("mkdir (nested)", async () => {
+test(".mkdir(…) (nested)", async () => {
   const dir = (await Path.makeTempDir()).join("mkdir-test/nested");
   expect(await dir.exists()).toBe(false);
   expect(() => dir.mkdir({ recursive: false })).toThrow("no such file");
@@ -176,7 +176,21 @@ test("mkdir (nested)", async () => {
   expect(await dir.exists()).toBe(true);
 });
 
-test(".rename()", async () => {
+test(".cp(…)", async () => {
+  const parentDir = await Path.makeTempDir();
+  const file1 = parentDir.join("file1.txt");
+  const file2 = parentDir.join("file2.txt");
+
+  await file1.write("hello world");
+  expect(await file1.exists()).toBe(true);
+  expect(await file2.exists()).toBe(false);
+
+  await file1.cp(file2);
+  expect(await file1.exists()).toBe(true);
+  expect(await file2.exists()).toBe(true);
+});
+
+test(".rename(…)", async () => {
   const parentDir = await Path.makeTempDir();
   const file1 = parentDir.join("file1.txt");
   const file2 = parentDir.join("file2.txt");
@@ -201,7 +215,7 @@ test(".makeTempDir(…)", async () => {
   expect(tempDir2.basename.path).toStartWith("foo");
 });
 
-test("rm (file)", async () => {
+test(".rm(…) (file)", async () => {
   const file = (await Path.makeTempDir()).join("file.txt");
   await file.write("");
   expect(await file.existsAsFile()).toBe(true);
@@ -211,7 +225,7 @@ test("rm (file)", async () => {
   expect(async () => file.rm()).toThrowError(/ENOENT/);
 });
 
-test("rm (folder)", async () => {
+test(".rm(…) (folder)", async () => {
   const tempDir = await Path.makeTempDir();
   const file = tempDir.join("file.txt");
   await file.write("");
@@ -223,7 +237,7 @@ test("rm (folder)", async () => {
   expect(async () => tempDir.rm()).toThrowError(/ENOENT/);
 });
 
-test("rm_rf (file)", async () => {
+test(".rm_rf(…) (file)", async () => {
   const file = (await Path.makeTempDir()).join("file.txt");
   await file.write("");
   expect(await file.existsAsFile()).toBe(true);
@@ -234,7 +248,7 @@ test("rm_rf (file)", async () => {
   expect(await file.existsAsFile()).toBe(false);
 });
 
-test("rm_rf (folder)", async () => {
+test(".rm_rf(…) (folder)", async () => {
   const tempDir = await Path.makeTempDir();
   await tempDir.join("file.txt").write("");
   expect(tempDir.path).toContain("/js-temp-");
@@ -245,7 +259,7 @@ test("rm_rf (folder)", async () => {
   expect(await tempDir.exists()).toBe(false);
 });
 
-test(".fileText()", async () => {
+test(".readText()", async () => {
   const file = (await Path.makeTempDir()).join("file.txt");
   await file.write("hi");
   await file.write("bye");
@@ -254,7 +268,7 @@ test(".fileText()", async () => {
   expect(await readFile(file.path, "utf-8")).toBe("bye");
 });
 
-test(".fileJSON()", async () => {
+test(".readJSON()", async () => {
   const file = (await Path.makeTempDir()).join("file.json");
   await file.write(JSON.stringify({ foo: "bar" }));
 
@@ -268,14 +282,14 @@ test(".fileJSON()", async () => {
 test(".write(…)", async () => {
   const tempDir = await Path.makeTempDir();
   const file = tempDir.join("file.json");
-  await file.write("foo");
+  expect(await file.write("foo")).toBe(file);
 
   expect(await readFile(join(tempDir.path, "./file.json"), "utf-8")).toEqual(
     "foo",
   );
 
   const file2 = tempDir.join("nested/file2.json");
-  await file2.write("bar");
+  expect(await file2.write("bar")).toBe(file2);
   expect(
     await readFile(join(tempDir.path, "./nested/file2.json"), "utf-8"),
   ).toEqual("bar");
@@ -283,7 +297,7 @@ test(".write(…)", async () => {
 
 test(".writeJSON(…)", async () => {
   const file = (await Path.makeTempDir()).join("file.json");
-  await file.writeJSON({ foo: "bar" });
+  expect(await file.writeJSON({ foo: "bar" })).toBe(file);
 
   expect(await file.readJSON()).toEqual<Record<string, string>>({ foo: "bar" });
 });
@@ -296,23 +310,37 @@ test(".readDir(…)", async () => {
   const contentsAsStrings = await dir.readDir();
   expect(new Set(contentsAsStrings)).toEqual(new Set(["file.txt", "dir"]));
 
-  // const contentsAsEntries = await dir.readDir({ withFileTypes: true });
+  const contentsAsEntries = await dir.readDir({ withFileTypes: true });
+  expect(contentsAsEntries.map((entry) => entry.name)).toEqual([
+    "file.txt",
+    "dir",
+  ]);
 });
 
-test("homedir", async () => {
+test(".homedir", async () => {
   expect(Path.homedir.path).toEqual("/mock/home/dir");
 });
 
-test("XDG", async () => {
+test(".xdg", async () => {
   expect(Path.xdg.cache.path).toEqual("/mock/home/dir/.cache");
   expect(Path.xdg.config.path).toEqual("/xdg/config");
   expect(Path.xdg.data.path).toEqual("/mock/home/dir/.local/share");
   expect(Path.xdg.state.path).toEqual("/mock/home/dir/.local/state");
+  expect(Path.xdg.runtime).toBeUndefined();
+  expect(Path.xdg.runtimeWithStateFallback.path).toEqual(
+    "/mock/home/dir/.local/state",
+  );
 });
 
 const spy = spyOn(console, "log");
 
-test("debugPrint", async () => {
+test(".debugPrint(…)", async () => {
   Path.homedir.debugPrint("foo");
   expect(spy.mock.calls).toEqual([["foo"], ["/mock/home/dir"]]);
 });
+
+test(".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/Path.ts

@@ -0,0 +1,446 @@
+import type { Abortable } from "node:events";
+import type { Dirent, ObjectEncodingOptions, OpenMode } from "node:fs";
+import {
+  cp,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, extname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  xdgCache,
+  xdgConfig,
+  xdgData,
+  xdgRuntime,
+  xdgState,
+} from "xdg-basedir";
+
+// Modifying the type of `readdir(…)` from `node:fs/promises` to remove the
+// first parameter is difficult, if not impossible. So we give up and duplicate
+// the types manually. This ensures ergonomic types, such as an inferred return
+// type of `string[]` when `options` is not passed.
+
+declare function readDirType(
+  options?:
+    | (ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+      })
+    | BufferEncoding
+    | null,
+): Promise<string[]>;
+
+declare function readDirType(
+  options:
+    | {
+        encoding: "buffer";
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+      }
+    | "buffer",
+): Promise<Buffer[]>;
+
+declare function readDirType(
+  options?:
+    | (ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+      })
+    | BufferEncoding
+    | null,
+): Promise<string[] | Buffer[]>;
+
+declare function readDirType(
+  options: ObjectEncodingOptions & {
+    withFileTypes: true;
+    recursive?: boolean | undefined;
+  },
+): Promise<Dirent[]>;
+
+declare function readDirType(options: {
+  encoding: "buffer";
+  withFileTypes: true;
+  recursive?: boolean | undefined;
+}): Promise<Dirent<Buffer>[]>;
+
+declare function readFileType(
+  options?:
+    | ({
+        encoding?: null | undefined;
+        flag?: OpenMode | undefined;
+      } & Abortable)
+    | null,
+): Promise<Buffer>;
+declare function readFileType(
+  options:
+    | ({
+        encoding: BufferEncoding;
+        flag?: OpenMode | undefined;
+      } & Abortable)
+    | BufferEncoding,
+): Promise<string>;
+declare function readFileType(
+  options?:
+    | (ObjectEncodingOptions &
+        Abortable & {
+          flag?: OpenMode | undefined;
+        })
+    | BufferEncoding
+    | null,
+): Promise<string | Buffer>;
+
+export class Path {
+  // @ts-expect-error ts(2564): False positive. https://github.com/microsoft/TypeScript/issues/32194
+  #path: string;
+  /**
+   * If `path` is a string starting with `file:///`, it will be parsed as a file URL.
+   */
+  constructor(path: string | URL | Path) {
+    this.#setNormalizedPath(Path.#pathlikeToString(path));
+  }
+
+  /**
+   * Similar to `new URL(path, base)`, but accepting and returning `Path` objects.
+   * Note that `base` must be one of:
+   *
+   * - a valid second argument to `new URL(…)`.
+   * - a `Path` representing an absolute path.
+   *
+   */
+  static resolve(path: string | URL | Path, base: string | URL | Path): Path {
+    const baseURL = (() => {
+      if (!(base instanceof Path)) {
+        return base;
+      }
+      if (!base.isAbsolutePath()) {
+        throw new Error(
+          "The `base` arg to `Path.resolve(…)` must be an absolute path.",
+        );
+      }
+      return pathToFileURL(base.#path);
+    })();
+    return new Path(new URL(Path.#pathlikeToString(path), baseURL));
+  }
+
+  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");
+  }
+
+  #setNormalizedPath(path: string): void {
+    this.#path = join(path);
+  }
+
+  isAbsolutePath(): boolean {
+    return this.#path.startsWith("/");
+  }
+
+  toFileURL(): URL {
+    if (!this.isAbsolutePath()) {
+      throw new Error(
+        "Tried to convert to file URL when the path is not absolute.",
+      );
+    }
+    return pathToFileURL(this.#path);
+  }
+
+  /**
+   * The `Path` can have a trailing slash, indicating that it represents a
+   * directory. (If there is no trailing slash, it can represent either a file
+   * or a directory.)
+   *
+   * Some operations will refuse to treat a directory path as a file path. This
+   * function identifies such paths.
+   */
+  hasTrailingSlash(): boolean {
+    // TODO: handle Windows semantically
+    return this.#path.endsWith("/");
+  }
+
+  /**
+   * Same as `.toString()`, but more concise.
+   */
+  get path() {
+    return this.#path;
+  }
+
+  toString(): string {
+    return this.#path;
+  }
+
+  /** Constructs a new path by appending the given path segments.
+   * This follows `node` semantics for absolute paths: leading slashes in the given descendant segments are ignored.
+   */
+  join(...segments: (string | Path)[]): Path {
+    const segmentStrings = segments.map((segment) =>
+      segment instanceof Path ? segment.path : segment,
+    );
+    return new Path(join(this.#path, ...segmentStrings));
+  }
+
+  extendBasename(suffix: string): Path {
+    const joinedSuffix = join(suffix);
+    if (joinedSuffix !== basename(joinedSuffix)) {
+      throw new Error("Invalid suffix to extend file name.");
+    }
+    // TODO: join basename and dirname instead?
+    return new Path(this.#path + joinedSuffix);
+  }
+
+  get parent(): Path {
+    return new Path(dirname(this.#path));
+  }
+
+  // Normally I'd stick with `node`'s name, but I think `.dirname` is a
+  // particularly poor name. So we support `.dirname` for discovery but mark it
+  // as deprecated, even if it will never be removed.
+  /** @deprecated Alias for `.parent`. */
+  get dirname(): Path {
+    return this.parent;
+  }
+
+  get basename(): Path {
+    return new Path(basename(this.#path));
+  }
+
+  get extension(): string {
+    mustNotHaveTrailingSlash(this);
+    return extname(this.#path);
+  }
+
+  // Normally I'd stick with `node`'s name, but I think `.extname` is a
+  // particularly poor name. So we support `.extname` for discovery but mark it
+  // as deprecated, even if it will never be removed.
+  /** @deprecated Alias for `.extension`. */
+  get extname(): string {
+    return this.extension;
+  }
+
+  // TODO: find a neat way to dedup with the sync version?
+  async exists(constraints?: {
+    mustBe: "file" | "directory";
+  }): Promise<boolean> {
+    let stats: Awaited<ReturnType<typeof stat>>;
+    try {
+      stats = await stat(this.#path);
+      // biome-ignore lint/suspicious/noExplicitAny: TypeScript limitation
+    } catch (e: any) {
+      if (e.code === "ENOENT") {
+        return false;
+      }
+      throw e;
+    }
+    if (!constraints?.mustBe) {
+      return true;
+    }
+    switch (constraints?.mustBe) {
+      case "file": {
+        mustNotHaveTrailingSlash(this);
+        if (stats.isFile()) {
+          return true;
+        }
+        throw new Error(`Path exists but is not a file: ${this.#path}`);
+      }
+      case "directory": {
+        if (stats.isDirectory()) {
+          return true;
+        }
+        throw new Error(`Path exists but is not a directory: ${this.#path}`);
+      }
+      default: {
+        throw new Error("Invalid path type constraint");
+      }
+    }
+  }
+
+  async existsAsFile(): Promise<boolean> {
+    return this.exists({ mustBe: "file" });
+  }
+
+  async existsAsDir(): Promise<boolean> {
+    return this.exists({ mustBe: "directory" });
+  }
+
+  // I don't think `mkdir` is a great name, but it does match the
+  // well-established canonical commandline name. So in this case we keep the
+  // awkward abbreviation.
+  /** Defaults to `recursive: true`. */
+  async mkdir(options?: Parameters<typeof mkdir>[1]): Promise<Path> {
+    const optionsObject = (() => {
+      if (typeof options === "string" || typeof options === "number") {
+        return { mode: options };
+      }
+      return options ?? {};
+    })();
+    await mkdir(this.#path, { recursive: true, ...optionsObject });
+    return this;
+  }
+
+  // TODO: check idempotency semantics when the destination exists and is a folder.
+  /** Returns the destination path. */
+  async cp(
+    destination: string | URL | Path,
+    options?: Parameters<typeof cp>[2],
+  ): Promise<Path> {
+    await cp(this.#path, new Path(destination).#path, options);
+    return new Path(destination);
+  }
+
+  // TODO: check idempotency semantics when the destination exists and is a folder.
+  async rename(destination: string | URL | Path): Promise<void> {
+    await rename(this.#path, new Path(destination).#path);
+  }
+
+  /** Create a temporary dir inside the global temp dir for the current user. */
+  static async makeTempDir(prefix?: string): Promise<Path> {
+    return new Path(
+      await mkdtemp(new Path(tmpdir()).join(prefix ?? "js-temp-").toString()),
+    );
+  }
+
+  async rm(options?: Parameters<typeof rm>[1]): Promise<void> {
+    await rm(this.#path, options);
+  }
+
+  /**
+   * Equivalent to:
+   *
+   *     .rm({ recursive: true, force: true, ...(options ?? {}) })
+   *
+   */
+  async rm_rf(options?: Parameters<typeof rm>[1]): Promise<void> {
+    await this.rm({ recursive: true, force: true, ...(options ?? {}) });
+  }
+
+  read: typeof readFileType = (options) =>
+    // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.
+    readFile(this.#path, options as any) as any;
+
+  async readText(): Promise<string> {
+    return readFile(this.#path, "utf-8");
+  }
+
+  async readJSON<T>(): Promise<T> {
+    return JSON.parse(await this.readText());
+  }
+
+  /** Creates intermediate directories if they do not exist.
+   *
+   * Returns the original `Path` (for chaining).
+   */
+  async write(
+    data: Parameters<typeof writeFile>[1],
+    options?: Parameters<typeof writeFile>[2],
+  ): Promise<Path> {
+    await this.parent.mkdir();
+    await writeFile(this.#path, data, options);
+    return this;
+  }
+
+  /**
+   * If only `data` is provided, this is equivalent to:
+   *
+   *     .write(JSON.stringify(data, null, "  "));
+   *
+   * `replacer` and `space` can also be specified, making this equivalent to:
+   *
+   *     .write(JSON.stringify(data, replacer, space));
+   *
+   * Returns the original `Path` (for chaining).
+   */
+  async writeJSON<T>(
+    data: T,
+    replacer: Parameters<typeof JSON.stringify>[1] = null,
+    space: Parameters<typeof JSON.stringify>[2] = "  ",
+  ): Promise<Path> {
+    await this.write(JSON.stringify(data, replacer, space));
+    return this;
+  }
+
+  // Normally we'd add a `@deprecated` alias named `.readdir`, but that would
+  // differ only by capitalization of a single non-leading character. This can
+  // be a bit confusing, especially when autocompleting. So for this function in
+  // particular we don't include an alias.
+  readDir: typeof readDirType = (options) =>
+    // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.
+    readdir(this.#path, options as any) as any;
+
+  static get homedir(): Path {
+    return new Path(homedir());
+  }
+
+  static xdg = {
+    cache: new Path(xdgCache ?? Path.homedir.join(".cache")),
+    config: new Path(xdgConfig ?? Path.homedir.join(".config")),
+    data: new Path(xdgData ?? Path.homedir.join(".local/share")),
+    state: new Path(xdgState ?? Path.homedir.join(".local/state")),
+    /**
+     * {@link Path.xdg.runtime} does not have a default value. Consider
+     * {@link Path.xdg.runtimeWithStateFallback} if you need a fallback but do not have a particular fallback in mind.
+     */
+    runtime: xdgRuntime ? new Path(xdgRuntime) : undefined,
+    runtimeWithStateFallback: xdgRuntime
+      ? new Path(xdgRuntime)
+      : new Path(xdgState ?? Path.homedir.join(".local/state")),
+  };
+
+  /** Chainable function to print the path. Prints the same as:
+   *
+   *     if (args.length > 0) {
+   *      console.log(...args);
+   *     }
+   *     console.log(this.path);
+   *
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: This is the correct type, based on `console.log(…)`.
+  debugPrint(...args: any[]): Path {
+    if (args.length > 0) {
+      console.log(...args);
+    }
+    console.log(this.#path);
+    return this;
+  }
+}
+
+/**
+ * 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;
+}
+
+export function mustNotHaveTrailingSlash(path: Path): void {
+  if (path.hasTrailingSlash()) {
+    throw new Error(
+      "Path ends with a slash, which cannot be treated as a file.",
+    );
+  }
+}