@kikiutils/shared 15.0.2 → 15.1.0

package/dist/types/index.d.ts

@@ -2,15 +2,45 @@ import { FilteredKeyPath } from "./filtered-key-path.js";
 import { Blob as Blob$1, Buffer, File as File$1 } from "node:buffer";
 
 //#region src/types/index.d.ts
+/**
+ * A generic string-keyed object for utility APIs that intentionally accept any value shape.
+ */
 type AnyRecord = Record<string, any>;
+/**
+ * Binary-like inputs accepted by `toBuffer` across browser and Node.js runtimes.
+ */
 type BinaryInput = ArrayBuffer | Blob | Buffer | File | Blob$1 | File$1 | Uint8Array;
+/**
+ * Boolean values represented either as booleans or common string literals.
+ */
 type Booleanish = 'false' | 'true' | boolean;
+/**
+ * Accepts either a full object or a partial patch of that object.
+ */
 type MaybePartial<T> = Partial<T> | T;
+/**
+ * Accepts either a mutable value or a readonly view of that value.
+ */
 type MaybeReadonly<T> = Readonly<T> | T;
+/**
+ * Explicitly nullable value helper.
+ */
 type Nullable<T> = null | T;
+/**
+ * Number-like value represented as a number or a numeric string.
+ */
 type Numberish = number | string;
+/**
+ * A `Record` where every key is optional.
+ */
 type PartialRecord<K extends keyof any, T> = Partial<Record<K, T>>;
+/**
+ * A readonly `PartialRecord`.
+ */
 type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialRecord<K, T>>;
+/**
+ * A readonly `Record`.
+ */
 type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;
 //#endregion
 export { AnyRecord, BinaryInput, Booleanish, type FilteredKeyPath, MaybePartial, MaybeReadonly, Nullable, Numberish, PartialRecord, ReadonlyPartialRecord, ReadonlyRecord };

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types/index.ts"],"mappings":";;;;KAQY,SAAA,GAAY,MAAA;AAAA,KACZ,WAAA,GAAc,WAAA,GAAc,IAAA,GAAO,MAAA,GAAS,IAAA,GAAO,MAAA,GAAW,MAAA,GAAW,UAAA;AAAA,KACzE,UAAA;AAAA,KACA,YAAA,MAAkB,OAAA,CAAQ,CAAA,IAAK,CAAA;AAAA,KAC/B,aAAA,MAAmB,QAAA,CAAS,CAAA,IAAK,CAAA;AAAA,KACjC,QAAA,aAAqB,CAAA;AAAA,KACrB,SAAA;AAAA,KACA,aAAA,2BAAwC,OAAA,CAAQ,MAAA,CAAO,CAAA,EAAG,CAAA;AAAA,KAC1D,qBAAA,2BAAgD,QAAA,CAAS,aAAA,CAAc,CAAA,EAAG,CAAA;AAAA,KAC1E,cAAA,2BAAyC,QAAA,CAAS,MAAA,CAAO,CAAA,EAAG,CAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types/index.ts"],"mappings":";;;;;;AAWA;KAAY,SAAA,GAAY,MAAA;;;;KAKZ,WAAA,GAAc,WAAA,GAAc,IAAA,GAAO,MAAA,GAAS,IAAA,GAAO,MAAA,GAAW,MAAA,GAAW,UAAA;;;;KAKzE,UAAA;;;;KAKA,YAAA,MAAkB,OAAA,CAAQ,CAAA,IAAK,CAAA;;;;KAK/B,aAAA,MAAmB,QAAA,CAAS,CAAA,IAAK,CAAA;;;;KAKjC,QAAA,aAAqB,CAAA;;;;KAKrB,SAAA;AApBZ;;;AAAA,KAyBY,aAAA,2BAAwC,OAAA,CAAQ,MAAA,CAAO,CAAA,EAAG,CAAA;;AApBtE;;KAyBY,qBAAA,2BAAgD,QAAA,CAAS,aAAA,CAAc,CAAA,EAAG,CAAA;;;;KAK1E,cAAA,2BAAyC,QAAA,CAAS,MAAA,CAAO,CAAA,EAAG,CAAA"}

package/dist/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param {string} url - The target URL to modify\n * @param {string} redirectPath - The path to use as the redirect destination\n * (must be an absolute path starting with '/')\n *\n * @returns {string} A new URL string with the `redirect` query parameter\n *\n * @throws {Error} If redirectPath is not a valid relative path (must start with '/')\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    if (!redirectPath.startsWith('/')) {\n        throw new Error(\n            `Invalid redirect path: \"${redirectPath}\". Redirect paths must be absolute paths starting with '/'.`,\n        );\n    }\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;AACxE,KAAI,CAAC,aAAa,WAAW,IAAI,CAC7B,OAAM,IAAI,MACN,2BAA2B,aAAa,6DAC3C;CAGL,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,IAAI;CACnD,MAAM,CAAC,MAAM,SAAS,eAAe,IAAI,MAAM,IAAI;CACnD,MAAM,eAAe,IAAI,gBAAgB,SAAS;AAClD,cAAa,IAAI,YAAY,aAAa;CAC1C,MAAM,cAAc,aAAa,UAAU;AAC3C,QAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG"}
+{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param {string} url - The target URL to modify\n * @param {string} redirectPath - The path to use as the redirect destination\n * (must be an absolute path starting with '/')\n *\n * @returns {string} A new URL string with the `redirect` query parameter\n *\n * @throws {Error} If redirectPath is not a valid relative path (must start with '/')\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    if (!redirectPath.startsWith('/')) {\n        throw new Error(\n            `Invalid redirect path: \"${redirectPath}\". Redirect paths must be absolute paths starting with '/'.`,\n        );\n    }\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;CACxE,IAAI,CAAC,aAAa,WAAW,IAAI,EAC7B,MAAM,IAAI,MACN,2BAA2B,aAAa,6DAC3C;CAGL,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,IAAI;CACnD,MAAM,CAAC,MAAM,SAAS,eAAe,IAAI,MAAM,IAAI;CACnD,MAAM,eAAe,IAAI,gBAAgB,SAAS;CAClD,aAAa,IAAI,YAAY,aAAa;CAC1C,MAAM,cAAc,aAAa,UAAU;CAC3C,OAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG"}

package/dist/vue.js.map

@@ -1 +1 @@
-{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport type { Nullable } from './types';\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setInterval>>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearIntervalRef(intervalRef: Ref<Nullable<ReturnType<typeof setInterval>>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setTimeout>>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setTimeout>>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * Designed for use with `<KeepAlive>` components. Scroll state is saved on\n * route leave and restored when the component is activated again.\n *\n * Note: Without `<KeepAlive>`, the component state is destroyed on unmount,\n * so scroll position will not be preserved.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement)\n *\n * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<Nullable<T>>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAgB,yCAAyC,KAAa;AAClE,QAAO,yBAAyB,KAAK,UAAU,CAAC,SAAS;;;;;;;AAQ7D,SAAgB,iBAAiB,aAA4D;AACzF,KAAI,YAAY,MAAO,eAAc,YAAY,MAAM;AACvD,aAAY,QAAQ;;;;;;;AAQxB,SAAgB,gBAAgB,YAA0D;AACtF,KAAI,WAAW,MAAO,cAAa,WAAW,MAAM;AACpD,YAAW,QAAQ;;;;;;;;;;;;;;;;AAiBvB,SAAgB,kBAAmD,cAAgC;CAC/F,IAAI,aAAa;CACjB,IAAI,YAAY;AAChB,mBAAkB;AACd,MAAI,CAAC,aAAa,MAAO;AACzB,eAAa,MAAM,aAAa;AAChC,eAAa,MAAM,YAAY;GACjC;AAEF,0BAAyB;AACrB,eAAa,aAAa,OAAO,cAAc;AAC/C,cAAY,aAAa,OAAO,aAAa;GAC/C"}
+{"version":3,"file":"vue.js","names":[],"sources":["../src/vue.ts"],"sourcesContent":["import { onActivated } from 'vue';\nimport type { Ref } from 'vue';\nimport {\n    onBeforeRouteLeave,\n    useRoute,\n} from 'vue-router';\n\nimport type { Nullable } from './types';\nimport { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current Vue Router route's fullPath as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current route fullPath as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentRouteToUrl(url: string) {\n    return appendRedirectParamToUrl(url, useRoute().fullPath);\n}\n\n/**\n * Clears an interval referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setInterval>>>} intervalRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearIntervalRef(intervalRef: Ref<Nullable<ReturnType<typeof setInterval>>>) {\n    if (intervalRef.value) clearInterval(intervalRef.value);\n    intervalRef.value = null;\n}\n\n/**\n * Clears a timeout referenced by a Vue ref and sets it to null.\n *\n * @param {Ref<Nullable<ReturnType<typeof setTimeout>>>} timeoutRef - A Vue ref holding a NodeJS.Timeout or null\n */\nexport function clearTimeoutRef(timeoutRef: Ref<Nullable<ReturnType<typeof setTimeout>>>) {\n    if (timeoutRef.value) clearTimeout(timeoutRef.value);\n    timeoutRef.value = null;\n}\n\n/**\n * A Vue composition function that remembers and restores scroll position\n * of a scrollable container across route changes and keep-alive activation.\n *\n * Designed for use with `<KeepAlive>` components. Scroll state is saved on\n * route leave and restored when the component is activated again.\n *\n * Note: Without `<KeepAlive>`, the component state is destroyed on unmount,\n * so scroll position will not be preserved.\n *\n * @template T - The type of the scrollable element (defaults to HTMLElement)\n *\n * @param {Ref<Nullable<T>>} containerRef - A ref to the scrollable HTML element\n */\nexport function usePreserveScroll<T extends Element = HTMLElement>(containerRef: Ref<Nullable<T>>) {\n    let scrollLeft = 0;\n    let scrollTop = 0;\n    onActivated(() => {\n        if (!containerRef.value) return;\n        containerRef.value.scrollLeft = scrollLeft;\n        containerRef.value.scrollTop = scrollTop;\n    });\n\n    onBeforeRouteLeave(() => {\n        scrollLeft = containerRef.value?.scrollLeft || 0;\n        scrollTop = containerRef.value?.scrollTop || 0;\n    });\n}\n"],"mappings":";;;;;;;;;;;AAiBA,SAAgB,yCAAyC,KAAa;CAClE,OAAO,yBAAyB,KAAK,UAAU,CAAC,SAAS;;;;;;;AAQ7D,SAAgB,iBAAiB,aAA4D;CACzF,IAAI,YAAY,OAAO,cAAc,YAAY,MAAM;CACvD,YAAY,QAAQ;;;;;;;AAQxB,SAAgB,gBAAgB,YAA0D;CACtF,IAAI,WAAW,OAAO,aAAa,WAAW,MAAM;CACpD,WAAW,QAAQ;;;;;;;;;;;;;;;;AAiBvB,SAAgB,kBAAmD,cAAgC;CAC/F,IAAI,aAAa;CACjB,IAAI,YAAY;CAChB,kBAAkB;EACd,IAAI,CAAC,aAAa,OAAO;EACzB,aAAa,MAAM,aAAa;EAChC,aAAa,MAAM,YAAY;GACjC;CAEF,yBAAyB;EACrB,aAAa,aAAa,OAAO,cAAc;EAC/C,YAAY,aAAa,OAAO,aAAa;GAC/C"}

package/dist/web.js.map

@@ -1 +1 @@
-{"version":3,"file":"web.js","names":[],"sources":["../src/web.ts"],"sourcesContent":["import { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current location as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentLocationToUrl(url: string) {\n    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;\n    return appendRedirectParamToUrl(url, currentPath);\n}\n\n/**\n * Navigates to the given URL, appending the current browser location\n * (path, query, and hash) as the `redirect` query parameter.\n *\n * Useful for redirecting to login or other gateways while preserving\n * the current location for post-auth navigation.\n *\n * @param {string} url - The destination URL to navigate to\n * @param {number} [delayMs] - Optional delay in milliseconds before navigation\n */\nexport function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number) {\n    if (delayMs === undefined) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));\n    else return setTimeout(() => window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url)), delayMs);\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,4CAA4C,KAAa;AAErE,QAAO,yBAAyB,KADZ,GAAG,OAAO,SAAS,WAAW,OAAO,SAAS,SAAS,OAAO,SAAS,OAC1C;;;;;;;;;;;;AAarD,SAAgB,8CAA8C,KAAa,SAAkB;AACzF,KAAI,YAAY,KAAA,EAAW,QAAO,SAAS,OAAO,4CAA4C,IAAI,CAAC;KAC9F,QAAO,iBAAiB,OAAO,SAAS,OAAO,4CAA4C,IAAI,CAAC,EAAE,QAAQ"}
+{"version":3,"file":"web.js","names":[],"sources":["../src/web.ts"],"sourcesContent":["import { appendRedirectParamToUrl } from './url';\n\n/**\n * Appends the current browser URL (including path, query, and hash) as the `redirect` query parameter to the given URL.\n *\n * @param {string} url - The base URL to modify\n *\n * @returns {string} A new URL with the current location as the `redirect` parameter\n */\nexport function appendRedirectParamFromCurrentLocationToUrl(url: string) {\n    const currentPath = `${window.location.pathname}${window.location.search}${window.location.hash}`;\n    return appendRedirectParamToUrl(url, currentPath);\n}\n\n/**\n * Navigates to the given URL, appending the current browser location\n * (path, query, and hash) as the `redirect` query parameter.\n *\n * Useful for redirecting to login or other gateways while preserving\n * the current location for post-auth navigation.\n *\n * @param {string} url - The destination URL to navigate to\n * @param {number} [delayMs] - Optional delay in milliseconds before navigation\n */\nexport function assignUrlWithRedirectParamFromCurrentLocation(url: string, delayMs?: number) {\n    if (delayMs === undefined) window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url));\n    else return setTimeout(() => window.location.assign(appendRedirectParamFromCurrentLocationToUrl(url)), delayMs);\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,4CAA4C,KAAa;CAErE,OAAO,yBAAyB,KAAK,GADd,OAAO,SAAS,WAAW,OAAO,SAAS,SAAS,OAAO,SAAS,OAC1C;;;;;;;;;;;;AAarD,SAAgB,8CAA8C,KAAa,SAAkB;CACzF,IAAI,YAAY,KAAA,GAAW,OAAO,SAAS,OAAO,4CAA4C,IAAI,CAAC;MAC9F,OAAO,iBAAiB,OAAO,SAAS,OAAO,4CAA4C,IAAI,CAAC,EAAE,QAAQ"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "15.0.2",
+  "version": "15.1.0",
   "description": "A lightweight and modular utility library for modern JavaScript and TypeScript — includes secure hashing, flexible logging, datetime tools, Vue/web helpers, storage abstraction, and more.",
   "author": "kiki-kanri",
   "license": "MIT",
@@ -77,7 +77,7 @@
     "element-plus": "^2.13.7",
     "lru-cache": "^11.3.5",
     "millify": "^6.1.0",
-    "msgpackr": "^1.11.9",
+    "msgpackr": "^2.0.1",
     "node-ssh": "^13.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
@@ -136,12 +136,12 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^8.2.0",
-    "@kikiutils/eslint-config": "^9.0.1",
+    "@kikiutils/eslint-config": "^9.1.2",
     "@kikiutils/tsconfigs": "^6.0.0",
     "@noble/hashes": "^2.2.0",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.6.2",
     "@types/ssh2": "^1.15.5",
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.5",
     "async-validator": "^4.2.5",
     "bson": "^7.2.0",
     "changelogen": "^0.6.2",
@@ -149,30 +149,21 @@
     "cross-env": "^10.1.0",
     "date-fns": "^4.1.0",
     "decimal.js": "^10.6.0",
-    "element-plus": "^2.13.7",
-    "jsdom": "^29.0.2",
-    "knip": "^6.5.0",
-    "lru-cache": "^11.3.5",
+    "element-plus": "^2.14.0",
+    "jsdom": "^29.1.1",
+    "knip": "^6.12.2",
+    "lru-cache": "^11.3.6",
     "millify": "^6.1.0",
-    "msgpackr": "^1.11.10",
+    "msgpackr": "^2.0.1",
     "node-ssh": "^13.2.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "publint": "^0.3.18",
-    "tsdown": "^0.21.9",
+    "publint": "^0.3.20",
+    "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
     "unplugin-unused": "^0.5.7",
-    "vitest": "^4.1.4",
-    "vue": "^3.5.32",
-    "vue-router": "^5.0.4"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "cpu-features",
-      "esbuild",
-      "msgpackr-extract",
-      "ssh2",
-      "vue-demi"
-    ]
+    "vitest": "^4.1.5",
+    "vue": "^3.5.34",
+    "vue-router": "^5.0.6"
   }
 }

package/src/classes/path.ts

@@ -18,6 +18,10 @@ import {
 import type * as nodePath from 'node:path';
 
 type DropFirstParameters<T extends (...args: any) => any> = Parameters<T> extends [any, ...infer R] ? R : never;
+
+/**
+ * Values accepted by the `Path` constructor and path-composition methods.
+ */
 export type PathLike = fs.PathLike | Path;
 
 /**
@@ -29,6 +33,11 @@ export type PathLike = fs.PathLike | Path;
 export class Path {
     readonly #value: string;
 
+    /**
+     * 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
+     */
     constructor(...paths: PathLike[]) {
         this.#value = join(...this.#toStrings(paths));
     }

package/src/classes/precision-number.ts

@@ -1,22 +1,28 @@
 import { Decimal } from 'decimal.js';
 
+/**
+ * Values accepted by `PrecisionNumber` constructors and arithmetic methods.
+ */
 export type PrecisionNumberValue = Decimal.Value | PrecisionNumber | { toString: () => string };
 
 /**
- * Class representing a precision number with configurable decimal places and rounding.
+ * Chainable fixed-decimal wrapper around `decimal.js`.
  *
- * 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.).
+ * `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.
  *
- * The class also includes custom symbol methods to support Node.js inspection and primitive
- * type conversion.
+ * @example
+ * ```typescript
+ * import { PrecisionNumber } from '@kikiutils/shared/classes/precision-number';
  *
- * 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.
+ * 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')
+ * ```
  */
 export class PrecisionNumber {
     // Private properties
@@ -24,6 +30,13 @@ export class PrecisionNumber {
     readonly #rounding: Decimal.Rounding;
     #decimal: Decimal;
 
+    /**
+     * 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`)
+     */
     constructor(
         value: PrecisionNumberValue = '0',
         decimalPlaces: number = 2,
@@ -35,10 +48,19 @@ export class PrecisionNumber {
     }
 
     // Symbols
+
+    /**
+     * Returns the formatted value when inspected by Node.js utilities.
+     */
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.value;
     }
 
+    /**
+     * Converts to a number for numeric coercion and to the fixed string otherwise.
+     *
+     * @param {string} hint - JavaScript primitive-conversion hint
+     */
     [Symbol.toPrimitive](hint: string) {
         if (hint === 'number') return this.#decimal.toNumber();
         return this.value;
@@ -49,12 +71,42 @@ export class PrecisionNumber {
         return decimal.toDecimalPlaces(this.#decimalPlaces, this.#rounding);
     }
 
+    #valueToString(value: PrecisionNumberValue) {
+        return value.toString().trim();
+    }
+
     // Public getters
+
+    /**
+     * Decimal places retained by mutating operations and default formatting.
+     */
+    get decimalPlaces() {
+        return this.#decimalPlaces;
+    }
+
+    /**
+     * Decimal.js rounding mode used by mutating operations and default formatting.
+     */
+    get rounding() {
+        return this.#rounding;
+    }
+
+    /**
+     * Fixed-decimal string using the instance precision and rounding mode.
+     */
     get value() {
         return this.#decimal.toFixed(this.#decimalPlaces, this.#rounding);
     }
 
-    // Static methods
+    /**
+     * 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`)
+     *
+     * @returns {string} Fixed-decimal string
+     */
     static toFixed(
         value: PrecisionNumberValue,
         decimalPlaces: number = 2,
@@ -64,117 +116,340 @@ export class PrecisionNumber {
     }
 
     // Public methods
+
+    /**
+     * Replaces the current value with its absolute value.
+     *
+     * @returns {this} The current instance for chaining
+     */
     absoluteValue() {
         this.#decimal = this.#decimalToFixedDecimal(this.#decimal.absoluteValue());
         return this;
     }
 
+    /**
+     * Rounds the current value up to the nearest integer in place.
+     *
+     * The stored value still uses this instance's configured decimal places for output.
+     *
+     * @returns {this} The current instance for chaining
+     */
+    ceil() {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.ceil());
+        return this;
+    }
+
+    /**
+     * Restricts the current value to the inclusive range `[min, max]` in place.
+     *
+     * @param {PrecisionNumberValue} min - Lower bound
+     * @param {PrecisionNumberValue} max - Upper bound
+     *
+     * @returns {this} The current instance for chaining
+     *
+     * @throws {Error} If `min` is greater than `max`
+     */
+    clamp(min: PrecisionNumberValue, max: PrecisionNumberValue) {
+        const minDecimal = new Decimal(this.#valueToString(min));
+        const maxDecimal = new Decimal(this.#valueToString(max));
+        if (minDecimal.gt(maxDecimal)) throw new Error('Invalid clamp range: min cannot be greater than max');
+        this.#decimal = this.#decimalToFixedDecimal(Decimal.min(Decimal.max(this.#decimal, minDecimal), maxDecimal));
+        return this;
+    }
+
+    /**
+     * Returns a new instance with the same value, decimal places, and rounding mode.
+     */
+    clone() {
+        return new PrecisionNumber(this.#decimal, this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Divides the current value by another value in place.
+     *
+     * @param {PrecisionNumberValue} value - Divisor
+     *
+     * @returns {this} The current instance for chaining
+     */
     dividedBy(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.dividedBy(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.dividedBy(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Checks whether the current value equals another value.
+     *
+     * @param {PrecisionNumberValue} value - Value to compare
+     *
+     * @returns {boolean} `true` when both numeric values are equal
+     */
     equals(value: PrecisionNumberValue) {
-        return this.#decimal.equals(value.toString().trim());
+        return this.#decimal.equals(this.#valueToString(value));
+    }
+
+    /**
+     * Rounds the current value down to the nearest integer in place.
+     *
+     * The stored value still uses this instance's configured decimal places for output.
+     *
+     * @returns {this} The current instance for chaining
+     */
+    floor() {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.floor());
+        return this;
     }
 
+    /**
+     * Checks whether the current value is greater than another value.
+     */
     gt(value: PrecisionNumberValue) {
-        return this.#decimal.gt(value.toString().trim());
+        return this.#decimal.gt(this.#valueToString(value));
     }
 
+    /**
+     * Checks whether the current value is greater than or equal to another value.
+     */
     gte(value: PrecisionNumberValue) {
-        return this.#decimal.gte(value.toString().trim());
+        return this.#decimal.gte(this.#valueToString(value));
     }
 
+    /**
+     * Checks whether the current value is finite.
+     */
     isFinite() {
         return this.#decimal.isFinite();
     }
 
+    /**
+     * Checks whether the current value is an integer.
+     */
     isInteger() {
         return this.#decimal.isInteger();
     }
 
+    /**
+     * Checks whether the current value is `NaN`.
+     */
     isNaN() {
         return this.#decimal.isNaN();
     }
 
+    /**
+     * Checks whether the current value is negative.
+     */
     isNegative() {
         return this.#decimal.isNegative();
     }
 
+    /**
+     * Checks whether the current value is positive.
+     */
     isPositive() {
         return this.#decimal.isPositive();
     }
 
+    /**
+     * Checks whether the current value is zero.
+     */
     isZero() {
         return this.#decimal.isZero();
     }
 
+    /**
+     * Checks whether the current value is less than another value.
+     */
     lt(value: PrecisionNumberValue) {
-        return this.#decimal.lt(value.toString().trim());
+        return this.#decimal.lt(this.#valueToString(value));
     }
 
+    /**
+     * Checks whether the current value is less than or equal to another value.
+     */
     lte(value: PrecisionNumberValue) {
-        return this.#decimal.lte(value.toString().trim());
+        return this.#decimal.lte(this.#valueToString(value));
     }
 
+    /**
+     * Subtracts another value from the current value in place.
+     */
     minus(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.minus(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.minus(this.#valueToString(value)));
+        return this;
+    }
+
+    /**
+     * Replaces the current value with the remainder after division by another value.
+     *
+     * @param {PrecisionNumberValue} value - Divisor used to compute the remainder
+     *
+     * @returns {this} The current instance for chaining
+     */
+    modulo(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.modulo(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Negates the current value in place.
+     */
     negate() {
         this.#decimal = this.#decimalToFixedDecimal(this.#decimal.negated());
         return this;
     }
 
+    /**
+     * Adds another value to the current value in place.
+     */
     plus(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.plus(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.plus(this.#valueToString(value)));
+        return this;
+    }
+
+    /**
+     * Raises the current value to an exponent in place.
+     *
+     * @param {PrecisionNumberValue} value - Exponent
+     *
+     * @returns {this} The current instance for chaining
+     */
+    pow(value: PrecisionNumberValue) {
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.pow(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Multiplies the current value by another value in place.
+     */
     times(value: PrecisionNumberValue) {
-        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.times(value.toString().trim()));
+        this.#decimal = this.#decimalToFixedDecimal(this.#decimal.times(this.#valueToString(value)));
         return this;
     }
 
+    /**
+     * Returns a new instance with the absolute value.
+     */
     toAbsoluteValue() {
         return new PrecisionNumber(this.#decimal.absoluteValue(), this.#decimalPlaces, this.#rounding);
     }
 
+    /**
+     * Returns a new instance rounded up to the nearest integer.
+     */
+    toCeil() {
+        return new PrecisionNumber(this.#decimal.ceil(), this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Returns a new instance restricted to the inclusive range `[min, max]`.
+     *
+     * @param {PrecisionNumberValue} min - Lower bound
+     * @param {PrecisionNumberValue} max - Upper bound
+     *
+     * @throws {Error} If `min` is greater than `max`
+     */
+    toClamped(min: PrecisionNumberValue, max: PrecisionNumberValue) {
+        return this.clone().clamp(min, max);
+    }
+
+    /**
+     * Returns a new instance divided by another value.
+     */
     toDividedBy(value: PrecisionNumberValue) {
         return new PrecisionNumber(
-            this.#decimal.dividedBy(value.toString().trim()),
+            this.#decimal.dividedBy(this.#valueToString(value)),
             this.#decimalPlaces,
             this.#rounding,
         );
     }
 
+    /**
+     * Returns a new instance rounded down to the nearest integer.
+     */
+    toFloor() {
+        return new PrecisionNumber(this.#decimal.floor(), this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Serializes to the fixed-decimal string.
+     */
     toJSON() {
         return this.value;
     }
 
+    /**
+     * Returns a new instance with another value subtracted.
+     */
     toMinus(value: PrecisionNumberValue) {
-        return new PrecisionNumber(this.#decimal.minus(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+        return new PrecisionNumber(
+            this.#decimal.minus(this.#valueToString(value)),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
     }
 
+    /**
+     * Returns a new instance with the remainder after division by another value.
+     */
+    toModulo(value: PrecisionNumberValue) {
+        return new PrecisionNumber(
+            this.#decimal.modulo(this.#valueToString(value)),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
+    }
+
+    /**
+     * Returns a new instance with the value negated.
+     */
     toNegated() {
         return new PrecisionNumber(this.#decimal.negated(), this.#decimalPlaces, this.#rounding);
     }
 
+    /**
+     * Returns a new instance with another value added.
+     */
     toPlus(value: PrecisionNumberValue) {
-        return new PrecisionNumber(this.#decimal.plus(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+        return new PrecisionNumber(this.#decimal.plus(this.#valueToString(value)), this.#decimalPlaces, this.#rounding);
+    }
+
+    /**
+     * Returns a new instance raised to an exponent.
+     */
+    toPow(value: PrecisionNumberValue) {
+        return new PrecisionNumber(this.#decimal.pow(this.#valueToString(value)), this.#decimalPlaces, this.#rounding);
     }
 
+    /**
+     * Converts the current value to a JavaScript number.
+     *
+     * Use `toString`/`value` when preserving decimal precision is more important than native-number ergonomics.
+     */
+    toNumber() {
+        return this.#decimal.toNumber();
+    }
+
+    /**
+     * Converts the current value to its fixed-decimal string.
+     */
     toString() {
         return this.value;
     }
 
+    /**
+     * Formats the current value with custom precision and rounding for this call only.
+     */
     toFixed(decimalPlaces: number = this.#decimalPlaces, rounding: Decimal.Rounding = this.#rounding) {
         return this.#decimal.toFixed(decimalPlaces, rounding);
     }
 
+    /**
+     * Returns a new instance multiplied by another value.
+     */
     toTimes(value: PrecisionNumberValue) {
-        return new PrecisionNumber(this.#decimal.times(value.toString().trim()), this.#decimalPlaces, this.#rounding);
+        return new PrecisionNumber(
+            this.#decimal.times(this.#valueToString(value)),
+            this.#decimalPlaces,
+            this.#rounding,
+        );
     }
 }