path-class 0.6.1 → 0.7.1

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, stringifyIfPath } from ".";
+import { Path, stringifyIfPath } from "./Path";
 
 test("constructor", async () => {
   expect(new Path("foo").path).toEqual("foo");
@@ -176,6 +176,20 @@ test(".mkdir(…) (nested)", async () => {
   expect(await dir.exists()).toBe(true);
 });
 
+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");
@@ -268,14 +282,14 @@ test(".readJSON()", 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,7 +310,44 @@ 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(new Set(contentsAsEntries.map((entry) => entry.name))).toEqual(
+    new Set(["file.txt", "dir"]),
+  );
+});
+
+test(".symlink(…)", async () => {
+  const tempDir = await Path.makeTempDir();
+  const source = tempDir.join("foo.txt");
+  const target = tempDir.join("bar.txt");
+  await source.symlink(target);
+  expect(await target.existsAsFile()).toBe(false);
+  expect(() => target.readText()).toThrow(/ENOENT/);
+  await source.write("hello");
+  expect(await target.existsAsFile()).toBe(true);
+  expect(await target.readText()).toEqual("hello");
+});
+
+test(".stat(…)", async () => {
+  const file = (await Path.makeTempDir()).join("foo.txt");
+  await file.write("hello");
+
+  expect((await file.stat()).size).toEqual(5);
+  expect((await file.stat()).size).toBeTypeOf("number");
+  expect((await file.stat({ bigint: true })).size).toBeTypeOf("bigint");
+});
+
+test(".lstat(…)", async () => {
+  const tempDir = await Path.makeTempDir();
+  const source = tempDir.join("foo.txt");
+  const target = tempDir.join("bar.txt");
+  await source.symlink(target);
+  await source.write("hello");
+
+  expect((await source.lstat()).isSymbolicLink()).toBe(false);
+  expect((await target.lstat()).isSymbolicLink()).toBe(true);
+
+  expect(await target.readText()).toEqual("hello");
 });
 
 test(".homedir", async () => {
@@ -308,6 +359,10 @@ test(".xdg", async () => {
   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");

package/src/Path.ts

@@ -0,0 +1,398 @@
+import {
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  symlink,
+  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";
+import type { readDirType, readFileType } from "./modifiedNodeTypes";
+
+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;
+
+  /** Returns the destination path. */
+  async symlink(
+    target: string | URL | Path,
+    type?: Parameters<typeof symlink>[2],
+  ): Promise<Path> {
+    const targetPath = new Path(target);
+    await symlink(
+      this.path,
+      targetPath.path,
+      type as Exclude<Parameters<typeof symlink>[2], undefined>, // 🤷
+    );
+    return targetPath;
+  }
+
+  stat(options?: Parameters<typeof stat>[1]): ReturnType<typeof stat> {
+    return stat(this.path, options);
+  }
+
+  // I don't think `lstat` is a great name, but it does match the
+  // well-established canonical system call. So in this case we keep the
+  // awkward abbreviation.
+  lstat(options?: Parameters<typeof lstat>[1]): ReturnType<typeof lstat> {
+    return lstat(this.path, options);
+  }
+
+  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.",
+    );
+  }
+}