@helpers4/number 2.0.0-alpha.2 → 2.0.0-alpha.21

package/README.md

@@ -9,20 +9,24 @@ A set of helpers for working with URLs.
 
 ## Documentation
 
-[https://helpers4.js.org/number](https://helpers4.js.org/number)
+[https://helpers4.dev/typescript/categories/number/](https://helpers4.dev/typescript/categories/number/)
 
 <!-- AUTOMATIC-METHODS -->
 - clamp
-- roundTo
+- formatSize
 - random
+- roundTo
+- sum
 <!-- /AUTOMATIC-METHODS -->
 
 ## See
 
 <!-- AUTOMATIC-SIBLINGS -->
 - [array](../array)
+- [commit](../commit)
 - [date](../date)
 - [function](../function)
+- [math](../math)
 - [object](../object)
 - [observable](../observable)
 - [promise](../promise)
@@ -38,14 +42,16 @@ 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 |
-| date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | date 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 |
-| number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | number utilities |
+| 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 |
+| 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 |
 | promise | [@helpers4/promise](https://www.npmjs.com/package/@helpers4/promise) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/promise) | Promise utilities and error handling |
 | string | [@helpers4/string](https://www.npmjs.com/package/@helpers4/string) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/string) | String manipulation and formatting utilities |
-| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | type utilities |
+| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | Type checking and validation utilities |
 | url | [@helpers4/url](https://www.npmjs.com/package/@helpers4/url) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/url) | URL parsing and manipulation utilities |
 | version | [@helpers4/version](https://www.npmjs.com/package/@helpers4/version) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/version) | Version string manipulation utilities |
 <!-- /AUTOMATIC-CATEGORIES-TABLE -->

package/lib/index.d.ts

@@ -1,4 +1,92 @@
-export declare function clamp(value: number, min: number, max: number): number;
-export declare function roundTo(value: number, decimals: number): number;
-export declare function randomBetween(min: number, max: number): number;
-export declare function randomIntBetween(min: number, max: number): number;
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Clamps a number between min and max values
+ * @param value - The value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ * @since 1.9.0
+ */
+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
+ */
+/**
+ * Format a byte count into a human-readable string with the appropriate unit.
+ *
+ * Each unit is 1024 of the previous (binary prefix). The result is formatted
+ * with one decimal place.
+ *
+ * @param bytes - A non-negative integer representing a byte count.
+ * @returns A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.
+ * @example
+ * formatSize(0)               // '0.0B'
+ * formatSize(512)             // '512.0B'
+ * formatSize(1024)            // '1.0KB'
+ * formatSize(1536)            // '1.5KB'
+ * formatSize(1_048_576)       // '1.0MB'
+ * formatSize(1_073_741_824)   // '1.0GB'
+ * @since next
+ */
+declare function formatSize(bytes: number): string;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Generates a random number between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random number between min and max
+ * @since 1.9.0
+ */
+declare function randomBetween(min: number, max: number): number;
+/**
+ * Generates a random integer between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random integer between min and max
+ * @since 1.9.0
+ */
+declare function randomIntBetween(min: number, max: number): number;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Rounds a number to specified decimal places
+ * @param value - The number to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded number
+ * @since 1.9.0
+ */
+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, formatSize, randomBetween, randomIntBetween, roundTo, sum };

package/lib/index.js

@@ -1,22 +1,126 @@
-// helpers/number/clamp.ts
+//#region helpers/number/clamp.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Clamps a number between min and max values
+* @param value - The value to clamp
+* @param min - Minimum value
+* @param max - Maximum value
+* @returns Clamped value
+* @since 1.9.0
+*/
 function clamp(value, min, max) {
-  return Math.min(Math.max(value, min), max);
+	return Math.min(Math.max(value, min), max);
 }
-// helpers/number/roundTo.ts
-function roundTo(value, decimals) {
-  const multiplier = Math.pow(10, decimals);
-  return Math.round(value * multiplier) / multiplier;
+//#endregion
+//#region helpers/number/formatSize.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/** Size units in ascending order. */
+var UNITS = [
+	"B",
+	"KB",
+	"MB",
+	"GB",
+	"TB"
+];
+/**
+* Format a byte count into a human-readable string with the appropriate unit.
+*
+* Each unit is 1024 of the previous (binary prefix). The result is formatted
+* with one decimal place.
+*
+* @param bytes - A non-negative integer representing a byte count.
+* @returns A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.
+* @example
+* formatSize(0)               // '0.0B'
+* formatSize(512)             // '512.0B'
+* formatSize(1024)            // '1.0KB'
+* formatSize(1536)            // '1.5KB'
+* formatSize(1_048_576)       // '1.0MB'
+* formatSize(1_073_741_824)   // '1.0GB'
+* @since next
+*/
+function formatSize(bytes) {
+	let size = bytes;
+	let unitIndex = 0;
+	while (size >= 1024 && unitIndex < UNITS.length - 1) {
+		size /= 1024;
+		unitIndex++;
+	}
+	return `${size.toFixed(1)}${UNITS[unitIndex]}`;
 }
-// helpers/number/random.ts
+//#endregion
+//#region helpers/number/random.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Generates a random number between min and max (inclusive)
+* @param min - Minimum value
+* @param max - Maximum value
+* @returns Random number between min and max
+* @since 1.9.0
+*/
 function randomBetween(min, max) {
-  return Math.random() * (max - min) + min;
+	return Math.random() * (max - min) + min;
 }
+/**
+* Generates a random integer between min and max (inclusive)
+* @param min - Minimum value
+* @param max - Maximum value
+* @returns Random integer between min and max
+* @since 1.9.0
+*/
 function randomIntBetween(min, max) {
-  return Math.floor(Math.random() * (max - min + 1)) + min;
+	return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+//#endregion
+//#region helpers/number/roundTo.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Rounds a number to specified decimal places
+* @param value - The number to round
+* @param decimals - Number of decimal places
+* @returns Rounded number
+* @since 1.9.0
+*/
+function roundTo(value, decimals) {
+	const multiplier = Math.pow(10, 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);
 }
-export {
-  roundTo,
-  randomIntBetween,
-  randomBetween,
-  clamp
-};
+//#endregion
+export { clamp, formatSize, randomBetween, randomIntBetween, roundTo, sum };
+
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +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"}

package/llms.txt

@@ -0,0 +1,236 @@
+# @helpers4/number
+
+> Tree-shakable TypeScript utility functions for the `number` domain.
+> Package: `@helpers4/number` — Version: 2.0.0-alpha.21
+> License: LGPL-3.0-or-later
+
+## Installation
+
+```sh
+npm install @helpers4/number
+# or
+pnpm add @helpers4/number
+```
+
+## Usage
+
+```typescript
+import { clamp, formatSize, randomBetween, ... } from '@helpers4/number';
+```
+
+## Functions
+
+| Function | Description |
+|---|---|
+| `clamp` | Clamps a number between min and max values |
+| `formatSize` | Format a byte count into a human-readable string with the appropriate unit.  Each unit is 1024 of th |
+| `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. |
+
+---
+
+## API Reference
+
+### `clamp`
+
+Clamps a number between min and max values
+
+```typescript
+import { clamp } from '@helpers4/number';
+
+clamp(value: number, min: number, max: number): number
+```
+
+**Parameters:**
+
+- `value: number` — The value to clamp
+- `min: number` — Minimum value
+- `max: number` — Maximum value
+
+**Returns:** `number` — Clamped value
+
+**Examples:**
+
+*Clamp a value within range*
+
+Restricts a number to be within a min/max range.
+
+```typescript
+clamp(15, 0, 10)  // => 10
+clamp(-5, 0, 10)  // => 0
+clamp(5, 0, 10)   // => 5
+```
+
+---
+
+### `formatSize`
+
+Format a byte count into a human-readable string with the appropriate unit.
+
+Each unit is 1024 of the previous (binary prefix). The result is formatted
+with one decimal place.
+
+```typescript
+import { formatSize } from '@helpers4/number';
+
+formatSize(bytes: number): string
+```
+
+**Parameters:**
+
+- `bytes: number` — A non-negative integer representing a byte count.
+
+**Returns:** `string` — A human-readable string such as `'0.0B'`, `'1.5KB'`, `'3.2MB'`.
+
+**Examples:**
+
+*Format bytes to human-readable size*
+
+Converts a raw byte count to a human-readable string using binary prefixes.
+
+```typescript
+formatSize(0)             // '0.0B'
+formatSize(512)           // '512.0B'
+formatSize(1024)          // '1.0KB'
+formatSize(1_048_576)     // '1.0MB'
+formatSize(1_073_741_824) // '1.0GB'
+```
+
+---
+
+### `randomBetween`
+
+Generates a random number between min and max (inclusive)
+
+```typescript
+import { randomBetween } from '@helpers4/number';
+
+randomBetween(min: number, max: number): number
+```
+
+**Parameters:**
+
+- `min: number` — Minimum value
+- `max: number` — Maximum value
+
+**Returns:** `number` — Random number between min and max
+
+**Examples:**
+
+*Generate a random float in range*
+
+Returns a random number between min and max (inclusive).
+
+```typescript
+randomBetween(1, 10)
+// => e.g. 5.327...
+```
+
+*Generate a random integer in range*
+
+Returns a random integer between min and max (inclusive).
+
+```typescript
+randomIntBetween(1, 6)
+// => e.g. 4
+```
+
+---
+
+### `randomIntBetween`
+
+Generates a random integer between min and max (inclusive)
+
+```typescript
+import { randomIntBetween } from '@helpers4/number';
+
+randomIntBetween(min: number, max: number): number
+```
+
+**Parameters:**
+
+- `min: number` — Minimum value
+- `max: number` — Maximum value
+
+**Returns:** `number` — Random integer between min and max
+
+---
+
+### `roundTo`
+
+Rounds a number to specified decimal places
+
+```typescript
+import { roundTo } from '@helpers4/number';
+
+roundTo(value: number, decimals: number): number
+```
+
+**Parameters:**
+
+- `value: number` — The number to round
+- `decimals: number` — Number of decimal places
+
+**Returns:** `number` — Rounded number
+
+**Examples:**
+
+*Round to 2 decimal places*
+
+Rounds a floating-point number to the specified number of decimals.
+
+```typescript
+roundTo(3.14159, 2)
+// => 3.14
+```
+
+*Round to 0 decimal places*
+
+Effectively rounds to the nearest integer.
+
+```typescript
+roundTo(3.7, 0)
+// => 4
+```
+
+---
+
+### `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
+```
+
+---