Skip to content

Number API ​

clamp Clamp ​

Clamps a number to a closed interval.

Signature ​

ts
export function clamp(value: number, minimum: number, maximum: number): number;

Example ​

ts
import { clamp } from "@fast-china/utils";

const result = clamp(1, 1, 10);
console.log(result); // 1

Input ​

InputTypeRequired / defaultDescription
valuenumberRequiredNumber to clamp.
minimumnumberRequiredInclusive lower bound.
maximumnumberRequiredInclusive upper bound.

Returns ​

ValueTypeDescription
resultnumberValue satisfying minimum <= result <= maximum.

inRange Range ​

Checks whether a number lies within an interval.

Signature ​

ts
export function inRange(value: number, minimum: number, maximum: number, includeMaximum = false): boolean;

Example ​

ts
import { inRange } from "@fast-china/utils";

const result = inRange(1, 1, 10, false);
console.log(result); // true

Input ​

InputTypeRequired / defaultDescription
valuenumberRequiredNumber to check.
minimumnumberRequiredInclusive lower bound.
maximumnumberRequiredUpper bound.
includeMaximumunknownOptional; defaults to falseWhether the upper bound is inclusive; defaults to the half-open interval [minimum, maximum).

Returns ​

ValueTypeDescription
resultbooleantrue when the number satisfies the interval bounds.

roundTo Round ​

Rounds to a decimal precision.

Signature ​

ts
export function roundTo(value: number, digits = 0): number;

Example ​

ts
import { roundTo } from "@fast-china/utils";

const result = roundTo(1, 0);
console.log(result); // 1

Input ​

InputTypeRequired / defaultDescription
valuenumberRequiredFinite number.
digitsunknownOptional; defaults to 0Decimal places from -15 to 15; negative values mean tens, hundreds, and so on.

Returns ​

ValueTypeDescription
resultnumberNumber rounded using Math.round semantics.

sum Sum ​

Sums finite numbers.

Signature ​

ts
export function sum(values: readonly number[]): number;

Example ​

ts
import { sum } from "@fast-china/utils";

const result = sum([1, 2, 3]);
console.log(result); // 6

Input ​

InputTypeRequired / defaultDescription
valuesreadonly number[]RequiredNumber array; not mutated.

Returns ​

ValueTypeDescription
resultnumberArithmetic sum; empty input returns 0.

average Average ​

Calculates the arithmetic mean of finite numbers.

Signature ​

ts
export function average(values: readonly number[]): number | undefined;

Example ​

ts
import { average } from "@fast-china/utils";

const result = average([1, 2, 3]);
console.log(result); // 2

Input ​

InputTypeRequired / defaultDescription
valuesreadonly number[]RequiredNumber array; not mutated.

Returns ​

ValueTypeDescription
resultnumber | undefinedEmpty arrays or arrays containing only holes return undefined; holes do not contribute to the denominator.

lerp Interpolate ​

Linearly interpolates between two numbers.

Signature ​

ts
export function lerp(start: number, end: number, amount: number): number;

Example ​

ts
import { lerp } from "@fast-china/utils";

const result = lerp(0, 10, 1);

Input ​

InputTypeRequired / defaultDescription
startnumberRequiredStart at amount = 0.
endnumberRequiredEnd at amount = 1.
amountnumberRequiredInterpolation or extrapolation ratio.

Returns ​

ValueTypeDescription
resultnumberLinear result.

formatBytes Format ​

Omitting locale uses internal decimal formatting without Intl, retaining rounding, removal of trailing fractional zeros, and non-exponential output. Explicit locales continue to use Intl.NumberFormat without narrowing language support.

Nonnegative fractional byte counts are supported: formatBytes(0.5) returns "0.5 B", not a larger unit.

Formats nonnegative byte counts using SI or IEC units.

Signature ​

ts
export function formatBytes(bytes: number, options: FormatBytesOptions = {}): string;

Example ​

ts
import { formatBytes } from "@fast-china/utils";

const result = formatBytes(1_536, { base: 1024, decimals: 1 });

Input ​

InputTypeRequired / defaultDescription
bytesnumberRequiredNonnegative finite byte count.
optionsFormatBytesOptionsOptional; defaults to {}Base, decimal precision, and locale options.

Returns ​

ValueTypeDescription
resultstringFor example, 1.5 KiB.

randomInt Random ​

Generates a random integer in a half-open interval.

Signature ​

ts
export function randomInt(minimum: number, maximumExclusive: number): number;

Example ​

ts
import { randomInt } from "@fast-china/utils";

const result = randomInt(1, 10);

Input ​

InputTypeRequired / defaultDescription
minimumnumberRequiredInclusive safe-integer lower bound.
maximumExclusivenumberRequiredExclusive safe-integer upper bound; interval width is at most 2^32.

Returns ​

ValueTypeDescription
resultnumberRandom integer in [minimum, maximumExclusive).