path-class 0.2.0 → 0.3.1

package/dist/lib/path-class/index.d.ts

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 export declare class Path {
     #private;
     constructor(path: string | URL | Path);
@@ -6,18 +6,49 @@ export declare class Path {
     join(...segments: string[]): Path;
     extendBasename(suffix: string): Path;
     get parent(): Path;
-    get basename(): string;
+    /** @deprecated Alias for `.parent`. */
+    get dirname(): Path;
+    get basename(): Path;
+    get extension(): string;
+    /** @deprecated Alias for `.extension`. */
+    get extname(): string;
     exists(constraints?: {
         mustBe: "file" | "directory";
     }): Promise<boolean>;
     existsAsFile(): Promise<boolean>;
     existsAsDir(): Promise<boolean>;
-    mkdir(options: Parameters<typeof mkdir>[1]): Promise<void>;
-    copy(destination: string | URL | Path): Promise<void>;
+    /** Defaults to `recursive: true`. */
+    mkdir(options?: Parameters<typeof mkdir>[1]): Promise<Path>;
+    /** Returns the destination path. */
+    cp(destination: string | URL | Path, options?: Parameters<typeof cp>[2]): Promise<Path>;
+    rename(destination: string | URL | Path): Promise<void>;
+    /** Create a temporary dir inside the global temp dir for the current user. */
+    static makeTempDir(prefix?: string): Promise<Path>;
     trash(): Promise<void>;
+    rm(options?: Parameters<typeof rm>[1]): Promise<void>;
+    /**
+     * Equivalent to:
+     *
+     *     .rm({ recursive: true, force: true, ...(options ?? {}) })
+     *
+     */
+    rm_rf(options?: Parameters<typeof rm>[1]): Promise<void>;
     fileText(): Promise<string>;
     fileJSON<T>(): Promise<T>;
-    write(s: string): Promise<void>;
+    /** Returns the original `Path` (for chaining). */
+    write(data: Parameters<typeof writeFile>[1], options?: Parameters<typeof writeFile>[2]): Promise<Path>;
+    /**
+     * 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).
+     */
+    writeJSON<T>(data: T, replacer?: Parameters<typeof JSON.stringify>[1], space?: Parameters<typeof JSON.stringify>[2]): Promise<Path>;
     static get homedir(): Path;
     static xdg: {
         cache: Path;

package/dist/lib/path-class/index.js

@@ -1,7 +1,16 @@
 // src/index.ts
-import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import {
+  cp,
+  mkdir,
+  mkdtemp,
+  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 } from "node:url";
 import { default as trash } from "trash";
 import { xdgCache, xdgConfig, xdgData, xdgState } from "xdg-basedir";
@@ -44,8 +53,33 @@ var Path = class _Path {
   get parent() {
     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() {
+    return this.parent;
+  }
   get basename() {
-    return basename(this.#path);
+    return new _Path(basename(this.#path));
+  }
+  get extension() {
+    this.#mustNotHaveTrailingSlash();
+    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() {
+    return this.extension;
+  }
+  #mustNotHaveTrailingSlash() {
+    if (this.#path.endsWith("/")) {
+      throw new Error(
+        "Path ends with a slash, which cannot be treated as a file."
+      );
+    }
   }
   async exists(constraints) {
     let stats;
@@ -62,6 +96,7 @@ var Path = class _Path {
     }
     switch (constraints?.mustBe) {
       case "file": {
+        this.#mustNotHaveTrailingSlash();
         if (stats.isFile()) {
           return true;
         }
@@ -84,16 +119,50 @@ var Path = class _Path {
   async existsAsDir() {
     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) {
-    await mkdir(this.#path, options);
+    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.
-  async copy(destination) {
-    await cp(this.#path, new _Path(destination).#path);
+  /** Returns the destination path. */
+  async cp(destination, options) {
+    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) {
+    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) {
+    return new _Path(
+      await mkdtemp(new _Path(tmpdir()).join(prefix ?? "js-temp-").toString())
+    );
+  }
   async trash() {
-    await trash(this.#path);
+    await trash(this.#path, { glob: false });
+  }
+  async rm(options) {
+    await rm(this.#path, options);
+  }
+  /**
+   * Equivalent to:
+   *
+   *     .rm({ recursive: true, force: true, ...(options ?? {}) })
+   *
+   */
+  async rm_rf(options) {
+    await this.rm({ recursive: true, force: true, ...options ?? {} });
   }
   async fileText() {
     return readFile(this.#path, "utf-8");
@@ -101,8 +170,25 @@ var Path = class _Path {
   async fileJSON() {
     return JSON.parse(await this.fileText());
   }
-  async write(s) {
-    await writeFile(this.#path, s);
+  /** Returns the original `Path` (for chaining). */
+  async write(data, options) {
+    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(data, replacer = null, space = "  ") {
+    await this.write(JSON.stringify(data, replacer, space));
+    return this;
   }
   static get homedir() {
     return new _Path(homedir());

package/dist/lib/path-class/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/index.ts"],
-  "sourcesContent": ["import { cp, mkdir, readFile, stat, writeFile } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { basename, dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { default as trash } from \"trash\";\nimport { xdgCache, xdgConfig, xdgData, xdgState } from \"xdg-basedir\";\n\n// TODO: classes for relative vs. absolute?\n\nexport class Path {\n  // @ts-expect-error ts(2564): False positive. https://github.com/microsoft/TypeScript/issues/32194\n  #path: string;\n  constructor(path: string | URL | Path) {\n    if (path instanceof Path) {\n      this.#setNormalizedPath(path.#path);\n      return;\n    }\n    if (path instanceof URL) {\n      this.#setNormalizedPath(fileURLToPath(path));\n      return;\n    }\n    if (typeof path === \"string\") {\n      this.#setNormalizedPath(path);\n      return;\n    }\n    throw new Error(\"Invalid path\");\n  }\n\n  #setNormalizedPath(path: string) {\n    this.#path = join(path);\n  }\n\n  toString(): string {\n    return this.#path;\n  }\n\n  /// Constructs a new path by appending the given path segments.\n  // TODO: accept `Path` inputs?\n  join(...segments: string[]): Path {\n    return new Path(join(this.#path, ...segments));\n  }\n\n  extendBasename(suffix: string): Path {\n    const joinedSuffix = join(suffix);\n    if (joinedSuffix !== basename(joinedSuffix)) {\n      throw new Error(\"Invalid suffix to extend file name.\");\n    }\n    // TODO: join basename and dirname instead?\n    return new Path(this.#path + joinedSuffix);\n  }\n\n  get parent(): Path {\n    return new Path(dirname(this.#path));\n  }\n\n  get basename(): string {\n    return basename(this.#path);\n  }\n\n  async exists(constraints?: {\n    mustBe: \"file\" | \"directory\";\n  }): Promise<boolean> {\n    let stats: Awaited<ReturnType<typeof stat>>;\n    try {\n      stats = await stat(this.#path);\n      // biome-ignore lint/suspicious/noExplicitAny: TypeScript limitation\n    } catch (e: any) {\n      if (e.code === \"ENOENT\") {\n        return false;\n      }\n      throw e;\n    }\n    if (!constraints?.mustBe) {\n      return true;\n    }\n    switch (constraints?.mustBe) {\n      case \"file\": {\n        if (stats.isFile()) {\n          return true;\n        }\n        throw new Error(`Path exists but is not a file: ${this.#path}`);\n      }\n      case \"directory\": {\n        if (stats.isDirectory()) {\n          return true;\n        }\n        throw new Error(`Path exists but is not a directory: ${this.#path}`);\n      }\n      default: {\n        throw new Error(\"Invalid path type constraint\");\n      }\n    }\n  }\n\n  async existsAsFile(): Promise<boolean> {\n    return this.exists({ mustBe: \"file\" });\n  }\n\n  async existsAsDir(): Promise<boolean> {\n    return this.exists({ mustBe: \"directory\" });\n  }\n\n  async mkdir(options: Parameters<typeof mkdir>[1]): Promise<void> {\n    await mkdir(this.#path, options);\n  }\n\n  // TODO: check idempotency semantics when the destination exists and is a folder.\n  async copy(destination: string | URL | Path): Promise<void> {\n    await cp(this.#path, new Path(destination).#path);\n  }\n\n  // TODO: check idempotency semantics when the destination exists and is a folder.\n  async trash(): Promise<void> {\n    await trash(this.#path);\n  }\n\n  async fileText(): Promise<string> {\n    return readFile(this.#path, \"utf-8\");\n  }\n\n  async fileJSON<T>(): Promise<T> {\n    return JSON.parse(await this.fileText());\n  }\n\n  async write(s: string): Promise<void> {\n    await writeFile(this.#path, s);\n  }\n\n  static get homedir(): Path {\n    return new Path(homedir());\n  }\n\n  static xdg = {\n    cache: new Path(xdgCache ?? Path.homedir.join(\".cache\")),\n    config: new Path(xdgConfig ?? Path.homedir.join(\".config\")),\n    data: new Path(xdgData ?? Path.homedir.join(\".local/share\")),\n    state: new Path(xdgState ?? Path.homedir.join(\".local/state\")),\n  };\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import {\n  cp,\n  mkdir,\n  mkdtemp,\n  readFile,\n  rename,\n  rm,\n  stat,\n  writeFile,\n} from \"node:fs/promises\";\nimport { homedir, tmpdir } from \"node:os\";\nimport { basename, dirname, extname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { default as trash } from \"trash\";\nimport { xdgCache, xdgConfig, xdgData, xdgState } from \"xdg-basedir\";\n\n// TODO: classes for relative vs. absolute?\n\nexport class Path {\n  // @ts-expect-error ts(2564): False positive. https://github.com/microsoft/TypeScript/issues/32194\n  #path: string;\n  constructor(path: string | URL | Path) {\n    if (path instanceof Path) {\n      this.#setNormalizedPath(path.#path);\n      return;\n    }\n    if (path instanceof URL) {\n      this.#setNormalizedPath(fileURLToPath(path));\n      return;\n    }\n    if (typeof path === \"string\") {\n      this.#setNormalizedPath(path);\n      return;\n    }\n    throw new Error(\"Invalid path\");\n  }\n\n  #setNormalizedPath(path: string): void {\n    this.#path = join(path);\n  }\n\n  toString(): string {\n    return this.#path;\n  }\n\n  /// Constructs a new path by appending the given path segments.\n  // TODO: accept `Path` inputs?\n  join(...segments: string[]): Path {\n    return new Path(join(this.#path, ...segments));\n  }\n\n  extendBasename(suffix: string): Path {\n    const joinedSuffix = join(suffix);\n    if (joinedSuffix !== basename(joinedSuffix)) {\n      throw new Error(\"Invalid suffix to extend file name.\");\n    }\n    // TODO: join basename and dirname instead?\n    return new Path(this.#path + joinedSuffix);\n  }\n\n  get parent(): Path {\n    return new Path(dirname(this.#path));\n  }\n\n  // Normally I'd stick with `node`'s name, but I think `.dirname` is a\n  // particularly poor name. So we support `.dirname` for discovery but mark it\n  // as deprecated, even if it will never be removed.\n  /** @deprecated Alias for `.parent`. */\n  get dirname(): Path {\n    return this.parent;\n  }\n\n  get basename(): Path {\n    return new Path(basename(this.#path));\n  }\n\n  get extension(): string {\n    this.#mustNotHaveTrailingSlash();\n    return extname(this.#path);\n  }\n\n  // Normally I'd stick with `node`'s name, but I think `.extname` is a\n  // particularly poor name. So we support `.extname` for discovery but mark it\n  // as deprecated, even if it will never be removed.\n  /** @deprecated Alias for `.extension`. */\n  get extname(): string {\n    return this.extension;\n  }\n\n  #mustNotHaveTrailingSlash(): void {\n    if (this.#path.endsWith(\"/\")) {\n      throw new Error(\n        \"Path ends with a slash, which cannot be treated as a file.\",\n      );\n    }\n  }\n\n  async exists(constraints?: {\n    mustBe: \"file\" | \"directory\";\n  }): Promise<boolean> {\n    let stats: Awaited<ReturnType<typeof stat>>;\n    try {\n      stats = await stat(this.#path);\n      // biome-ignore lint/suspicious/noExplicitAny: TypeScript limitation\n    } catch (e: any) {\n      if (e.code === \"ENOENT\") {\n        return false;\n      }\n      throw e;\n    }\n    if (!constraints?.mustBe) {\n      return true;\n    }\n    switch (constraints?.mustBe) {\n      case \"file\": {\n        this.#mustNotHaveTrailingSlash();\n        if (stats.isFile()) {\n          return true;\n        }\n        throw new Error(`Path exists but is not a file: ${this.#path}`);\n      }\n      case \"directory\": {\n        if (stats.isDirectory()) {\n          return true;\n        }\n        throw new Error(`Path exists but is not a directory: ${this.#path}`);\n      }\n      default: {\n        throw new Error(\"Invalid path type constraint\");\n      }\n    }\n  }\n\n  async existsAsFile(): Promise<boolean> {\n    return this.exists({ mustBe: \"file\" });\n  }\n\n  async existsAsDir(): Promise<boolean> {\n    return this.exists({ mustBe: \"directory\" });\n  }\n\n  // I don't think `mkdir` is a great name, but it does match the\n  // well-established canonical commandline name. So in this case we keep the\n  // awkward abbreviation.\n  /** Defaults to `recursive: true`. */\n  async mkdir(options?: Parameters<typeof mkdir>[1]): Promise<Path> {\n    const optionsObject = (() => {\n      if (typeof options === \"string\" || typeof options === \"number\") {\n        return { mode: options };\n      }\n      return options ?? {};\n    })();\n    await mkdir(this.#path, { recursive: true, ...optionsObject });\n    return this;\n  }\n\n  // TODO: check idempotency semantics when the destination exists and is a folder.\n  /** Returns the destination path. */\n  async cp(\n    destination: string | URL | Path,\n    options?: Parameters<typeof cp>[2],\n  ): Promise<Path> {\n    await cp(this.#path, new Path(destination).#path, options);\n    return new Path(destination);\n  }\n\n  // TODO: check idempotency semantics when the destination exists and is a folder.\n  async rename(destination: string | URL | Path): Promise<void> {\n    await rename(this.#path, new Path(destination).#path);\n  }\n\n  /** Create a temporary dir inside the global temp dir for the current user. */\n  static async makeTempDir(prefix?: string): Promise<Path> {\n    return new Path(\n      await mkdtemp(new Path(tmpdir()).join(prefix ?? \"js-temp-\").toString()),\n    );\n  }\n\n  async trash(): Promise<void> {\n    await trash(this.#path, { glob: false });\n  }\n\n  async rm(options?: Parameters<typeof rm>[1]): Promise<void> {\n    await rm(this.#path, options);\n  }\n\n  /**\n   * Equivalent to:\n   *\n   *     .rm({ recursive: true, force: true, ...(options ?? {}) })\n   *\n   */\n  async rm_rf(options?: Parameters<typeof rm>[1]): Promise<void> {\n    await this.rm({ recursive: true, force: true, ...(options ?? {}) });\n  }\n\n  async fileText(): Promise<string> {\n    return readFile(this.#path, \"utf-8\");\n  }\n\n  async fileJSON<T>(): Promise<T> {\n    return JSON.parse(await this.fileText());\n  }\n\n  /** Returns the original `Path` (for chaining). */\n  async write(\n    data: Parameters<typeof writeFile>[1],\n    options?: Parameters<typeof writeFile>[2],\n  ): Promise<Path> {\n    await writeFile(this.#path, data, options);\n    return this;\n  }\n\n  /**\n   * If only `data` is provided, this is equivalent to:\n   *\n   *     .write(JSON.stringify(data, null, \"  \"));\n   *\n   * `replacer` and `space` can also be specified, making this equivalent to:\n   *\n   *     .write(JSON.stringify(data, replacer, space));\n   *\n   * Returns the original `Path` (for chaining).\n   */\n  async writeJSON<T>(\n    data: T,\n    replacer: Parameters<typeof JSON.stringify>[1] = null,\n    space: Parameters<typeof JSON.stringify>[2] = \"  \",\n  ): Promise<Path> {\n    await this.write(JSON.stringify(data, replacer, space));\n    return this;\n  }\n\n  static get homedir(): Path {\n    return new Path(homedir());\n  }\n\n  static xdg = {\n    cache: new Path(xdgCache ?? Path.homedir.join(\".cache\")),\n    config: new Path(xdgConfig ?? Path.homedir.join(\".config\")),\n    data: new Path(xdgData ?? Path.homedir.join(\".local/share\")),\n    state: new Path(xdgState ?? Path.homedir.join(\".local/state\")),\n  };\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-class",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "author": "Lucas Garron <code@garron.net>",
   "type": "module",
   "main": "./dist/lib/path-class/index.js",
@@ -14,15 +14,20 @@
   "devDependencies": {
     "@biomejs/biome": "^2.2.5",
     "@cubing/dev-config": "^0.3.6",
+    "@types/bun": "^1.3.0",
     "esbuild": "^0.25.10"
   },
   "dependencies": {
-    "@types/node": "^24.7.0",
+    "@types/node": "^24.7.1",
     "trash": "^10.0.0",
+    "typescript": "^5.9.3",
     "xdg-basedir": "^5.1.0"
   },
   "files": [
     "./dist/",
     "./src"
-  ]
+  ],
+  "scripts": {
+    "prepublishOnly": "make prepublishOnly"
+  }
 }

package/src/index.test.ts

@@ -0,0 +1,249 @@
+import { expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import { Path } from ".";
+
+test("constructor", async () => {
+  expect(new Path("foo").toString()).toEqual("foo");
+  expect(new Path("./relative").toString()).toEqual("relative");
+  expect(new Path("./relative/nested").toString()).toEqual("relative/nested");
+  expect(new Path("/absolute").toString()).toEqual("/absolute");
+  expect(new Path("/absolute/nested").toString()).toEqual("/absolute/nested");
+  expect(new Path("trailing/slash/").toString()).toEqual("trailing/slash/");
+});
+
+test("normalize", async () => {
+  expect(new Path("foo//bar").toString()).toEqual("foo/bar");
+  expect(new Path("foo////bar").toString()).toEqual("foo/bar");
+  expect(new Path("foo/bar/").toString()).toEqual("foo/bar/");
+  expect(new Path("foo/bar//").toString()).toEqual("foo/bar/");
+  expect(new Path("//absolute////bar").toString()).toEqual("/absolute/bar");
+});
+
+test("join", async () => {
+  expect(new Path("foo").join("bar").toString()).toEqual("foo/bar");
+  expect(new Path("foo/bar").join("bath", "kitchen/sink").toString()).toEqual(
+    "foo/bar/bath/kitchen/sink",
+  );
+});
+
+test("traverse", async () => {
+  expect(new Path("foo/bar").join("..").toString()).toEqual("foo");
+  expect(new Path("foo/bar").join(".").toString()).toEqual("foo/bar");
+  expect(new Path("foo/bar").join("../baz").toString()).toEqual("foo/baz");
+  expect(new Path("/absolute/path").join("../..").toString()).toEqual("/");
+  expect(new Path("/absolute/path").join("../../..").toString()).toEqual("/");
+  expect(new Path("/").join("..").toString()).toEqual("/");
+});
+
+test(".extendBasename(…)", async () => {
+  expect(
+    new Path("file.mp4").extendBasename(".hevc.qv65.mov").toString(),
+  ).toEqual("file.mp4.hevc.qv65.mov");
+  // Trailing dots should not be removed.
+  expect(
+    new Path("file.mp4.").extendBasename(".hevc.qv65.mov").toString(),
+  ).toEqual("file.mp4..hevc.qv65.mov");
+});
+
+test(".parent", async () => {
+  expect(new Path("/").parent.toString()).toEqual("/");
+  expect(new Path("dir").parent.toString()).toEqual(".");
+  expect(new Path("dir/").parent.toString()).toEqual(".");
+});
+
+test(".dirname", async () => {
+  expect(new Path("/").dirname.toString()).toEqual("/");
+  expect(new Path("dir").dirname.toString()).toEqual(".");
+  expect(new Path("dir/").dirname.toString()).toEqual(".");
+});
+
+test(".basename", async () => {
+  expect(new Path("/").basename.toString()).toEqual("."); // TODO?
+  expect(new Path("dir").basename.toString()).toEqual("dir");
+  expect(new Path("dir/").basename.toString()).toEqual("dir");
+  expect(Path.xdg.config.join("foo/bar.json").basename.toString()).toEqual(
+    "bar.json",
+  );
+});
+
+test(".extension", async () => {
+  expect(new Path("foo.txt").extension).toEqual(".txt");
+  expect(new Path("foo.").extension).toEqual(".");
+  expect(new Path("foo").extension).toEqual("");
+  expect(() => new Path("dir/").extension).toThrow();
+  expect(() => new Path("/").extension).toThrow();
+});
+
+test(".extname", async () => {
+  expect(new Path("foo.txt").extname).toEqual(".txt");
+  expect(new Path("foo.").extname).toEqual(".");
+  expect(new Path("foo").extname).toEqual("");
+  expect(() => new Path("dir/").extname).toThrow();
+  expect(() => new Path("/").extname).toThrow();
+});
+
+test(".existsAsFile()", async () => {
+  const filePath = (await Path.makeTempDir()).join("file.txt");
+  expect(await filePath.exists()).toBe(false);
+  expect(await filePath.exists({ mustBe: "file" })).toBe(false);
+  expect(await filePath.exists({ mustBe: "directory" })).toBe(false);
+  expect(await filePath.existsAsFile()).toBe(false);
+  await filePath.write("test");
+  expect(await filePath.exists()).toBe(true);
+  expect(await filePath.exists({ mustBe: "file" })).toBe(true);
+  expect(() => filePath.exists({ mustBe: "directory" })).toThrow(
+    /Path exists but is not a directory/,
+  );
+  expect(await filePath.existsAsFile()).toBe(true);
+});
+
+test(".existsAsDir()", async () => {
+  const filePath = await Path.makeTempDir();
+  expect(await filePath.exists()).toBe(true);
+  expect(() => filePath.exists({ mustBe: "file" })).toThrow(
+    /Path exists but is not a file/,
+  );
+  expect(await filePath.exists({ mustBe: "directory" })).toBe(true);
+  expect(await filePath.existsAsDir()).toBe(true);
+  await filePath.trash();
+  expect(await filePath.exists()).toBe(false);
+  expect(await filePath.exists({ mustBe: "file" })).toBe(false);
+  expect(await filePath.exists({ mustBe: "directory" })).toBe(false);
+  expect(await filePath.existsAsDir()).toBe(false);
+});
+
+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 () => {
+  const dir = (await Path.makeTempDir()).join("mkdir-test/nested");
+  expect(await dir.exists()).toBe(false);
+  expect(() => dir.mkdir({ recursive: false })).toThrow("no such file");
+  await dir.mkdir();
+  expect(await dir.exists()).toBe(true);
+});
+
+test(".rename()", 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.rename(file2);
+  expect(await file1.exists()).toBe(false);
+  expect(await file2.exists()).toBe(true);
+});
+
+test(".makeTempDir(…)", async () => {
+  const tempDir = await Path.makeTempDir();
+  expect(tempDir.toString()).toContain("/js-temp-");
+  expect(tempDir.basename.toString()).toStartWith("js-temp-");
+  expect(await tempDir.existsAsDir()).toBe(true);
+
+  const tempDir2 = await Path.makeTempDir("foo");
+  expect(tempDir2.toString()).not.toContain("/js-temp-");
+  expect(tempDir2.basename.toString()).toStartWith("foo");
+});
+
+test("trash", async () => {
+  const tempDir = await Path.makeTempDir();
+  expect(await tempDir.exists()).toBe(true);
+  await tempDir.trash();
+  expect(await tempDir.exists()).toBe(false);
+});
+
+test("rm (file)", async () => {
+  const file = (await Path.makeTempDir()).join("file.txt");
+  await file.write("");
+  expect(await file.existsAsFile()).toBe(true);
+  await file.rm();
+  expect(await file.existsAsFile()).toBe(false);
+  expect(await file.parent.existsAsDir()).toBe(true);
+  expect(async () => file.rm()).toThrowError(/ENOENT/);
+});
+
+test("rm (folder)", async () => {
+  const tempDir = await Path.makeTempDir();
+  const file = tempDir.join("file.txt");
+  await file.write("");
+  expect(await tempDir.existsAsDir()).toBe(true);
+  expect(async () => tempDir.rm()).toThrowError(/EACCES/);
+  await file.rm();
+  await tempDir.rm({ recursive: true });
+  expect(await tempDir.existsAsDir()).toBe(false);
+  expect(async () => tempDir.rm()).toThrowError(/ENOENT/);
+});
+
+test("rm_rf (file)", async () => {
+  const file = (await Path.makeTempDir()).join("file.txt");
+  await file.write("");
+  expect(await file.existsAsFile()).toBe(true);
+  await file.rm_rf();
+  expect(await file.existsAsFile()).toBe(false);
+  expect(await file.parent.existsAsDir()).toBe(true);
+  await file.rm_rf();
+  expect(await file.existsAsFile()).toBe(false);
+});
+
+test("rm_rf (folder)", async () => {
+  const tempDir = await Path.makeTempDir();
+  await tempDir.join("file.txt").write("");
+  expect(tempDir.toString()).toContain("/js-temp-");
+  expect(await tempDir.exists()).toBe(true);
+  await tempDir.rm_rf();
+  expect(await tempDir.exists()).toBe(false);
+  await tempDir.rm_rf();
+  expect(await tempDir.exists()).toBe(false);
+});
+
+test(".fileText()", async () => {
+  const file = (await Path.makeTempDir()).join("file.txt");
+  await file.write("hi");
+  await file.write("bye");
+
+  expect(await file.fileText()).toBe("bye");
+  expect(await readFile(file.toString(), "utf-8")).toBe("bye");
+});
+
+test(".fileJSON()", async () => {
+  const file = (await Path.makeTempDir()).join("file.json");
+  await file.write(JSON.stringify({ foo: "bar" }));
+
+  expect(await file.fileJSON()).toEqual<Record<string, string>>({ foo: "bar" });
+  expect(await file.fileJSON<Record<string, string>>()).toEqual({ foo: "bar" });
+  expect(await JSON.parse(await readFile(file.toString(), "utf-8"))).toEqual<
+    Record<string, string>
+  >({ foo: "bar" });
+});
+
+test(".write(…)", async () => {
+  const file = (await Path.makeTempDir()).join("file.json");
+  await file.write("foo");
+
+  expect(await file.fileText()).toEqual("foo");
+});
+
+test(".writeJSON(…)", async () => {
+  const file = (await Path.makeTempDir()).join("file.json");
+  await file.writeJSON({ foo: "bar" });
+
+  expect(await file.fileJSON()).toEqual<Record<string, string>>({ foo: "bar" });
+});
+
+test("homedir", async () => {
+  expect(Path.homedir.toString()).toEqual("/mock/home/dir");
+});
+
+test("XDG", async () => {
+  expect(Path.xdg.cache.toString()).toEqual("/mock/home/dir/.cache");
+  expect(Path.xdg.config.toString()).toEqual("/xdg/config");
+  expect(Path.xdg.data.toString()).toEqual("/mock/home/dir/.local/share");
+  expect(Path.xdg.state.toString()).toEqual("/mock/home/dir/.local/state");
+});

package/src/index.ts

@@ -1,6 +1,15 @@
-import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import {
+  cp,
+  mkdir,
+  mkdtemp,
+  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 } from "node:url";
 import { default as trash } from "trash";
 import { xdgCache, xdgConfig, xdgData, xdgState } from "xdg-basedir";
@@ -26,7 +35,7 @@ export class Path {
     throw new Error("Invalid path");
   }
 
-  #setNormalizedPath(path: string) {
+  #setNormalizedPath(path: string): void {
     this.#path = join(path);
   }
 
@@ -53,8 +62,37 @@ export class Path {
     return new Path(dirname(this.#path));
   }
 
-  get basename(): string {
-    return basename(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 {
+    this.#mustNotHaveTrailingSlash();
+    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;
+  }
+
+  #mustNotHaveTrailingSlash(): void {
+    if (this.#path.endsWith("/")) {
+      throw new Error(
+        "Path ends with a slash, which cannot be treated as a file.",
+      );
+    }
   }
 
   async exists(constraints?: {
@@ -75,6 +113,7 @@ export class Path {
     }
     switch (constraints?.mustBe) {
       case "file": {
+        this.#mustNotHaveTrailingSlash();
         if (stats.isFile()) {
           return true;
         }
@@ -100,18 +139,59 @@ export class Path {
     return this.exists({ mustBe: "directory" });
   }
 
-  async mkdir(options: Parameters<typeof mkdir>[1]): Promise<void> {
-    await mkdir(this.#path, options);
+  // 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.
-  async copy(destination: string | URL | Path): Promise<void> {
-    await cp(this.#path, new Path(destination).#path);
+  /** 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 trash(): Promise<void> {
-    await trash(this.#path);
+    await trash(this.#path, { glob: false });
+  }
+
+  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 ?? {}) });
   }
 
   async fileText(): Promise<string> {
@@ -122,8 +202,33 @@ export class Path {
     return JSON.parse(await this.fileText());
   }
 
-  async write(s: string): Promise<void> {
-    await writeFile(this.#path, s);
+  /** Returns the original `Path` (for chaining). */
+  async write(
+    data: Parameters<typeof writeFile>[1],
+    options?: Parameters<typeof writeFile>[2],
+  ): Promise<Path> {
+    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;
   }
 
   static get homedir(): Path {

package/src/test.preload.ts

@@ -0,0 +1,19 @@
+import { mock } from "bun:test";
+import nodeOS from "node:os";
+
+const nodeOSMocked = {
+  ...nodeOS,
+  homedir: () => "/mock/home/dir",
+};
+// biome-ignore lint/suspicious/noExplicitAny: This isn't worth wrangling types for.
+(nodeOSMocked as any).default = nodeOSMocked; // Needed because `xdg-basedir` imports the default.
+
+mock.module("node:os", () => {
+  return nodeOSMocked;
+});
+
+mock.module("os", () => {
+  return nodeOSMocked;
+});
+
+process.env = { XDG_CONFIG_HOME: "/xdg/config" };