@kikiutils/shared 15.0.3 → 15.1.1

package/README.md

@@ -5,30 +5,34 @@
 [![codecov][codecov-src]][codecov-href]
 [![License][license-src]][license-href]
 
-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.
+A lightweight, modular TypeScript utility library for Node.js and browser projects. It groups small, focused helpers for binary conversion, hashing, logging, dates, enum extraction, environment variables, numeric formatting, strings, URLs, Vue, web redirects, and typed storage wrappers.
 
 - [✨ Release Notes](./CHANGELOG.md)
 
 ## Features
 
-- 📋 Clipboard utilities — copy text and blobs using the modern Clipboard API (Browser only)
-- 📜 Logging utilities — simple and extensible logging via Consola and Pino
-- 🔒 Crypto utilities — secure hashing functions: MD5, SHA3-224/256/384/512
-- 📅 Datetime utilities — manipulate, format, and offset dates and ranges
-- 🔢 Enum utilities — extract enum keys and values (number or string)
-- 🌱 Environment helpers — safe env var access with error handling (Node only)
-- 📈 Math utilities — rounding, formatting percentages, and ratios
-- 💎 Number utilities — number padding, compact display, currency formatting
-- 🔤 String utilities — casing, trimming, random string generation, etc.
-- 🌐 URL utilities — parse and construct query strings and redirect URLs
-- 🧩 Vue 3 utilities — composables like scroll preservation and key handling
-- 🖥️ Web utilities — browser DOM helpers (e.g. scroll to top, key matching)
-- 🗄️ Storage utilities — enhanced localStorage, Redis, and LRU abstractions
-- 📦 Modular by design — import only what you need via `@kikiutils/shared/<module>`
+- 📦 Modular imports — import only the modules you use via `@kikiutils/shared/<module>`.
+- 🧱 TypeScript-first — ships source and declaration output for strongly typed utility APIs.
+- 🔁 General helpers — normalize single-or-array values with `extractFirstValue`.
+- 🧬 Binary helpers — convert `Blob`, `File`, `ArrayBuffer`, `Uint8Array`, and `Buffer` to Node `Buffer`.
+- 🔒 Hashing helpers — SHA-3 helpers for universal usage and Node `crypto` MD5/SHA-3 helpers.
+- 📜 Logging helpers — preconfigured Consola and Pino logger instances with env-based levels.
+- 📅 Date helpers — format dates and compute common ranges such as today, this week, and last month.
+- 🔢 Number and math helpers — compact number display, precise percentages, and fixed-decimal arithmetic.
+- 🔤 String/random helpers — random strings and randomized-length value generation.
+- 🧾 Object helpers — deterministic nested object serialization for signatures and cache keys.
+- 🧭 URL helpers — append or replace redirect query parameters safely.
+- 🌱 Environment helpers — read required environment variables with a dedicated missing-env error.
+- 🧩 Vue/web helpers — Vue Router redirects, timer ref cleanup, scroll preservation, and browser redirects.
+- 🗄️ Storage helpers — typed keyed-store facades for LRU cache and Redis-like storage.
+- 🛤️ Class utilities — immutable `Path` wrapper and chainable `PrecisionNumber` arithmetic.
+- 🧰 Shared types — reusable nullable, readonly, partial-record, binary-input, and filtered-key-path types.
 
 ## Requirements
 
 - **Node.js** `>=22.12.0`
+- **ESM** package (`"type": "module"`)
+- Optional peer dependencies are installed only when you use the modules that need them.
 
 ## Installation
 
@@ -38,70 +42,136 @@ Using [pnpm](https://pnpm.io):
 pnpm add @kikiutils/shared
 ```
 
-You can also use `yarn`, `npm`, or `bun`.
+You can also use `npm`, `yarn`, or `bun`.
 
 > [!NOTE]
-> This package is modular. It does not install all dependencies by default.
->
-> If a utility depends on a third-party package (e.g. `date-fns`), you must install it manually.
+> This package is intentionally modular. Imports such as `@kikiutils/shared/datetime` or `@kikiutils/shared/vue` may require their peer dependencies (`date-fns`, `vue`, and so on). Install only the peers used by your chosen modules.
 
-## Modules
+## Usage and import style
 
-```
-src/
-├── classes/           # Class-based utilities
-│   ├── path.ts        # Path manipulation
-│   ├── precision-number.ts # Decimal.js wrapper
-│   └── ssh-client.ts  # SSH client
-│
-├── storages/
-│   ├── lru/keyed-store.ts    # LRU cache wrapper
-│   └── redis/
-│       ├── keyed-store.ts     # Redis keyed store
-│       ├── msgpack.ts         # Redis + msgpack
-│       └── types.ts           # Storage interfaces
-│
-└── *.ts              # Utility functions (see table)
-```
-
-| File | Description |
-|------|-------------|
-| `buffer.ts` | Binary → Node.js Buffer |
-| `clipboard.ts` | Clipboard API (browser) |
-| `consola.ts` | Consola logger |
-| `crypto-hash.ts` | MD5, SHA3 (Node) |
-| `datetime.ts` | date-fns wrappers |
-| `element-plus.ts` | Element Plus form rules |
-| `enum.ts` | Enum value extractors |
-| `env.ts` | Env var accessor |
-| `event-awaiter.ts` | Async event wait |
-| `general.ts` | extractFirstValue |
-| `hash.ts` | SHA3 (browser) |
-| `math.ts` | toPercentageString |
-| `number.ts` | toCompactNumberString |
-| `object.ts` | deterministic stringify |
-| `pino.ts` | Pino logger |
-| `random.ts` | nested random length |
-| `string.ts` | randomString |
-| `time.ts` | abortableDelay |
-| `url.ts` | redirect param |
-| `vue.ts` | Vue composables |
-| `web.ts` | Web DOM helpers |
-
-## Usage
+Import individual modules to keep dependency usage explicit:
 
 ```typescript
 import { logger } from '@kikiutils/shared/consola';
 import { extractFirstValue } from '@kikiutils/shared/general';
 
-const data = [
+const value = extractFirstValue([
     0,
     1,
-];
+]);
+
+logger.info(value); // 0
+```
+
+## Module guide
+
+| Module | Runtime | Main exports | Use case |
+| --- | --- | --- | --- |
+| `buffer` | Node/browser-compatible inputs, Node output | `toBuffer` | Convert `Blob`, `File`, `ArrayBuffer`, `Uint8Array`, or `Buffer` to Node `Buffer`. |
+| `clipboard` | Browser | `copyTextToClipboard`, `copyBlobToClipboard` | Safe result wrappers around the modern Clipboard API. |
+| `consola` | Node/browser | `consolaLogger`, `logger` | Shared Consola instance with env-based log level. |
+| `crypto-hash` | Node | `cryptoMd5`, `cryptoSha3*`, `*ToBuffer` | Node `crypto` MD5/SHA-3 helpers with text or raw-buffer output. |
+| `datetime` | Node/browser | `formatDate`, `getDateRangeFromDate`, `getMidnightDateFromToday` | Date formatting and common date-range calculations via `date-fns`. |
+| `element-plus` | Vue/browser | `createElFormItemRuleWithDefaults` | Create Element Plus form rules with default `required`, `trigger`, and `type`. |
+| `enum` | Any | `getEnumValues`, `getEnumNumberValues`, `getEnumStringValues` | Extract TypeScript enum values while ignoring numeric reverse mappings. |
+| `env` | Node | `checkAndGetEnvValue`, `EnvironmentNotFoundError` | Read required env vars without treating empty strings as missing. |
+| `event-awaiter` | Any | `EventAwaiter` | Wait/trigger keyed asynchronous events with timeout, abort, strict, and override modes. |
+| `general` | Any | `extractFirstValue` | Normalize a single value or array into the first resolved value. |
+| `hash` | Any | `sha3224`, `sha3256`, `sha3384`, `sha3512` | SHA-3 helpers backed by `@noble/hashes`; returns hex strings. |
+| `math` | Any | `toPercentageString` | Precise percentage strings using `decimal.js`. |
+| `number` | Any | `toCompactNumberString` | Compact display strings using `millify`. |
+| `object` | Any | `stringifyObjectDeterministically` | Stable flattened object serialization for signatures/cache keys. |
+| `pino` | Node | `pinoLogger`, `logger` | Shared Pino logger with pretty output and env-based level. |
+| `random` | Any | `generateWithNestedRandomLength` | Generate values with a two-step randomized length. |
+| `string` | Any | `randomString` | Random strings from preset character sets. |
+| `time` | Any | `abortableDelay` | Promise delay that resolves early on abort. |
+| `url` | Any | `appendRedirectParamToUrl` | Add or replace a `redirect` query parameter. |
+| `vue` | Vue/browser | `appendRedirectParamFromCurrentRouteToUrl`, `clearIntervalRef`, `clearTimeoutRef`, `usePreserveScroll` | Vue Router redirect and ref cleanup helpers. |
+| `web` | Browser | `appendRedirectParamFromCurrentLocationToUrl`, `assignUrlWithRedirectParamFromCurrentLocation` | Browser redirect helpers based on `window.location`. |
+| `classes/path` | Node | `Path` | Immutable path wrapper plus common `fs/promises` delegations. |
+| `classes/precision-number` | Any | `PrecisionNumber` | Chainable fixed-decimal arithmetic powered by `decimal.js`. |
+| `storages/lru/keyed-store` | Any | `createLruKeyedStore` | Typed key resolver wrapper around `lru-cache`. |
+| `storages/redis/keyed-store` | Node | `createRedisKeyedStore` | Typed key resolver wrapper around Redis-like storage. |
+| `storages/redis/msgpack` | Node | `createRedisMsgpackStorage` | Redis-like storage facade with MessagePack serialization. |
+| `types` | TypeScript | Common utility types | Shared utility and path-filtering types. |
+
+## Examples
+
+### Required environment variable
+
+```typescript
+import { checkAndGetEnvValue } from '@kikiutils/shared/env';
+
+const apiKey = checkAndGetEnvValue('API_KEY');
+```
+
+### Date ranges
+
+```typescript
+import { getDateRangeFromDate } from '@kikiutils/shared/datetime';
+
+const range = getDateRangeFromDate(new Date(), 'thisWeek', { weekStartsOn: 1 });
+console.log(range.startDate, range.endDate);
+```
+
+### Precise numeric display
+
+```typescript
+import { PrecisionNumber } from '@kikiutils/shared/classes/precision-number';
+import { toPercentageString } from '@kikiutils/shared/math';
 
-const value = extractFirstValue(data);
-console.log(value); // 0
-logger.info(value);
+const amount = new PrecisionNumber('1.239', 2).plus('2.111');
+console.log(amount.toString()); // 3.35
+console.log(toPercentageString(1, 3, { decimalPlaces: 2 })); // 33.33%
+```
+
+### Browser redirect preservation
+
+```typescript
+import { appendRedirectParamToUrl } from '@kikiutils/shared/url';
+
+const loginUrl = appendRedirectParamToUrl('/login', '/dashboard?tab=home');
+// /login?redirect=%2Fdashboard%3Ftab%3Dhome
+```
+
+### LRU keyed store
+
+```typescript
+import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';
+import { LRUCache } from 'lru-cache';
+
+const cache = new LRUCache<string, { name: string }>({ max: 100 });
+const users = createLruKeyedStore<{ name: string }>(cache)((id: string) => `user:${id}`);
+
+users.setItem({ name: 'Alice' }, '1');
+console.log(users.getItem('1')); // { name: 'Alice' }
+```
+
+## Optional peer dependencies
+
+Most modules are tiny wrappers around platform APIs or optional peers. If your package manager does not auto-install peers, add the ones you import:
+
+| Module | Peer dependency |
+| --- | --- |
+| `crypto-hash` / `hash` | `@noble/hashes` for `hash`; Node `crypto` for `crypto-hash` |
+| `datetime` | `date-fns` |
+| `element-plus` | `async-validator`, `element-plus` |
+| `classes/precision-number`, `math` | `decimal.js` |
+| `number` | `millify` |
+| `consola` | `consola` |
+| `pino` | `pino`, `pino-pretty` |
+| `storages/lru/keyed-store` | `lru-cache` |
+| `storages/redis/msgpack` | `msgpackr` |
+| `vue` | `vue`, `vue-router` |
+
+## Development
+
+```bash
+pnpm install
+pnpm run lint
+pnpm run typecheck
+pnpm test
+pnpm run build
 ```
 
 ## License

package/dist/buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buffer.d.ts","names":[],"sources":["../src/buffer.ts"],"mappings":";;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAsB,QAAA,CAAS,KAAA,EAAO,WAAA,GAAW,OAAA,CAAA,MAAA,CAAA,eAAA"}
+{"version":3,"file":"buffer.d.ts","names":[],"sources":["../src/buffer.ts"],"mappings":";;;;;;AAkCA;;;;;;;;;;;;;;;AAAiD;;;;;;;;;;;;;iBAA3B,QAAA,CAAS,KAAA,EAAO,WAAA,GAAW,OAAA,CAAA,MAAA,CAAA,eAAA"}

package/dist/buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"buffer.js","names":[],"sources":["../src/buffer.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\n\nimport type { BinaryInput } from './types';\n\n/**\n * Converts various binary data types to a Node.js Buffer.\n *\n * This function provides a unified, efficient way to convert different binary formats\n * (Blob, Buffer, File, ArrayBuffer, or Uint8Array) into a Node.js Buffer.\n * It prioritizes zero-copy conversions for TypedArrays and ArrayBuffers to ensure\n * optimal performance.\n *\n * @param {ArrayBuffer | Blob | Buffer | File | Uint8Array} input - The binary data input to convert.\n * Supports Blob, Buffer, File, ArrayBuffer, and Uint8Array.\n *\n * @returns {Promise<Buffer>} A promise that resolves to a Node.js Buffer.\n *\n * @example\n * ```typescript\n * import { toBuffer } from '@kikiutils/shared/buffer';\n *\n * // From ArrayBuffer\n * const ab = new ArrayBuffer(8);\n * const bufferFromAB = await toBuffer(ab);\n *\n * // From Uint8Array (Zero-copy)\n * const u8 = new Uint8Array([10, 20, 30]);\n * const bufferFromU8 = await toBuffer(u8);\n *\n * // From Blob or File\n * const blob = new Blob(['data'], { type: 'text/plain' });\n * const bufferFromBlob = await toBuffer(blob);\n * ```\n */\nexport async function toBuffer(input: BinaryInput) {\n    if (Buffer.isBuffer(input)) return input;\n    if (input instanceof ArrayBuffer) return Buffer.from(input);\n    if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength);\n    if (typeof input.arrayBuffer === 'function') return Buffer.from(await input.arrayBuffer());\n    // eslint-disable-next-line style/max-len\n    throw new TypeError('The provided input is not a supported binary type (Blob, Buffer, File, ArrayBuffer, or Uint8Array).');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,eAAsB,SAAS,OAAoB;AAC/C,KAAI,OAAO,SAAS,MAAM,CAAE,QAAO;AACnC,KAAI,iBAAiB,YAAa,QAAO,OAAO,KAAK,MAAM;AAC3D,KAAI,iBAAiB,WAAY,QAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,WAAW;AACrG,KAAI,OAAO,MAAM,gBAAgB,WAAY,QAAO,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAE1F,OAAM,IAAI,UAAU,sGAAsG"}
+{"version":3,"file":"buffer.js","names":[],"sources":["../src/buffer.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\n\nimport type { BinaryInput } from './types';\n\n/**\n * Converts various binary data types to a Node.js Buffer.\n *\n * This function provides a unified, efficient way to convert different binary formats\n * (Blob, Buffer, File, ArrayBuffer, or Uint8Array) into a Node.js Buffer.\n * It prioritizes zero-copy conversions for TypedArrays and ArrayBuffers to ensure\n * optimal performance.\n *\n * @param {ArrayBuffer | Blob | Buffer | File | Uint8Array} input - The binary data input to convert.\n * Supports Blob, Buffer, File, ArrayBuffer, and Uint8Array.\n *\n * @returns {Promise<Buffer>} A promise that resolves to a Node.js Buffer.\n *\n * @example\n * ```typescript\n * import { toBuffer } from '@kikiutils/shared/buffer';\n *\n * // From ArrayBuffer\n * const ab = new ArrayBuffer(8);\n * const bufferFromAB = await toBuffer(ab);\n *\n * // From Uint8Array (Zero-copy)\n * const u8 = new Uint8Array([10, 20, 30]);\n * const bufferFromU8 = await toBuffer(u8);\n *\n * // From Blob or File\n * const blob = new Blob(['data'], { type: 'text/plain' });\n * const bufferFromBlob = await toBuffer(blob);\n * ```\n */\nexport async function toBuffer(input: BinaryInput) {\n    if (Buffer.isBuffer(input)) return input;\n    if (input instanceof ArrayBuffer) return Buffer.from(input);\n    if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength);\n    if (typeof input.arrayBuffer === 'function') return Buffer.from(await input.arrayBuffer());\n    // eslint-disable-next-line style/max-len\n    throw new TypeError('The provided input is not a supported binary type (Blob, Buffer, File, ArrayBuffer, or Uint8Array).');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,eAAsB,SAAS,OAAoB;CAC/C,IAAI,OAAO,SAAS,KAAK,GAAG,OAAO;CACnC,IAAI,iBAAiB,aAAa,OAAO,OAAO,KAAK,KAAK;CAC1D,IAAI,iBAAiB,YAAY,OAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,UAAU;CACpG,IAAI,OAAO,MAAM,gBAAgB,YAAY,OAAO,OAAO,KAAK,MAAM,MAAM,YAAY,CAAC;CAEzF,MAAM,IAAI,UAAU,qGAAqG;AAC7H"}

package/dist/classes/path.d.ts

@@ -6,6 +6,9 @@ import * as fs from "node:fs";
 
 //#region src/classes/path.d.ts
 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.
+ */
 type PathLike = fs.PathLike | Path;
 /**
  * Class representing a file system path with various utility methods for path operations.
@@ -15,6 +18,11 @@ type PathLike = fs.PathLike | Path;
  */
 declare class Path {
   #private;
+  /**
+   * Creates a normalized path value by joining the provided path segments.
+   *
+   * @param {PathLike[]} paths - Path segments accepted by Node.js `path.join` or another `Path` instance
+   */
   constructor(...paths: PathLike[]);
   [Symbol.toPrimitive](hint: string): string;
   /**

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

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","names":[],"sources":["../../src/classes/path.ts"],"mappings":";;;;;;;KAmBK,mBAAA,eAAkC,IAAA,iBAAqB,UAAA,CAAW,CAAA,8BAA+B,CAAA;AAAA,KAC1F,QAAA,GAAW,EAAA,CAAG,QAAA,GAAW,IAAA;AAHM;;;;;;AAAA,cAW9B,IAAA;EAAA;iBAGM,KAAA,EAAO,QAAA;EAAA,CASrB,MAAA,CAAO,WAAA,EAAa,IAAA;EArB8E;;AACvG;EADuG,IAwC/F,MAAA,CAAA,GAAM,IAAA;;;;MAON,KAAA,CAAA;EA9C6B;;;EAAA,OAuD1B,MAAA,CAAO,UAAA,EAAY,QAAA,CAAS,qBAAA,GAAqB,IAAA;EA/C3C;;;EAAA,OAsDN,OAAA,CAAA,GAAW,KAAA,EAAO,QAAA,KAAU,IAAA;EAvBzB;;;EAgCV,QAAA,CAAS,MAAA;EAT0B;;;EAgBnC,OAAA,CAAA,GAAO,IAAA;EA4BkB;;;EArBzB,OAAA,CAAA;EA0CO;;;EAnCP,UAAA,CAAA;EAuE+C;;;EAhE/C,SAAA,CAAA,GAAS,IAAA;EAuEM;;;EAhEf,IAAA,CAAA,GAAQ,KAAA,EAAO,QAAA,KAAU,IAAA;EAuE2B;;;EAhEpD,KAAA,CAAA,GAAK,QAAA,CAAA,UAAA;EA+EQ;;;EAxEb,QAAA,CAAS,EAAA,EAAI,QAAA,GAAQ,IAAA;EAmFlB;;;EA5EH,OAAA,CAAA,GAAO,IAAA;EAIP,MAAA,CAAA;EAiFc;;;EA1Ed,gBAAA,CAAA;EAoFQ;;;;;EA3ER,QAAA,CAAA;EA6FU;;;EApFV,MAAA,CAAA,GAAU,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,MAAA,IAAO,OAAA;EA4FnD;;;EArFH,UAAA,CAAA,GAAc,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,UAAA,IAAW,OAAA;EA4F3D;;;EArFH,KAAA,CAAA,GAAS,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,KAAA,IAAM,OAAA;EA6FjD;;;EAtFH,KAAA,CAAA,GAAS,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,KAAA,IAAM,OAAA;EAqGjD;;;EA9FH,QAAA,CAAA,GAAY,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,QAAA,IAAS,OAAA;EAqGlD;;;EA9FR,KAAA,CACI,OAAA,EAAS,EAAA,CAAG,oBAAA;IACR,SAAA;EAAA,IAEL,OAAA;EACH,KAAA,CACI,OAAA,IACK,EAAA,CAAG,oBAAA;IACF,SAAA;EAAA,KAEF,EAAA,CAAG,IAAA,UAER,OAAA;EACH,KAAA,CAAM,OAAA,GAAU,EAAA,CAAG,oBAAA,GAAuB,EAAA,CAAG,IAAA,UAAc,OAAA;EA2GpB;;;EAnGvC,IAAA,CAAA,GAAQ,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,IAAA,IAAK,OAAA,CAAA,EAAA,CAAA,QAAA,CAAA,UAAA;EA0GnC;;;EAnGf,OAAA,CACI,IAAA,EAAM,QAAA,EACN,OAAA,GACI,cAAA,IACC,EAAA,CAAG,qBAAA;IACF,SAAA;IACA,aAAA;EAAA,YAGP,OAAA;EACH,OAAA,CACI,IAAA,EAAM,QAAA,EACN,OAAA;IAGM,QAAA;IACA,SAAA;IACA,aAAA;EAAA,IAEP,OAAA,CAAQ,MAAA;EACX,OAAA,CACI,IAAA,EAAM,QAAA,EACN,OAAA,GACI,cAAA,IACC,EAAA,CAAG,qBAAA;IACF,SAAA;IACA,aAAA;EAAA,YAGP,OAAA,CAAQ,MAAA;EACX,OAAA,CACI,IAAA,EAAM,QAAA,EACN,OAAA,EAAS,EAAA,CAAG,qBAAA;IACR,SAAA;IACA,aAAA;EAAA,IAEL,OAAA,CAAQ,EAAA,CAAG,MAAA;EACd,OAAA,CACI,IAAA,EAAM,QAAA,EACN,OAAA;IACI,QAAA;IACA,SAAA;IACA,aAAA;EAAA,IAEL,OAAA,CAAQ,EAAA,CAAG,MAAA,CAAO,MAAA;EAnPpB;;;EA2PD,QAAA,CACI,OAAA,IACK,SAAA;IACC,QAAA;IACA,IAAA,GAAO,EAAA,CAAG,QAAA;EAAA,YAGjB,OAAA,CAAQ,MAAA;EACX,QAAA,CACI,OAAA,GACK,SAAA;IACC,QAAA,EAAU,cAAA;IACV,IAAA,GAAO,EAAA,CAAG,QAAA;EAAA,KAEZ,cAAA,GACL,OAAA;EACH,QAAA,CACI,OAAA,IAEQ,SAAA,GACA,EAAA,CAAG,qBAAA;IACD,IAAA,GAAO,EAAA,CAAG,QAAA;EAAA,KAEd,cAAA,UAEP,OAAA,CAAQ,MAAA;EA1OwB;;;EAkPnC,MAAA,CAAO,OAAA,EAAS,QAAA,GAAQ,OAAA;EAlOjB;;;EAyOP,EAAA,CAAA,GAAM,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,EAAA,IAAG,OAAA;EApNrC;;;EA2NT,KAAA,CAAA,GAAS,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,KAAA,IAAM,OAAA;EApN3B;;;EA2NzB,IAAA,CACI,IAAA,GAAO,EAAA,CAAG,WAAA;IACN,MAAA;EAAA,IAEL,OAAA,CAAQ,EAAA,CAAG,KAAA;EACd,IAAA,CACI,IAAA,EAAM,EAAA,CAAG,WAAA;IACL,MAAA;EAAA,IAEL,OAAA,CAAQ,EAAA,CAAG,WAAA;EACd,IAAA,CAAK,IAAA,GAAO,EAAA,CAAG,WAAA,GAAc,OAAA,CAAQ,EAAA,CAAG,WAAA,GAAc,EAAA,CAAG,KAAA;EA5MzD;;;EAoNA,QAAA,CAAA,GAAY,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,QAAA,IAAS,OAAA;EA3LhD;;;EAkMV,MAAA,CAAA,GAAM,OAAA;EAlMgD;;;EAyMtD,SAAA,CAAA,GAAa,IAAA,EAAM,mBAAA,QAA2B,GAAA,CAAI,SAAA,IAAU,OAAA;AAAA"}
+{"version":3,"file":"path.d.ts","names":[],"sources":["../../src/classes/path.ts"],"mappings":"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"}

package/dist/classes/path.js

@@ -9,6 +9,11 @@ import { basename, dirname, extname, format, isAbsolute, join, normalize, parse,
 */
 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
+	*/
 	constructor(...paths) {
 		this.#value = join(...this.#toStrings(paths));
 	}

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;\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"],"mappings":"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"}
+{"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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"}

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

@@ -1,56 +1,260 @@
 import { Decimal } from "decimal.js";
 
 //#region src/classes/precision-number.d.ts
+/**
+ * Values accepted by `PrecisionNumber` constructors and arithmetic methods.
+ */
 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')
+ * ```
  */
 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`)
+   */
   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.
+   */
+  get decimalPlaces(): number;
+  /**
+   * Decimal.js rounding mode used by mutating operations and default formatting.
+   */
+  get rounding(): Decimal.Rounding;
+  /**
+   * Fixed-decimal string using the instance precision and rounding mode.
+   */
   get value(): string;
+  /**
+   * 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, rounding?: Decimal.Rounding): string;
+  /**
+   * Replaces the current value with its absolute value.
+   *
+   * @returns {this} The current instance for chaining
+   */
   absoluteValue(): 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;
+  /**
+   * 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): this;
+  /**
+   * Returns a new instance with the same value, decimal places, and rounding mode.
+   */
+  clone(): PrecisionNumber;
+  /**
+   * Divides the current value by another value in place.
+   *
+   * @param {PrecisionNumberValue} value - Divisor
+   *
+   * @returns {this} The current instance for chaining
+   */
   dividedBy(value: PrecisionNumberValue): 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): boolean;
+  /**
+   * 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;
+  /**
+   * Checks whether the current value is greater than another value.
+   */
   gt(value: PrecisionNumberValue): boolean;
+  /**
+   * Checks whether the current value is greater than or equal to another value.
+   */
   gte(value: PrecisionNumberValue): boolean;
+  /**
+   * Checks whether the current value is finite.
+   */
   isFinite(): boolean;
+  /**
+   * Checks whether the current value is an integer.
+   */
   isInteger(): boolean;
+  /**
+   * Checks whether the current value is `NaN`.
+   */
   isNaN(): boolean;
+  /**
+   * Checks whether the current value is negative.
+   */
   isNegative(): boolean;
+  /**
+   * Checks whether the current value is positive.
+   */
   isPositive(): boolean;
+  /**
+   * Checks whether the current value is zero.
+   */
   isZero(): boolean;
+  /**
+   * Checks whether the current value is less than another value.
+   */
   lt(value: PrecisionNumberValue): boolean;
+  /**
+   * Checks whether the current value is less than or equal to another value.
+   */
   lte(value: PrecisionNumberValue): boolean;
+  /**
+   * Subtracts another value from the current value in place.
+   */
   minus(value: PrecisionNumberValue): 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;
+  /**
+   * Negates the current value in place.
+   */
   negate(): this;
+  /**
+   * Adds another value to the current value in place.
+   */
   plus(value: PrecisionNumberValue): 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;
+  /**
+   * Multiplies the current value by another value in place.
+   */
   times(value: PrecisionNumberValue): this;
+  /**
+   * Returns a new instance with the absolute value.
+   */
   toAbsoluteValue(): PrecisionNumber;
+  /**
+   * Returns a new instance rounded up to the nearest integer.
+   */
+  toCeil(): PrecisionNumber;
+  /**
+   * 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): PrecisionNumber;
+  /**
+   * Returns a new instance divided by another value.
+   */
   toDividedBy(value: PrecisionNumberValue): PrecisionNumber;
+  /**
+   * Returns a new instance rounded down to the nearest integer.
+   */
+  toFloor(): PrecisionNumber;
+  /**
+   * Serializes to the fixed-decimal string.
+   */
   toJSON(): string;
+  /**
+   * Returns a new instance with another value subtracted.
+   */
   toMinus(value: PrecisionNumberValue): PrecisionNumber;
+  /**
+   * Returns a new instance with the remainder after division by another value.
+   */
+  toModulo(value: PrecisionNumberValue): PrecisionNumber;
+  /**
+   * Returns a new instance with the value negated.
+   */
   toNegated(): PrecisionNumber;
+  /**
+   * Returns a new instance with another value added.
+   */
   toPlus(value: PrecisionNumberValue): PrecisionNumber;
+  /**
+   * Returns a new instance raised to an exponent.
+   */
+  toPow(value: PrecisionNumberValue): PrecisionNumber;
+  /**
+   * Converts the current value to a JavaScript number.
+   *
+   * Use `toString`/`value` when preserving decimal precision is more important than native-number ergonomics.
+   */
+  toNumber(): number;
+  /**
+   * Converts the current value to its fixed-decimal string.
+   */
   toString(): string;
+  /**
+   * Formats the current value with custom precision and rounding for this call only.
+   */
   toFixed(decimalPlaces?: number, rounding?: Decimal.Rounding): string;
+  /**
+   * Returns a new instance multiplied by another value.
+   */
   toTimes(value: PrecisionNumberValue): PrecisionNumber;
 }
 //#endregion