Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sebamar88/bytekit/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The NumberUtils class provides comprehensive number utilities including locale-aware formatting, currency and percentage formatting, mathematical operations, random number generation, and statistical functions. All utilities are isomorphic and work in both Node.js and browser environments.
Source: workspace/source/src/utils/helpers/NumberUtils.ts:46
Interfaces
Options for number formatting.
interface FormatNumberOptions {
locale?: string; // Locale for formatting (e.g., 'en-US', 'es-AR')
minimumFractionDigits?: number; // Minimum fraction digits
maximumFractionDigits?: number; // Maximum fraction digits
useGrouping?: boolean; // Use grouping separators (thousands)
}
interface FormatCurrencyOptions extends FormatNumberOptions {
currency?: string; // Currency code (e.g., 'USD', 'EUR', 'ARS')
currencyDisplay?: "symbol" | "narrowSymbol" | "code" | "name";
}
interface FormatPercentOptions {
locale?: string; // Locale for formatting
decimals?: number; // Decimal places
isPercentage?: boolean; // Whether value is already a percentage
}
Methods
Format a number according to locale.
static format(
value: number,
locale?: string,
options?: FormatNumberOptions
): string
value: number - Number to formatlocale?: string - Locale codeoptions?: FormatNumberOptions - Formatting options
Returns: string - Formatted number string
Example:
import { NumberUtils } from 'bytekit';
NumberUtils.format(1234567.89, 'es-AR'); // '1.234.567,89'
NumberUtils.format(1234567.89, 'en-US'); // '1,234,567.89'
NumberUtils.format(3.14159, 'en-US', { maximumFractionDigits: 2 }); // '3.14'
currency
Format a number as currency.
static currency(
value: number,
currency: string = "USD",
locale?: string,
options?: FormatCurrencyOptions
): string
value: number - Amount to formatcurrency: string - Currency code (default: ‘USD’)locale?: string - Locale codeoptions?: FormatCurrencyOptions - Formatting options
Returns: string - Formatted currency string
Example:
NumberUtils.currency(99.99, 'USD'); // '$99.99'
NumberUtils.currency(1500, 'EUR', 'de-DE'); // '1.500,00 €'
NumberUtils.currency(2500.5, 'ARS', 'es-AR'); // '$ 2.500,50'
percentage
Format a number as percentage.
static percentage(value: number, options?: FormatPercentOptions): string
value: number - Value to format (0.5 = 50% by default)options?: FormatPercentOptions - Formatting options
Returns: string - Formatted percentage string
Example:
NumberUtils.percentage(0.456); // '45.6%'
NumberUtils.percentage(75, { isPercentage: true }); // '75%'
NumberUtils.percentage(0.3333, { decimals: 2 }); // '33.33%'
ordinal
Convert number to ordinal string.
static ordinal(value: number, locale: string = "en"): string
value: number - Number to convertlocale: string - Locale code (default: ‘en’)
Returns: string - Ordinal string
Example:
NumberUtils.ordinal(1); // '1st'
NumberUtils.ordinal(2); // '2nd'
NumberUtils.ordinal(3); // '3rd'
NumberUtils.ordinal(4); // '4th'
NumberUtils.ordinal(11); // '11th'
NumberUtils.ordinal(21); // '21st'
NumberUtils.ordinal(1, 'es'); // '1°'
clamp
Clamp a number between min and max values.
static clamp(value: number, min: number, max: number): number
value: number - Number to clampmin: number - Minimum valuemax: number - Maximum value
Returns: number - Clamped value
Example:
NumberUtils.clamp(150, 0, 100); // 100
NumberUtils.clamp(-50, 0, 100); // 0
NumberUtils.clamp(50, 0, 100); // 50
round
Round a number to specified decimal places.
static round(value: number, decimals: number = 0): number
value: number - Number to rounddecimals: number - Decimal places (default: 0)
Returns: number - Rounded number
Example:
NumberUtils.round(3.14159, 2); // 3.14
NumberUtils.round(3.14159, 4); // 3.1416
NumberUtils.round(1234.5, -2); // 1200 (round to hundreds)
floor
Floor a number to specified decimal places.
static floor(value: number, decimals: number = 0): number
value: number - Number to floordecimals: number - Decimal places (default: 0)
Returns: number - Floored number
Example:
NumberUtils.floor(3.999, 2); // 3.99
NumberUtils.floor(3.999); // 3
ceil
Ceil a number to specified decimal places.
static ceil(value: number, decimals: number = 0): number
value: number - Number to ceildecimals: number - Decimal places (default: 0)
Returns: number - Ceiled number
Example:
NumberUtils.ceil(3.001, 2); // 3.01
NumberUtils.ceil(3.001); // 4
range
Generate an array of numbers from start to end (inclusive).
static range(start: number, end: number, step: number = 1): number[]
start: number - Starting numberend: number - Ending number (inclusive)step: number - Step increment (default: 1)
Returns: number[] - Array of numbers
Throws: Error if step is zero
Example:
NumberUtils.range(1, 5); // [1, 2, 3, 4, 5]
NumberUtils.range(0, 10, 2); // [0, 2, 4, 6, 8, 10]
NumberUtils.range(5, 1); // [5, 4, 3, 2, 1]
random
Generate a random integer between min and max (inclusive).
static random(min: number, max: number): number
min: number - Minimum valuemax: number - Maximum value
Returns: number - Random integer
Example:
NumberUtils.random(1, 100); // Random number between 1 and 100
NumberUtils.random(1, 6); // Dice roll
randomFloat
Generate a random float between min and max.
static randomFloat(min: number, max: number, decimals: number = 2): number
min: number - Minimum valuemax: number - Maximum valuedecimals: number - Decimal places (default: 2)
Returns: number - Random float
Example:
NumberUtils.randomFloat(0, 1); // 0.47
NumberUtils.randomFloat(0, 100, 3); // 47.893
isEven
Check if a number is even.
static isEven(value: number): boolean
value: number - Number to check
Returns: boolean - True if even
Example:
NumberUtils.isEven(4); // true
NumberUtils.isEven(5); // false
isOdd
Check if a number is odd.
static isOdd(value: number): boolean
value: number - Number to check
Returns: boolean - True if odd
Example:
NumberUtils.isOdd(5); // true
NumberUtils.isOdd(4); // false
isInteger
Check if a number is an integer.
static isInteger(value: number): boolean
value: number - Number to check
Returns: boolean - True if integer
Example:
NumberUtils.isInteger(5); // true
NumberUtils.isInteger(5.5); // false
isFloat
Check if a number is a float (has decimal places).
static isFloat(value: number): boolean
value: number - Number to check
Returns: boolean - True if float
Example:
NumberUtils.isFloat(5.5); // true
NumberUtils.isFloat(5); // false
isPositive
Check if a number is positive.
static isPositive(value: number): boolean
value: number - Number to check
Returns: boolean - True if positive
Example:
NumberUtils.isPositive(5); // true
NumberUtils.isPositive(-5); // false
isNegative
Check if a number is negative.
static isNegative(value: number): boolean
value: number - Number to check
Returns: boolean - True if negative
Example:
NumberUtils.isNegative(-5); // true
NumberUtils.isNegative(5); // false
isBetween
Check if a number is between min and max (inclusive).
static isBetween(value: number, min: number, max: number): boolean
value: number - Number to checkmin: number - Minimum valuemax: number - Maximum value
Returns: boolean - True if value is between min and max
Example:
NumberUtils.isBetween(5, 1, 10); // true
NumberUtils.isBetween(0, 1, 10); // false
NumberUtils.isBetween(1, 1, 10); // true (inclusive)
toWords
Convert number to words.
static toWords(value: number, locale: string = "en"): string
value: number - Number to convertlocale: string - Locale (‘en’ or ‘es’, default: ‘en’)
Returns: string - Number in words
Example:
NumberUtils.toWords(123); // 'one hundred twenty-three'
NumberUtils.toWords(1000); // 'one thousand'
NumberUtils.toWords(123, 'es'); // 'ciento veintitrés'
Format bytes to human readable string.
static formatBytes(bytes: number, decimals: number = 2): string
bytes: number - Number of bytesdecimals: number - Decimal places (default: 2)
Returns: string - Formatted string
Example:
NumberUtils.formatBytes(1536); // '1.5 KB'
NumberUtils.formatBytes(1048576); // '1 MB'
NumberUtils.formatBytes(1073741824); // '1 GB'
parse
Parse a formatted number string back to number.
static parse(value: string, locale: string = "en"): number
value: string - Formatted number stringlocale: string - Locale code (default: ‘en’)
Returns: number - Parsed number
Example:
NumberUtils.parse('1,234.56'); // 1234.56
NumberUtils.parse('1.234,56', 'es'); // 1234.56
NumberUtils.parse('$1,234.56'); // 1234.56 (removes currency symbols)
pad
Add padding zeros to a number.
static pad(value: number, length: number): string
value: number - Number to padlength: number - Desired string length
Returns: string - Padded string
Example:
NumberUtils.pad(5, 3); // '005'
NumberUtils.pad(42, 5); // '00042'
sum
Calculate the sum of numbers.
static sum(values: number[]): number
values: number[] - Array of numbers
Returns: number - Sum of all numbers
Example:
NumberUtils.sum([1, 2, 3, 4, 5]); // 15
average
Calculate the average (mean) of numbers.
static average(values: number[]): number
values: number[] - Array of numbers
Returns: number - Average value (0 if empty)
Example:
NumberUtils.average([1, 2, 3, 4, 5]); // 3
mean
Alias for average.
static mean(values: number[]): number
Calculate the median of numbers.
static median(values: number[]): number
values: number[] - Array of numbers
Returns: number - Median value (0 if empty)
Example:
NumberUtils.median([1, 2, 3, 4, 5]); // 3
NumberUtils.median([1, 2, 3, 4]); // 2.5
mode
Calculate the mode (most frequent value) of numbers.
static mode(values: number[]): number | null
values: number[] - Array of numbers
Returns: number | null - Most frequent value or null if empty
Example:
NumberUtils.mode([1, 2, 2, 3, 3, 3]); // 3
min
Calculate the minimum value.
static min(values: number[]): number | null
values: number[] - Array of numbers
Returns: number | null - Minimum value or null if empty
Example:
NumberUtils.min([3, 1, 4, 1, 5]); // 1
max
Calculate the maximum value.
static max(values: number[]): number | null
values: number[] - Array of numbers
Returns: number | null - Maximum value or null if empty
Example:
NumberUtils.max([3, 1, 4, 1, 5]); // 5
standardDeviation
Calculate the standard deviation.
static standardDeviation(
values: number[],
population: boolean = true
): number
values: number[] - Array of numberspopulation: boolean - Use population formula (default: true)
Returns: number - Standard deviation (0 if empty)
Example:
const data = [2, 4, 4, 4, 5, 5, 7, 9];
NumberUtils.standardDeviation(data); // 2
variance
Calculate variance.
static variance(values: number[], population: boolean = true): number
values: number[] - Array of numberspopulation: boolean - Use population formula (default: true)
Returns: number - Variance (0 if empty)
Example:
const data = [2, 4, 4, 4, 5, 5, 7, 9];
NumberUtils.variance(data); // 4
percentile
Calculate percentile.
static percentile(values: number[], p: number): number
values: number[] - Array of numbersp: number - Percentile (0-100)
Returns: number - Percentile value (0 if empty)
Example:
const data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
NumberUtils.percentile(data, 90); // 9.1
NumberUtils.percentile(data, 50); // 5.5 (median)