@kikiutils/shared 18.0.1 → 18.2.0

package/dist/classes/path.js

@@ -1,28 +1,24 @@
 import * as fsp from "node:fs/promises";
-import { basename, dirname, extname, format, isAbsolute, join, normalize, parse, relative, resolve, toNamespacedPath } from "node:path";
+import * as nodePath from "node:path";
 //#region src/classes/path.ts
 /**
-* 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.
 */
 var Path = class Path {
 	#value;
 	/**
 	* 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) {
-		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;
+		this.#value = nodePath.join(...this.#toStrings(paths));
 	}
 	#newInstance(...paths) {
 		return new Path(...paths);
@@ -31,126 +27,222 @@ var Path = class Path {
 		return paths.map((path) => path.toString());
 	}
 	/**
-	* @see {@link nodePath.dirname}
+	* The parent directory as a new `Path`; this instance is unchanged.
+	*
+	* @see {@link Path.dirname}
 	*/
 	get parent() {
 		return this.dirname();
 	}
 	/**
-	* Returns the internal path string value.
+	* The normalized path string stored by this instance.
 	*/
 	get value() {
 		return this.#value;
 	}
 	/**
-	* @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) {
-		return new Path(format(pathObject));
+		return new Path(nodePath.format(pathObject));
 	}
 	/**
-	* @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) {
 		return new this(...paths).resolve();
 	}
+	[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;
+	}
 	/**
-	* @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) {
-		return basename(this.#value, suffix);
+		return nodePath.basename(this.#value, suffix);
 	}
 	/**
-	* @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() {
-		return this.#newInstance(dirname(this.#value));
+		return this.#newInstance(nodePath.dirname(this.#value));
 	}
 	/**
-	* @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() {
-		return extname(this.#value);
+		return nodePath.extname(this.#value);
 	}
 	/**
-	* @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() {
-		return isAbsolute(this.#value);
+		return nodePath.isAbsolute(this.#value);
 	}
 	/**
-	* @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() {
-		return this.#newInstance(normalize(this.#value));
+		return this.#newInstance(nodePath.normalize(this.#value));
 	}
 	/**
-	* @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) {
 		return this.#newInstance(this.#value, ...this.#toStrings(paths));
 	}
 	/**
-	* @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() {
-		return parse(this.#value);
+		return nodePath.parse(this.#value);
 	}
 	/**
-	* @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) {
-		return this.#newInstance(relative(this.#value, to.toString()));
+		return this.#newInstance(nodePath.relative(this.#value, to.toString()));
 	}
 	/**
-	* @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() {
-		return this.#newInstance(resolve(this.#value));
+		return this.#newInstance(nodePath.resolve(this.#value));
 	}
 	toJSON() {
 		return this.#value;
 	}
 	/**
-	* @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() {
-		return toNamespacedPath(this.#value);
+		return nodePath.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.
+	* Returns the stored path as a string.
 	*/
 	toString() {
 		return this.#value;
 	}
 	/**
-	* @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) {
 		return fsp.access(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.appendFile(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.chmod(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.chown(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.copyFile(this.#value, ...args);
@@ -159,7 +251,12 @@ var Path = class Path {
 		return fsp.mkdir(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.open(this.#value, ...args);
@@ -171,40 +268,77 @@ var Path = class Path {
 		return fsp.readFile(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.rename(this.#value, newPath.toString());
 	}
 	/**
-	* @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) {
 		return fsp.rm(this.#value, ...args);
 	}
 	/**
-	* @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) {
 		return fsp.rmdir(this.#value, ...args);
 	}
-	stat(...args) {
-		return fsp.stat(this.#value, ...args);
+	async stat(opts) {
+		try {
+			return await fsp.stat(this.#value, opts);
+		} catch (error) {
+			if (opts?.throwIfNoEntry === false && error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+			throw error;
+		}
 	}
 	/**
-	* @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) {
 		return fsp.truncate(this.#value, ...args);
 	}
 	/**
-	* @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() {
 		return fsp.unlink(this.#value);
 	}
 	/**
-	* @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) {
 		return fsp.writeFile(this.#value, ...args);

package/dist/classes/path.js.map

@@ -1 +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\ntype DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extends [any, ...infer R] ? R : never;\n\n/**\n * Values accepted by the `Path` constructor and path-composition methods.\n */\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    /**\n     * Creates a normalized path value by joining the provided path segments.\n     *\n     * @param {PathLike[]} paths - Path segments accepted by Node.js `path.join` or another `Path` instance\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"],"mappings":"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"}
+{"version":3,"file":"path.js","names":[],"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 * as nodePath from 'node:path';\n\ntype DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extends [any, ...infer R] ? R : never;\n\n/**\n * Values accepted by the `Path` constructor and path-composition methods.\n */\nexport type PathLike = fs.PathLike | Path;\n\n/**\n * An immutable file system path with Node.js path and file operations.\n *\n * @remarks\n * Path-composition methods return new instances and leave this instance unchanged.\n * File operations act on the stored path and forward Node.js defaults and promise rejections.\n * They do not update the stored path, including after a successful rename.\n * The constructor joins stringified inputs using the platform-specific Node.js path rules.\n */\nexport class Path {\n    // Private instance properties\n    readonly #value: string;\n\n    // Constructor\n\n    /**\n     * Creates a normalized path value by joining the provided path segments.\n     *\n     * @param paths - Path segments accepted by Node.js `path.join` or another `Path` instance.\n     */\n    constructor(...paths: PathLike[]) {\n        this.#value = nodePath.join(...this.#toStrings(paths));\n    }\n\n    // Private instance 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 instance accessors\n\n    /**\n     * The parent directory as a new `Path`; this instance is unchanged.\n     *\n     * @see {@link Path.dirname}\n     */\n    get parent() {\n        return this.dirname();\n    }\n\n    /**\n     * The normalized path string stored by this instance.\n     */\n    get value() {\n        return this.#value;\n    }\n\n    // Public static methods\n\n    /**\n     * Creates a new path from a Node.js path object.\n     *\n     * @param pathObject - The path components to format.\n     *\n     * @returns A new normalized `Path`.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.format}\n     */\n    static format(pathObject: nodePath.FormatInputPathObject) {\n        return new Path(nodePath.format(pathObject));\n    }\n\n    /**\n     * Resolves joined path segments to an absolute path.\n     *\n     * @remarks\n     * Inputs are joined before resolution; unlike Node.js `path.resolve`,\n     * later absolute segments do not reset the path.\n     *\n     * @param paths - The stringified path segments to join.\n     *\n     * @returns A new absolute `Path`.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.resolve}\n     */\n    static resolve(...paths: PathLike[]) {\n        return new this(...paths).resolve();\n    }\n\n    // Public instance methods\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    /**\n     * Returns the final component of this path.\n     *\n     * @param suffix - An optional exact suffix to remove.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.basename}\n     */\n    basename(suffix?: string) {\n        return nodePath.basename(this.#value, suffix);\n    }\n\n    /**\n     * Returns the parent directory of this path.\n     *\n     * @returns A new `Path`; this instance is unchanged.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.dirname}\n     */\n    dirname() {\n        return this.#newInstance(nodePath.dirname(this.#value));\n    }\n\n    /**\n     * Returns the extension of the final path component.\n     *\n     * @returns The extension including its leading dot, or an empty string when absent.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.extname}\n     */\n    extname() {\n        return nodePath.extname(this.#value);\n    }\n\n    /**\n     * Checks whether this path is absolute on the current platform.\n     *\n     * @returns Whether this path is absolute.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.isAbsolute}\n     */\n    isAbsolute() {\n        return nodePath.isAbsolute(this.#value);\n    }\n\n    /**\n     * Normalizes separators and relative segments in this path.\n     *\n     * @returns A new `Path`; this instance is unchanged.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.normalize}\n     */\n    normalize() {\n        return this.#newInstance(nodePath.normalize(this.#value));\n    }\n\n    /**\n     * Joins additional segments onto this path.\n     *\n     * @param paths - The stringified path segments to append.\n     *\n     * @returns A new normalized `Path`; this instance is unchanged.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.join}\n     */\n    join(...paths: PathLike[]) {\n        return this.#newInstance(this.#value, ...this.#toStrings(paths));\n    }\n\n    /**\n     * Parses this path into its root, directory, basename, extension, and name.\n     *\n     * @returns A new object containing the path components.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.parse}\n     */\n    parse() {\n        return nodePath.parse(this.#value);\n    }\n\n    /**\n     * Computes a relative path from this path to the destination.\n     *\n     * @param to - The destination path.\n     *\n     * @returns A new `Path`; this instance is unchanged.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.relative}\n     */\n    relative(to: PathLike) {\n        return this.#newInstance(nodePath.relative(this.#value, to.toString()));\n    }\n\n    /**\n     * Resolves this path to an absolute path using the current working directory.\n     *\n     * @remarks\n     * Relative paths use the current working directory. This instance is unchanged.\n     *\n     * @returns A new absolute `Path`.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.resolve}\n     */\n    resolve() {\n        return this.#newInstance(nodePath.resolve(this.#value));\n    }\n\n    toJSON() {\n        return this.#value;\n    }\n\n    /**\n     * Converts this path to the Windows namespace form when applicable.\n     *\n     * @returns The namespace-converted path string; this instance is unchanged.\n     * On non-Windows platforms, the path text is unchanged.\n     *\n     * @see {@link https://nodejs.org/api/path.html | Node.js path.toNamespacedPath}\n     */\n    toNamespacedPath() {\n        return nodePath.toNamespacedPath(this.#value);\n    }\n\n    /**\n     * Returns the stored path as a string.\n     */\n    toString() {\n        return this.#value;\n    }\n\n    /**\n     * Checks access permissions for the stored path.\n     *\n     * @remarks\n     * The promise resolves when the access check succeeds and rejects if access is denied or the path is missing.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.access}\n     */\n    access(...args: DropFirstParameters<typeof fsp.access>) {\n        return fsp.access(this.#value, ...args);\n    }\n\n    /**\n     * Appends data to the file at the stored path.\n     *\n     * @remarks\n     * The promise resolves when appending completes; a missing file is created according to the supplied options.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.appendFile}\n     */\n    appendFile(...args: DropFirstParameters<typeof fsp.appendFile>) {\n        return fsp.appendFile(this.#value, ...args);\n    }\n\n    /**\n     * Changes the permissions of the stored path.\n     *\n     * @remarks\n     * The promise resolves when the permissions are changed.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.chmod}\n     */\n    chmod(...args: DropFirstParameters<typeof fsp.chmod>) {\n        return fsp.chmod(this.#value, ...args);\n    }\n\n    /**\n     * Changes the owner and group of the stored path.\n     *\n     * @remarks\n     * The promise resolves when the ownership is changed.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.chown}\n     */\n    chown(...args: DropFirstParameters<typeof fsp.chown>) {\n        return fsp.chown(this.#value, ...args);\n    }\n\n    /**\n     * Copies the file at the stored path to a destination.\n     *\n     * @remarks\n     * The promise resolves when copying completes. The stored path remains the source path.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.copyFile}\n     */\n    copyFile(...args: DropFirstParameters<typeof fsp.copyFile>) {\n        return fsp.copyFile(this.#value, ...args);\n    }\n\n    /**\n     * Creates a directory at the stored path.\n     *\n     * @remarks\n     * The promise resolves after creation. Recursive mode resolves to the first created directory path, or\n     * `undefined` if no directory is created; nonrecursive mode resolves without a value.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.mkdir}\n     */\n    mkdir(options: fs.MakeDirectoryOptions & { recursive: true }): Promise<string | undefined>;\n    mkdir(\n        options?:\n          | (fs.MakeDirectoryOptions & { recursive?: false })\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     * Opens the file at the stored path.\n     *\n     * @remarks\n     * The promise resolves to a new file handle. The caller must close the handle when it is no longer needed.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.open}\n     */\n    open(...args: DropFirstParameters<typeof fsp.open>) {\n        return fsp.open(this.#value, ...args);\n    }\n\n    /**\n     * Reads the entries of the directory at the stored path.\n     *\n     * @remarks\n     * The promise resolves to names, buffers, or directory entries according to the options.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.readdir}\n     */\n    readdir(\n        options?:\n          | BufferEncoding\n          | (fs.ObjectEncodingOptions & {\n              recursive?: boolean;\n              withFileTypes?: false;\n          })\n          | null,\n    ): Promise<string[]>;\n    readdir(\n        options:\n          | 'buffer'\n          | {\n              encoding: 'buffer';\n              recursive?: boolean;\n              withFileTypes?: false;\n          },\n    ): Promise<Buffer[]>;\n    readdir(\n        options?:\n          | BufferEncoding\n          | (fs.ObjectEncodingOptions & {\n              recursive?: boolean;\n              withFileTypes?: false;\n          })\n          | null,\n    ): Promise<Buffer[] | string[]>;\n    readdir(\n        options: fs.ObjectEncodingOptions & {\n            recursive?: boolean;\n            withFileTypes: true;\n        },\n    ): Promise<fs.Dirent[]>;\n    readdir(\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     * Reads the entire file at the stored path.\n     *\n     * @remarks\n     * The promise resolves to a string when a text encoding is supplied, or a `Buffer` otherwise.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.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     * Renames or moves the file or directory at the stored path.\n     *\n     * @remarks\n     * The promise resolves when the rename completes. This instance retains its original stored path.\n     *\n     * @param newPath - The destination path; this instance retains its original value.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.rename}\n     */\n    rename(newPath: PathLike) {\n        return fsp.rename(this.#value, newPath.toString());\n    }\n\n    /**\n     * Removes the file or directory at the stored path.\n     *\n     * @remarks\n     * The promise resolves after removal according to the supplied options.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.rm}\n     */\n    rm(...args: DropFirstParameters<typeof fsp.rm>) {\n        return fsp.rm(this.#value, ...args);\n    }\n\n    /**\n     * Removes the directory at the stored path.\n     *\n     * @remarks\n     * The promise resolves after directory removal.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.rmdir}\n     */\n    rmdir(...args: DropFirstParameters<typeof fsp.rmdir>) {\n        return fsp.rmdir(this.#value, ...args);\n    }\n\n    /**\n     * Reads file system metadata for the stored path.\n     *\n     * @remarks\n     * The promise resolves to `Stats`, or `BigIntStats` when `bigint` is enabled.\n     * If `throwIfNoEntry` is `false`, a missing path resolves to `undefined` instead of rejecting.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.stat}\n     */\n    stat(\n        opts?: fs.StatOptions & {\n            bigint?: false;\n            throwIfNoEntry?: true;\n        },\n    ): Promise<fs.Stats>;\n    stat(\n        opts: fs.StatOptions & {\n            bigint: true;\n            throwIfNoEntry?: true;\n        },\n    ): Promise<fs.BigIntStats>;\n    stat(\n        opts: fs.StatOptions & {\n            bigint?: false;\n            throwIfNoEntry: false;\n        },\n    ): Promise<fs.Stats | undefined>;\n    stat(\n        opts: fs.StatOptions & {\n            bigint: true;\n            throwIfNoEntry: false;\n        },\n    ): Promise<fs.BigIntStats | undefined>;\n    stat(opts: fs.StatOptions & { throwIfNoEntry?: true }): Promise<fs.BigIntStats | fs.Stats>;\n    stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats | undefined>;\n    async stat(opts?: fs.StatOptions): Promise<fs.BigIntStats | fs.Stats | undefined> {\n        try {\n            return await fsp.stat(this.#value, opts);\n        } catch (error) {\n            if (\n                opts?.throwIfNoEntry === false\n                && error instanceof Error\n                && 'code' in error\n                && error.code === 'ENOENT'\n            ) return undefined;\n\n            throw error;\n        }\n    }\n\n    /**\n     * Truncates or extends the file at the stored path.\n     *\n     * @remarks\n     * The promise resolves when the file reaches the requested length in bytes; the default length is `0`.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.truncate}\n     */\n    truncate(...args: DropFirstParameters<typeof fsp.truncate>) {\n        return fsp.truncate(this.#value, ...args);\n    }\n\n    /**\n     * Deletes the file or symbolic link at the stored path.\n     *\n     * @remarks\n     * The promise resolves after deletion; directories are not removed.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.unlink}\n     */\n    unlink() {\n        return fsp.unlink(this.#value);\n    }\n\n    /**\n     * Writes data to the file at the stored path.\n     *\n     * @remarks\n     * The promise resolves when writing completes; the default flag replaces existing file contents.\n     *\n     * @see {@link https://nodejs.org/api/fs.html | Node.js fsPromises.writeFile}\n     */\n    writeFile(...args: DropFirstParameters<typeof fsp.writeFile>) {\n        return fsp.writeFile(this.#value, ...args);\n    }\n}\n"],"mappings":"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"}

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

@@ -3,44 +3,41 @@ import { Decimal } from "decimal.js";
 /**
  * Values accepted by `PrecisionNumber` constructors and arithmetic methods.
  */
-type PrecisionNumberValue = Decimal.Value | PrecisionNumber | {
+export type PrecisionNumberValue = Decimal.Value | PrecisionNumber | {
   toString: () => string;
 };
 /**
- * Chainable fixed-decimal wrapper around `decimal.js`.
+ * A fixed-decimal number with mutable and immutable arithmetic operations.
  *
+ * @remarks
  * `PrecisionNumber` stores values as `Decimal`, rounds every mutating operation to
  * the configured decimal places, and exposes both mutable and immutable arithmetic
  * methods. Mutable methods (`plus`, `minus`, `times`, `dividedBy`, `modulo`,
  * `pow`, `clamp`, `ceil`, `floor`, `negate`, `absoluteValue`) update the current
  * instance and return `this`; immutable methods prefixed with `to` return a new
- * `PrecisionNumber` with the same precision settings.
+ * `PrecisionNumber` with the same precision settings, leaving this instance unchanged.
+ * Decimal.js exceptions propagate unchanged; non-finite arithmetic results are not converted into exceptions.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { PrecisionNumber } from '@kikiutils/shared/classes/precision-number';
  *
  * const value = new PrecisionNumber('1.239', 2).plus('2.111');
- * value.toString(); // '3.35'
- * value.toMinus('1').toString(); // '2.35' (original value remains '3.35')
+ * value.toString(); // => '3.35'
+ * value.toMinus('1').toString(); // => '2.35' (original value remains '3.35')
  * ```
  */
-declare class PrecisionNumber {
+export declare class PrecisionNumber {
   #private;
   /**
    * Creates a fixed-decimal number.
    *
-   * @param {PrecisionNumberValue} [value] - Initial value (default: `'0'`)
-   * @param {number} [decimalPlaces] - Decimal places retained after operations (default: `2`)
-   * @param {Decimal.Rounding} [rounding] - Decimal.js rounding mode (default: `Decimal.ROUND_DOWN`)
+   * @param value - Initial value (default: `'0'`).
+   * @param decimalPlaces - Decimal places retained after operations (default: `2`).
+   * @param rounding - Decimal.js rounding mode (default: `Decimal.ROUND_DOWN`).
    */
   constructor(value?: PrecisionNumberValue, decimalPlaces?: number, rounding?: Decimal.Rounding);
-  /**
-   * Converts to a number for numeric coercion and to the fixed string otherwise.
-   *
-   * @param {string} hint - JavaScript primitive-conversion hint
-   */
-  [Symbol.toPrimitive](hint: string): string | number;
   /**
    * Decimal places retained by mutating operations and default formatting.
    */
@@ -56,36 +53,43 @@ declare class PrecisionNumber {
   /**
    * Formats a value with decimal.js without creating a reusable instance.
    *
-   * @param {PrecisionNumberValue} value - Value to format
-   * @param {number} [decimalPlaces] - Decimal places to output (default: `2`)
-   * @param {Decimal.Rounding} [rounding] - Decimal.js rounding mode (default: `Decimal.ROUND_DOWN`)
+   * @param value - Value to format.
+   * @param decimalPlaces - Decimal places to output (default: `2`).
+   * @param rounding - Decimal.js rounding mode (default: `Decimal.ROUND_DOWN`).
    *
-   * @returns {string} Fixed-decimal string
+   * @returns Fixed-decimal string.
    */
   static toFixed(value: PrecisionNumberValue, decimalPlaces?: number, rounding?: Decimal.Rounding): string;
+  /**
+   * Converts to a number for numeric coercion and to the fixed string otherwise.
+   *
+   * @param hint - JavaScript primitive-conversion hint.
+   */
+  [Symbol.toPrimitive](hint: string): string | number;
   /**
    * Replaces the current value with its absolute value.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    */
   absoluteValue(): this;
   /**
    * Rounds the current value up to the nearest integer in place.
    *
+   * @remarks
    * The stored value still uses this instance's configured decimal places for output.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    */
   ceil(): this;
   /**
    * Restricts the current value to the inclusive range `[min, max]` in place.
    *
-   * @param {PrecisionNumberValue} min - Lower bound
-   * @param {PrecisionNumberValue} max - Upper bound
+   * @param min - Lower bound.
+   * @param max - Upper bound.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    *
-   * @throws {Error} If `min` is greater than `max`
+   * @throws Error if `min` is greater than `max`.
    */
   clamp(min: PrecisionNumberValue, max: PrecisionNumberValue): this;
   /**
@@ -95,25 +99,26 @@ declare class PrecisionNumber {
   /**
    * Divides the current value by another value in place.
    *
-   * @param {PrecisionNumberValue} value - Divisor
+   * @param value - Divisor.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    */
   dividedBy(value: PrecisionNumberValue): this;
   /**
    * Checks whether the current value equals another value.
    *
-   * @param {PrecisionNumberValue} value - Value to compare
+   * @param value - Value to compare.
    *
-   * @returns {boolean} `true` when both numeric values are equal
+   * @returns Whether both numeric values are equal.
    */
   equals(value: PrecisionNumberValue): boolean;
   /**
    * Rounds the current value down to the nearest integer in place.
    *
+   * @remarks
    * The stored value still uses this instance's configured decimal places for output.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    */
   floor(): this;
   /**
@@ -163,9 +168,9 @@ declare class PrecisionNumber {
   /**
    * Replaces the current value with the remainder after division by another value.
    *
-   * @param {PrecisionNumberValue} value - Divisor used to compute the remainder
+   * @param value - Divisor used to compute the remainder.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    */
   modulo(value: PrecisionNumberValue): this;
   /**
@@ -179,9 +184,9 @@ declare class PrecisionNumber {
   /**
    * Raises the current value to an exponent in place.
    *
-   * @param {PrecisionNumberValue} value - Exponent
+   * @param value - Exponent.
    *
-   * @returns {this} The current instance for chaining
+   * @returns This instance for chaining.
    */
   pow(value: PrecisionNumberValue): this;
   /**
@@ -199,10 +204,10 @@ declare class PrecisionNumber {
   /**
    * Returns a new instance restricted to the inclusive range `[min, max]`.
    *
-   * @param {PrecisionNumberValue} min - Lower bound
-   * @param {PrecisionNumberValue} max - Upper bound
+   * @param min - Lower bound.
+   * @param max - Upper bound.
    *
-   * @throws {Error} If `min` is greater than `max`
+   * @throws Error if `min` is greater than `max`.
    */
   toClamped(min: PrecisionNumberValue, max: PrecisionNumberValue): PrecisionNumber;
   /**
@@ -240,6 +245,7 @@ declare class PrecisionNumber {
   /**
    * Converts the current value to a JavaScript number.
    *
+   * @remarks
    * Use `toString`/`value` when preserving decimal precision is more important than native-number ergonomics.
    */
   toNumber(): number;
@@ -257,5 +263,4 @@ declare class PrecisionNumber {
   toTimes(value: PrecisionNumberValue): PrecisionNumber;
 }
 //#endregion
-export { PrecisionNumber, PrecisionNumberValue };
 //# sourceMappingURL=precision-number.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"precision-number.d.ts","names":[],"sources":["../../src/classes/precision-number.ts"],"mappings":";;;;;KAKY,uBAAuB,QAAQ,QAAQ;EAAoB;;;;;;;;;;;;;;;;;;;;;cAqB1D;;;;;;;;;EAcL,YAAA,QAAO,sBACP,wBACA,WAAU,QAAQ;;;;;;GAqBrB,OAAO,aAAa;;;;MAmBjB;;;;MAOA,YAAQ,QAAA;;;;MAOR;;;;;;;;;;SAaG,QACH,OAAO,sBACP,wBACA,WAAU,QAAQ;;;;;;EAYtB;;;;;;;;EAYA;;;;;;;;;;;EAeA,MAAM,KAAK,sBAAsB,KAAK;;;;EAWtC,SAAK;;;;;;;;EAWL,UAAU,OAAO;;;;;;;;EAYjB,OAAO,OAAO;;;;;;;;EAWd;;;;EAQA,GAAG,OAAO;;;;EAOV,IAAI,OAAO;;;;EAOX;;;;EAOA;;;;EAOA;;;;EAOA;;;;EAOA;;;;EAOA;;;;EAOA,GAAG,OAAO;;;;EAOV,IAAI,OAAO;;;;EAOX,MAAM,OAAO;;;;;;;;EAYb,OAAO,OAAO;;;;EAQd;;;;EAQA,KAAK,OAAO;;;;;;;;EAYZ,IAAI,OAAO;;;;EAQX,MAAM,OAAO;;;;EAQb,mBAAe;;;;EAOf,UAAM;;;;;;;;;EAYN,UAAU,KAAK,sBAAsB,KAAK,uBAAoB;;;;EAO9D,YAAY,OAAO,uBAAoB;;;;EAWvC,WAAO;;;;EAOP;;;;EAOA,QAAQ,OAAO,uBAAoB;;;;EAWnC,SAAS,OAAO,uBAAoB;;;;EAWpC,aAAS;;;;EAOT,OAAO,OAAO,uBAAoB;;;;EAOlC,MAAM,OAAO,uBAAoB;;;;;;EASjC;;;;EAOA;;;;EAOA,QAAQ,wBAA6C,WAAU,QAAQ;;;;EAOvE,QAAQ,OAAO,uBAAoB"}
+{"version":3,"file":"precision-number.d.ts","names":[],"sources":["../../src/classes/precision-number.ts"],"mappings":";;;;;YAKY,uBAAuB,QAAQ,QAAQ;EAAoB;;;;;;;;;;;;;;;;;;;;;;;;qBAwB1D;;;;;;;;;EAgBL,YAAA,QAAO,sBACP,wBACA,WAAU,QAAQ;;;;MAqBlB;;;;MAOA,YAAQ,QAAA;;;;MAOR;;;;;;;;;;SAeG,QACH,OAAO,sBACP,wBACA,WAAU,QAAQ;;;;;;GAmBrB,OAAO,aAAa;;;;;;EAUrB;;;;;;;;;EAaA;;;;;;;;;;;EAeA,MAAM,KAAK,sBAAsB,KAAK;;;;EAWtC,SAAK;;;;;;;;EAWL,UAAU,OAAO;;;;;;;;EAYjB,OAAO,OAAO;;;;;;;;;EAYd;;;;EAQA,GAAG,OAAO;;;;EAOV,IAAI,OAAO;;;;EAOX;;;;EAOA;;;;EAOA;;;;EAOA;;;;EAOA;;;;EAOA;;;;EAOA,GAAG,OAAO;;;;EAOV,IAAI,OAAO;;;;EAOX,MAAM,OAAO;;;;;;;;EAYb,OAAO,OAAO;;;;EAQd;;;;EAQA,KAAK,OAAO;;;;;;;;EAYZ,IAAI,OAAO;;;;EAQX,MAAM,OAAO;;;;EAQb,mBAAe;;;;EAOf,UAAM;;;;;;;;;EAYN,UAAU,KAAK,sBAAsB,KAAK,uBAAoB;;;;EAO9D,YAAY,OAAO,uBAAoB;;;;EAWvC,WAAO;;;;EAOP;;;;EAOA,QAAQ,OAAO,uBAAoB;;;;EAWnC,SAAS,OAAO,uBAAoB;;;;EAWpC,aAAS;;;;EAOT,OAAO,OAAO,uBAAoB;;;;EAOlC,MAAM,OAAO,uBAAoB;;;;;;;EAUjC;;;;EAOA;;;;EAOA,QAAQ,wBAA6C,WAAU,QAAQ;;;;EAOvE,QAAQ,OAAO,uBAAoB"}