@helpers4/number 2.0.0-beta.0 → 2.0.0

package/README.md

@@ -13,7 +13,11 @@ A set of helpers for working with URLs.
 
 <!-- AUTOMATIC-METHODS -->
 - clamp
+- formatCompact
 - formatSize
+- inRange
+- lerp
+- mean
 - random
 - roundTo
 - sum
@@ -23,10 +27,12 @@ A set of helpers for working with URLs.
 
 <!-- AUTOMATIC-SIBLINGS -->
 - [array](../array)
+- [ci](../ci)
 - [commit](../commit)
 - [date](../date)
 - [function](../function)
-- [math](../math)
+- [id](../id)
+- [markdown](../markdown)
 - [object](../object)
 - [observable](../observable)
 - [promise](../promise)
@@ -42,10 +48,12 @@ A set of helpers for working with URLs.
 | Name | Package | Source Code | Description |
 |------|---------|-------------|-------------|
 | array | [@helpers4/array](https://www.npmjs.com/package/@helpers4/array) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/array) | Array manipulation utilities |
+| ci | [@helpers4/ci](https://www.npmjs.com/package/@helpers4/ci) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/ci) | CI/CD workflow status utilities |
 | commit | [@helpers4/commit](https://www.npmjs.com/package/@helpers4/commit) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/commit) | Conventional Commits parsing and analysis |
 | date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | Date and time utility functions |
 | 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 |
-| math | [@helpers4/math](https://www.npmjs.com/package/@helpers4/math) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/math) | Mathematical utility functions and calculations |
+| 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 |
 | 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,29 @@
  */
 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
+ */
+/**
+ * Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).
+ *
+ * Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion
+ * of `formatSize` in the same `format*` family.
+ *
+ * @param value - The number to format.
+ * @param locale - BCP 47 locale tag. Defaults to the runtime locale.
+ * @returns A compact string representation of the number.
+ * @example
+ * formatCompact(1_500_000);        // '1.5M'  (en-US locale)
+ * formatCompact(1_000);            // '1K'
+ * formatCompact(999);              // '999'
+ * formatCompact(1_500_000, 'fr'); // '1,5 M'
+ * @since 2.0.0
+ */
+declare function formatCompact(value: number, locale?: string): string;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -33,10 +56,91 @@ declare function clamp(value: number, min: number, max: number): number;
  * formatSize(1536)            // '1.5KB'
  * formatSize(1_048_576)       // '1.0MB'
  * formatSize(1_073_741_824)   // '1.0GB'
- * @since next
+ * @since 2.0.0
  */
 declare function formatSize(bytes: number): string;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Options for {@link inRange}.
+ */
+interface InRangeOptions {
+    /**
+     * Which boundary (or boundaries) are included in the range.
+     * - `'both'` (default): `min <= value <= max`
+     * - `'min'`: `min <= value < max`
+     * - `'max'`: `min < value <= max`
+     * - `'none'`: `min < value < max`
+     */
+    inclusive?: 'both' | 'min' | 'max' | 'none';
+}
+/**
+ * Checks whether a number falls within `[min, max]` (both inclusive by default).
+ *
+ * @param value - The number to test
+ * @param min - Lower bound
+ * @param max - Upper bound
+ * @param options - Boundary inclusion mode (default: `'both'`)
+ * @returns `true` if `value` is within the specified range
+ * @example
+ * inRange(5, 1, 10)          // => true
+ * inRange(1, 1, 10)          // => true  (min inclusive)
+ * inRange(1, 1, 10, { inclusive: 'none' })  // => false
+ * inRange(10, 1, 10, { inclusive: 'max' })  // => true
+ * @since 2.0.0
+ */
+declare function inRange(value: number, min: number, max: number, options?: InRangeOptions): boolean;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Linearly interpolates between `start` and `end` by the factor `t`.
+ *
+ * - `t = 0` returns `start`.
+ * - `t = 1` returns `end`.
+ * - Values of `t` outside `[0, 1]` extrapolate beyond the range.
+ *
+ * @param start - The start value.
+ * @param end - The end value.
+ * @param t - The interpolation factor.
+ * @returns The interpolated value.
+ * @example
+ * lerp(0, 100, 0);    // 0
+ * lerp(0, 100, 1);    // 100
+ * lerp(0, 100, 0.5);  // 50
+ * lerp(0, 100, 0.25); // 25
+ * @since 2.0.0
+ */
+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
@@ -89,4 +193,5 @@ declare function roundTo(value: number, decimals: number): number;
  */
 declare function sum(array: readonly number[]): number;
 
-export { clamp, formatSize, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, formatCompact, formatSize, inRange, lerp, mean, randomBetween, randomIntBetween, roundTo, sum };
+export type { InRangeOptions };

package/lib/index.js

@@ -16,6 +16,32 @@ function clamp(value, min, max) {
 	return Math.min(Math.max(value, min), max);
 }
 //#endregion
+//#region helpers/number/formatCompact.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).
+*
+* Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion
+* of `formatSize` in the same `format*` family.
+*
+* @param value - The number to format.
+* @param locale - BCP 47 locale tag. Defaults to the runtime locale.
+* @returns A compact string representation of the number.
+* @example
+* formatCompact(1_500_000);        // '1.5M'  (en-US locale)
+* formatCompact(1_000);            // '1K'
+* formatCompact(999);              // '999'
+* formatCompact(1_500_000, 'fr'); // '1,5 M'
+* @since 2.0.0
+*/
+function formatCompact(value, locale) {
+	return new Intl.NumberFormat(locale, { notation: "compact" }).format(value);
+}
+//#endregion
 //#region helpers/number/formatSize.ts
 /**
 * This file is part of helpers4.
@@ -45,7 +71,7 @@ var UNITS = [
 * formatSize(1536)            // '1.5KB'
 * formatSize(1_048_576)       // '1.0MB'
 * formatSize(1_073_741_824)   // '1.0GB'
-* @since next
+* @since 2.0.0
 */
 function formatSize(bytes) {
 	let size = bytes;
@@ -57,6 +83,83 @@ function formatSize(bytes) {
 	return `${size.toFixed(1)}${UNITS[unitIndex]}`;
 }
 //#endregion
+//#region helpers/number/inRange.ts
+/**
+* Checks whether a number falls within `[min, max]` (both inclusive by default).
+*
+* @param value - The number to test
+* @param min - Lower bound
+* @param max - Upper bound
+* @param options - Boundary inclusion mode (default: `'both'`)
+* @returns `true` if `value` is within the specified range
+* @example
+* inRange(5, 1, 10)          // => true
+* inRange(1, 1, 10)          // => true  (min inclusive)
+* inRange(1, 1, 10, { inclusive: 'none' })  // => false
+* inRange(10, 1, 10, { inclusive: 'max' })  // => true
+* @since 2.0.0
+*/
+function inRange(value, min, max, options = {}) {
+	const { inclusive = "both" } = options;
+	return (inclusive === "both" || inclusive === "min" ? value >= min : value > min) && (inclusive === "both" || inclusive === "max" ? value <= max : value < max);
+}
+//#endregion
+//#region helpers/number/lerp.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Linearly interpolates between `start` and `end` by the factor `t`.
+*
+* - `t = 0` returns `start`.
+* - `t = 1` returns `end`.
+* - Values of `t` outside `[0, 1]` extrapolate beyond the range.
+*
+* @param start - The start value.
+* @param end - The end value.
+* @param t - The interpolation factor.
+* @returns The interpolated value.
+* @example
+* lerp(0, 100, 0);    // 0
+* lerp(0, 100, 1);    // 100
+* lerp(0, 100, 0.5);  // 50
+* lerp(0, 100, 0.25); // 25
+* @since 2.0.0
+*/
+function lerp(start, end, t) {
+	if (t === 0) return start;
+	if (t === 1) return end;
+	if (Object.is(start, end)) return start;
+	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.
@@ -121,6 +224,6 @@ function sum(array) {
 	return array.reduce((acc, n) => acc + n, 0);
 }
 //#endregion
-export { clamp, formatSize, randomBetween, randomIntBetween, roundTo, sum };
+export { clamp, 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/formatSize.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/** 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 next\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 * 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;AACrE,QAAO,KAAK,IAAI,KAAK,IAAI,OAAO,IAAI,EAAE,IAAI;;;;;;;;;;ACR5C,IAAM,QAAQ;CAAC;CAAK;CAAM;CAAM;CAAM;CAAK;;;;;;;;;;;;;;;;;;AAmB3C,SAAgB,WAAW,OAAuB;CAChD,IAAI,OAAO;CACX,IAAI,YAAY;AAEhB,QAAO,QAAQ,QAAQ,YAAY,MAAM,SAAS,GAAG;AACnD,UAAQ;AACR;;AAGF,QAAO,GAAG,KAAK,QAAQ,EAAE,GAAG,MAAM;;;;;;;;;;;;;;;;ACtBpC,SAAgB,cAAc,KAAa,KAAqB;AAC9D,QAAO,KAAK,QAAQ,IAAI,MAAM,OAAO;;;;;;;;;AAUvC,SAAgB,iBAAiB,KAAa,KAAqB;AACjE,QAAO,KAAK,MAAM,KAAK,QAAQ,IAAI,MAAM,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;ACZvD,SAAgB,QAAQ,OAAe,UAA0B;CAC/D,MAAM,aAAa,KAAK,IAAI,IAAI,SAAS;AACzC,QAAO,KAAK,MAAM,QAAQ,WAAW,GAAG;;;;;;;;;;;;;;;;;;ACA1C,SAAgB,IAAI,OAAkC;AACpD,QAAO,MAAM,QAAQ,KAAK,MAAM,MAAM,GAAG,EAAE"}
+{"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"}

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-beta.0
+> Package: `@helpers4/number` — Version: 2.0.0
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,7 +15,7 @@ pnpm add @helpers4/number
 ## Usage
 
 ```typescript
-import { clamp, formatSize, randomBetween, ... } from '@helpers4/number';
+import { clamp, formatCompact, formatSize, ... } from '@helpers4/number';
 ```
 
 ## Functions
@@ -23,7 +23,11 @@ import { clamp, formatSize, randomBetween, ... } from '@helpers4/number';
 | Function | Description |
 |---|---|
 | `clamp` | Clamps a number between min and max values |
+| `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). |
+| `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 |
@@ -65,6 +69,48 @@ clamp(5, 0, 10)   // => 5
 
 ---
 
+### `formatCompact`
+
+Formats a number using compact notation (e.g. `1_500_000 → "1.5M"`).
+
+Thin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion
+of `formatSize` in the same `format*` family.
+
+```typescript
+import { formatCompact } from '@helpers4/number';
+
+formatCompact(value: number, locale?: string): string
+```
+
+**Parameters:**
+
+- `value: number` — The number to format.
+- `locale?: string` — BCP 47 locale tag. Defaults to the runtime locale.
+
+**Returns:** `string` — A compact string representation of the number.
+
+**Examples:**
+
+*Compact large numbers*
+
+Formats a number using K / M suffixes for readability.
+
+```typescript
+formatCompact(1_500_000, 'en') // => '1.5M'
+formatCompact(1_000, 'en')     // => '1K'
+formatCompact(999, 'en')       // => '999'
+```
+
+*Locale-aware formatting*
+
+Uses the provided locale for the decimal separator and suffix.
+
+```typescript
+formatCompact(1_500_000, 'fr') // => '1,5 M'
+```
+
+---
+
 ### `formatSize`
 
 Format a byte count into a human-readable string with the appropriate unit.
@@ -100,6 +146,128 @@ formatSize(1_073_741_824) // '1.0GB'
 
 ---
 
+### `inRange`
+
+Checks whether a number falls within `[min, max]` (both inclusive by default).
+
+```typescript
+import { inRange } from '@helpers4/number';
+
+inRange(value: number, min: number, max: number, options: InRangeOptions): boolean
+```
+
+**Parameters:**
+
+- `value: number` — The number to test
+- `min: number` — Lower bound
+- `max: number` — Upper bound
+- `options: InRangeOptions` (default: `{}`) — Boundary inclusion mode (default: `'both'`)
+
+**Returns:** `boolean` — `true` if `value` is within the specified range
+
+**Examples:**
+
+*Check if a value is within bounds (inclusive)*
+
+Both min and max are included by default.
+
+```typescript
+inRange(5, 1, 10)   // => true
+inRange(0, 1, 10)   // => false
+inRange(1, 1, 10)   // => true  (min included)
+inRange(10, 1, 10)  // => true  (max included)
+```
+
+*Exclusive range*
+
+Use { inclusive: "none" } for open interval (min, max).
+
+```typescript
+inRange(5, 1, 10, { inclusive: 'none' })  // => true
+inRange(1, 1, 10, { inclusive: 'none' })  // => false
+inRange(10, 1, 10, { inclusive: 'none' }) // => false
+```
+
+---
+
+### `lerp`
+
+Linearly interpolates between `start` and `end` by the factor `t`.
+
+- `t = 0` returns `start`.
+- `t = 1` returns `end`.
+- Values of `t` outside `[0, 1]` extrapolate beyond the range.
+
+```typescript
+import { lerp } from '@helpers4/number';
+
+lerp(start: number, end: number, t: number): number
+```
+
+**Parameters:**
+
+- `start: number` — The start value.
+- `end: number` — The end value.
+- `t: number` — The interpolation factor.
+
+**Returns:** `number` — The interpolated value.
+
+**Examples:**
+
+*Interpolate between two values*
+
+Returns the value between start and end at position t (0 = start, 1 = end).
+
+```typescript
+lerp(0, 100, 0)    // => 0
+lerp(0, 100, 0.5)  // => 50
+lerp(0, 100, 1)    // => 100
+```
+
+*Animate a colour channel*
+
+t outside [0, 1] extrapolates beyond the range.
+
+```typescript
+lerp(0, 255, 0.5) // => 127.5
+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)

package/meta/api.json

@@ -1,6 +1,6 @@
 {
   "category": "number",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0",
   "functions": [
     {
       "name": "clamp",
@@ -43,11 +43,53 @@
       ],
       "sourceFile": "clamp.ts"
     },
+    {
+      "name": "formatCompact",
+      "kind": "function",
+      "description": "Formats a number using compact notation (e.g. `1_500_000 → \"1.5M\"`).\n\nThin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion\nof `formatSize` in the same `format*` family.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "formatCompact(value: number, locale?: string): string",
+          "description": "Formats a number using compact notation (e.g. `1_500_000 → \"1.5M\"`).\n\nThin wrapper over `Intl.NumberFormat` with `notation: 'compact'`. Companion\nof `formatSize` in the same `format*` family.",
+          "params": [
+            {
+              "name": "value",
+              "type": "number",
+              "description": "The number to format."
+            },
+            {
+              "name": "locale",
+              "type": "string",
+              "description": "BCP 47 locale tag. Defaults to the runtime locale.",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "string",
+            "description": "A compact string representation of the number."
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Compact large numbers",
+          "description": "Formats a number using K / M suffixes for readability.",
+          "code": "formatCompact(1_500_000, 'en') // => '1.5M'\nformatCompact(1_000, 'en')     // => '1K'\nformatCompact(999, 'en')       // => '999'"
+        },
+        {
+          "title": "Locale-aware formatting",
+          "description": "Uses the provided locale for the decimal separator and suffix.",
+          "code": "formatCompact(1_500_000, 'fr') // => '1,5 M'"
+        }
+      ],
+      "sourceFile": "formatCompact.ts"
+    },
     {
       "name": "formatSize",
       "kind": "function",
       "description": "Format a byte count into a human-readable string with the appropriate unit.\n\nEach unit is 1024 of the previous (binary prefix). The result is formatted\nwith one decimal place.",
-      "since": "next",
+      "since": "2.0.0",
       "signatures": [
         {
           "signature": "formatSize(bytes: number): string",
@@ -74,6 +116,142 @@
       ],
       "sourceFile": "formatSize.ts"
     },
+    {
+      "name": "inRange",
+      "kind": "function",
+      "description": "Checks whether a number falls within `[min, max]` (both inclusive by default).",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "inRange(value: number, min: number, max: number, options: InRangeOptions): boolean",
+          "description": "Checks whether a number falls within `[min, max]` (both inclusive by default).",
+          "params": [
+            {
+              "name": "value",
+              "type": "number",
+              "description": "The number to test"
+            },
+            {
+              "name": "min",
+              "type": "number",
+              "description": "Lower bound"
+            },
+            {
+              "name": "max",
+              "type": "number",
+              "description": "Upper bound"
+            },
+            {
+              "name": "options",
+              "type": "InRangeOptions",
+              "description": "Boundary inclusion mode (default: `'both'`)",
+              "defaultValue": "{}"
+            }
+          ],
+          "returns": {
+            "type": "boolean",
+            "description": "`true` if `value` is within the specified range"
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Check if a value is within bounds (inclusive)",
+          "description": "Both min and max are included by default.",
+          "code": "inRange(5, 1, 10)   // => true\ninRange(0, 1, 10)   // => false\ninRange(1, 1, 10)   // => true  (min included)\ninRange(10, 1, 10)  // => true  (max included)"
+        },
+        {
+          "title": "Exclusive range",
+          "description": "Use { inclusive: \"none\" } for open interval (min, max).",
+          "code": "inRange(5, 1, 10, { inclusive: 'none' })  // => true\ninRange(1, 1, 10, { inclusive: 'none' })  // => false\ninRange(10, 1, 10, { inclusive: 'none' }) // => false"
+        }
+      ],
+      "sourceFile": "inRange.ts",
+      "relatedTypes": [
+        {
+          "name": "InRangeOptions",
+          "description": "Options for inRange.",
+          "typeDefinition": "interface InRangeOptions {\n  inclusive?: \"min\" | \"max\" | \"both\" | \"none\";\n}"
+        }
+      ]
+    },
+    {
+      "name": "lerp",
+      "kind": "function",
+      "description": "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.",
+      "since": "2.0.0",
+      "signatures": [
+        {
+          "signature": "lerp(start: number, end: number, t: number): number",
+          "description": "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.",
+          "params": [
+            {
+              "name": "start",
+              "type": "number",
+              "description": "The start value."
+            },
+            {
+              "name": "end",
+              "type": "number",
+              "description": "The end value."
+            },
+            {
+              "name": "t",
+              "type": "number",
+              "description": "The interpolation factor."
+            }
+          ],
+          "returns": {
+            "type": "number",
+            "description": "The interpolated value."
+          }
+        }
+      ],
+      "examples": [
+        {
+          "title": "Interpolate between two values",
+          "description": "Returns the value between start and end at position t (0 = start, 1 = end).",
+          "code": "lerp(0, 100, 0)    // => 0\nlerp(0, 100, 0.5)  // => 50\nlerp(0, 100, 1)    // => 100"
+        },
+        {
+          "title": "Animate a colour channel",
+          "description": "t outside [0, 1] extrapolates beyond the range.",
+          "code": "lerp(0, 255, 0.5) // => 127.5\nlerp(0, 10, 2)    // => 20  (extrapolation)"
+        }
+      ],
+      "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",

package/meta/examples.json

@@ -11,6 +11,21 @@
         }
       ]
     },
+    {
+      "name": "formatCompact",
+      "examples": [
+        {
+          "title": "Compact large numbers",
+          "description": "Formats a number using K / M suffixes for readability.",
+          "code": "formatCompact(1_500_000, 'en') // => '1.5M'\nformatCompact(1_000, 'en')     // => '1K'\nformatCompact(999, 'en')       // => '999'"
+        },
+        {
+          "title": "Locale-aware formatting",
+          "description": "Uses the provided locale for the decimal separator and suffix.",
+          "code": "formatCompact(1_500_000, 'fr') // => '1,5 M'"
+        }
+      ]
+    },
     {
       "name": "formatSize",
       "examples": [
@@ -21,6 +36,46 @@
         }
       ]
     },
+    {
+      "name": "inRange",
+      "examples": [
+        {
+          "title": "Check if a value is within bounds (inclusive)",
+          "description": "Both min and max are included by default.",
+          "code": "inRange(5, 1, 10)   // => true\ninRange(0, 1, 10)   // => false\ninRange(1, 1, 10)   // => true  (min included)\ninRange(10, 1, 10)  // => true  (max included)"
+        },
+        {
+          "title": "Exclusive range",
+          "description": "Use { inclusive: \"none\" } for open interval (min, max).",
+          "code": "inRange(5, 1, 10, { inclusive: 'none' })  // => true\ninRange(1, 1, 10, { inclusive: 'none' })  // => false\ninRange(10, 1, 10, { inclusive: 'none' }) // => false"
+        }
+      ]
+    },
+    {
+      "name": "lerp",
+      "examples": [
+        {
+          "title": "Interpolate between two values",
+          "description": "Returns the value between start and end at position t (0 = start, 1 = end).",
+          "code": "lerp(0, 100, 0)    // => 0\nlerp(0, 100, 0.5)  // => 50\nlerp(0, 100, 1)    // => 100"
+        },
+        {
+          "title": "Animate a colour channel",
+          "description": "t outside [0, 1] extrapolates beyond the range.",
+          "code": "lerp(0, 255, 0.5) // => 127.5\nlerp(0, 10, 2)    // => 20  (extrapolation)"
+        }
+      ]
+    },
+    {
+      "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": [

package/package.json

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