path-class 0.6.1 → 0.7.0

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

@@ -0,0 +1,155 @@
+import type { Abortable } from "node:events";
+import type { Dirent, ObjectEncodingOptions, OpenMode } from "node:fs";
+import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+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 declare class Path {
+    #private;
+    /**
+     * If `path` is a string starting with `file:///`, it will be parsed as a file URL.
+     */
+    constructor(path: string | URL | 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;
+    isAbsolutePath(): boolean;
+    toFileURL(): URL;
+    /**
+     * 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;
+    /**
+     * Same as `.toString()`, but more concise.
+     */
+    get path(): string;
+    toString(): string;
+    /** 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;
+    extendBasename(suffix: string): Path;
+    get parent(): Path;
+    /** @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>;
+    /** 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>;
+    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>;
+    read: typeof readFileType;
+    readText(): Promise<string>;
+    readJSON<T>(): Promise<T>;
+    /** Creates intermediate directories if they do not exist.
+     *
+     * 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>;
+    readDir: typeof readDirType;
+    static get homedir(): Path;
+    static xdg: {
+        cache: Path;
+        config: Path;
+        data: Path;
+        state: Path;
+        /**
+         * {@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: Path | undefined;
+        runtimeWithStateFallback: Path;
+    };
+    /** Chainable function to print the path. Prints the same as:
+     *
+     *     if (args.length > 0) {
+     *      console.log(...args);
+     *     }
+     *     console.log(this.path);
+     *
+     */
+    debugPrint(...args: any[]): 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 declare function stringifyIfPath<T>(value: T | Path): T | string;
+export declare function mustNotHaveTrailingSlash(path: Path): void;
+export {};

package/dist/lib/path-class/chunks/chunk-KSCIGSNU.js

@@ -0,0 +1,317 @@
+// src/Path.ts
+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";
+var Path = class _Path {
+  // @ts-expect-error ts(2564): False positive. https://github.com/microsoft/TypeScript/issues/32194
+  #path;
+  /**
+   * If `path` is a string starting with `file:///`, it will be parsed as a file URL.
+   */
+  constructor(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, base) {
+    const baseURL = (() => {
+      if (!(base instanceof _Path)) {
+        return base;
+      }
+      if (!base.isAbsolutePath()) {
+        throw new Error(
+          "The `base` arg to `Path.resolve(\u2026)` must be an absolute path."
+        );
+      }
+      return pathToFileURL(base.#path);
+    })();
+    return new _Path(new URL(_Path.#pathlikeToString(path), baseURL));
+  }
+  static #pathlikeToString(path) {
+    if (path instanceof _Path) {
+      return path.#path;
+    }
+    if (path instanceof URL) {
+      return fileURLToPath(path);
+    }
+    if (typeof path === "string") {
+      if (path.startsWith("file:///")) {
+        return fileURLToPath(path);
+      }
+      return path;
+    }
+    throw new Error("Invalid path");
+  }
+  #setNormalizedPath(path) {
+    this.#path = join(path);
+  }
+  isAbsolutePath() {
+    return this.#path.startsWith("/");
+  }
+  toFileURL() {
+    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() {
+    return this.#path.endsWith("/");
+  }
+  /**
+   * Same as `.toString()`, but more concise.
+   */
+  get path() {
+    return this.#path;
+  }
+  toString() {
+    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) {
+    const segmentStrings = segments.map(
+      (segment) => segment instanceof _Path ? segment.path : segment
+    );
+    return new _Path(join(this.#path, ...segmentStrings));
+  }
+  extendBasename(suffix) {
+    const joinedSuffix = join(suffix);
+    if (joinedSuffix !== basename(joinedSuffix)) {
+      throw new Error("Invalid suffix to extend file name.");
+    }
+    return new _Path(this.#path + joinedSuffix);
+  }
+  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 new _Path(basename(this.#path));
+  }
+  get extension() {
+    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() {
+    return this.extension;
+  }
+  // TODO: find a neat way to dedup with the sync version?
+  async exists(constraints) {
+    let stats;
+    try {
+      stats = await stat(this.#path);
+    } catch (e) {
+      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() {
+    return this.exists({ mustBe: "file" });
+  }
+  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) {
+    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, 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 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 ?? {} });
+  }
+  read = (options) => (
+    // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.
+    readFile(this.#path, options)
+  );
+  async readText() {
+    return readFile(this.#path, "utf-8");
+  }
+  async readJSON() {
+    return JSON.parse(await this.readText());
+  }
+  /** Creates intermediate directories if they do not exist.
+   *
+   * Returns the original `Path` (for chaining).
+   */
+  async write(data, options) {
+    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(data, replacer = null, space = "  ") {
+    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 = (options) => (
+    // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.
+    readdir(this.#path, options)
+  );
+  static get homedir() {
+    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) : void 0,
+    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) {
+    if (args.length > 0) {
+      console.log(...args);
+    }
+    console.log(this.#path);
+    return this;
+  }
+};
+function stringifyIfPath(value) {
+  if (value instanceof Path) {
+    return value.toString();
+  }
+  return value;
+}
+function mustNotHaveTrailingSlash(path) {
+  if (path.hasTrailingSlash()) {
+    throw new Error(
+      "Path ends with a slash, which cannot be treated as a file."
+    );
+  }
+}
+
+export {
+  Path,
+  stringifyIfPath,
+  mustNotHaveTrailingSlash
+};
+//# sourceMappingURL=chunk-KSCIGSNU.js.map

package/dist/lib/path-class/chunks/chunk-KSCIGSNU.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/Path.ts"],
+  "sourcesContent": ["import type { Abortable } from \"node:events\";\nimport type { Dirent, ObjectEncodingOptions, OpenMode } from \"node:fs\";\nimport {\n  cp,\n  mkdir,\n  mkdtemp,\n  readdir,\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, pathToFileURL } from \"node:url\";\nimport {\n  xdgCache,\n  xdgConfig,\n  xdgData,\n  xdgRuntime,\n  xdgState,\n} from \"xdg-basedir\";\n\n// Modifying the type of `readdir(\u2026)` from `node:fs/promises` to remove the\n// first parameter is difficult, if not impossible. So we give up and duplicate\n// the types manually. This ensures ergonomic types, such as an inferred return\n// type of `string[]` when `options` is not passed.\n\ndeclare function readDirType(\n  options?:\n    | (ObjectEncodingOptions & {\n        withFileTypes?: false | undefined;\n        recursive?: boolean | undefined;\n      })\n    | BufferEncoding\n    | null,\n): Promise<string[]>;\n\ndeclare function readDirType(\n  options:\n    | {\n        encoding: \"buffer\";\n        withFileTypes?: false | undefined;\n        recursive?: boolean | undefined;\n      }\n    | \"buffer\",\n): Promise<Buffer[]>;\n\ndeclare function readDirType(\n  options?:\n    | (ObjectEncodingOptions & {\n        withFileTypes?: false | undefined;\n        recursive?: boolean | undefined;\n      })\n    | BufferEncoding\n    | null,\n): Promise<string[] | Buffer[]>;\n\ndeclare function readDirType(\n  options: ObjectEncodingOptions & {\n    withFileTypes: true;\n    recursive?: boolean | undefined;\n  },\n): Promise<Dirent[]>;\n\ndeclare function readDirType(options: {\n  encoding: \"buffer\";\n  withFileTypes: true;\n  recursive?: boolean | undefined;\n}): Promise<Dirent<Buffer>[]>;\n\ndeclare function readFileType(\n  options?:\n    | ({\n        encoding?: null | undefined;\n        flag?: OpenMode | undefined;\n      } & Abortable)\n    | null,\n): Promise<Buffer>;\ndeclare function readFileType(\n  options:\n    | ({\n        encoding: BufferEncoding;\n        flag?: OpenMode | undefined;\n      } & Abortable)\n    | BufferEncoding,\n): Promise<string>;\ndeclare function readFileType(\n  options?:\n    | (ObjectEncodingOptions &\n        Abortable & {\n          flag?: OpenMode | undefined;\n        })\n    | BufferEncoding\n    | null,\n): Promise<string | Buffer>;\n\nexport class Path {\n  // @ts-expect-error ts(2564): False positive. https://github.com/microsoft/TypeScript/issues/32194\n  #path: string;\n  /**\n   * If `path` is a string starting with `file:///`, it will be parsed as a file URL.\n   */\n  constructor(path: string | URL | Path) {\n    this.#setNormalizedPath(Path.#pathlikeToString(path));\n  }\n\n  /**\n   * Similar to `new URL(path, base)`, but accepting and returning `Path` objects.\n   * Note that `base` must be one of:\n   *\n   * - a valid second argument to `new URL(\u2026)`.\n   * - a `Path` representing an absolute path.\n   *\n   */\n  static resolve(path: string | URL | Path, base: string | URL | Path): Path {\n    const baseURL = (() => {\n      if (!(base instanceof Path)) {\n        return base;\n      }\n      if (!base.isAbsolutePath()) {\n        throw new Error(\n          \"The `base` arg to `Path.resolve(\u2026)` must be an absolute path.\",\n        );\n      }\n      return pathToFileURL(base.#path);\n    })();\n    return new Path(new URL(Path.#pathlikeToString(path), baseURL));\n  }\n\n  static #pathlikeToString(path: string | URL | Path): string {\n    if (path instanceof Path) {\n      return path.#path;\n    }\n    if (path instanceof URL) {\n      return fileURLToPath(path);\n    }\n    if (typeof path === \"string\") {\n      // TODO: allow turning off this heuristic?\n      if (path.startsWith(\"file:///\")) {\n        return fileURLToPath(path);\n      }\n      return path;\n    }\n    throw new Error(\"Invalid path\");\n  }\n\n  #setNormalizedPath(path: string): void {\n    this.#path = join(path);\n  }\n\n  isAbsolutePath(): boolean {\n    return this.#path.startsWith(\"/\");\n  }\n\n  toFileURL(): URL {\n    if (!this.isAbsolutePath()) {\n      throw new Error(\n        \"Tried to convert to file URL when the path is not absolute.\",\n      );\n    }\n    return pathToFileURL(this.#path);\n  }\n\n  /**\n   * The `Path` can have a trailing slash, indicating that it represents a\n   * directory. (If there is no trailing slash, it can represent either a file\n   * or a directory.)\n   *\n   * Some operations will refuse to treat a directory path as a file path. This\n   * function identifies such paths.\n   */\n  hasTrailingSlash(): boolean {\n    // TODO: handle Windows semantically\n    return this.#path.endsWith(\"/\");\n  }\n\n  /**\n   * Same as `.toString()`, but more concise.\n   */\n  get path() {\n    return this.#path;\n  }\n\n  toString(): string {\n    return this.#path;\n  }\n\n  /** Constructs a new path by appending the given path segments.\n   * This follows `node` semantics for absolute paths: leading slashes in the given descendant segments are ignored.\n   */\n  join(...segments: (string | Path)[]): Path {\n    const segmentStrings = segments.map((segment) =>\n      segment instanceof Path ? segment.path : segment,\n    );\n    return new Path(join(this.#path, ...segmentStrings));\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    mustNotHaveTrailingSlash(this);\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  // TODO: find a neat way to dedup with the sync version?\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        mustNotHaveTrailingSlash(this);\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 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  read: typeof readFileType = (options) =>\n    // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.\n    readFile(this.#path, options as any) as any;\n\n  async readText(): Promise<string> {\n    return readFile(this.#path, \"utf-8\");\n  }\n\n  async readJSON<T>(): Promise<T> {\n    return JSON.parse(await this.readText());\n  }\n\n  /** Creates intermediate directories if they do not exist.\n   *\n   * Returns the original `Path` (for chaining).\n   */\n  async write(\n    data: Parameters<typeof writeFile>[1],\n    options?: Parameters<typeof writeFile>[2],\n  ): Promise<Path> {\n    await this.parent.mkdir();\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  // Normally we'd add a `@deprecated` alias named `.readdir`, but that would\n  // differ only by capitalization of a single non-leading character. This can\n  // be a bit confusing, especially when autocompleting. So for this function in\n  // particular we don't include an alias.\n  readDir: typeof readDirType = (options) =>\n    // biome-ignore lint/suspicious/noExplicitAny: Needed to wrangle the types.\n    readdir(this.#path, options as any) as any;\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     * {@link Path.xdg.runtime} does not have a default value. Consider\n     * {@link Path.xdg.runtimeWithStateFallback} if you need a fallback but do not have a particular fallback in mind.\n     */\n    runtime: xdgRuntime ? new Path(xdgRuntime) : undefined,\n    runtimeWithStateFallback: xdgRuntime\n      ? new Path(xdgRuntime)\n      : new Path(xdgState ?? Path.homedir.join(\".local/state\")),\n  };\n\n  /** Chainable function to print the path. Prints the same as:\n   *\n   *     if (args.length > 0) {\n   *      console.log(...args);\n   *     }\n   *     console.log(this.path);\n   *\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: This is the correct type, based on `console.log(\u2026)`.\n  debugPrint(...args: any[]): Path {\n    if (args.length > 0) {\n      console.log(...args);\n    }\n    console.log(this.#path);\n    return this;\n  }\n}\n\n/**\n * This function is useful to serialize any `Path`s in a structure to pass on to\n * functions that do not know about the `Path` class, e.g.\n *\n *     function process(args: (string | Path)[]) {\n *       const argsAsStrings = args.map(stringifyIfPath);\n *     }\n *\n */\nexport function stringifyIfPath<T>(value: T | Path): T | string {\n  if (value instanceof Path) {\n    return value.toString();\n  }\n  return value;\n}\n\nexport function mustNotHaveTrailingSlash(path: Path): void {\n  if (path.hasTrailingSlash()) {\n    throw new Error(\n      \"Path ends with a slash, which cannot be treated as a file.\",\n    );\n  }\n}\n"],
+  "mappings": ";AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,SAAS,cAAc;AAChC,SAAS,UAAU,SAAS,SAAS,YAAY;AACjD,SAAS,eAAe,qBAAqB;AAC7C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA4EA,IAAM,OAAN,MAAM,MAAK;AAAA;AAAA,EAEhB;AAAA;AAAA;AAAA;AAAA,EAIA,YAAY,MAA2B;AACrC,SAAK,mBAAmB,MAAK,kBAAkB,IAAI,CAAC;AAAA,EACtD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,OAAO,QAAQ,MAA2B,MAAiC;AACzE,UAAM,WAAW,MAAM;AACrB,UAAI,EAAE,gBAAgB,QAAO;AAC3B,eAAO;AAAA,MACT;AACA,UAAI,CAAC,KAAK,eAAe,GAAG;AAC1B,cAAM,IAAI;AAAA,UACR;AAAA,QACF;AAAA,MACF;AACA,aAAO,cAAc,KAAK,KAAK;AAAA,IACjC,GAAG;AACH,WAAO,IAAI,MAAK,IAAI,IAAI,MAAK,kBAAkB,IAAI,GAAG,OAAO,CAAC;AAAA,EAChE;AAAA,EAEA,OAAO,kBAAkB,MAAmC;AAC1D,QAAI,gBAAgB,OAAM;AACxB,aAAO,KAAK;AAAA,IACd;AACA,QAAI,gBAAgB,KAAK;AACvB,aAAO,cAAc,IAAI;AAAA,IAC3B;AACA,QAAI,OAAO,SAAS,UAAU;AAE5B,UAAI,KAAK,WAAW,UAAU,GAAG;AAC/B,eAAO,cAAc,IAAI;AAAA,MAC3B;AACA,aAAO;AAAA,IACT;AACA,UAAM,IAAI,MAAM,cAAc;AAAA,EAChC;AAAA,EAEA,mBAAmB,MAAoB;AACrC,SAAK,QAAQ,KAAK,IAAI;AAAA,EACxB;AAAA,EAEA,iBAA0B;AACxB,WAAO,KAAK,MAAM,WAAW,GAAG;AAAA,EAClC;AAAA,EAEA,YAAiB;AACf,QAAI,CAAC,KAAK,eAAe,GAAG;AAC1B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,WAAO,cAAc,KAAK,KAAK;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,mBAA4B;AAE1B,WAAO,KAAK,MAAM,SAAS,GAAG;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAAO;AACT,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,WAAmB;AACjB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAKA,QAAQ,UAAmC;AACzC,UAAM,iBAAiB,SAAS;AAAA,MAAI,CAAC,YACnC,mBAAmB,QAAO,QAAQ,OAAO;AAAA,IAC3C;AACA,WAAO,IAAI,MAAK,KAAK,KAAK,OAAO,GAAG,cAAc,CAAC;AAAA,EACrD;AAAA,EAEA,eAAe,QAAsB;AACnC,UAAM,eAAe,KAAK,MAAM;AAChC,QAAI,iBAAiB,SAAS,YAAY,GAAG;AAC3C,YAAM,IAAI,MAAM,qCAAqC;AAAA,IACvD;AAEA,WAAO,IAAI,MAAK,KAAK,QAAQ,YAAY;AAAA,EAC3C;AAAA,EAEA,IAAI,SAAe;AACjB,WAAO,IAAI,MAAK,QAAQ,KAAK,KAAK,CAAC;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAI,UAAgB;AAClB,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,IAAI,WAAiB;AACnB,WAAO,IAAI,MAAK,SAAS,KAAK,KAAK,CAAC;AAAA,EACtC;AAAA,EAEA,IAAI,YAAoB;AACtB,6BAAyB,IAAI;AAC7B,WAAO,QAAQ,KAAK,KAAK;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,IAAI,UAAkB;AACpB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,MAAM,OAAO,aAEQ;AACnB,QAAI;AACJ,QAAI;AACF,cAAQ,MAAM,KAAK,KAAK,KAAK;AAAA,IAE/B,SAAS,GAAQ;AACf,UAAI,EAAE,SAAS,UAAU;AACvB,eAAO;AAAA,MACT;AACA,YAAM;AAAA,IACR;AACA,QAAI,CAAC,aAAa,QAAQ;AACxB,aAAO;AAAA,IACT;AACA,YAAQ,aAAa,QAAQ;AAAA,MAC3B,KAAK,QAAQ;AACX,iCAAyB,IAAI;AAC7B,YAAI,MAAM,OAAO,GAAG;AAClB,iBAAO;AAAA,QACT;AACA,cAAM,IAAI,MAAM,kCAAkC,KAAK,KAAK,EAAE;AAAA,MAChE;AAAA,MACA,KAAK,aAAa;AAChB,YAAI,MAAM,YAAY,GAAG;AACvB,iBAAO;AAAA,QACT;AACA,cAAM,IAAI,MAAM,uCAAuC,KAAK,KAAK,EAAE;AAAA,MACrE;AAAA,MACA,SAAS;AACP,cAAM,IAAI,MAAM,8BAA8B;AAAA,MAChD;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,eAAiC;AACrC,WAAO,KAAK,OAAO,EAAE,QAAQ,OAAO,CAAC;AAAA,EACvC;AAAA,EAEA,MAAM,cAAgC;AACpC,WAAO,KAAK,OAAO,EAAE,QAAQ,YAAY,CAAC;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,MAAM,SAAsD;AAChE,UAAM,iBAAiB,MAAM;AAC3B,UAAI,OAAO,YAAY,YAAY,OAAO,YAAY,UAAU;AAC9D,eAAO,EAAE,MAAM,QAAQ;AAAA,MACzB;AACA,aAAO,WAAW,CAAC;AAAA,IACrB,GAAG;AACH,UAAM,MAAM,KAAK,OAAO,EAAE,WAAW,MAAM,GAAG,cAAc,CAAC;AAC7D,WAAO;AAAA,EACT;AAAA;AAAA;AAAA,EAIA,MAAM,GACJ,aACA,SACe;AACf,UAAM,GAAG,KAAK,OAAO,IAAI,MAAK,WAAW,EAAE,OAAO,OAAO;AACzD,WAAO,IAAI,MAAK,WAAW;AAAA,EAC7B;AAAA;AAAA,EAGA,MAAM,OAAO,aAAiD;AAC5D,UAAM,OAAO,KAAK,OAAO,IAAI,MAAK,WAAW,EAAE,KAAK;AAAA,EACtD;AAAA;AAAA,EAGA,aAAa,YAAY,QAAgC;AACvD,WAAO,IAAI;AAAA,MACT,MAAM,QAAQ,IAAI,MAAK,OAAO,CAAC,EAAE,KAAK,UAAU,UAAU,EAAE,SAAS,CAAC;AAAA,IACxE;AAAA,EACF;AAAA,EAEA,MAAM,GAAG,SAAmD;AAC1D,UAAM,GAAG,KAAK,OAAO,OAAO;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,MAAM,SAAmD;AAC7D,UAAM,KAAK,GAAG,EAAE,WAAW,MAAM,OAAO,MAAM,GAAI,WAAW,CAAC,EAAG,CAAC;AAAA,EACpE;AAAA,EAEA,OAA4B,CAAC;AAAA;AAAA,IAE3B,SAAS,KAAK,OAAO,OAAc;AAAA;AAAA,EAErC,MAAM,WAA4B;AAChC,WAAO,SAAS,KAAK,OAAO,OAAO;AAAA,EACrC;AAAA,EAEA,MAAM,WAA0B;AAC9B,WAAO,KAAK,MAAM,MAAM,KAAK,SAAS,CAAC;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,MACJ,MACA,SACe;AACf,UAAM,KAAK,OAAO,MAAM;AACxB,UAAM,UAAU,KAAK,OAAO,MAAM,OAAO;AACzC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,MAAM,UACJ,MACA,WAAiD,MACjD,QAA8C,MAC/B;AACf,UAAM,KAAK,MAAM,KAAK,UAAU,MAAM,UAAU,KAAK,CAAC;AACtD,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAA8B,CAAC;AAAA;AAAA,IAE7B,QAAQ,KAAK,OAAO,OAAc;AAAA;AAAA,EAEpC,WAAW,UAAgB;AACzB,WAAO,IAAI,MAAK,QAAQ,CAAC;AAAA,EAC3B;AAAA,EAEA,OAAO,MAAM;AAAA,IACX,OAAO,IAAI,MAAK,YAAY,MAAK,QAAQ,KAAK,QAAQ,CAAC;AAAA,IACvD,QAAQ,IAAI,MAAK,aAAa,MAAK,QAAQ,KAAK,SAAS,CAAC;AAAA,IAC1D,MAAM,IAAI,MAAK,WAAW,MAAK,QAAQ,KAAK,cAAc,CAAC;AAAA,IAC3D,OAAO,IAAI,MAAK,YAAY,MAAK,QAAQ,KAAK,cAAc,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA,IAK7D,SAAS,aAAa,IAAI,MAAK,UAAU,IAAI;AAAA,IAC7C,0BAA0B,aACtB,IAAI,MAAK,UAAU,IACnB,IAAI,MAAK,YAAY,MAAK,QAAQ,KAAK,cAAc,CAAC;AAAA,EAC5D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,cAAc,MAAmB;AAC/B,QAAI,KAAK,SAAS,GAAG;AACnB,cAAQ,IAAI,GAAG,IAAI;AAAA,IACrB;AACA,YAAQ,IAAI,KAAK,KAAK;AACtB,WAAO;AAAA,EACT;AACF;AAWO,SAAS,gBAAmB,OAA6B;AAC9D,MAAI,iBAAiB,MAAM;AACzB,WAAO,MAAM,SAAS;AAAA,EACxB;AACA,SAAO;AACT;AAEO,SAAS,yBAAyB,MAAkB;AACzD,MAAI,KAAK,iBAAiB,GAAG;AAC3B,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

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

@@ -1,148 +1 @@
-import type { Abortable } from "node:events";
-import type { Dirent, ObjectEncodingOptions, OpenMode } from "node:fs";
-import { cp, mkdir, rm, writeFile } from "node:fs/promises";
-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 declare class Path {
-    #private;
-    /**
-     * If `path` is a string starting with `file:///`, it will be parsed as a file URL.
-     */
-    constructor(path: string | URL | 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;
-    isAbsolutePath(): boolean;
-    toFileURL(): URL;
-    /**
-     * 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;
-    /**
-     * Same as `.toString()`, but more concise.
-     */
-    get path(): string;
-    toString(): string;
-    /** 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;
-    extendBasename(suffix: string): Path;
-    get parent(): Path;
-    /** @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>;
-    /** 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>;
-    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>;
-    read: typeof readFileType;
-    readText(): Promise<string>;
-    readJSON<T>(): Promise<T>;
-    /** Creates intermediate directories if they do not exist.
-     *
-     * 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>;
-    readDir: typeof readDirType;
-    static get homedir(): Path;
-    static xdg: {
-        cache: Path;
-        config: Path;
-        data: Path;
-        state: Path;
-    };
-    /** Chainable function to print the path. Prints the same as:
-     *
-     *     if (args.length > 0) {
-     *      console.log(...args);
-     *     }
-     *     console.log(this.path);
-     *
-     */
-    debugPrint(...args: any[]): 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 declare function stringifyIfPath<T>(value: T | Path): T | string;
-export {};
+export * from "./Path";