@kikiutils/shared 18.0.0 → 18.1.0

package/dist/classes/path.d.ts

@@ -8,146 +8,259 @@ type DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extend
 /**
  * Values accepted by the `Path` constructor and path-composition methods.
  */
-type PathLike = fs.PathLike | Path;
+export type PathLike = fs.PathLike | Path;
 /**
- * Class representing a file system path with various utility methods for path operations.
+ * An immutable file system path with Node.js path and file operations.
  *
- * All methods in the `Path` class are immutable, returning new instances with modified values
- * and leaving the original instance unchanged.
+ * @remarks
+ * Path-composition methods return new instances and leave this instance unchanged.
+ * File operations act on the stored path and forward Node.js defaults and promise rejections.
+ * They do not update the stored path, including after a successful rename.
+ * The constructor joins stringified inputs using the platform-specific Node.js path rules.
  */
-declare class Path {
+export declare class Path {
   #private;
   /**
    * Creates a normalized path value by joining the provided path segments.
    *
-   * @param {PathLike[]} paths - Path segments accepted by Node.js `path.join` or another `Path` instance
+   * @param paths - Path segments accepted by Node.js `path.join` or another `Path` instance.
    */
   constructor(...paths: PathLike[]);
-  [Symbol.toPrimitive](hint: string): string;
   /**
-   * @see {@link nodePath.dirname}
+   * The parent directory as a new `Path`; this instance is unchanged.
+   *
+   * @see {@link Path.dirname}
    */
   get parent(): Path;
   /**
-   * Returns the internal path string value.
+   * The normalized path string stored by this instance.
    */
   get value(): string;
   /**
-   * @see {@link nodePath.format}
+   * Creates a new path from a Node.js path object.
+   *
+   * @param pathObject - The path components to format.
+   *
+   * @returns A new normalized `Path`.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.format}
    */
   static format(pathObject: nodePath.FormatInputPathObject): Path;
   /**
-   * @see {@link nodePath.resolve}
+   * Resolves joined path segments to an absolute path.
+   *
+   * @remarks
+   * Inputs are joined before resolution; unlike Node.js `path.resolve`,
+   * later absolute segments do not reset the path.
+   *
+   * @param paths - The stringified path segments to join.
+   *
+   * @returns A new absolute `Path`.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.resolve}
    */
   static resolve(...paths: PathLike[]): Path;
+  [Symbol.toPrimitive](hint: string): string;
   /**
-   * @see {@link nodePath.basename}
+   * Returns the final component of this path.
+   *
+   * @param suffix - An optional exact suffix to remove.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.basename}
    */
   basename(suffix?: string): string;
   /**
-   * @see {@link nodePath.dirname}
+   * Returns the parent directory of this path.
+   *
+   * @returns A new `Path`; this instance is unchanged.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.dirname}
    */
   dirname(): Path;
   /**
-   * @see {@link nodePath.extname}
+   * Returns the extension of the final path component.
+   *
+   * @returns The extension including its leading dot, or an empty string when absent.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.extname}
    */
   extname(): string;
   /**
-   * @see {@link nodePath.isAbsolute}
+   * Checks whether this path is absolute on the current platform.
+   *
+   * @returns Whether this path is absolute.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.isAbsolute}
    */
   isAbsolute(): boolean;
   /**
-   * @see {@link nodePath.normalize}
+   * Normalizes separators and relative segments in this path.
+   *
+   * @returns A new `Path`; this instance is unchanged.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.normalize}
    */
   normalize(): Path;
   /**
-   * @see {@link nodePath.join}
+   * Joins additional segments onto this path.
+   *
+   * @param paths - The stringified path segments to append.
+   *
+   * @returns A new normalized `Path`; this instance is unchanged.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.join}
    */
   join(...paths: PathLike[]): Path;
   /**
-   * @see {@link nodePath.parse}
+   * Parses this path into its root, directory, basename, extension, and name.
+   *
+   * @returns A new object containing the path components.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.parse}
    */
   parse(): nodePath.ParsedPath;
   /**
-   * @see {@link nodePath.relative}
+   * Computes a relative path from this path to the destination.
+   *
+   * @param to - The destination path.
+   *
+   * @returns A new `Path`; this instance is unchanged.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.relative}
    */
   relative(to: PathLike): Path;
   /**
-   * @see {@link nodePath.resolve}
+   * Resolves this path to an absolute path using the current working directory.
+   *
+   * @remarks
+   * Relative paths use the current working directory. This instance is unchanged.
+   *
+   * @returns A new absolute `Path`.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.resolve}
    */
   resolve(): Path;
   toJSON(): string;
   /**
-   * @see {@link nodePath.toNamespacedPath}
+   * Converts this path to the Windows namespace form when applicable.
+   *
+   * @returns The namespace-converted path string; this instance is unchanged.
+   * On non-Windows platforms, the path text is unchanged.
+   *
+   * @see {@link https://nodejs.org/api/path.html | Node.js path.toNamespacedPath}
    */
   toNamespacedPath(): string;
   /**
-   * Converts the Path instance to a string.
-   * This method returns the internal path string value,
-   * making it useful for implicit and explicit string conversions.
+   * Returns the stored path as a string.
    */
   toString(): string;
   /**
-   * @see {@link fsp.access}
+   * Checks access permissions for the stored path.
+   *
+   * @remarks
+   * The promise resolves when the access check succeeds and rejects if access is denied or the path is missing.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.access}
    */
   access(...args: DropFirstParameters<typeof fsp.access>): Promise<void>;
   /**
-   * @see {@link fsp.appendFile}
+   * Appends data to the file at the stored path.
+   *
+   * @remarks
+   * The promise resolves when appending completes; a missing file is created according to the supplied options.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.appendFile}
    */
   appendFile(...args: DropFirstParameters<typeof fsp.appendFile>): Promise<void>;
   /**
-   * @see {@link fsp.chmod}
+   * Changes the permissions of the stored path.
+   *
+   * @remarks
+   * The promise resolves when the permissions are changed.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.chmod}
    */
   chmod(...args: DropFirstParameters<typeof fsp.chmod>): Promise<void>;
   /**
-   * @see {@link fsp.chown}
+   * Changes the owner and group of the stored path.
+   *
+   * @remarks
+   * The promise resolves when the ownership is changed.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.chown}
    */
   chown(...args: DropFirstParameters<typeof fsp.chown>): Promise<void>;
   /**
-   * @see {@link fsp.copyFile}
+   * Copies the file at the stored path to a destination.
+   *
+   * @remarks
+   * The promise resolves when copying completes. The stored path remains the source path.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.copyFile}
    */
   copyFile(...args: DropFirstParameters<typeof fsp.copyFile>): Promise<void>;
   /**
-   * @see {@link fsp.mkdir}
+   * Creates a directory at the stored path.
+   *
+   * @remarks
+   * The promise resolves after creation. Recursive mode resolves to the first created directory path, or
+   * `undefined` if no directory is created; nonrecursive mode resolves without a value.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.mkdir}
    */
   mkdir(options: fs.MakeDirectoryOptions & {
     recursive: true;
-  }): Promise<string>;
+  }): Promise<string | undefined>;
   mkdir(options?: (fs.MakeDirectoryOptions & {
     recursive?: false;
   }) | fs.Mode | null): Promise<void>;
   mkdir(options?: fs.MakeDirectoryOptions | fs.Mode | null): Promise<string | undefined>;
   /**
-   * @see {@link fsp.open}
+   * Opens the file at the stored path.
+   *
+   * @remarks
+   * The promise resolves to a new file handle. The caller must close the handle when it is no longer needed.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.open}
    */
   open(...args: DropFirstParameters<typeof fsp.open>): Promise<fs.promises.FileHandle>;
   /**
-   * @see {@link fsp.readdir}
+   * Reads the entries of the directory at the stored path.
+   *
+   * @remarks
+   * The promise resolves to names, buffers, or directory entries according to the options.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.readdir}
    */
-  readdir(path: PathLike, options?: BufferEncoding | (fs.ObjectEncodingOptions & {
+  readdir(options?: BufferEncoding | (fs.ObjectEncodingOptions & {
     recursive?: boolean;
     withFileTypes?: false;
   }) | null): Promise<string[]>;
-  readdir(path: PathLike, options: 'buffer' | {
+  readdir(options: 'buffer' | {
     encoding: 'buffer';
     recursive?: boolean;
     withFileTypes?: false;
   }): Promise<Buffer[]>;
-  readdir(path: PathLike, options?: BufferEncoding | (fs.ObjectEncodingOptions & {
+  readdir(options?: BufferEncoding | (fs.ObjectEncodingOptions & {
     recursive?: boolean;
     withFileTypes?: false;
   }) | null): Promise<Buffer[] | string[]>;
-  readdir(path: PathLike, options: fs.ObjectEncodingOptions & {
+  readdir(options: fs.ObjectEncodingOptions & {
     recursive?: boolean;
     withFileTypes: true;
   }): Promise<fs.Dirent[]>;
-  readdir(path: PathLike, options: {
+  readdir(options: {
     encoding: 'buffer';
     recursive?: boolean;
     withFileTypes: true;
   }): Promise<fs.Dirent<Buffer>[]>;
   /**
-   * @see {@link fsp.readFile}
+   * Reads the entire file at the stored path.
+   *
+   * @remarks
+   * The promise resolves to a string when a text encoding is supplied, or a `Buffer` otherwise.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.readFile}
    */
   readFile(options?: (Abortable & {
     encoding?: null;
@@ -161,40 +274,90 @@ declare class Path {
     flag?: fs.OpenMode;
   }) | BufferEncoding | null): Promise<Buffer | string>;
   /**
-   * @see {@link fsp.rename}
+   * Renames or moves the file or directory at the stored path.
+   *
+   * @remarks
+   * The promise resolves when the rename completes. This instance retains its original stored path.
+   *
+   * @param newPath - The destination path; this instance retains its original value.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.rename}
    */
   rename(newPath: PathLike): Promise<void>;
   /**
-   * @see {@link fsp.rm}
+   * Removes the file or directory at the stored path.
+   *
+   * @remarks
+   * The promise resolves after removal according to the supplied options.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.rm}
    */
   rm(...args: DropFirstParameters<typeof fsp.rm>): Promise<void>;
   /**
-   * @see {@link fsp.rmdir}
+   * Removes the directory at the stored path.
+   *
+   * @remarks
+   * The promise resolves after directory removal.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.rmdir}
    */
   rmdir(...args: DropFirstParameters<typeof fsp.rmdir>): Promise<void>;
   /**
-   * @see {@link fsp.stat}
+   * Reads file system metadata for the stored path.
+   *
+   * @remarks
+   * The promise resolves to `Stats`, or `BigIntStats` when `bigint` is enabled.
+   * If `throwIfNoEntry` is `false`, a missing path resolves to `undefined` instead of rejecting.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.stat}
    */
   stat(opts?: fs.StatOptions & {
     bigint?: false;
+    throwIfNoEntry?: true;
   }): Promise<fs.Stats>;
   stat(opts: fs.StatOptions & {
     bigint: true;
+    throwIfNoEntry?: true;
   }): Promise<fs.BigIntStats>;
-  stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats>;
+  stat(opts: fs.StatOptions & {
+    bigint?: false;
+    throwIfNoEntry: false;
+  }): Promise<fs.Stats | undefined>;
+  stat(opts: fs.StatOptions & {
+    bigint: true;
+    throwIfNoEntry: false;
+  }): Promise<fs.BigIntStats | undefined>;
+  stat(opts: fs.StatOptions & {
+    throwIfNoEntry?: true;
+  }): Promise<fs.BigIntStats | fs.Stats>;
+  stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats | undefined>;
   /**
-   * @see {@link fsp.truncate}
+   * Truncates or extends the file at the stored path.
+   *
+   * @remarks
+   * The promise resolves when the file reaches the requested length in bytes; the default length is `0`.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.truncate}
    */
   truncate(...args: DropFirstParameters<typeof fsp.truncate>): Promise<void>;
   /**
-   * @see {@link fsp.unlink}
+   * Deletes the file or symbolic link at the stored path.
+   *
+   * @remarks
+   * The promise resolves after deletion; directories are not removed.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.unlink}
    */
   unlink(): Promise<void>;
   /**
-   * @see {@link fsp.writeFile}
+   * Writes data to the file at the stored path.
+   *
+   * @remarks
+   * The promise resolves when writing completes; the default flag replaces existing file contents.
+   *
+   * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.writeFile}
    */
   writeFile(...args: DropFirstParameters<typeof fsp.writeFile>): Promise<void>;
 }
 //#endregion
-export { Path, PathLike };
 //# sourceMappingURL=path.d.ts.map

package/dist/classes/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","names":[],"sources":["../../src/classes/path.ts"],"mappings":";;;;;;KAmBK,oBAAoB,cAAc,qBAAqB,WAAW,0BAA0B,KAAK;;;;KAK1F,WAAW,GAAG,WAAW;;;;;;;cAQxB;;;;;;;EAQG,eAAG,OAAO;GASrB,OAAO,aAAa;;;;MAmBjB,UAAM;;;;MAON;;;;SASG,OAAO,YAAY,SAAS,wBAAqB;;;;SAOjD,WAAW,OAAO,aAAU;;;;EASnC,SAAS;;;;EAOT,WAAO;;;;EAOP;;;;EAOA;;;;EAOA,aAAS;;;;EAOT,QAAQ,OAAO,aAAU;;;;EAOzB,SAAK,SAAA;;;;EAOL,SAAS,IAAI,WAAQ;;;;EAOrB,WAAO;EAIP;;;;EAOA;;;;;;EASA;;;;EASA,UAAU,MAAM,2BAA2B,IAAI,UAAO;;;;EAOtD,cAAc,MAAM,2BAA2B,IAAI,cAAW;;;;EAO9D,SAAS,MAAM,2BAA2B,IAAI,SAAM;;;;EAOpD,SAAS,MAAM,2BAA2B,IAAI,SAAM;;;;EAOpD,YAAY,MAAM,2BAA2B,IAAI,YAAS;;;;EAO1D,MACI,SAAS,GAAG;IACR;MAEL;EACH,MACI,WACK,GAAG;IACF;OAEF,GAAG,cAER;EACH,MAAM,UAAU,GAAG,uBAAuB,GAAG,cAAc;;;;EAQ3D,QAAQ,MAAM,2BAA2B,IAAI,QAAK,QAAA,GAAA,SAAA;;;;EAOlD,QACI,MAAM,UACN,UACI,kBACC,GAAG;IACF;IACA;cAGP;EACH,QACI,MAAM,UACN;IAGM;IACA;IACA;MAEP,QAAQ;EACX,QACI,MAAM,UACN,UACI,kBACC,GAAG;IACF;IACA;cAGP,QAAQ;EACX,QACI,MAAM,UACN,SAAS,GAAG;IACR;IACA;MAEL,QAAQ,GAAG;EACd,QACI,MAAM,UACN;IACI;IACA;IACA;MAEL,QAAQ,GAAG,OAAO;;;;EAQrB,SACI,WACK;IACC;IACA,OAAO,GAAG;cAGjB,QAAQ;EACX,SACI,UACK;IACC,UAAU;IACV,OAAO,GAAG;OAEZ,iBACL;EACH,SACI,WAEQ,YACA,GAAG;IACD,OAAO,GAAG;OAEd,wBAEP,QAAQ;;;;EAQX,OAAO,SAAS,WAAQ;;;;EAOxB,MAAM,MAAM,2BAA2B,IAAI,MAAG;;;;EAO9C,SAAS,MAAM,2BAA2B,IAAI,SAAM;;;;EAOpD,KACI,OAAO,GAAG;IACN;MAEL,QAAQ,GAAG;EACd,KACI,MAAM,GAAG;IACL;MAEL,QAAQ,GAAG;EACd,KAAK,OAAO,GAAG,cAAc,QAAQ,GAAG,cAAc,GAAG;;;;EAQzD,YAAY,MAAM,2BAA2B,IAAI,YAAS;;;;EAO1D,UAAM;;;;EAON,aAAa,MAAM,2BAA2B,IAAI,aAAU"}
+{"version":3,"file":"path.d.ts","names":[],"sources":["../../src/classes/path.ts"],"mappings":";;;;;;KAMK,oBAAoB,cAAc,qBAAqB,WAAW,0BAA0B,KAAK;;;;YAK1F,WAAW,GAAG,WAAW;;;;;;;;;;qBAWxB;;;;;;;EAWG,eAAG,OAAO;;;;;;MAoBlB,UAAM;;;;MAON;;;;;;;;;;SAeG,OAAO,YAAY,SAAS,wBAAqB;;;;;;;;;;;;;;SAiBjD,WAAW,OAAO,aAAU;GASlC,OAAO,aAAa;;;;;;;;EAYrB,SAAS;;;;;;;;EAWT,WAAO;;;;;;;;EAWP;;;;;;;;EAWA;;;;;;;;EAWA,aAAS;;;;;;;;;;EAaT,QAAQ,OAAO,aAAU;;;;;;;;EAWzB,SAAK,SAAA;;;;;;;;;;EAaL,SAAS,IAAI,WAAQ;;;;;;;;;;;EAcrB,WAAO;EAIP;;;;;;;;;EAYA;;;;EAOA;;;;;;;;;EAYA,UAAU,MAAM,2BAA2B,IAAI,UAAO;;;;;;;;;EAYtD,cAAc,MAAM,2BAA2B,IAAI,cAAW;;;;;;;;;EAY9D,SAAS,MAAM,2BAA2B,IAAI,SAAM;;;;;;;;;EAYpD,SAAS,MAAM,2BAA2B,IAAI,SAAM;;;;;;;;;EAYpD,YAAY,MAAM,2BAA2B,IAAI,YAAS;;;;;;;;;;EAa1D,MAAM,SAAS,GAAG;IAAyB;MAAoB;EAC/D,MACI,WACK,GAAG;IAAyB;OAC7B,GAAG,cAER;EACH,MAAM,UAAU,GAAG,uBAAuB,GAAG,cAAc;;;;;;;;;EAa3D,QAAQ,MAAM,2BAA2B,IAAI,QAAK,QAAA,GAAA,SAAA;;;;;;;;;EAYlD,QACI,UACI,kBACC,GAAG;IACF;IACA;cAGP;EACH,QACI;IAGM;IACA;IACA;MAEP,QAAQ;EACX,QACI,UACI,kBACC,GAAG;IACF;IACA;cAGP,QAAQ;EACX,QACI,SAAS,GAAG;IACR;IACA;MAEL,QAAQ,GAAG;EACd,QACI;IACI;IACA;IACA;MAEL,QAAQ,GAAG,OAAO;;;;;;;;;EAarB,SACI,WACK;IACC;IACA,OAAO,GAAG;cAGjB,QAAQ;EACX,SACI,UACK;IACC,UAAU;IACV,OAAO,GAAG;OAEZ,iBACL;EACH,SACI,WAEQ,YACA,GAAG;IACD,OAAO,GAAG;OAEd,wBAEP,QAAQ;;;;;;;;;;;EAeX,OAAO,SAAS,WAAQ;;;;;;;;;EAYxB,MAAM,MAAM,2BAA2B,IAAI,MAAG;;;;;;;;;EAY9C,SAAS,MAAM,2BAA2B,IAAI,SAAM;;;;;;;;;;EAapD,KACI,OAAO,GAAG;IACN;IACA;MAEL,QAAQ,GAAG;EACd,KACI,MAAM,GAAG;IACL;IACA;MAEL,QAAQ,GAAG;EACd,KACI,MAAM,GAAG;IACL;IACA;MAEL,QAAQ,GAAG;EACd,KACI,MAAM,GAAG;IACL;IACA;MAEL,QAAQ,GAAG;EACd,KAAK,MAAM,GAAG;IAAgB;MAA0B,QAAQ,GAAG,cAAc,GAAG;EACpF,KAAK,OAAO,GAAG,cAAc,QAAQ,GAAG,cAAc,GAAG;;;;;;;;;EAazD,YAAY,MAAM,2BAA2B,IAAI,YAAS;;;;;;;;;EAY1D,UAAM;;;;;;;;;EAYN,aAAa,MAAM,2BAA2B,IAAI,aAAU"}