@rtorcato/js-common / numbers
numbers
Interfaces
FormatPercentOptions
Defined in: numbers/index.ts:42
Options for formatPercent.
Properties
fractionDigits?
optionalfractionDigits?:number
Defined in: numbers/index.ts:44
Number of decimal places (default: 0).
signed?
optionalsigned?:boolean
Defined in: numbers/index.ts:51
Force a leading + on positive values (e.g. +2.14%). Zero is never signed,
regardless of this option, since +0% / -0% reads as noise — this is decided
by the rounded, displayed value, so a value that rounds to zero at the given
fractionDigits is unsigned too. Default: false.
Functions
clamp()
clamp(
value,min,max):number
Defined in: numbers/index.ts:16
Clamps a number between a minimum and maximum value.
Example
clamp(15, 0, 10) // 10
clamp(-5, 0, 10) // 0
clamp(5, 0, 10) // 5
Parameters
value
number
The number to clamp.
min
number
The minimum value.
max
number
The maximum value.
Returns
number
The clamped value.
roundTo()
roundTo(
value,decimals?):number
Defined in: numbers/index.ts:34
Rounds a number to a specified number of decimal places.
Example
roundTo(3.14159) // 3.14
roundTo(3.14159, 3) // 3.142
roundTo(1234.5, 0) // 1235
Parameters
value
number
The number to round.
decimals?
number = 2
The number of decimal places. Defaults to 2.
Returns
number
The rounded number.
formatPercent()
formatPercent(
value,fractionDigitsOrOptions?):string
Defined in: numbers/index.ts:74
Formats a number as a percentage string.
value is always treated as a fraction (0.25 → "25%"), matching the existing
behaviour — it is not a pre-multiplied percentage (25 would format as "2500%").
Example
formatPercent(0.25) // '25%'
formatPercent(0.1234, 1) // '12.3%'
formatPercent(0.0214, { fractionDigits: 2, signed: true }) // '+2.14%'
formatPercent(-0.0088, { fractionDigits: 2, signed: true }) // '-0.88%'
formatPercent(0, { signed: true }) // '0%' (zero is never signed)
formatPercent(0.00001, { fractionDigits: 2, signed: true }) // '0.00%' (rounds to zero)
Parameters
value
number
The value to format, as a fraction (e.g. 0.25 for 25%).
fractionDigitsOrOptions?
number | FormatPercentOptions
Number of decimal places (default: 0), or an options object.
Returns
string
The formatted percentage string.
between()
between(
value,min,max,inclusive?):boolean
Defined in: numbers/index.ts:100
Checks if a number is between two values.
Parameters
value
number
The number to check.
min
number
The minimum value.
max
number
The maximum value.
inclusive?
boolean = true
Whether the range is inclusive (default: true).
Returns
boolean
True if the number is between min and max, false otherwise.
sum()
sum(
numbers):number
Defined in: numbers/index.ts:109
Returns the sum of an array of numbers.
Parameters
numbers
number[]
The array of numbers to sum.
Returns
number
The sum of the numbers.
average()
average(
numbers):number
Defined in: numbers/index.ts:118
Returns the average of an array of numbers.
Parameters
numbers
number[]
The array of numbers.
Returns
number
The average value, or 0 if the array is empty.
mod()
mod(
n,m):number
Defined in: numbers/index.ts:128
Returns the true mathematical modulus, handling negative numbers correctly.
Parameters
n
number
The dividend.
m
number
The divisor.
Returns
number
The modulus result.
variance()
variance(
numbers,options?):number
Defined in: numbers/index.ts:151
Returns the variance of an array of numbers.
Defaults to the population variance (divide by n). Pass
{ sample: true } for the sample variance (Bessel's correction, n - 1) —
the right choice when the values are a sample drawn from a larger population,
such as a volatility estimate.
Example
variance([2, 4, 4, 4, 5, 5, 7, 9]) // 4
variance([2, 4, 4, 4, 5, 5, 7, 9], { sample: true }) // 4.571428...
Parameters
numbers
number[]
The array of numbers.
options?
sample divides by n - 1 instead of n.
sample?
boolean
Returns
number
The variance, or 0 when there are too few values (empty array, or a
single value with sample: true).
stdDev()
stdDev(
numbers,options?):number
Defined in: numbers/index.ts:172
Returns the standard deviation of an array of numbers — the square root of variance, with the same population/sample choice.
Example
stdDev([2, 4, 4, 4, 5, 5, 7, 9]) // 2
stdDev([2, 4, 4, 4, 5, 5, 7, 9], { sample: true }) // 2.13808...
Parameters
numbers
number[]
The array of numbers.
options?
sample divides by n - 1 instead of n.
sample?
boolean
Returns
number
The standard deviation, or 0 when there are too few values.
median()
median(
numbers):number
Defined in: numbers/index.ts:189
Returns the median of an array of numbers. Even-length inputs return the mean of the two middle values. The input array is not mutated.
Example
median([3, 1, 2]) // 2
median([4, 1, 3, 2]) // 2.5
Parameters
numbers
number[]
The array of numbers.
Returns
number
The median, or 0 if the array is empty.
percentile()
percentile(
numbers,p):number
Defined in: numbers/index.ts:211
Returns the pth percentile of an array of numbers using linear
interpolation between closest ranks (the R-7 method, matching Excel's
PERCENTILE.INC and NumPy's default): the value at position
(n - 1) * p / 100 in the sorted values, interpolated between neighbours.
The input array is not mutated.
Example
percentile([1, 2, 3, 4], 50) // 2.5
percentile([1, 2, 3, 4], 25) // 1.75
percentile([1, 2, 3, 4], 100) // 4
Parameters
numbers
number[]
The array of numbers.
p
number
The percentile to compute, 0–100 (clamped).
Returns
number
The percentile value, or 0 if the array is empty.