@kikiutils/shared 13.3.0 → 13.5.0

package/README.md

@@ -9,6 +9,8 @@ A lightweight and modular utility library for modern JavaScript and TypeScript
 
 - [✨ Release Notes](./CHANGELOG.md)
 
+TODO: update README
+
 ## Features
 
 - 📋 Clipboard utilities — copy text and blobs using the modern Clipboard API (Browser only)

package/dist/classes/path.d.ts

@@ -0,0 +1,220 @@
+import { Buffer } from "node:buffer";
+import * as fsp from "node:fs/promises";
+import * as nodePath from "node:path";
+import * as fsExtra from "fs-extra";
+import { Abortable } from "node:events";
+import * as fs from "node:fs";
+import { JFReadOptions, JFWriteOptions } from "jsonfile";
+
+//#region src/classes/path.d.ts
+type DoNotRemoveOrUseThisType = typeof fsExtra;
+type DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extends [any, ...infer R] ? R : never;
+type PathLike = fs.PathLike | Path;
+/**
+ * Class representing a file system path with various utility methods for path operations.
+ *
+ * All methods in the `Path` class are immutable, returning new instances with modified values
+ * and leaving the original instance unchanged.
+ */
+declare class Path {
+  #private;
+  constructor(...paths: PathLike[]);
+  [Symbol.toPrimitive](hint: string): string;
+  /**
+   * @see {@link nodePath.dirname}
+   */
+  get parent(): Path;
+  /**
+   * Returns the internal path string value.
+   */
+  get value(): string;
+  /**
+   * @see {@link nodePath.format}
+   */
+  static format(pathObject: nodePath.FormatInputPathObject): Path;
+  /**
+   * @see {@link nodePath.resolve}
+   */
+  static resolve(...paths: PathLike[]): Path;
+  /**
+   * @see {@link nodePath.basename}
+   */
+  basename(suffix?: string): string;
+  /**
+   * @see {@link nodePath.dirname}
+   */
+  dirname(): Path;
+  /**
+   * @see {@link nodePath.extname}
+   */
+  extname(): string;
+  /**
+   * @see {@link nodePath.isAbsolute}
+   */
+  isAbsolute(): boolean;
+  /**
+   * @see {@link nodePath.normalize}
+   */
+  normalize(): Path;
+  /**
+   * @see {@link nodePath.join}
+   */
+  join(...paths: PathLike[]): Path;
+  /**
+   * @see {@link nodePath.parse}
+   */
+  parse(): nodePath.ParsedPath;
+  /**
+   * @see {@link nodePath.relative}
+   */
+  relative(to: PathLike): Path;
+  /**
+   * @see {@link nodePath.resolve}
+   */
+  resolve(): Path;
+  toJSON(): string;
+  /**
+   * @see {@link nodePath.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.
+   */
+  toString(): string;
+  /**
+   * @see {@link fsp.access}
+   */
+  access(...args: DropFirstParameters<typeof fsp.access>): Promise<void>;
+  /**
+   * @see {@link fsp.appendFile}
+   */
+  appendFile(...args: DropFirstParameters<typeof fsp.appendFile>): Promise<void>;
+  /**
+   * @see {@link fsp.chmod}
+   */
+  chmod(...args: DropFirstParameters<typeof fsp.chmod>): Promise<void>;
+  /**
+   * @see {@link fsp.chown}
+   */
+  chown(...args: DropFirstParameters<typeof fsp.chown>): Promise<void>;
+  /**
+   * @see {@link fsp.copyFile}
+   */
+  copyFile(...args: DropFirstParameters<typeof fsp.copyFile>): Promise<void>;
+  /**
+   * @see {@link fsp.mkdir}
+   */
+  mkdir(options: fs.MakeDirectoryOptions & {
+    recursive: true;
+  }): Promise<string>;
+  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}
+   */
+  open(...args: DropFirstParameters<typeof fsp.open>): Promise<fs.promises.FileHandle>;
+  /**
+   * @see {@link fsp.readdir}
+   */
+  readdir(path: PathLike, options?: BufferEncoding | (fs.ObjectEncodingOptions & {
+    recursive?: boolean;
+    withFileTypes?: false;
+  }) | null): Promise<string[]>;
+  readdir(path: PathLike, options: 'buffer' | {
+    encoding: 'buffer';
+    recursive?: boolean;
+    withFileTypes?: false;
+  }): Promise<Buffer[]>;
+  readdir(path: PathLike, options?: BufferEncoding | (fs.ObjectEncodingOptions & {
+    recursive?: boolean;
+    withFileTypes?: false;
+  }) | null): Promise<Buffer[] | string[]>;
+  readdir(path: PathLike, options: fs.ObjectEncodingOptions & {
+    recursive?: boolean;
+    withFileTypes: true;
+  }): Promise<fs.Dirent[]>;
+  readdir(path: PathLike, options: {
+    encoding: 'buffer';
+    recursive?: boolean;
+    withFileTypes: true;
+  }): Promise<fs.Dirent<Buffer>[]>;
+  /**
+   * @see {@link fsp.readFile}
+   */
+  readFile(options?: (Abortable & {
+    encoding?: null;
+    flag?: fs.OpenMode;
+  }) | null): Promise<Buffer>;
+  readFile(options: (Abortable & {
+    encoding: BufferEncoding;
+    flag?: fs.OpenMode;
+  }) | BufferEncoding): Promise<string>;
+  readFile(options?: (Abortable & fs.ObjectEncodingOptions & {
+    flag?: fs.OpenMode;
+  }) | BufferEncoding | null): Promise<Buffer | string>;
+  /**
+   * @see {@link fsp.rename}
+   */
+  rename(newPath: PathLike): Promise<void>;
+  /**
+   * @see {@link fsp.rm}
+   */
+  rm(...args: DropFirstParameters<typeof fsp.rm>): Promise<void>;
+  /**
+   * @see {@link fsp.rmdir}
+   */
+  rmdir(...args: DropFirstParameters<typeof fsp.rmdir>): Promise<void>;
+  /**
+   * @see {@link fsp.stat}
+   */
+  stat(opts?: fs.StatOptions & {
+    bigint?: false;
+  }): Promise<fs.Stats>;
+  stat(opts: fs.StatOptions & {
+    bigint: true;
+  }): Promise<fs.BigIntStats>;
+  stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats>;
+  /**
+   * @see {@link fsp.truncate}
+   */
+  truncate(...args: DropFirstParameters<typeof fsp.truncate>): Promise<void>;
+  /**
+   * @see {@link fsp.unlink}
+   */
+  unlink(): Promise<void>;
+  /**
+   * @see {@link fsp.writeFile}
+   */
+  writeFile(...args: DropFirstParameters<typeof fsp.writeFile>): Promise<void>;
+  /**
+   * @see {@link fsExtra.ensureDir}
+   */
+  ensureDir(options?: fsExtra.EnsureDirOptions | number): Promise<void>;
+  /**
+   * @see {@link fsExtra.ensureDir}
+   */
+  mkdirp: (options?: fsExtra.EnsureDirOptions | number) => Promise<void>;
+  /**
+   * @see {@link fsExtra.ensureDir}
+   */
+  mkdirs: (options?: fsExtra.EnsureDirOptions | number) => Promise<void>;
+  /**
+   * @see {@link fsExtra.readJson}
+   */
+  readJson<T = any>(options?: JFReadOptions): Promise<T>;
+  /**
+   * @see {@link fsExtra.remove}
+   */
+  remove(): Promise<void>;
+  /**
+   * @see {@link fsExtra.writeJson}
+   */
+  writeJson(data: any, options?: JFWriteOptions): Promise<void>;
+}
+//#endregion
+export { DoNotRemoveOrUseThisType, Path, PathLike };
+//# sourceMappingURL=path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","names":[],"sources":["../../src/classes/path.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/classes/path.js

@@ -0,0 +1,245 @@
+import * as fsp from "node:fs/promises";
+import { basename, dirname, extname, format, isAbsolute, join, normalize, parse, relative, resolve, toNamespacedPath } from "node:path";
+import * as fsExtra from "fs-extra";
+
+//#region src/classes/path.ts
+/**
+* Class representing a file system path with various utility methods for path operations.
+*
+* All methods in the `Path` class are immutable, returning new instances with modified values
+* and leaving the original instance unchanged.
+*/
+var Path = class Path {
+	#value;
+	constructor(...paths) {
+		this.#value = join(...this.#toStrings(paths));
+	}
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return this.#value;
+	}
+	[Symbol.toPrimitive](hint) {
+		if (hint === "number") throw new TypeError("Cannot convert a Path to a number");
+		return this.#value;
+	}
+	#newInstance(...paths) {
+		return new Path(...paths);
+	}
+	#toStrings(paths) {
+		return paths.map((path) => path.toString());
+	}
+	/**
+	* @see {@link nodePath.dirname}
+	*/
+	get parent() {
+		return this.dirname();
+	}
+	/**
+	* Returns the internal path string value.
+	*/
+	get value() {
+		return this.#value;
+	}
+	/**
+	* @see {@link nodePath.format}
+	*/
+	static format(pathObject) {
+		return new Path(format(pathObject));
+	}
+	/**
+	* @see {@link nodePath.resolve}
+	*/
+	static resolve(...paths) {
+		return new this(...paths).resolve();
+	}
+	/**
+	* @see {@link nodePath.basename}
+	*/
+	basename(suffix) {
+		return basename(this.#value, suffix);
+	}
+	/**
+	* @see {@link nodePath.dirname}
+	*/
+	dirname() {
+		return this.#newInstance(dirname(this.#value));
+	}
+	/**
+	* @see {@link nodePath.extname}
+	*/
+	extname() {
+		return extname(this.#value);
+	}
+	/**
+	* @see {@link nodePath.isAbsolute}
+	*/
+	isAbsolute() {
+		return isAbsolute(this.#value);
+	}
+	/**
+	* @see {@link nodePath.normalize}
+	*/
+	normalize() {
+		return this.#newInstance(normalize(this.#value));
+	}
+	/**
+	* @see {@link nodePath.join}
+	*/
+	join(...paths) {
+		return this.#newInstance(this.#value, ...this.#toStrings(paths));
+	}
+	/**
+	* @see {@link nodePath.parse}
+	*/
+	parse() {
+		return parse(this.#value);
+	}
+	/**
+	* @see {@link nodePath.relative}
+	*/
+	relative(to) {
+		return this.#newInstance(relative(this.#value, to.toString()));
+	}
+	/**
+	* @see {@link nodePath.resolve}
+	*/
+	resolve() {
+		return this.#newInstance(resolve(this.#value));
+	}
+	toJSON() {
+		return this.#value;
+	}
+	/**
+	* @see {@link nodePath.toNamespacedPath}
+	*/
+	toNamespacedPath() {
+		return toNamespacedPath(this.#value);
+	}
+	/**
+	* Converts the Path instance to a string.
+	* This method returns the internal path string value,
+	* making it useful for implicit and explicit string conversions.
+	*/
+	toString() {
+		return this.#value;
+	}
+	/**
+	* @see {@link fsp.access}
+	*/
+	access(...args) {
+		return fsp.access(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.appendFile}
+	*/
+	appendFile(...args) {
+		return fsp.appendFile(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.chmod}
+	*/
+	chmod(...args) {
+		return fsp.chmod(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.chown}
+	*/
+	chown(...args) {
+		return fsp.chown(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.copyFile}
+	*/
+	copyFile(...args) {
+		return fsp.copyFile(this.#value, ...args);
+	}
+	mkdir(...args) {
+		return fsp.mkdir(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.open}
+	*/
+	open(...args) {
+		return fsp.open(this.#value, ...args);
+	}
+	readdir(...args) {
+		return fsp.readdir(this.#value, ...args);
+	}
+	readFile(...args) {
+		return fsp.readFile(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.rename}
+	*/
+	rename(newPath) {
+		return fsp.rename(this.#value, newPath.toString());
+	}
+	/**
+	* @see {@link fsp.rm}
+	*/
+	rm(...args) {
+		return fsp.rm(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.rmdir}
+	*/
+	rmdir(...args) {
+		return fsp.rmdir(this.#value, ...args);
+	}
+	stat(...args) {
+		return fsp.stat(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.truncate}
+	*/
+	truncate(...args) {
+		return fsp.truncate(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsp.unlink}
+	*/
+	unlink() {
+		return fsp.unlink(this.#value);
+	}
+	/**
+	* @see {@link fsp.writeFile}
+	*/
+	writeFile(...args) {
+		return fsp.writeFile(this.#value, ...args);
+	}
+	/**
+	* @see {@link fsExtra.ensureDir}
+	*/
+	ensureDir(options) {
+		return fsExtra.ensureDir(this.#value, options);
+	}
+	/**
+	* @see {@link fsExtra.ensureDir}
+	*/
+	mkdirp = this.ensureDir;
+	/**
+	* @see {@link fsExtra.ensureDir}
+	*/
+	mkdirs = this.ensureDir;
+	/**
+	* @see {@link fsExtra.readJson}
+	*/
+	async readJson(options) {
+		return await fsExtra.readJson(this.#value, options);
+	}
+	/**
+	* @see {@link fsExtra.remove}
+	*/
+	remove() {
+		return fsExtra.remove(this.#value);
+	}
+	/**
+	* @see {@link fsExtra.writeJson}
+	*/
+	writeJson(data, options) {
+		return fsExtra.writeJson(this.#value, data, options);
+	}
+};
+
+//#endregion
+export { Path };
+//# sourceMappingURL=path.js.map

package/dist/classes/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","names":["#value","#toStrings","#newInstance"],"sources":["../../src/classes/path.ts"],"sourcesContent":["import type { Buffer } from 'node:buffer';\nimport type { Abortable } from 'node:events';\nimport type * as fs from 'node:fs';\nimport * as fsp from 'node:fs/promises';\nimport {\n    basename,\n    dirname,\n    extname,\n    format,\n    isAbsolute,\n    join,\n    normalize,\n    parse,\n    relative,\n    resolve,\n    toNamespacedPath,\n} from 'node:path';\nimport type * as nodePath from 'node:path';\n\nimport * as fsExtra from 'fs-extra';\nimport type {\n    JFReadOptions,\n    JFWriteOptions,\n} from 'jsonfile';\n\nexport type DoNotRemoveOrUseThisType = typeof fsExtra;\ntype DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extends [any, ...infer R] ? R : never;\nexport type PathLike = fs.PathLike | Path;\n\n/**\n * Class representing a file system path with various utility methods for path operations.\n *\n * All methods in the `Path` class are immutable, returning new instances with modified values\n * and leaving the original instance unchanged.\n */\nexport class Path {\n    readonly #value: string;\n\n    constructor(...paths: PathLike[]) {\n        this.#value = join(...this.#toStrings(paths));\n    }\n\n    // Symbols\n    [Symbol.for('nodejs.util.inspect.custom')]() {\n        return this.#value;\n    }\n\n    [Symbol.toPrimitive](hint: string) {\n        if (hint === 'number') throw new TypeError('Cannot convert a Path to a number');\n        return this.#value;\n    }\n\n    // Private methods\n    #newInstance(...paths: PathLike[]) {\n        return new Path(...paths);\n    }\n\n    #toStrings(paths: PathLike[]) {\n        return paths.map((path) => path.toString());\n    }\n\n    // Public getters\n\n    /**\n     * @see {@link nodePath.dirname}\n     */\n    get parent() {\n        return this.dirname();\n    }\n\n    /**\n     * Returns the internal path string value.\n     */\n    get value() {\n        return this.#value;\n    }\n\n    // Public static methods\n\n    /**\n     * @see {@link nodePath.format}\n     */\n    static format(pathObject: nodePath.FormatInputPathObject) {\n        return new Path(format(pathObject));\n    }\n\n    /**\n     * @see {@link nodePath.resolve}\n     */\n    static resolve(...paths: PathLike[]) {\n        return new this(...paths).resolve();\n    }\n\n    // Public base methods\n\n    /**\n     * @see {@link nodePath.basename}\n     */\n    basename(suffix?: string) {\n        return basename(this.#value, suffix);\n    }\n\n    /**\n     * @see {@link nodePath.dirname}\n     */\n    dirname() {\n        return this.#newInstance(dirname(this.#value));\n    }\n\n    /**\n     * @see {@link nodePath.extname}\n     */\n    extname() {\n        return extname(this.#value);\n    }\n\n    /**\n     * @see {@link nodePath.isAbsolute}\n     */\n    isAbsolute() {\n        return isAbsolute(this.#value);\n    }\n\n    /**\n     * @see {@link nodePath.normalize}\n     */\n    normalize() {\n        return this.#newInstance(normalize(this.#value));\n    }\n\n    /**\n     * @see {@link nodePath.join}\n     */\n    join(...paths: PathLike[]) {\n        return this.#newInstance(this.#value, ...this.#toStrings(paths));\n    }\n\n    /**\n     * @see {@link nodePath.parse}\n     */\n    parse() {\n        return parse(this.#value);\n    }\n\n    /**\n     * @see {@link nodePath.relative}\n     */\n    relative(to: PathLike) {\n        return this.#newInstance(relative(this.#value, to.toString()));\n    }\n\n    /**\n     * @see {@link nodePath.resolve}\n     */\n    resolve() {\n        return this.#newInstance(resolve(this.#value));\n    }\n\n    toJSON() {\n        return this.#value;\n    }\n\n    /**\n     * @see {@link nodePath.toNamespacedPath}\n     */\n    toNamespacedPath() {\n        return toNamespacedPath(this.#value);\n    }\n\n    /**\n     * Converts the Path instance to a string.\n     * This method returns the internal path string value,\n     * making it useful for implicit and explicit string conversions.\n     */\n    toString() {\n        return this.#value;\n    }\n\n    // Some commonly used promise fs methods\n\n    /**\n     * @see {@link fsp.access}\n     */\n    access(...args: DropFirstParameters<typeof fsp.access>) {\n        return fsp.access(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.appendFile}\n     */\n    appendFile(...args: DropFirstParameters<typeof fsp.appendFile>) {\n        return fsp.appendFile(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.chmod}\n     */\n    chmod(...args: DropFirstParameters<typeof fsp.chmod>) {\n        return fsp.chmod(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.chown}\n     */\n    chown(...args: DropFirstParameters<typeof fsp.chown>) {\n        return fsp.chown(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.copyFile}\n     */\n    copyFile(...args: DropFirstParameters<typeof fsp.copyFile>) {\n        return fsp.copyFile(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.mkdir}\n     */\n    mkdir(\n        options: fs.MakeDirectoryOptions & {\n            recursive: true;\n        },\n    ): Promise<string>;\n    mkdir(\n        options?:\n          | (fs.MakeDirectoryOptions & {\n              recursive?: false;\n          })\n          | fs.Mode\n          | null,\n    ): Promise<void>;\n    mkdir(options?: fs.MakeDirectoryOptions | fs.Mode | null): Promise<string | undefined>;\n    mkdir(...args: any): any {\n        return fsp.mkdir(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.open}\n     */\n    open(...args: DropFirstParameters<typeof fsp.open>) {\n        return fsp.open(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.readdir}\n     */\n    readdir(\n        path: PathLike,\n        options?:\n          | BufferEncoding\n          | (fs.ObjectEncodingOptions & {\n              recursive?: boolean;\n              withFileTypes?: false;\n          })\n          | null,\n    ): Promise<string[]>;\n    readdir(\n        path: PathLike,\n        options:\n          | 'buffer'\n          | {\n              encoding: 'buffer';\n              recursive?: boolean;\n              withFileTypes?: false;\n          },\n    ): Promise<Buffer[]>;\n    readdir(\n        path: PathLike,\n        options?:\n          | BufferEncoding\n          | (fs.ObjectEncodingOptions & {\n              recursive?: boolean;\n              withFileTypes?: false;\n          })\n          | null,\n    ): Promise<Buffer[] | string[]>;\n    readdir(\n        path: PathLike,\n        options: fs.ObjectEncodingOptions & {\n            recursive?: boolean;\n            withFileTypes: true;\n        },\n    ): Promise<fs.Dirent[]>;\n    readdir(\n        path: PathLike,\n        options: {\n            encoding: 'buffer';\n            recursive?: boolean;\n            withFileTypes: true;\n        },\n    ): Promise<fs.Dirent<Buffer>[]>;\n    readdir(...args: any): any {\n        return fsp.readdir(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.readFile}\n     */\n    readFile(\n        options?:\n          | (Abortable & {\n              encoding?: null;\n              flag?: fs.OpenMode;\n          })\n          | null,\n    ): Promise<Buffer>;\n    readFile(\n        options:\n          | (Abortable & {\n              encoding: BufferEncoding;\n              flag?: fs.OpenMode;\n          })\n          | BufferEncoding,\n    ): Promise<string>;\n    readFile(\n        options?:\n            | (\n              & Abortable\n              & fs.ObjectEncodingOptions\n              & { flag?: fs.OpenMode }\n            )\n            | BufferEncoding\n            | null,\n    ): Promise<Buffer | string>;\n    readFile(...args: any): any {\n        return fsp.readFile(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.rename}\n     */\n    rename(newPath: PathLike) {\n        return fsp.rename(this.#value, newPath.toString());\n    }\n\n    /**\n     * @see {@link fsp.rm}\n     */\n    rm(...args: DropFirstParameters<typeof fsp.rm>) {\n        return fsp.rm(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.rmdir}\n     */\n    rmdir(...args: DropFirstParameters<typeof fsp.rmdir>) {\n        return fsp.rmdir(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.stat}\n     */\n    stat(\n        opts?: fs.StatOptions & {\n            bigint?: false;\n        },\n    ): Promise<fs.Stats>;\n    stat(\n        opts: fs.StatOptions & {\n            bigint: true;\n        },\n    ): Promise<fs.BigIntStats>;\n    stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats>;\n    stat(...args: any): any {\n        return fsp.stat(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.truncate}\n     */\n    truncate(...args: DropFirstParameters<typeof fsp.truncate>) {\n        return fsp.truncate(this.#value, ...args);\n    }\n\n    /**\n     * @see {@link fsp.unlink}\n     */\n    unlink() {\n        return fsp.unlink(this.#value);\n    }\n\n    /**\n     * @see {@link fsp.writeFile}\n     */\n    writeFile(...args: DropFirstParameters<typeof fsp.writeFile>) {\n        return fsp.writeFile(this.#value, ...args);\n    }\n\n    // Some commonly used promise fs extra methods\n\n    /**\n     * @see {@link fsExtra.ensureDir}\n     */\n    ensureDir(options?: fsExtra.EnsureDirOptions | number) {\n        return fsExtra.ensureDir(this.#value, options);\n    }\n\n    /**\n     * @see {@link fsExtra.ensureDir}\n     */\n    mkdirp = this.ensureDir;\n\n    /**\n     * @see {@link fsExtra.ensureDir}\n     */\n    mkdirs = this.ensureDir;\n\n    /**\n     * @see {@link fsExtra.readJson}\n     */\n    async readJson<T = any>(options?: JFReadOptions) {\n        return await fsExtra.readJson(this.#value, options) as T;\n    }\n\n    /**\n     * @see {@link fsExtra.remove}\n     */\n    remove() {\n        return fsExtra.remove(this.#value);\n    }\n\n    /**\n     * @see {@link fsExtra.writeJson}\n     */\n    writeJson(data: any, options?: JFWriteOptions) {\n        return fsExtra.writeJson(this.#value, data, options);\n    }\n}\n"],"mappings":";;;;;;;;;;;AAmCA,IAAa,OAAb,MAAa,KAAK;CACd,CAASA;CAET,YAAY,GAAG,OAAmB;AAC9B,QAAKA,QAAS,KAAK,GAAG,MAAKC,UAAW,MAAM,CAAC;;CAIjD,CAAC,OAAO,IAAI,6BAA6B,IAAI;AACzC,SAAO,MAAKD;;CAGhB,CAAC,OAAO,aAAa,MAAc;AAC/B,MAAI,SAAS,SAAU,OAAM,IAAI,UAAU,oCAAoC;AAC/E,SAAO,MAAKA;;CAIhB,aAAa,GAAG,OAAmB;AAC/B,SAAO,IAAI,KAAK,GAAG,MAAM;;CAG7B,WAAW,OAAmB;AAC1B,SAAO,MAAM,KAAK,SAAS,KAAK,UAAU,CAAC;;;;;CAQ/C,IAAI,SAAS;AACT,SAAO,KAAK,SAAS;;;;;CAMzB,IAAI,QAAQ;AACR,SAAO,MAAKA;;;;;CAQhB,OAAO,OAAO,YAA4C;AACtD,SAAO,IAAI,KAAK,OAAO,WAAW,CAAC;;;;;CAMvC,OAAO,QAAQ,GAAG,OAAmB;AACjC,SAAO,IAAI,KAAK,GAAG,MAAM,CAAC,SAAS;;;;;CAQvC,SAAS,QAAiB;AACtB,SAAO,SAAS,MAAKA,OAAQ,OAAO;;;;;CAMxC,UAAU;AACN,SAAO,MAAKE,YAAa,QAAQ,MAAKF,MAAO,CAAC;;;;;CAMlD,UAAU;AACN,SAAO,QAAQ,MAAKA,MAAO;;;;;CAM/B,aAAa;AACT,SAAO,WAAW,MAAKA,MAAO;;;;;CAMlC,YAAY;AACR,SAAO,MAAKE,YAAa,UAAU,MAAKF,MAAO,CAAC;;;;;CAMpD,KAAK,GAAG,OAAmB;AACvB,SAAO,MAAKE,YAAa,MAAKF,OAAQ,GAAG,MAAKC,UAAW,MAAM,CAAC;;;;;CAMpE,QAAQ;AACJ,SAAO,MAAM,MAAKD,MAAO;;;;;CAM7B,SAAS,IAAc;AACnB,SAAO,MAAKE,YAAa,SAAS,MAAKF,OAAQ,GAAG,UAAU,CAAC,CAAC;;;;;CAMlE,UAAU;AACN,SAAO,MAAKE,YAAa,QAAQ,MAAKF,MAAO,CAAC;;CAGlD,SAAS;AACL,SAAO,MAAKA;;;;;CAMhB,mBAAmB;AACf,SAAO,iBAAiB,MAAKA,MAAO;;;;;;;CAQxC,WAAW;AACP,SAAO,MAAKA;;;;;CAQhB,OAAO,GAAG,MAA8C;AACpD,SAAO,IAAI,OAAO,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM3C,WAAW,GAAG,MAAkD;AAC5D,SAAO,IAAI,WAAW,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM/C,MAAM,GAAG,MAA6C;AAClD,SAAO,IAAI,MAAM,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM1C,MAAM,GAAG,MAA6C;AAClD,SAAO,IAAI,MAAM,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM1C,SAAS,GAAG,MAAgD;AACxD,SAAO,IAAI,SAAS,MAAKA,OAAQ,GAAG,KAAK;;CAoB7C,MAAM,GAAG,MAAgB;AACrB,SAAO,IAAI,MAAM,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM1C,KAAK,GAAG,MAA4C;AAChD,SAAO,IAAI,KAAK,MAAKA,OAAQ,GAAG,KAAK;;CAmDzC,QAAQ,GAAG,MAAgB;AACvB,SAAO,IAAI,QAAQ,MAAKA,OAAQ,GAAG,KAAK;;CAgC5C,SAAS,GAAG,MAAgB;AACxB,SAAO,IAAI,SAAS,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM7C,OAAO,SAAmB;AACtB,SAAO,IAAI,OAAO,MAAKA,OAAQ,QAAQ,UAAU,CAAC;;;;;CAMtD,GAAG,GAAG,MAA0C;AAC5C,SAAO,IAAI,GAAG,MAAKA,OAAQ,GAAG,KAAK;;;;;CAMvC,MAAM,GAAG,MAA6C;AAClD,SAAO,IAAI,MAAM,MAAKA,OAAQ,GAAG,KAAK;;CAiB1C,KAAK,GAAG,MAAgB;AACpB,SAAO,IAAI,KAAK,MAAKA,OAAQ,GAAG,KAAK;;;;;CAMzC,SAAS,GAAG,MAAgD;AACxD,SAAO,IAAI,SAAS,MAAKA,OAAQ,GAAG,KAAK;;;;;CAM7C,SAAS;AACL,SAAO,IAAI,OAAO,MAAKA,MAAO;;;;;CAMlC,UAAU,GAAG,MAAiD;AAC1D,SAAO,IAAI,UAAU,MAAKA,OAAQ,GAAG,KAAK;;;;;CAQ9C,UAAU,SAA6C;AACnD,SAAO,QAAQ,UAAU,MAAKA,OAAQ,QAAQ;;;;;CAMlD,SAAS,KAAK;;;;CAKd,SAAS,KAAK;;;;CAKd,MAAM,SAAkB,SAAyB;AAC7C,SAAO,MAAM,QAAQ,SAAS,MAAKA,OAAQ,QAAQ;;;;;CAMvD,SAAS;AACL,SAAO,QAAQ,OAAO,MAAKA,MAAO;;;;;CAMtC,UAAU,MAAW,SAA0B;AAC3C,SAAO,QAAQ,UAAU,MAAKA,OAAQ,MAAM,QAAQ"}

package/dist/classes/precision-number.d.ts

@@ -0,0 +1,58 @@
+import { Decimal } from "decimal.js";
+
+//#region src/classes/precision-number.d.ts
+type PrecisionNumberValue = Decimal.Value | PrecisionNumber | {
+  toString: () => string;
+};
+/**
+ * Class representing a precision number with configurable decimal places and rounding.
+ *
+ * This class leverages the Decimal.js library to ensure accurate arithmetic operations
+ * with floating point numbers. It provides methods for various arithmetic operations
+ * (addition, subtraction, multiplication, division) as well as comparison and utility
+ * methods to check the state of the number (e.g., if it is finite, an integer, zero, etc.).
+ *
+ * The class also includes custom symbol methods to support Node.js inspection and primitive
+ * type conversion.
+ *
+ * The class supports in-place modification methods that alter the current instance's value,
+ * such as `plus`, `minus`, `times`, `dividedBy`, and others. Additionally, methods prefixed
+ * with `to` (e.g., `toPlus`, `toMinus`) return a new instance of `PrecisionNumber` with the
+ * modified value, leaving the original instance unchanged.
+ */
+declare class PrecisionNumber {
+  #private;
+  constructor(value?: PrecisionNumberValue, decimalPlaces?: number, rounding?: Decimal.Rounding);
+  [Symbol.toPrimitive](hint: string): string | number;
+  get value(): string;
+  static toFixed(value: PrecisionNumberValue, decimalPlaces?: number, rounding?: Decimal.Rounding): string;
+  absoluteValue(): this;
+  dividedBy(value: PrecisionNumberValue): this;
+  equals(value: PrecisionNumberValue): boolean;
+  gt(value: PrecisionNumberValue): boolean;
+  gte(value: PrecisionNumberValue): boolean;
+  isFinite(): boolean;
+  isInteger(): boolean;
+  isNaN(): boolean;
+  isNegative(): boolean;
+  isPositive(): boolean;
+  isZero(): boolean;
+  lt(value: PrecisionNumberValue): boolean;
+  lte(value: PrecisionNumberValue): boolean;
+  minus(value: PrecisionNumberValue): this;
+  negate(): this;
+  plus(value: PrecisionNumberValue): this;
+  times(value: PrecisionNumberValue): this;
+  toAbsoluteValue(): PrecisionNumber;
+  toDividedBy(value: PrecisionNumberValue): PrecisionNumber;
+  toJSON(): string;
+  toMinus(value: PrecisionNumberValue): PrecisionNumber;
+  toNegated(): PrecisionNumber;
+  toPlus(value: PrecisionNumberValue): PrecisionNumber;
+  toString(): string;
+  toFixed(decimalPlaces?: number, rounding?: Decimal.Rounding): string;
+  toTimes(value: PrecisionNumberValue): PrecisionNumber;
+}
+//#endregion
+export { PrecisionNumber, PrecisionNumberValue };
+//# sourceMappingURL=precision-number.d.ts.map

package/dist/classes/precision-number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precision-number.d.ts","names":[],"sources":["../../src/classes/precision-number.ts"],"sourcesContent":[],"mappings":";;;KAEY,oBAAA,GAAuB,OAAA,CAAQ,QAAQ;;AAAnD,CAAA;;;;;AAkBA;;;;;;;;;;;;AAgGe,cAhGF,eAAA,CAgGE;UAIE;aAUD,CAAA,KAAA,CAAA,EAvGD,oBAuGC,EAAA,aAAA,CAAA,EAAA,MAAA,EAAA,QAAA,CAAA,EArGE,OAAA,CAAQ,QAqGV;GAzFX,MAAA,CAAO,WAAA,EA8FK,IAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,MAAA;MAKE,KAAA,CAAA,CAAA,EAAA,MAAA;SAII,OAAA,CAAA,KAAA,EAtFR,oBAsFQ,EAAA,aAAA,CAAA,EAAA,MAAA,EAAA,QAAA,CAAA,EApFL,OAAA,CAAQ,QAoFH,CAAA,EAAA,MAAA;eAAoB,CAAA,CAAA,EAAA,IAAA;WAYxB,CAAA,KAAA,EArFE,oBAqFF,CAAA,EAAA,IAAA;QAAoB,CAAA,KAAA,EAhFrB,oBAgFqB,CAAA,EAAA,OAAA;KAI1B,KAAA,EAhFC,oBAgFD,CAAA,EAAA,OAAA;KAIK,CAAA,KAAA,EAhFH,oBAgFG,CAAA,EAAA,OAAA;UAAoB,CAAA,CAAA,EAAA,OAAA;WAQ6B,CAAA,CAAQ,EAAA,OAAA;OAIxD,CAAA,CAAA,EAAA,OAAA;YAAoB,CAAA,CAAA,EAAA,OAAA;EAAA,UAAA,CAAA,CAAA,EAAA,OAAA;;YAhEzB;aAIC;eAIE;;cAUD;eAKC;qBAKE;qBAII,uBAAoB;;iBAYxB,uBAAoB;eAI1B;gBAIK,uBAAoB;;6CAQ6B,OAAA,CAAQ;iBAIxD,uBAAoB"}