Numeric Utilities

# clamp function

      signature
      
clamp(lo: number, hi: number, value: number): number

Clamps value to the closed interval [lo, hi].

Useful when mapping statistical outputs (e.g. probabilities, normalised scores) to a bounded domain before rendering.

Parameters

Name	Type	Description
lo	number	Lower bound (inclusive).
hi	number	Upper bound (inclusive).
value	number	The value to clamp.

Returns

number

lo if value < lo, hi if value > hi, otherwise value.

Example

clamp(0, 1, -0.3)  // 0
clamp(0, 1, 1.7)   // 1
clamp(0, 1, 0.5)   // 0.5

// Partial application — create a unit-clamp helper
const unitClamp = clamp(0, 1);
unitClamp(sigmoid(-100))  // 0 (not quite, but clamped to 0)

# isFiniteNumber function

packages/math/src/numeric.ts:46

      signature
      
isFiniteNumber(value: unknown): boolean

Returns true when value is a finite, non-NaN number (i.e., safe for arithmetic). Rejects NaN, Infinity, -Infinity, null, and undefined.

Replaces the inline isValid guard scattered across @statili/stats regression methods.

Parameters

Name	Type	Description
value	unknown	Any value to test.

Returns

boolean

true if value is a finite number, false otherwise.

Example

isFiniteNumber(3.14)      // true
isFiniteNumber(NaN)       // false
isFiniteNumber(Infinity)  // false
isFiniteNumber(null)      // false

# lerp function

packages/math/src/numeric.ts:95

      signature
      
lerp(a: number, b: number, t: number): number

Linearly interpolates between a and b by factor t.

t = 0 returns a
t = 1 returns b
t = 0.5 returns the midpoint
Values outside [0, 1] extrapolate beyond the endpoints

Handy for generating evenly-spaced prediction points along a regression curve or animating transitions between two chart states.

Parameters

Name	Type	Description
a	number	Start value.
b	number	End value.
t	number	Interpolation factor (typically `[0, 1]`).

Returns

number

a + (b - a) * t

Example

lerp(0, 10, 0.5)   // 5
lerp(2, 8, 0.25)   // 3.5
lerp(0, 100, 1.1)  // 110  (extrapolation)

# round function

packages/math/src/numeric.ts:24

      signature
      
round(precision: number, value: number): number

Rounds a number to a given decimal precision using the 10^precision factor strategy. Handles edge-cases where precision is undefined, null, or non-finite by returning the raw value unchanged.

Partial-application pattern — precision is the infrequently-changing “config” argument, so it sits first, making it easy to create specialised rounding helpers:

Parameters

Name	Type	Description
precision	number	Number of decimal places to round to (e.g. `2` → `1.235` rounds to `1.24`). Pass `0` for integer rounding.
value	number	The number to round.

Returns

number

The rounded number, or value unchanged when precision is not a finite number.

Example

round(2, 1.2345)  // 1.23
round(0, 3.7)     // 4

// Partial application
const toCents = round(2);
toCents(19.999)   // 20