@helpers4/number 2.0.0 → 2.0.2

package/README.md

@@ -13,6 +13,7 @@ A set of helpers for working with URLs.
 
 <!-- AUTOMATIC-METHODS -->
 - clamp
+- correctFloat
 - formatCompact
 - formatSize
 - inRange
@@ -33,6 +34,7 @@ A set of helpers for working with URLs.
 - [function](../function)
 - [id](../id)
 - [markdown](../markdown)
+- [node](../node)
 - [object](../object)
 - [observable](../observable)
 - [promise](../promise)
@@ -54,6 +56,7 @@ A set of helpers for working with URLs.
 | function | [@helpers4/function](https://www.npmjs.com/package/@helpers4/function) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/function) | Function utilities and type guards |
 | id | [@helpers4/id](https://www.npmjs.com/package/@helpers4/id) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/id) | Unique identifier generation utilities |
 | markdown | [@helpers4/markdown](https://www.npmjs.com/package/@helpers4/markdown) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/markdown) | Markdown formatting and escaping utilities |
+| node | [@helpers4/node](https://www.npmjs.com/package/@helpers4/node) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/node) | Node.js-specific utilities |
 | number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | Number utility functions and validation |
 | object | [@helpers4/object](https://www.npmjs.com/package/@helpers4/object) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/object) | Object manipulation utilities |
 | observable | [@helpers4/observable](https://www.npmjs.com/package/@helpers4/observable) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/observable) | Observable utilities and combinators |

package/lib/index.d.ts

@@ -13,6 +13,30 @@
  */
 declare function clamp(value: number, min: number, max: number): number;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Corrects floating-point arithmetic errors by rounding to a given number
+ * of significant digits. Useful after calculations that accumulate binary
+ * floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).
+ *
+ * The default precision of 14 significant digits eliminates typical
+ * rounding noise for values in the range used by most applications.
+ * Note: for values whose integer part already consumes 14 or more digits
+ * (i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal
+ * digits and will silently truncate them. Increase `precision` if you
+ * need to correct drift in very large numbers.
+ *
+ * @param value - The floating-point value to correct
+ * @param precision - Integer number of significant digits (default: 14)
+ * @returns The corrected value
+ * @since 2.0.2
+ */
+declare function correctFloat(value: number, precision?: number): number;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -193,5 +217,5 @@ declare function roundTo(value: number, decimals: number): number;
  */
 declare function sum(array: readonly number[]): number;
 
-export { clamp, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, correctFloat, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
 export type { InRangeOptions };

package/lib/index.js

@@ -16,6 +16,36 @@ function clamp(value, min, max) {
 	return Math.min(Math.max(value, min), max);
 }
 //#endregion
+//#region helpers/number/correctFloat.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Corrects floating-point arithmetic errors by rounding to a given number
+* of significant digits. Useful after calculations that accumulate binary
+* floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).
+*
+* The default precision of 14 significant digits eliminates typical
+* rounding noise for values in the range used by most applications.
+* Note: for values whose integer part already consumes 14 or more digits
+* (i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal
+* digits and will silently truncate them. Increase `precision` if you
+* need to correct drift in very large numbers.
+*
+* @param value - The floating-point value to correct
+* @param precision - Integer number of significant digits (default: 14)
+* @returns The corrected value
+* @since 2.0.2
+*/
+function correctFloat(value, precision = 14) {
+	if (!Number.isFinite(value)) throw new RangeError(`correctFloat: value must be a finite number, got ${value}`);
+	if (!Number.isInteger(precision) || precision < 1 || precision > 100) throw new RangeError(`correctFloat: precision must be an integer between 1 and 100, got ${precision}`);
+	const result = parseFloat(value.toPrecision(precision));
+	return Object.is(value, -0) && result === 0 ? -0 : result;
+}
+//#endregion
 //#region helpers/number/formatCompact.ts
 /**
 * This file is part of helpers4.
@@ -224,6 +254,6 @@ function sum(array) {
 	return array.reduce((acc, n) => acc + n, 0);
 }
 //#endregion
-export { clamp, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, correctFloat, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
 
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/formatCompact.ts","../../../helpers/number/formatSize.ts","../../../helpers/number/inRange.ts","../../../helpers/number/lerp.ts","../../../helpers/number/mean.ts","../../../helpers/number/random.ts","../../../helpers/number/roundTo.ts","../../../helpers/number/sum.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Clamps a number between min and max values\n * @param value - The value to clamp\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Clamped value\n * @since 1.9.0\n */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Formats a number using compact notation (e.g. `1_500_000 → \"1.5M\"`).\n *\n * Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion\n * of `formatSize` in the same `format*` family.\n *\n * @param value - The number to format.\n * @param locale - BCP 47 locale tag. Defaults to the runtime locale.\n * @returns A compact string representation of the number.\n * @example\n * formatCompact(1_500_000);        // '1.5M'  (en-US locale)\n * formatCompact(1_000);            // '1K'\n * formatCompact(999);              // '999'\n * formatCompact(1_500_000, 'fr'); // '1,5 M'\n * @since 2.0.0\n */\nexport function formatCompact(value: number, locale?: string): string {\n  return new Intl.NumberFormat(locale, { notation: 'compact' }).format(value);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/** Size units in ascending order. */\nconst UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;\n\n/**\n * Format a byte count into a human-readable string with the appropriate unit.\n *\n * Each unit is 1024 of the previous (binary prefix). The result is formatted\n * with one decimal place.\n *\n * @param bytes - A non-negative integer representing a byte count.\n * @returns A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.\n * @example\n * formatSize(0)               // '0.0B'\n * formatSize(512)             // '512.0B'\n * formatSize(1024)            // '1.0KB'\n * formatSize(1536)            // '1.5KB'\n * formatSize(1_048_576)       // '1.0MB'\n * formatSize(1_073_741_824)   // '1.0GB'\n * @since 2.0.0\n */\nexport function formatSize(bytes: number): string {\n  let size = bytes;\n  let unitIndex = 0;\n\n  while (size >= 1024 && unitIndex < UNITS.length - 1) {\n    size /= 1024;\n    unitIndex++;\n  }\n\n  return `${size.toFixed(1)}${UNITS[unitIndex]}`;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Options for {@link inRange}.\n */\nexport interface InRangeOptions {\n  /**\n   * Which boundary (or boundaries) are included in the range.\n   * - `'both'` (default): `min <= value <= max`\n   * - `'min'`: `min <= value < max`\n   * - `'max'`: `min < value <= max`\n   * - `'none'`: `min < value < max`\n   */\n  inclusive?: 'both' | 'min' | 'max' | 'none';\n}\n\n/**\n * Checks whether a number falls within `[min, max]` (both inclusive by default).\n *\n * @param value - The number to test\n * @param min - Lower bound\n * @param max - Upper bound\n * @param options - Boundary inclusion mode (default: `'both'`)\n * @returns `true` if `value` is within the specified range\n * @example\n * inRange(5, 1, 10)          // => true\n * inRange(1, 1, 10)          // => true  (min inclusive)\n * inRange(1, 1, 10, { inclusive: 'none' })  // => false\n * inRange(10, 1, 10, { inclusive: 'max' })  // => true\n * @since 2.0.0\n */\nexport function inRange(value: number, min: number, max: number, options: InRangeOptions = {}): boolean {\n  const { inclusive = 'both' } = options;\n  const minOk = inclusive === 'both' || inclusive === 'min' ? value >= min : value > min;\n  const maxOk = inclusive === 'both' || inclusive === 'max' ? value <= max : value < max;\n  return minOk && maxOk;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Linearly interpolates between `start` and `end` by the factor `t`.\n *\n * - `t = 0` returns `start`.\n * - `t = 1` returns `end`.\n * - Values of `t` outside `[0, 1]` extrapolate beyond the range.\n *\n * @param start - The start value.\n * @param end - The end value.\n * @param t - The interpolation factor.\n * @returns The interpolated value.\n * @example\n * lerp(0, 100, 0);    // 0\n * lerp(0, 100, 1);    // 100\n * lerp(0, 100, 0.5);  // 50\n * lerp(0, 100, 0.25); // 25\n * @since 2.0.0\n */\nexport function lerp(start: number, end: number, t: number): number {\n  if (t === 0) return start;\n  if (t === 1) return end;\n  if (Object.is(start, end)) return start;\n  return start + (end - start) * t;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the arithmetic mean (average) of an array of numbers.\n * Returns `NaN` for an empty array.\n *\n * Pairs with {@link sum} for aggregate operations.\n *\n * @param array - The array of numbers to average\n * @returns The arithmetic mean, or `NaN` if the array is empty\n * @example\n * mean([1, 2, 3, 4])  // => 2.5\n * mean([10])          // => 10\n * mean([])            // => NaN\n * @since 2.0.0\n */\nexport function mean(array: readonly number[]): number {\n  if (array.length === 0) return NaN;\n  return array.reduce((acc, n) => acc + n, 0) / array.length;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Generates a random number between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random number between min and max\n * @since 1.9.0\n */\nexport function randomBetween(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generates a random integer between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random integer between min and max\n * @since 1.9.0\n */\nexport function randomIntBetween(min: number, max: number): number {\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Rounds a number to specified decimal places\n * @param value - The number to round\n * @param decimals - Number of decimal places\n * @returns Rounded number\n * @since 1.9.0\n */\nexport function roundTo(value: number, decimals: number): number {\n  const multiplier = Math.pow(10, decimals);\n  return Math.round(value * multiplier) / multiplier;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the sum of an array of numbers.\n * @param array - The array of numbers to sum\n * @returns The sum of all values\n * @example\n * sum([1, 2, 3, 4])\n * // => 10\n * @since 2.0.0\n */\nexport function sum(array: readonly number[]): number {\n  return array.reduce((acc, n) => acc + n, 0);\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,MAAM,OAAe,KAAa,KAAqB;CACrE,OAAO,KAAK,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,GAAG;AAC3C;;;;;;;;;;;;;;;;;;;;;;;;ACMA,SAAgB,cAAc,OAAe,QAAyB;CACpE,OAAO,IAAI,KAAK,aAAa,QAAQ,EAAE,UAAU,UAAU,CAAC,EAAE,OAAO,KAAK;AAC5E;;;;;;;;;ACjBA,IAAM,QAAQ;CAAC;CAAK;CAAM;CAAM;CAAM;AAAI;;;;;;;;;;;;;;;;;;AAmB1C,SAAgB,WAAW,OAAuB;CAChD,IAAI,OAAO;CACX,IAAI,YAAY;CAEhB,OAAO,QAAQ,QAAQ,YAAY,MAAM,SAAS,GAAG;EACnD,QAAQ;EACR;CACF;CAEA,OAAO,GAAG,KAAK,QAAQ,CAAC,IAAI,MAAM;AACpC;;;;;;;;;;;;;;;;;;ACDA,SAAgB,QAAQ,OAAe,KAAa,KAAa,UAA0B,CAAC,GAAY;CACtG,MAAM,EAAE,YAAY,WAAW;CAG/B,QAFc,cAAc,UAAU,cAAc,QAAQ,SAAS,MAAM,QAAQ,SACrE,cAAc,UAAU,cAAc,QAAQ,SAAS,MAAM,QAAQ;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;AChBA,SAAgB,KAAK,OAAe,KAAa,GAAmB;CAClE,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,OAAO,GAAG,OAAO,GAAG,GAAG,OAAO;CAClC,OAAO,SAAS,MAAM,SAAS;AACjC;;;;;;;;;;;;;;;;;;;;;;ACTA,SAAgB,KAAK,OAAkC;CACrD,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,OAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC,IAAI,MAAM;AACtD;;;;;;;;;;;;;;;ACVA,SAAgB,cAAc,KAAa,KAAqB;CAC9D,OAAO,KAAK,OAAO,KAAK,MAAM,OAAO;AACvC;;;;;;;;AASA,SAAgB,iBAAiB,KAAa,KAAqB;CACjE,OAAO,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE,IAAI;AACvD;;;;;;;;;;;;;;;ACbA,SAAgB,QAAQ,OAAe,UAA0B;CAC/D,MAAM,aAAa,KAAK,IAAI,IAAI,QAAQ;CACxC,OAAO,KAAK,MAAM,QAAQ,UAAU,IAAI;AAC1C;;;;;;;;;;;;;;;;;ACDA,SAAgB,IAAI,OAAkC;CACpD,OAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC;AAC5C"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/correctFloat.ts","../../../helpers/number/formatCompact.ts","../../../helpers/number/formatSize.ts","../../../helpers/number/inRange.ts","../../../helpers/number/lerp.ts","../../../helpers/number/mean.ts","../../../helpers/number/random.ts","../../../helpers/number/roundTo.ts","../../../helpers/number/sum.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Clamps a number between min and max values\n * @param value - The value to clamp\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Clamped value\n * @since 1.9.0\n */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Corrects floating-point arithmetic errors by rounding to a given number\n * of significant digits. Useful after calculations that accumulate binary\n * floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n *\n * The default precision of 14 significant digits eliminates typical\n * rounding noise for values in the range used by most applications.\n * Note: for values whose integer part already consumes 14 or more digits\n * (i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\n * digits and will silently truncate them. Increase `precision` if you\n * need to correct drift in very large numbers.\n *\n * @param value - The floating-point value to correct\n * @param precision - Integer number of significant digits (default: 14)\n * @returns The corrected value\n * @since 2.0.2\n */\nexport function correctFloat(value: number, precision: number = 14): number {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`correctFloat: value must be a finite number, got ${value}`);\n  }\n  if (!Number.isInteger(precision) || precision < 1 || precision > 100) {\n    throw new RangeError(`correctFloat: precision must be an integer between 1 and 100, got ${precision}`);\n  }\n  const result = parseFloat(value.toPrecision(precision));\n  // toPrecision(-0) produces \"0.000…\" (no minus sign per spec) — restore the sign bit.\n  return Object.is(value, -0) && result === 0 ? -0 : result;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Formats a number using compact notation (e.g. `1_500_000 → \"1.5M\"`).\n *\n * Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion\n * of `formatSize` in the same `format*` family.\n *\n * @param value - The number to format.\n * @param locale - BCP 47 locale tag. Defaults to the runtime locale.\n * @returns A compact string representation of the number.\n * @example\n * formatCompact(1_500_000);        // '1.5M'  (en-US locale)\n * formatCompact(1_000);            // '1K'\n * formatCompact(999);              // '999'\n * formatCompact(1_500_000, 'fr'); // '1,5 M'\n * @since 2.0.0\n */\nexport function formatCompact(value: number, locale?: string): string {\n  return new Intl.NumberFormat(locale, { notation: 'compact' }).format(value);\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/** Size units in ascending order. */\nconst UNITS = ['B', 'KB', 'MB', 'GB', 'TB'] as const;\n\n/**\n * Format a byte count into a human-readable string with the appropriate unit.\n *\n * Each unit is 1024 of the previous (binary prefix). The result is formatted\n * with one decimal place.\n *\n * @param bytes - A non-negative integer representing a byte count.\n * @returns A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.\n * @example\n * formatSize(0)               // '0.0B'\n * formatSize(512)             // '512.0B'\n * formatSize(1024)            // '1.0KB'\n * formatSize(1536)            // '1.5KB'\n * formatSize(1_048_576)       // '1.0MB'\n * formatSize(1_073_741_824)   // '1.0GB'\n * @since 2.0.0\n */\nexport function formatSize(bytes: number): string {\n  let size = bytes;\n  let unitIndex = 0;\n\n  while (size >= 1024 && unitIndex < UNITS.length - 1) {\n    size /= 1024;\n    unitIndex++;\n  }\n\n  return `${size.toFixed(1)}${UNITS[unitIndex]}`;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Options for {@link inRange}.\n */\nexport interface InRangeOptions {\n  /**\n   * Which boundary (or boundaries) are included in the range.\n   * - `'both'` (default): `min <= value <= max`\n   * - `'min'`: `min <= value < max`\n   * - `'max'`: `min < value <= max`\n   * - `'none'`: `min < value < max`\n   */\n  inclusive?: 'both' | 'min' | 'max' | 'none';\n}\n\n/**\n * Checks whether a number falls within `[min, max]` (both inclusive by default).\n *\n * @param value - The number to test\n * @param min - Lower bound\n * @param max - Upper bound\n * @param options - Boundary inclusion mode (default: `'both'`)\n * @returns `true` if `value` is within the specified range\n * @example\n * inRange(5, 1, 10)          // => true\n * inRange(1, 1, 10)          // => true  (min inclusive)\n * inRange(1, 1, 10, { inclusive: 'none' })  // => false\n * inRange(10, 1, 10, { inclusive: 'max' })  // => true\n * @since 2.0.0\n */\nexport function inRange(value: number, min: number, max: number, options: InRangeOptions = {}): boolean {\n  const { inclusive = 'both' } = options;\n  const minOk = inclusive === 'both' || inclusive === 'min' ? value >= min : value > min;\n  const maxOk = inclusive === 'both' || inclusive === 'max' ? value <= max : value < max;\n  return minOk && maxOk;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Linearly interpolates between `start` and `end` by the factor `t`.\n *\n * - `t = 0` returns `start`.\n * - `t = 1` returns `end`.\n * - Values of `t` outside `[0, 1]` extrapolate beyond the range.\n *\n * @param start - The start value.\n * @param end - The end value.\n * @param t - The interpolation factor.\n * @returns The interpolated value.\n * @example\n * lerp(0, 100, 0);    // 0\n * lerp(0, 100, 1);    // 100\n * lerp(0, 100, 0.5);  // 50\n * lerp(0, 100, 0.25); // 25\n * @since 2.0.0\n */\nexport function lerp(start: number, end: number, t: number): number {\n  if (t === 0) return start;\n  if (t === 1) return end;\n  if (Object.is(start, end)) return start;\n  return start + (end - start) * t;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the arithmetic mean (average) of an array of numbers.\n * Returns `NaN` for an empty array.\n *\n * Pairs with {@link sum} for aggregate operations.\n *\n * @param array - The array of numbers to average\n * @returns The arithmetic mean, or `NaN` if the array is empty\n * @example\n * mean([1, 2, 3, 4])  // => 2.5\n * mean([10])          // => 10\n * mean([])            // => NaN\n * @since 2.0.0\n */\nexport function mean(array: readonly number[]): number {\n  if (array.length === 0) return NaN;\n  return array.reduce((acc, n) => acc + n, 0) / array.length;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Generates a random number between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random number between min and max\n * @since 1.9.0\n */\nexport function randomBetween(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generates a random integer between min and max (inclusive)\n * @param min - Minimum value\n * @param max - Maximum value\n * @returns Random integer between min and max\n * @since 1.9.0\n */\nexport function randomIntBetween(min: number, max: number): number {\n  return Math.floor(Math.random() * (max - min + 1)) + min;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Rounds a number to specified decimal places\n * @param value - The number to round\n * @param decimals - Number of decimal places\n * @returns Rounded number\n * @since 1.9.0\n */\nexport function roundTo(value: number, decimals: number): number {\n  const multiplier = Math.pow(10, decimals);\n  return Math.round(value * multiplier) / multiplier;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Calculates the sum of an array of numbers.\n * @param array - The array of numbers to sum\n * @returns The sum of all values\n * @example\n * sum([1, 2, 3, 4])\n * // => 10\n * @since 2.0.0\n */\nexport function sum(array: readonly number[]): number {\n  return array.reduce((acc, n) => acc + n, 0);\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,MAAM,OAAe,KAAa,KAAqB;CACrE,OAAO,KAAK,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,GAAG;AAC3C;;;;;;;;;;;;;;;;;;;;;;;;;ACOA,SAAgB,aAAa,OAAe,YAAoB,IAAY;CAC1E,IAAI,CAAC,OAAO,SAAS,KAAK,GACxB,MAAM,IAAI,WAAW,oDAAoD,OAAO;CAElF,IAAI,CAAC,OAAO,UAAU,SAAS,KAAK,YAAY,KAAK,YAAY,KAC/D,MAAM,IAAI,WAAW,qEAAqE,WAAW;CAEvG,MAAM,SAAS,WAAW,MAAM,YAAY,SAAS,CAAC;CAEtD,OAAO,OAAO,GAAG,OAAO,EAAE,KAAK,WAAW,IAAI,KAAK;AACrD;;;;;;;;;;;;;;;;;;;;;;;;ACXA,SAAgB,cAAc,OAAe,QAAyB;CACpE,OAAO,IAAI,KAAK,aAAa,QAAQ,EAAE,UAAU,UAAU,CAAC,EAAE,OAAO,KAAK;AAC5E;;;;;;;;;ACjBA,IAAM,QAAQ;CAAC;CAAK;CAAM;CAAM;CAAM;AAAI;;;;;;;;;;;;;;;;;;AAmB1C,SAAgB,WAAW,OAAuB;CAChD,IAAI,OAAO;CACX,IAAI,YAAY;CAEhB,OAAO,QAAQ,QAAQ,YAAY,MAAM,SAAS,GAAG;EACnD,QAAQ;EACR;CACF;CAEA,OAAO,GAAG,KAAK,QAAQ,CAAC,IAAI,MAAM;AACpC;;;;;;;;;;;;;;;;;;ACDA,SAAgB,QAAQ,OAAe,KAAa,KAAa,UAA0B,CAAC,GAAY;CACtG,MAAM,EAAE,YAAY,WAAW;CAG/B,QAFc,cAAc,UAAU,cAAc,QAAQ,SAAS,MAAM,QAAQ,SACrE,cAAc,UAAU,cAAc,QAAQ,SAAS,MAAM,QAAQ;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;AChBA,SAAgB,KAAK,OAAe,KAAa,GAAmB;CAClE,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,MAAM,GAAG,OAAO;CACpB,IAAI,OAAO,GAAG,OAAO,GAAG,GAAG,OAAO;CAClC,OAAO,SAAS,MAAM,SAAS;AACjC;;;;;;;;;;;;;;;;;;;;;;ACTA,SAAgB,KAAK,OAAkC;CACrD,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,OAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC,IAAI,MAAM;AACtD;;;;;;;;;;;;;;;ACVA,SAAgB,cAAc,KAAa,KAAqB;CAC9D,OAAO,KAAK,OAAO,KAAK,MAAM,OAAO;AACvC;;;;;;;;AASA,SAAgB,iBAAiB,KAAa,KAAqB;CACjE,OAAO,KAAK,MAAM,KAAK,OAAO,KAAK,MAAM,MAAM,EAAE,IAAI;AACvD;;;;;;;;;;;;;;;ACbA,SAAgB,QAAQ,OAAe,UAA0B;CAC/D,MAAM,aAAa,KAAK,IAAI,IAAI,QAAQ;CACxC,OAAO,KAAK,MAAM,QAAQ,UAAU,IAAI;AAC1C;;;;;;;;;;;;;;;;;ACDA,SAAgB,IAAI,OAAkC;CACpD,OAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,CAAC;AAC5C"}

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/number
 
 > Tree-shakable TypeScript utility functions for the `number` domain.
-> Package: `@helpers4/number` — Version: 2.0.0
+> Package: `@helpers4/number` — Version: 2.0.2
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,7 +15,7 @@ pnpm add @helpers4/number
 ## Usage
 
 ```typescript
-import { clamp, formatCompact, formatSize, ... } from '@helpers4/number';
+import { clamp, correctFloat, formatCompact, ... } from '@helpers4/number';
 ```
 
 ## Functions
@@ -23,6 +23,7 @@ import { clamp, formatCompact, formatSize, ... } from '@helpers4/number';
 | Function | Description |
 |---|---|
 | `clamp` | Clamps a number between min and max values |
+| `correctFloat` | Corrects floating-point arithmetic errors by rounding to a given number of significant digits. Usefu |
 | `formatCompact` | Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).  Thin wrapper over `Intl.Number |
 | `formatSize` | Format a byte count into a human-readable string with the appropriate unit.  Each unit is 1024 of th |
 | `inRange` | Checks whether a number falls within `[min, max]` (both inclusive by default). |
@@ -69,6 +70,54 @@ clamp(5, 0, 10)   // => 5
 
 ---
 
+### `correctFloat`
+
+Corrects floating-point arithmetic errors by rounding to a given number
+of significant digits. Useful after calculations that accumulate binary
+floating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).
+
+The default precision of 14 significant digits eliminates typical
+rounding noise for values in the range used by most applications.
+Note: for values whose integer part already consumes 14 or more digits
+(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal
+digits and will silently truncate them. Increase `precision` if you
+need to correct drift in very large numbers.
+
+```typescript
+import { correctFloat } from '@helpers4/number';
+
+correctFloat(value: number, precision: number): number
+```
+
+**Parameters:**
+
+- `value: number` — The floating-point value to correct
+- `precision: number` (default: `14`) — Integer number of significant digits (default: 14)
+
+**Returns:** `number` — The corrected value
+
+**Examples:**
+
+*Fix floating-point drift*
+
+Corrects the classic 0.1 + 0.2 floating-point arithmetic error.
+
+```typescript
+0.1 + 0.2              // => 0.30000000000000004
+correctFloat(0.1 + 0.2)  // => 0.3
+```
+
+*Custom significant-digit precision*
+
+Pass a second argument to control how many significant digits to keep.
+
+```typescript
+correctFloat(1.23456789, 4)  // => 1.235
+correctFloat(1.23456789, 6)  // => 1.23457
+```
+
+---
+
 ### `formatCompact`
 
 Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "number",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "functions": [
     {
       "name": "clamp",
@@ -43,6 +43,48 @@
       ],
       "sourceFile": "clamp.ts"
     },
+    {
+      "name": "correctFloat",
+      "kind": "function",
+      "description": "Corrects floating-point arithmetic errors by rounding to a given number\nof significant digits. Useful after calculations that accumulate binary\nfloating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n\nThe default precision of 14 significant digits eliminates typical\nrounding noise for values in the range used by most applications.\nNote: for values whose integer part already consumes 14 or more digits\n(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\ndigits and will silently truncate them. Increase `precision` if you\nneed to correct drift in very large numbers.",
+      "since": "2.0.2",
+      "signatures": [
+        {
+          "signature": "correctFloat(value: number, precision: number): number",
+          "description": "Corrects floating-point arithmetic errors by rounding to a given number\nof significant digits. Useful after calculations that accumulate binary\nfloating-point drift (e.g. `0.1 + 0.2 === 0.30000000000000004`).\n\nThe default precision of 14 significant digits eliminates typical\nrounding noise for values in the range used by most applications.\nNote: for values whose integer part already consumes 14 or more digits\n(i.e. |value| ≥ 1e13), toPrecision(14) has no room left for decimal\ndigits and will silently truncate them. Increase `precision` if you\nneed to correct drift in very large numbers.",
+          "params": [
+            {
+              "name": "value",
+              "type": "number",
+              "description": "The floating-point value to correct"
+            },
+            {
+              "name": "precision",
+              "type": "number",
+              "description": "Integer number of significant digits (default: 14)",
+              "defaultValue": "14"
+            }
+          ],
+          "returns": {
+            "type": "number",
+            "description": "The corrected value"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Fix floating-point drift",
+          "description": "Corrects the classic 0.1 + 0.2 floating-point arithmetic error.",
+          "code": "0.1 + 0.2              // => 0.30000000000000004\ncorrectFloat(0.1 + 0.2)  // => 0.3"
+        },
+        {
+          "title": "Custom significant-digit precision",
+          "description": "Pass a second argument to control how many significant digits to keep.",
+          "code": "correctFloat(1.23456789, 4)  // => 1.235\ncorrectFloat(1.23456789, 6)  // => 1.23457"
+        }
+      ],
+      "sourceFile": "correctFloat.ts"
+    },
     {
       "name": "formatCompact",
       "kind": "function",

package/meta/examples.json

@@ -11,6 +11,21 @@
         }
       ]
     },
+    {
+      "name": "correctFloat",
+      "examples": [
+        {
+          "title": "Fix floating-point drift",
+          "description": "Corrects the classic 0.1 + 0.2 floating-point arithmetic error.",
+          "code": "0.1 + 0.2              // => 0.30000000000000004\ncorrectFloat(0.1 + 0.2)  // => 0.3"
+        },
+        {
+          "title": "Custom significant-digit precision",
+          "description": "Pass a second argument to control how many significant digits to keep.",
+          "code": "correctFloat(1.23456789, 4)  // => 1.235\ncorrectFloat(1.23456789, 6)  // => 1.23457"
+        }
+      ]
+    },
     {
       "name": "formatCompact",
       "examples": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/number",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for number.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -28,6 +28,7 @@
     "helpers",
     "number",
     "clamp",
+    "correctFloat",
     "formatCompact",
     "formatSize",
     "inRange",