# @helpers4/number

> Tree-shakable TypeScript utility functions for the `number` domain.
> Package: `@helpers4/number` — Version: 2.0.0
> License: LGPL-3.0-or-later

## Installation

```sh
npm install @helpers4/number
# or
pnpm add @helpers4/number
```

## Usage

```typescript
import { clamp, formatCompact, formatSize, ... } from '@helpers4/number';
```

## Functions

| 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 |
| `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
```

---

### `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.

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'
```

---

### `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)

```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
```

---
