@helpers4/number 2.0.3 → 2.1.0

package/README.md

@@ -23,10 +23,8 @@ A set of helpers for working with URLs.
 - isOdd
 - isPositive
 - lerp
-- mean
 - random
 - roundTo
-- sum
 <!-- /AUTOMATIC-METHODS -->
 
 ## See

package/lib/index.d.ts

@@ -30,9 +30,23 @@ declare function clamp(value: number, min: number, max: number): number;
  * digits and will silently truncate them. Increase `precision` if you
  * need to correct drift in very large numbers.
  *
+ * Note: IEEE-754 doubles carry at most ~17 significant decimal digits.
+ * Precision values above 17 pad with digits that reflect the underlying
+ * binary representation rather than correcting drift.
+ *
  * @param value - The floating-point value to correct
- * @param precision - Integer number of significant digits (default: 14)
+ * @param precision - Integer number of significant digits between 1 and 100
+ *   (default: 14). Values above 17 are valid but expose binary noise beyond
+ *   IEEE-754's meaningful range.
  * @returns The corrected value
+ * @example
+ * correctFloat(0.1 + 0.2) // => 0.3
+ * correctFloat(1.1 - 0.3) // => 0.8
+ * correctFloat(0.1 * 3)   // => 0.3
+ *
+ * // Custom precision: keep 4 significant digits
+ * correctFloat(1.23456789, 4) // => 1.235
+ * correctFloat(1.23456789, 6) // => 1.23457
  * @since 2.0.2
  */
 declare function correctFloat(value: number, precision?: number): number;
@@ -80,15 +94,18 @@ interface ExtractNumberOptions {
  * @returns The extracted number, or `undefined` if none was found
  * @example
  * extractNumber('16.5px')        // => 16.5
+ * extractNumber('.5rem')         // => 0.5   (leading-dot decimal)
+ * extractNumber('-.5')           // => -0.5  (leading-dot with sign)
  * extractNumber('Wafer 10')      // => 10
  * extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
  * extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+ * extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)
  * extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
  * extractNumber('1e5 mol')       // => 100000
  * extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
  * extractNumber('no number')     // => undefined
  * extractNumber(42)              // => 42
- * @since 2.0.3
+ * @since 2.0.4
  */
 declare function extractNumber(value: unknown, options?: ExtractNumberOptions): number | undefined;
 
@@ -291,27 +308,6 @@ declare function isPositive(value: unknown): value is number;
  */
 declare function lerp(start: number, end: number, t: number): number;
 
-/**
- * This file is part of helpers4.
- * Copyright (C) 2025 baxyz
- * SPDX-License-Identifier: LGPL-3.0-or-later
- */
-/**
- * Calculates the arithmetic mean (average) of an array of numbers.
- * Returns `NaN` for an empty array.
- *
- * Pairs with {@link sum} for aggregate operations.
- *
- * @param array - The array of numbers to average
- * @returns The arithmetic mean, or `NaN` if the array is empty
- * @example
- * mean([1, 2, 3, 4])  // => 2.5
- * mean([10])          // => 10
- * mean([])            // => NaN
- * @since 2.0.0
- */
-declare function mean(array: readonly number[]): number;
-
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -348,21 +344,5 @@ declare function randomIntBetween(min: number, max: number): number;
  */
 declare function roundTo(value: number, decimals: number): number;
 
-/**
- * This file is part of helpers4.
- * Copyright (C) 2025 baxyz
- * SPDX-License-Identifier: LGPL-3.0-or-later
- */
-/**
- * Calculates the sum of an array of numbers.
- * @param array - The array of numbers to sum
- * @returns The sum of all values
- * @example
- * sum([1, 2, 3, 4])
- * // => 10
- * @since 2.0.0
- */
-declare function sum(array: readonly number[]): number;
-
-export { clamp, correctFloat, extractNumber, formatCompact, formatSize, inRange, isEven, isNegative, isOdd, isPositive, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, correctFloat, extractNumber, formatCompact, formatSize, inRange, isEven, isNegative, isOdd, isPositive, lerp, randomBetween, randomIntBetween, roundTo };
 export type { ExtractNumberOptions, InRangeOptions };

package/lib/index.js

@@ -34,22 +34,37 @@ function clamp(value, min, max) {
 * digits and will silently truncate them. Increase `precision` if you
 * need to correct drift in very large numbers.
 *
+* Note: IEEE-754 doubles carry at most ~17 significant decimal digits.
+* Precision values above 17 pad with digits that reflect the underlying
+* binary representation rather than correcting drift.
+*
 * @param value - The floating-point value to correct
-* @param precision - Integer number of significant digits (default: 14)
+* @param precision - Integer number of significant digits between 1 and 100
+*   (default: 14). Values above 17 are valid but expose binary noise beyond
+*   IEEE-754's meaningful range.
 * @returns The corrected value
+* @example
+* correctFloat(0.1 + 0.2) // => 0.3
+* correctFloat(1.1 - 0.3) // => 0.8
+* correctFloat(0.1 * 3)   // => 0.3
+*
+* // Custom precision: keep 4 significant digits
+* correctFloat(1.23456789, 4) // => 1.235
+* correctFloat(1.23456789, 6) // => 1.23457
 * @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;
+	return Object.is(value, -0) ? -0 : result;
 }
 //#endregion
 //#region helpers/number/extractNumber.ts
-var NUMBER_TOKEN = /(-)?(\d+(?:\.\d+)?)([eE][+-]?\d+)?/g;
+var NUMBER_TOKEN = /(-)?(\d+(?:\.\d+)?|(?<![\p{L}\p{N}_])\.\d+)([eE][+-]?\d+)?/u;
+var WORD_CHAR = /[\p{L}\p{N}_]/u;
 function isWordChar(char) {
-	return char !== void 0 && /[\p{L}\p{N}_]/u.test(char);
+	return char !== void 0 && WORD_CHAR.test(char);
 }
 /**
 * Extracts the first number embedded anywhere in a string, or passes through a `number`.
@@ -66,29 +81,32 @@ function isWordChar(char) {
 * @returns The extracted number, or `undefined` if none was found
 * @example
 * extractNumber('16.5px')        // => 16.5
+* extractNumber('.5rem')         // => 0.5   (leading-dot decimal)
+* extractNumber('-.5')           // => -0.5  (leading-dot with sign)
 * extractNumber('Wafer 10')      // => 10
 * extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
 * extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+* extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)
 * extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
 * extractNumber('1e5 mol')       // => 100000
 * extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
 * extractNumber('no number')     // => undefined
 * extractNumber(42)              // => 42
-* @since 2.0.3
+* @since 2.0.4
 */
 function extractNumber(value, options = {}) {
 	const { sign = "auto", exponent = "auto" } = options;
 	if (typeof value === "number") return Number.isNaN(value) ? void 0 : value;
 	if (typeof value !== "string") return;
-	NUMBER_TOKEN.lastIndex = 0;
+	const re = new RegExp(NUMBER_TOKEN.source, "gu");
 	let match;
-	while ((match = NUMBER_TOKEN.exec(value)) !== null) {
+	while ((match = re.exec(value)) !== null) {
 		const [full, signChar, mantissa, exponentPart] = match;
 		const start = match.index;
 		if (signChar) {
 			const before = value[start - 1];
 			if (!(sign === "strict" ? true : sign === "ignore" ? false : !isWordChar(before))) {
-				NUMBER_TOKEN.lastIndex = start + 1;
+				re.lastIndex = start + 1;
 				continue;
 			}
 		}
@@ -321,31 +339,6 @@ function lerp(start, end, t) {
 	return start + (end - start) * t;
 }
 //#endregion
-//#region helpers/number/mean.ts
-/**
-* This file is part of helpers4.
-* Copyright (C) 2025 baxyz
-* SPDX-License-Identifier: LGPL-3.0-or-later
-*/
-/**
-* Calculates the arithmetic mean (average) of an array of numbers.
-* Returns `NaN` for an empty array.
-*
-* Pairs with {@link sum} for aggregate operations.
-*
-* @param array - The array of numbers to average
-* @returns The arithmetic mean, or `NaN` if the array is empty
-* @example
-* mean([1, 2, 3, 4])  // => 2.5
-* mean([10])          // => 10
-* mean([])            // => NaN
-* @since 2.0.0
-*/
-function mean(array) {
-	if (array.length === 0) return NaN;
-	return array.reduce((acc, n) => acc + n, 0) / array.length;
-}
-//#endregion
 //#region helpers/number/random.ts
 /**
 * This file is part of helpers4.
@@ -391,25 +384,6 @@ function roundTo(value, decimals) {
 	return Math.round(value * multiplier) / multiplier;
 }
 //#endregion
-//#region helpers/number/sum.ts
-/**
-* This file is part of helpers4.
-* Copyright (C) 2025 baxyz
-* SPDX-License-Identifier: LGPL-3.0-or-later
-*/
-/**
-* Calculates the sum of an array of numbers.
-* @param array - The array of numbers to sum
-* @returns The sum of all values
-* @example
-* sum([1, 2, 3, 4])
-* // => 10
-* @since 2.0.0
-*/
-function sum(array) {
-	return array.reduce((acc, n) => acc + n, 0);
-}
-//#endregion
-export { clamp, correctFloat, extractNumber, formatCompact, formatSize, inRange, isEven, isNegative, isOdd, isPositive, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, correctFloat, extractNumber, formatCompact, formatSize, inRange, isEven, isNegative, isOdd, isPositive, lerp, randomBetween, randomIntBetween, roundTo };
 
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/correctFloat.ts","../../../helpers/number/extractNumber.ts","../../../helpers/number/formatCompact.ts","../../../helpers/number/formatSize.ts","../../../helpers/number/inRange.ts","../../../helpers/number/isEven.ts","../../../helpers/number/isNegative.ts","../../../helpers/number/isOdd.ts","../../../helpers/number/isPositive.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 * Options for {@link extractNumber}.\n */\nexport interface ExtractNumberOptions {\n  /**\n   * How to interpret a `-` immediately before the matched digits.\n   * - `'auto'`: treated as a minus sign unless it is glued to a preceding letter/digit\n   *   (e.g. `'-111'` and `'xxx -111'` → negative, but `'xxx-111'` → separator, positive).\n   * - `'strict'`: always treated as a minus sign.\n   * - `'ignore'`: never treated as a minus sign (always a separator).\n   * @default 'auto'\n   */\n  sign?: 'auto' | 'strict' | 'ignore';\n\n  /**\n   * How to interpret a trailing scientific-notation suffix (`e`/`E` + digits, e.g. `1.5e-10`).\n   * - `'auto'`: treated as an exponent unless it is glued to a following letter/digit\n   *   (e.g. `'1e5'` and `'1e5 mol'` → exponential, but `'1e5kg'` → mantissa only).\n   * - `'strict'`: always treated as an exponent.\n   * - `'ignore'`: never treated as an exponent (mantissa only).\n   * @default 'auto'\n   */\n  exponent?: 'auto' | 'strict' | 'ignore';\n}\n\nconst NUMBER_TOKEN = /(-)?(\\d+(?:\\.\\d+)?)([eE][+-]?\\d+)?/g;\n\nfunction isWordChar(char: string | undefined): boolean {\n  return char !== undefined && /[\\p{L}\\p{N}_]/u.test(char);\n}\n\n/**\n * Extracts the first number embedded anywhere in a string, or passes through a `number`.\n *\n * Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\n * the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\n * is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\n * disambiguated with {@link ExtractNumberOptions.sign} and {@link ExtractNumberOptions.exponent}.\n *\n * Returns `undefined` if no number can be found.\n *\n * @param value - The value to extract a number from\n * @param options - Options controlling sign and exponent disambiguation\n * @returns The extracted number, or `undefined` if none was found\n * @example\n * extractNumber('16.5px')        // => 16.5\n * extractNumber('Wafer 10')      // => 10\n * extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\n * extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\n * extractNumber('-111')          // => -111  ('-' at the start of the string → sign)\n * extractNumber('1e5 mol')       // => 100000\n * extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\n * extractNumber('no number')     // => undefined\n * extractNumber(42)              // => 42\n * @since 2.0.3\n */\nexport function extractNumber(value: unknown, options: ExtractNumberOptions = {}): number | undefined {\n  const { sign = 'auto', exponent = 'auto' } = options;\n\n  if (typeof value === 'number') {\n    return Number.isNaN(value) ? undefined : value;\n  }\n\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n\n  NUMBER_TOKEN.lastIndex = 0;\n  let match: RegExpExecArray | null;\n\n  while ((match = NUMBER_TOKEN.exec(value)) !== null) {\n    const [full, signChar, mantissa, exponentPart] = match;\n    const start = match.index;\n\n    if (signChar) {\n      const before = value[start - 1];\n      const keepSign = sign === 'strict' ? true : sign === 'ignore' ? false : !isWordChar(before);\n\n      if (!keepSign) {\n        // Re-scan from right after the '-' so the digits are matched as a fresh, unsigned number.\n        NUMBER_TOKEN.lastIndex = start + 1;\n        continue;\n      }\n    }\n\n    const keepExponent = exponentPart\n      ? exponent === 'strict'\n        ? true\n        : exponent === 'ignore'\n          ? false\n          : !isWordChar(value[start + full.length])\n      : false;\n\n    const numericText = (signChar ?? '') + mantissa + (keepExponent ? exponentPart : '');\n    return Number(numericText);\n  }\n\n  return undefined;\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 * Checks if a value is an even integer.\n *\n * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.\n *\n * @param value - The value to check\n * @returns `true` if value is an integer divisible by 2\n * @example\n * isEven(2)    // => true\n * isEven(0)    // => true\n * isEven(-4)   // => true\n * isEven(3)    // => false\n * isEven(1.5)  // => false  (not an integer)\n * isEven('2')  // => false\n * @since 2.0.3\n */\nexport function isEven(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value % 2 === 0;\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 * Checks if a value is a number less than 0.\n *\n * Returns `false` for `NaN`, `0`, positive numbers, and non-number types.\n *\n * @param value - The value to check\n * @returns True if value is a negative number\n * @example\n * isNegative(-1)        // => true\n * isNegative(-0.5)      // => true\n * isNegative(-Infinity) // => true\n * isNegative(0)         // => false\n * isNegative(1)         // => false\n * isNegative(NaN)       // => false\n * @since 2.0.0\n */\nexport function isNegative(value: unknown): value is number {\n  return typeof value === 'number' && value < 0;\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 * Checks if a value is an odd integer.\n *\n * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.\n *\n * @param value - The value to check\n * @returns `true` if value is an integer not divisible by 2\n * @example\n * isOdd(3)    // => true\n * isOdd(1)    // => true\n * isOdd(-7)   // => true\n * isOdd(2)    // => false\n * isOdd(1.5)  // => false  (not an integer)\n * isOdd('3')  // => false\n * @since 2.0.3\n */\nexport function isOdd(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value % 2 !== 0;\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 * Checks if a value is a number greater than 0.\n *\n * Returns `false` for `NaN`, `0`, negative numbers, and non-number types.\n *\n * @param value - The value to check\n * @returns True if value is a positive number\n * @example\n * isPositive(42)       // => true\n * isPositive(0.1)      // => true\n * isPositive(Infinity) // => true\n * isPositive(0)        // => false\n * isPositive(-1)       // => false\n * isPositive(NaN)      // => false\n * @since 2.0.0\n */\nexport function isPositive(value: unknown): value is number {\n  return typeof value === 'number' && value > 0;\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":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/number/clamp.ts","../../../helpers/number/correctFloat.ts","../../../helpers/number/extractNumber.ts","../../../helpers/number/formatCompact.ts","../../../helpers/number/formatSize.ts","../../../helpers/number/inRange.ts","../../../helpers/number/isEven.ts","../../../helpers/number/isNegative.ts","../../../helpers/number/isOdd.ts","../../../helpers/number/isPositive.ts","../../../helpers/number/lerp.ts","../../../helpers/number/random.ts","../../../helpers/number/roundTo.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 * Note: IEEE-754 doubles carry at most ~17 significant decimal digits.\n * Precision values above 17 pad with digits that reflect the underlying\n * binary representation rather than correcting drift.\n *\n * @param value - The floating-point value to correct\n * @param precision - Integer number of significant digits between 1 and 100\n *   (default: 14). Values above 17 are valid but expose binary noise beyond\n *   IEEE-754's meaningful range.\n * @returns The corrected value\n * @example\n * correctFloat(0.1 + 0.2) // => 0.3\n * correctFloat(1.1 - 0.3) // => 0.8\n * correctFloat(0.1 * 3)   // => 0.3\n *\n * // Custom precision: keep 4 significant digits\n * correctFloat(1.23456789, 4) // => 1.235\n * correctFloat(1.23456789, 6) // => 1.23457\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) ? -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 * Options for {@link extractNumber}.\n */\nexport interface ExtractNumberOptions {\n  /**\n   * How to interpret a `-` immediately before the matched digits.\n   * - `'auto'`: treated as a minus sign unless it is glued to a preceding letter/digit\n   *   (e.g. `'-111'` and `'xxx -111'` → negative, but `'xxx-111'` → separator, positive).\n   * - `'strict'`: always treated as a minus sign.\n   * - `'ignore'`: never treated as a minus sign (always a separator).\n   * @default 'auto'\n   */\n  sign?: 'auto' | 'strict' | 'ignore';\n\n  /**\n   * How to interpret a trailing scientific-notation suffix (`e`/`E` + digits, e.g. `1.5e-10`).\n   * - `'auto'`: treated as an exponent unless it is glued to a following letter/digit\n   *   (e.g. `'1e5'` and `'1e5 mol'` → exponential, but `'1e5kg'` → mantissa only).\n   * - `'strict'`: always treated as an exponent.\n   * - `'ignore'`: never treated as an exponent (mantissa only).\n   * @default 'auto'\n   */\n  exponent?: 'auto' | 'strict' | 'ignore';\n}\n\n// (?<![\\p{L}\\p{N}_]) prevents matching a leading-dot decimal immediately after a word\n// character (e.g. the '.5' in 'text.5' is a property separator, not a decimal point).\n// No `g` flag — cloned per call via `new RegExp(…, 'gu')` so each invocation has its own lastIndex.\nconst NUMBER_TOKEN = /(-)?(\\d+(?:\\.\\d+)?|(?<![\\p{L}\\p{N}_])\\.\\d+)([eE][+-]?\\d+)?/u;\nconst WORD_CHAR = /[\\p{L}\\p{N}_]/u;\n\nfunction isWordChar(char: string | undefined): boolean {\n  return char !== undefined && WORD_CHAR.test(char);\n}\n\n/**\n * Extracts the first number embedded anywhere in a string, or passes through a `number`.\n *\n * Unlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\n * the string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\n * is ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\n * disambiguated with {@link ExtractNumberOptions.sign} and {@link ExtractNumberOptions.exponent}.\n *\n * Returns `undefined` if no number can be found.\n *\n * @param value - The value to extract a number from\n * @param options - Options controlling sign and exponent disambiguation\n * @returns The extracted number, or `undefined` if none was found\n * @example\n * extractNumber('16.5px')        // => 16.5\n * extractNumber('.5rem')         // => 0.5   (leading-dot decimal)\n * extractNumber('-.5')           // => -0.5  (leading-dot with sign)\n * extractNumber('Wafer 10')      // => 10\n * extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\n * extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\n * extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)\n * extractNumber('-111')          // => -111  ('-' at the start of the string → sign)\n * extractNumber('1e5 mol')       // => 100000\n * extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\n * extractNumber('no number')     // => undefined\n * extractNumber(42)              // => 42\n * @since 2.0.4\n */\nexport function extractNumber(value: unknown, options: ExtractNumberOptions = {}): number | undefined {\n  const { sign = 'auto', exponent = 'auto' } = options;\n\n  if (typeof value === 'number') {\n    return Number.isNaN(value) ? undefined : value;\n  }\n\n  if (typeof value !== 'string') {\n    return undefined;\n  }\n\n  const re = new RegExp(NUMBER_TOKEN.source, 'gu');\n  let match: RegExpExecArray | null;\n\n  while ((match = re.exec(value)) !== null) {\n    const [full, signChar, mantissa, exponentPart] = match;\n    const start = match.index;\n\n    if (signChar) {\n      const before = value[start - 1];\n      const keepSign = sign === 'strict' ? true : sign === 'ignore' ? false : !isWordChar(before);\n\n      if (!keepSign) {\n        // Re-scan from right after the '-' so the digits are matched as a fresh, unsigned number.\n        re.lastIndex = start + 1;\n        continue;\n      }\n    }\n\n    const keepExponent = exponentPart\n      ? exponent === 'strict'\n        ? true\n        : exponent === 'ignore'\n          ? false\n          : !isWordChar(value[start + full.length])\n      : false;\n\n    const numericText = (signChar ?? '') + mantissa + (keepExponent ? exponentPart : '');\n    return Number(numericText);\n  }\n\n  return undefined;\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 * Checks if a value is an even integer.\n *\n * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and odd integers.\n *\n * @param value - The value to check\n * @returns `true` if value is an integer divisible by 2\n * @example\n * isEven(2)    // => true\n * isEven(0)    // => true\n * isEven(-4)   // => true\n * isEven(3)    // => false\n * isEven(1.5)  // => false  (not an integer)\n * isEven('2')  // => false\n * @since 2.0.3\n */\nexport function isEven(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value % 2 === 0;\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 * Checks if a value is a number less than 0.\n *\n * Returns `false` for `NaN`, `0`, positive numbers, and non-number types.\n *\n * @param value - The value to check\n * @returns True if value is a negative number\n * @example\n * isNegative(-1)        // => true\n * isNegative(-0.5)      // => true\n * isNegative(-Infinity) // => true\n * isNegative(0)         // => false\n * isNegative(1)         // => false\n * isNegative(NaN)       // => false\n * @since 2.0.0\n */\nexport function isNegative(value: unknown): value is number {\n  return typeof value === 'number' && value < 0;\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 * Checks if a value is an odd integer.\n *\n * Returns `false` for non-numbers, non-integers, `NaN`, `Infinity`, and even integers.\n *\n * @param value - The value to check\n * @returns `true` if value is an integer not divisible by 2\n * @example\n * isOdd(3)    // => true\n * isOdd(1)    // => true\n * isOdd(-7)   // => true\n * isOdd(2)    // => false\n * isOdd(1.5)  // => false  (not an integer)\n * isOdd('3')  // => false\n * @since 2.0.3\n */\nexport function isOdd(value: unknown): value is number {\n  return typeof value === 'number' && Number.isInteger(value) && value % 2 !== 0;\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 * Checks if a value is a number greater than 0.\n *\n * Returns `false` for `NaN`, `0`, negative numbers, and non-number types.\n *\n * @param value - The value to check\n * @returns True if value is a positive number\n * @example\n * isPositive(42)       // => true\n * isPositive(0.1)      // => true\n * isPositive(Infinity) // => true\n * isPositive(0)        // => false\n * isPositive(-1)       // => false\n * isPositive(NaN)      // => false\n * @since 2.0.0\n */\nexport function isPositive(value: unknown): value is number {\n  return typeof value === 'number' && value > 0;\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 * 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"],"mappings":"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"}

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/number
 
 > Tree-shakable TypeScript utility functions for the `number` domain.
-> Package: `@helpers4/number` — Version: 2.0.3
+> Package: `@helpers4/number` — Version: 2.1.0
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -33,11 +33,9 @@ import { clamp, correctFloat, extractNumber, ... } from '@helpers4/number';
 | `isOdd` | Checks if a value is an odd integer.  Returns `false` for non-numbers, non-integers, `NaN`, `Infinit |
 | `isPositive` | Checks if a value is a number greater than 0.  Returns `false` for `NaN`, `0`, negative numbers, and |
 | `lerp` | Linearly interpolates between `start` and `end` by the factor `t`.  - `t = 0` returns `start`. - `t  |
-| `mean` | Calculates the arithmetic mean (average) of an array of numbers. Returns `NaN` for an empty array.   |
 | `randomBetween` | Generates a random number between min and max (inclusive) |
 | `randomIntBetween` | Generates a random integer between min and max (inclusive) |
 | `roundTo` | Rounds a number to specified decimal places |
-| `sum` | Calculates the sum of an array of numbers. |
 
 ---
 
@@ -88,6 +86,10 @@ Note: for values whose integer part already consumes 14 or more digits
 digits and will silently truncate them. Increase `precision` if you
 need to correct drift in very large numbers.
 
+Note: IEEE-754 doubles carry at most ~17 significant decimal digits.
+Precision values above 17 pad with digits that reflect the underlying
+binary representation rather than correcting drift.
+
 ```typescript
 import { correctFloat } from '@helpers4/number';
 
@@ -97,7 +99,9 @@ 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)
+- `precision: number` (default: `14`) — Integer number of significant digits between 1 and 100
+  (default: 14). Values above 17 are valid but expose binary noise beyond
+  IEEE-754's meaningful range.
 
 **Returns:** `number` — The corrected value
 
@@ -154,9 +158,12 @@ extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined
 ```typescript
 ```ts
 extractNumber('16.5px')        // => 16.5
+extractNumber('.5rem')         // => 0.5   (leading-dot decimal)
+extractNumber('-.5')           // => -0.5  (leading-dot with sign)
 extractNumber('Wafer 10')      // => 10
 extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
 extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)
 extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
 extractNumber('1e5 mol')       // => 100000
 extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
@@ -490,39 +497,6 @@ lerp(0, 10, 2)    // => 20  (extrapolation)
 
 ---
 
-### `mean`
-
-Calculates the arithmetic mean (average) of an array of numbers.
-Returns `NaN` for an empty array.
-
-Pairs with sum for aggregate operations.
-
-```typescript
-import { mean } from '@helpers4/number';
-
-mean(array: readonly number[]): number
-```
-
-**Parameters:**
-
-- `array: readonly number[]` — The array of numbers to average
-
-**Returns:** `number` — The arithmetic mean, or `NaN` if the array is empty
-
-**Examples:**
-
-*Average a list of numbers*
-
-Returns the arithmetic mean of the array; NaN for empty arrays.
-
-```typescript
-mean([1, 2, 3, 4])  // => 2.5
-mean([10, 20, 30])  // => 20
-mean([])            // => NaN
-```
-
----
-
 ### `randomBetween`
 
 Generates a random number between min and max (inclusive)
@@ -619,41 +593,3 @@ roundTo(3.7, 0)
 ```
 
 ---
-
-### `sum`
-
-Calculates the sum of an array of numbers.
-
-```typescript
-import { sum } from '@helpers4/number';
-
-sum(array: readonly number[]): number
-```
-
-**Parameters:**
-
-- `array: readonly number[]` — The array of numbers to sum
-
-**Returns:** `number` — The sum of all values
-
-**Examples:**
-
-*Sum numbers*
-
-Calculates the sum of an array of numbers.
-
-```typescript
-sum([1, 2, 3, 4])
-// => 10
-```
-
-*Sum with negative numbers*
-
-Handles negative numbers correctly.
-
-```typescript
-sum([10, -3, 5, -2])
-// => 10
-```
-
----

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "number",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "functions": [
     {
       "name": "clamp",
@@ -46,12 +46,12 @@
     {
       "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.",
+      "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.\n\nNote: IEEE-754 doubles carry at most ~17 significant decimal digits.\nPrecision values above 17 pad with digits that reflect the underlying\nbinary representation rather than correcting drift.",
       "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.",
+          "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.\n\nNote: IEEE-754 doubles carry at most ~17 significant decimal digits.\nPrecision values above 17 pad with digits that reflect the underlying\nbinary representation rather than correcting drift.",
           "params": [
             {
               "name": "value",
@@ -61,7 +61,7 @@
             {
               "name": "precision",
               "type": "number",
-              "description": "Integer number of significant digits (default: 14)",
+              "description": "Integer number of significant digits between 1 and 100\n  (default: 14). Values above 17 are valid but expose binary noise beyond\n  IEEE-754's meaningful range.",
               "defaultValue": "14"
             }
           ],
@@ -89,7 +89,7 @@
       "name": "extractNumber",
       "kind": "function",
       "description": "Extracts the first number embedded anywhere in a string, or passes through a `number`.\n\nUnlike a plain `parseFloat`/`parseInt`, the number does not need to be at the start of\nthe string: digits are searched for anywhere, so leading/trailing text (units, labels, ...)\nis ignored. A `-` before the digits and a scientific-notation suffix (`e`/`E`) are\ndisambiguated with ExtractNumberOptions.sign and ExtractNumberOptions.exponent.\n\nReturns `undefined` if no number can be found.",
-      "since": "2.0.3",
+      "since": "2.0.4",
       "signatures": [
         {
           "signature": "extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined",
@@ -117,7 +117,7 @@
         {
           "title": "extractNumber",
           "description": "",
-          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
+          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('.5rem')         // => 0.5   (leading-dot decimal)\nextractNumber('-.5')           // => -0.5  (leading-dot with sign)\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
         }
       ],
       "sourceFile": "extractNumber.ts"
@@ -427,37 +427,6 @@
       ],
       "sourceFile": "lerp.ts"
     },
-    {
-      "name": "mean",
-      "kind": "function",
-      "description": "Calculates the arithmetic mean (average) of an array of numbers.\nReturns `NaN` for an empty array.\n\nPairs with sum for aggregate operations.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "mean(array: readonly number[]): number",
-          "description": "Calculates the arithmetic mean (average) of an array of numbers.\nReturns `NaN` for an empty array.\n\nPairs with sum for aggregate operations.",
-          "params": [
-            {
-              "name": "array",
-              "type": "readonly number[]",
-              "description": "The array of numbers to average"
-            }
-          ],
-          "returns": {
-            "type": "number",
-            "description": "The arithmetic mean, or `NaN` if the array is empty"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Average a list of numbers",
-          "description": "Returns the arithmetic mean of the array; NaN for empty arrays.",
-          "code": "mean([1, 2, 3, 4])  // => 2.5\nmean([10, 20, 30])  // => 20\nmean([])            // => NaN"
-        }
-      ],
-      "sourceFile": "mean.ts"
-    },
     {
       "name": "randomBetween",
       "kind": "function",
@@ -569,42 +538,6 @@
         }
       ],
       "sourceFile": "roundTo.ts"
-    },
-    {
-      "name": "sum",
-      "kind": "function",
-      "description": "Calculates the sum of an array of numbers.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "sum(array: readonly number[]): number",
-          "description": "Calculates the sum of an array of numbers.",
-          "params": [
-            {
-              "name": "array",
-              "type": "readonly number[]",
-              "description": "The array of numbers to sum"
-            }
-          ],
-          "returns": {
-            "type": "number",
-            "description": "The sum of all values"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Sum numbers",
-          "description": "Calculates the sum of an array of numbers.",
-          "code": "sum([1, 2, 3, 4])\n// => 10"
-        },
-        {
-          "title": "Sum with negative numbers",
-          "description": "Handles negative numbers correctly.",
-          "code": "sum([10, -3, 5, -2])\n// => 10"
-        }
-      ],
-      "sourceFile": "sum.ts"
     }
   ]
 }

package/meta/examples.json

@@ -32,7 +32,7 @@
         {
           "title": "extractNumber",
           "description": "",
-          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
+          "code": "```ts\nextractNumber('16.5px')        // => 16.5\nextractNumber('.5rem')         // => 0.5   (leading-dot decimal)\nextractNumber('-.5')           // => -0.5  (leading-dot with sign)\nextractNumber('Wafer 10')      // => 10\nextractNumber('xxx-111')       // => 111   ('-' glued to text → separator)\nextractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)\nextractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)\nextractNumber('-111')          // => -111  ('-' at the start of the string → sign)\nextractNumber('1e5 mol')       // => 100000\nextractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)\nextractNumber('no number')     // => undefined\nextractNumber(42)              // => 42\n```"
         }
       ]
     },
@@ -141,16 +141,6 @@
         }
       ]
     },
-    {
-      "name": "mean",
-      "examples": [
-        {
-          "title": "Average a list of numbers",
-          "description": "Returns the arithmetic mean of the array; NaN for empty arrays.",
-          "code": "mean([1, 2, 3, 4])  // => 2.5\nmean([10, 20, 30])  // => 20\nmean([])            // => NaN"
-        }
-      ]
-    },
     {
       "name": "randomBetween",
       "examples": [
@@ -180,21 +170,6 @@
           "code": "roundTo(3.7, 0)\n// => 4"
         }
       ]
-    },
-    {
-      "name": "sum",
-      "examples": [
-        {
-          "title": "Sum numbers",
-          "description": "Calculates the sum of an array of numbers.",
-          "code": "sum([1, 2, 3, 4])\n// => 10"
-        },
-        {
-          "title": "Sum with negative numbers",
-          "description": "Handles negative numbers correctly.",
-          "code": "sum([10, -3, 5, -2])\n// => 10"
-        }
-      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/number",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for number.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -38,10 +38,8 @@
     "isOdd",
     "isPositive",
     "lerp",
-    "mean",
     "random",
-    "roundTo",
-    "sum"
+    "roundTo"
   ],
   "files": [
     "lib/index.js",