path-class 0.6.1 → 0.7.1

package/src/sync/index.ts

@@ -0,0 +1,215 @@
+import {
+  cpSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { mustNotHaveTrailingSlash, Path } from "../Path";
+import "./static";
+import type { readDirSyncType, readFileSyncType } from "./modifiedNodeTypes";
+
+// Note that (non-static) functions in this file are defined using `function(…)
+// { … }` rather than arrow functions, specifically because we want `this` to
+// operate on the `Path` instance.
+
+declare module "../Path" {
+  interface Path {
+    existsSync(constraints?: { mustBe: "file" | "directory" }): boolean;
+    existsAsFileSync(): boolean;
+    existsAsDirSync(): boolean;
+
+    mkdirSync(options?: Parameters<typeof mkdirSync>[1]): Path;
+    cpSync(
+      destination: string | URL | Path,
+      options?: Parameters<typeof cpSync>[2],
+    ): Path;
+    renameSync(destination: string | URL | Path): void;
+
+    rmSync(options?: Parameters<typeof rmSync>[1]): void;
+    rm_rfSync(options?: Parameters<typeof rmSync>[1]): void;
+
+    readSync: typeof readFileSyncType;
+    readTextSync(): string;
+    readJSONSync<T>(): T;
+
+    writeSync(
+      data: Parameters<typeof writeFileSync>[1],
+      options?: Parameters<typeof writeFileSync>[2] | undefined,
+    ): Path;
+    writeJSONSync<T>(
+      data: T,
+      replacer?: Parameters<typeof JSON.stringify>[1],
+      space?: Parameters<typeof JSON.stringify>[2],
+    ): Path;
+
+    readDirSync: typeof readDirSyncType;
+
+    /** Returns the destination path. */
+    symlinkSync(
+      target: string | URL | Path,
+      type?: Parameters<typeof symlinkSync>[2],
+    ): Path;
+
+    statSync(
+      options?: Parameters<typeof statSync>[1],
+    ): ReturnType<typeof statSync>;
+
+    // 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.
+    lstatSync(
+      options?: Parameters<typeof lstatSync>[1],
+    ): ReturnType<typeof lstatSync>;
+  }
+}
+
+// TODO: find a neat way to dedup with the async version?
+Path.prototype.existsSync = function (constraints?: {
+  mustBe: "file" | "directory";
+}): boolean {
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(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");
+    }
+  }
+};
+
+Path.prototype.existsAsFileSync = function (): boolean {
+  return this.existsSync({ mustBe: "file" });
+};
+
+Path.prototype.existsAsDirSync = function (): boolean {
+  return this.existsSync({ mustBe: "directory" });
+};
+
+Path.prototype.mkdirSync = function (
+  options?: Parameters<typeof mkdirSync>[1],
+): Path {
+  const optionsObject = (() => {
+    if (typeof options === "string" || typeof options === "number") {
+      return { mode: options };
+    }
+    return options ?? {};
+  })();
+  mkdirSync(this.path, { recursive: true, ...optionsObject });
+  return this;
+};
+
+Path.prototype.cpSync = function (
+  destination: string | URL | Path,
+  options?: Parameters<typeof cpSync>[2],
+): Path {
+  cpSync(this.path, new Path(destination).path, options);
+  return new Path(destination);
+};
+
+Path.prototype.renameSync = function (destination: string | URL | Path): void {
+  renameSync(this.path, new Path(destination).path);
+};
+
+Path.prototype.rmSync = function (
+  options?: Parameters<typeof rmSync>[1],
+): void {
+  rmSync(this.path, options);
+};
+
+Path.prototype.rm_rfSync = function (
+  options?: Parameters<typeof rmSync>[1],
+): void {
+  this.rmSync({ recursive: true, force: true, ...(options ?? {}) });
+};
+
+Path.prototype.readSync = function () {
+  /** @ts-expect-error ts(2683) */
+  return readFileSync(this.path);
+} as typeof readFileSyncType;
+
+Path.prototype.readTextSync = function (): string {
+  return readFileSync(this.path, "utf-8");
+};
+
+Path.prototype.readJSONSync = function <T>(): T {
+  return JSON.parse(this.readTextSync());
+};
+
+Path.prototype.writeSync = function (
+  data: Parameters<typeof writeFileSync>[1],
+  options?: Parameters<typeof writeFileSync>[2],
+): Path {
+  this.parent.mkdirSync();
+  writeFileSync(this.path, data, options);
+  return this;
+};
+
+Path.prototype.writeJSONSync = function <T>(
+  data: T,
+  replacer: Parameters<typeof JSON.stringify>[1] = null,
+  space: Parameters<typeof JSON.stringify>[2] = "  ",
+): Path {
+  this.parent.mkdirSync();
+  this.writeSync(JSON.stringify(data, replacer, space));
+  return this;
+};
+
+/** @ts-expect-error ts(2322): Wrangle types */
+Path.prototype.readDirSync = function (options) {
+  // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.
+  return readdirSync(this.path, options as any);
+};
+
+Path.prototype.symlinkSync = function symlink(
+  target: string | URL | Path,
+  type?: Parameters<typeof symlinkSync>[2],
+): Path {
+  const targetPath = new Path(target);
+  symlinkSync(
+    this.path,
+    targetPath.path,
+    type as Exclude<Parameters<typeof symlinkSync>[2], undefined>, // 🤷
+  );
+  return targetPath;
+};
+
+Path.prototype.statSync = function (
+  options?: Parameters<typeof statSync>[1],
+): ReturnType<typeof statSync> {
+  return statSync(this.path, options);
+};
+
+Path.prototype.lstatSync = function (
+  options?: Parameters<typeof lstatSync>[1],
+): ReturnType<typeof lstatSync> {
+  return lstatSync(this.path, options);
+};

package/src/sync/modifiedNodeTypes.ts

@@ -0,0 +1,66 @@
+// Note: this file is `.ts` rather than `.d.ts` to ensure it ends up in the `tsc` output.
+
+import type { Dirent, ObjectEncodingOptions } from "node:fs";
+
+export declare function readFileSyncType(
+  options?: {
+    encoding?: null | undefined;
+    flag?: string | undefined;
+  } | null,
+): NonSharedBuffer;
+export declare function readFileSyncType(
+  options:
+    | {
+        encoding: BufferEncoding;
+        flag?: string | undefined;
+      }
+    | BufferEncoding,
+): string;
+export declare function readFileSyncType(
+  options?:
+    | (ObjectEncodingOptions & {
+        flag?: string | undefined;
+      })
+    | BufferEncoding
+    | null,
+): string | NonSharedBuffer;
+
+export declare function readDirSyncType(
+  options?:
+    | {
+        encoding: BufferEncoding | null;
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+      }
+    | BufferEncoding
+    | null,
+): string[];
+export declare function readDirSyncType(
+  options:
+    | {
+        encoding: "buffer";
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+      }
+    | "buffer",
+): Buffer[];
+export declare function readDirSyncType(
+  options?:
+    | (ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+      })
+    | BufferEncoding
+    | null,
+): string[] | Buffer[];
+export declare function readDirSyncType(
+  options: ObjectEncodingOptions & {
+    withFileTypes: true;
+    recursive?: boolean | undefined;
+  },
+): Dirent[];
+export declare function readDirSyncType(options: {
+  encoding: "buffer";
+  withFileTypes: true;
+  recursive?: boolean | undefined;
+}): Dirent<Buffer>[];

package/src/sync/static.ts

@@ -0,0 +1,14 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { Path } from "../Path";
+
+declare module "../Path" {
+  namespace Path {
+    export function makeTempDirSync(prefix?: string): Path;
+  }
+}
+
+Path.makeTempDirSync = (prefix?: string): Path =>
+  new Path(
+    mkdtempSync(new Path(tmpdir()).join(prefix ?? "js-temp-").toString()),
+  );

package/src/sync/sync.test.ts

@@ -0,0 +1,224 @@
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Path } from "../Path";
+import "./index";
+
+test(".existsAsFileSync()", () => {
+  const filePath = Path.makeTempDirSync().join("file.txt");
+  expect(filePath.existsSync()).toBe(false);
+  expect(filePath.existsSync({ mustBe: "file" })).toBe(false);
+  expect(filePath.existsSync({ mustBe: "directory" })).toBe(false);
+  expect(filePath.existsAsFileSync()).toBe(false);
+  filePath.writeSync("test");
+  expect(filePath.existsSync()).toBe(true);
+  expect(filePath.existsSync({ mustBe: "file" })).toBe(true);
+  expect(() => filePath.existsSync({ mustBe: "directory" })).toThrow(
+    /Path exists but is not a directory/,
+  );
+  expect(filePath.existsAsFileSync()).toBe(true);
+});
+
+test(".existsAsDir()", () => {
+  const filePath = Path.makeTempDirSync();
+  expect(filePath.existsSync()).toBe(true);
+  expect(() => filePath.existsSync({ mustBe: "file" })).toThrow(
+    /Path exists but is not a file/,
+  );
+  expect(filePath.existsSync({ mustBe: "directory" })).toBe(true);
+  expect(filePath.existsAsDirSync()).toBe(true);
+  filePath.rm_rfSync();
+  expect(filePath.existsSync()).toBe(false);
+  expect(filePath.existsSync({ mustBe: "file" })).toBe(false);
+  expect(filePath.existsSync({ mustBe: "directory" })).toBe(false);
+  expect(filePath.existsAsDirSync()).toBe(false);
+});
+
+test(".mkdirSync(…) (un-nested)", () => {
+  const dir = Path.makeTempDirSync().join("mkdir-test");
+  expect(dir.existsSync()).toBe(false);
+  dir.mkdirSync();
+  expect(dir.existsSync()).toBe(true);
+});
+
+test(".mkdirSync(…) (nested)", () => {
+  const dir = Path.makeTempDirSync().join("mkdir-test/nested");
+  expect(dir.existsSync()).toBe(false);
+  expect(() => dir.mkdirSync({ recursive: false })).toThrow("no such file");
+  dir.mkdirSync();
+  expect(dir.existsSync()).toBe(true);
+});
+
+test(".cpSync(…)", () => {
+  const parentDir = Path.makeTempDirSync();
+  const file1 = parentDir.join("file1.txt");
+  const file2 = parentDir.join("file2.txt");
+
+  file1.writeSync("hello world");
+  expect(file1.existsSync()).toBe(true);
+  expect(file2.existsSync()).toBe(false);
+
+  file1.cpSync(file2);
+  expect(file1.existsSync()).toBe(true);
+  expect(file2.existsSync()).toBe(true);
+});
+
+test(".renameSync(…)", () => {
+  const parentDir = Path.makeTempDirSync();
+  const file1 = parentDir.join("file1.txt");
+  const file2 = parentDir.join("file2.txt");
+
+  file1.writeSync("hello world");
+  expect(file1.existsSync()).toBe(true);
+  expect(file2.existsSync()).toBe(false);
+
+  file1.renameSync(file2);
+  expect(file1.existsSync()).toBe(false);
+  expect(file2.existsSync()).toBe(true);
+});
+
+test(".makeTempDirSync(…)", () => {
+  const tempDir = Path.makeTempDirSync();
+  expect(tempDir.path).toContain("/js-temp-");
+  expect(tempDir.basename.path).toStartWith("js-temp-");
+  expect(tempDir.existsAsDirSync()).toBe(true);
+
+  const tempDir2 = Path.makeTempDirSync("foo");
+  expect(tempDir2.path).not.toContain("/js-temp-");
+  expect(tempDir2.basename.path).toStartWith("foo");
+});
+
+test(".rmSync(…) (file)", () => {
+  const file = Path.makeTempDirSync().join("file.txt");
+  file.writeSync("");
+  expect(file.existsAsFileSync()).toBe(true);
+  file.rmSync();
+  expect(file.existsAsFileSync()).toBe(false);
+  expect(file.parent.existsAsDirSync()).toBe(true);
+  expect(() => file.rmSync()).toThrowError(/ENOENT/);
+});
+
+test(".rmSync(…) (folder)", () => {
+  const tempDir = Path.makeTempDirSync();
+  const file = tempDir.join("file.txt");
+  file.writeSync("");
+  expect(tempDir.existsAsDirSync()).toBe(true);
+  expect(() => tempDir.rmSync()).toThrowError(/EACCES|EFAULT/);
+  file.rmSync();
+  tempDir.rmSync({ recursive: true });
+  expect(tempDir.existsAsDirSync()).toBe(false);
+  expect(() => tempDir.rmSync()).toThrowError(/ENOENT/);
+});
+
+test(".rm_rfSync(…) (file)", () => {
+  const file = Path.makeTempDirSync().join("file.txt");
+  file.writeSync("");
+  expect(file.existsAsFileSync()).toBe(true);
+  file.rm_rfSync();
+  expect(file.existsAsFileSync()).toBe(false);
+  expect(file.parent.existsAsDirSync()).toBe(true);
+  file.rm_rfSync();
+  expect(file.existsAsFileSync()).toBe(false);
+});
+
+test(".rm_rfSync(…) (folder)", () => {
+  const tempDir = Path.makeTempDirSync();
+  tempDir.join("file.txt").writeSync("");
+  expect(tempDir.path).toContain("/js-temp-");
+  expect(tempDir.existsSync()).toBe(true);
+  tempDir.rm_rfSync();
+  expect(tempDir.existsSync()).toBe(false);
+  tempDir.rm_rfSync();
+  expect(tempDir.existsSync()).toBe(false);
+});
+
+test(".readTextSync()", () => {
+  const file = Path.makeTempDirSync().join("file.txt");
+  file.writeSync("hi");
+  file.writeSync("bye");
+
+  expect(file.readTextSync()).toBe("bye");
+  expect(readFileSync(file.path, "utf-8")).toBe("bye");
+});
+
+test(".readJSONWync()", () => {
+  const file = Path.makeTempDirSync().join("file.json");
+  file.writeSync(JSON.stringify({ foo: "bar" }));
+
+  expect(file.readJSONSync()).toEqual<Record<string, string>>({ foo: "bar" });
+  expect(file.readJSONSync<Record<string, string>>()).toEqual({ foo: "bar" });
+  expect(JSON.parse(readFileSync(file.path, "utf-8"))).toEqual<
+    Record<string, string>
+  >({ foo: "bar" });
+});
+
+test(".writeSync(…)", () => {
+  const tempDir = Path.makeTempDirSync();
+  const file = tempDir.join("file.json");
+  expect(file.writeSync("foo")).toBe(file);
+
+  expect(readFileSync(join(tempDir.path, "./file.json"), "utf-8")).toEqual(
+    "foo",
+  );
+
+  const file2 = tempDir.join("nested/file2.json");
+  expect(file2.writeSync("bar")).toBe(file2);
+  expect(
+    readFileSync(join(tempDir.path, "./nested/file2.json"), "utf-8"),
+  ).toEqual("bar");
+});
+
+test(".writeJSONSync(…)", () => {
+  const file = Path.makeTempDirSync().join("file.json");
+  expect(file.writeJSONSync({ foo: "bar" })).toBe(file);
+
+  expect(file.readJSONSync()).toEqual<Record<string, string>>({ foo: "bar" });
+});
+
+test(".readDirSync(…)", () => {
+  const dir = Path.makeTempDirSync();
+  dir.join("file.txt").writeSync("hello");
+  dir.join("dir/file.json").writeSync("hello");
+
+  const contentsAsStrings = dir.readDirSync();
+  expect(new Set(contentsAsStrings)).toEqual(new Set(["file.txt", "dir"]));
+
+  const contentsAsEntries = dir.readDirSync({ withFileTypes: true });
+  expect(new Set(contentsAsEntries.map((entry) => entry.name))).toEqual(
+    new Set(["file.txt", "dir"]),
+  );
+});
+
+test(".symlinkSync(…)", () => {
+  const tempDir = Path.makeTempDirSync();
+  const source = tempDir.join("foo.txt");
+  const target = tempDir.join("bar.txt");
+  source.symlinkSync(target);
+  expect(target.existsAsFileSync()).toBe(false);
+  expect(() => target.readText()).toThrow(/ENOENT/);
+  source.writeSync("hello");
+  expect(target.existsAsFileSync()).toBe(true);
+  expect(target.readTextSync()).toEqual("hello");
+});
+
+test(".statSync(…)", () => {
+  const file = Path.makeTempDirSync().join("foo.txt");
+  file.writeSync("hello");
+
+  expect(file.statSync()?.size).toEqual(5);
+  expect(file.statSync()?.size).toBeTypeOf("number");
+  expect(file.statSync({ bigint: true })?.size).toBeTypeOf("bigint");
+});
+
+test(".lstatSync(…)", () => {
+  const tempDir = Path.makeTempDirSync();
+  const source = tempDir.join("foo.txt");
+  const target = tempDir.join("bar.txt");
+  source.symlinkSync(target);
+  source.writeSync("hello");
+
+  expect(source.lstatSync()?.isSymbolicLink()).toBe(false);
+  expect(target.lstatSync()?.isSymbolicLink()).toBe(true);
+
+  expect(target.readTextSync()).toEqual("hello");
+});