shelving/util/numbermodule

Type guards, conversions, rounding, clamping, and arithmetic utilities for numbers. The conversion functions (getNumber(), getInteger()) accept strings and Date instances as well as raw numbers, and always return a finite value or undefined — never NaN or Infinity.

Things to know:

  • isNumber() and isInteger() accept optional min/max bounds so you can validate a range in one call.
  • getNumber strips non-numeric characters from strings before parsing, making it tolerant of formatted input like "$1,200.50".
  • -0 is normalised to 0 by both getNumber and getInteger.
  • boundNumber() clamps to [min, max]; wrapNumber() wraps around like a clock (works in both directions).
  • roundNumber() trims trailing zeros, unlike num.toFixed().

Usage

Type guards and conversion

ts
import { isNumber, isInteger, getNumber, getInteger, requireNumber, requireInteger } from "shelving/util";

isNumber(42);           // true
isNumber(NaN);          // false
isNumber(5, 1, 10);     // true  (within range)
isNumber(0, 1, 10);     // false (below min)

getNumber("$1,200.50"); // 1200.5  (non-numeric chars stripped)
getNumber("hello");     // undefined
getNumber(new Date(0)); // 0  (milliseconds)

requireNumber("42", 0, 100); // 42
requireInteger("7");         // 7

Rounding and truncation

ts
import { roundNumber, truncateNumber, roundStep } from "shelving/util";

roundNumber(3.14159, 2);  // 3.14
truncateNumber(3.99, 1);  // 3.9
roundStep(17, 5);         // 15  (nearest multiple of 5)

Clamping and wrapping

ts
import { boundNumber, wrapNumber, isBetween } from "shelving/util";

boundNumber(12, 2, 8);  // 8   (clamped to max)
wrapNumber(12, 2, 8);   // 6   (wraps around)
wrapNumber(-2, 2, 8);   // 4   (wraps in reverse)

isBetween(5, 1, 10);    // true

Utilities

ts
import { getPercent, sumNumbers, getClosestNumber } from "shelving/util";

getPercent(25, 200);              // 12.5  (25 is 12.5% of 200)
sumNumbers([1, 2, 3, 4]);         // 10
getClosestNumber([1, 5, 10], 4);  // 5

Functions

Go

isNumber()function

Is a value a finite number (optionally within a specified min/max range)?

isNumber(value: unknown, min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY): value is number
Go

assertNumber()function

Assert that a value is a finite number (optionally within a specified min/max range).

assertNumber(value: unknown, min?: number, max?: number, caller: AnyCaller = assertNumber): asserts value is number
Go

getNumber()function

Convert an unknown value to a finite number, or return undefined if it cannot be converted.

getNumber(value: unknown): number | undefined
Go

requireNumber()function

Convert a possible number to a finite number, or throw ValueError if the value cannot be converted.

requireNumber(value: PossibleNumber, min?: number, max?: number, caller?: AnyCaller): number
Go

isInteger()function

Is an unknown value an integer (optionally within specified min/max values)?

isInteger(value: unknown, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER): value is number
Go

assertInteger()function

Assert that a value is an integer (optionally within specified min/max values).

assertInteger(value: unknown, min?: number, max?: number, caller: AnyCaller = assertInteger): asserts value is number
Go

getInteger()function

Convert an unknown value to an integer, or return undefined if it cannot be converted.

getInteger(value: unknown): number | undefined
Go

requireInteger()function

Convert a possible number to an integer, or throw ValueError if the value cannot be converted.

requireInteger(value: PossibleNumber, min?: number, max?: number, caller: AnyCaller = requireInteger): number
Go

isBetween()function

Is a number within a specified range?

isBetween(num: number, min: number, max: number): boolean
Go

roundStep()function

Round numbers to a given step.

roundStep(num: number, step = 1): number
Go

roundNumber()function

Round a number to a specified set of decimal places.

roundNumber(num: number, precision = 0): number
Go

truncateNumber()function

Truncate a number to a specified set of decimal places.

truncateNumber(num: number, precision = 0): number
Go

boundNumber()function

Bound a number between two values.

boundNumber(num: number, min: number, max: number): number
Go

wrapNumber()function

Wrap a number between two values.

wrapNumber(num: number, min: number, max: number): number
Go

getPercent()function

Get a number as a percentage of another number.

getPercent(numerator: number, denumerator = 100): void
Go

sumNumbers()function

Sum an iterable set of numbers and return the total.

sumNumbers(nums: Iterable<number>): number
Go

getClosestNumber()function

Find the number that's closest to a target in an iterable set of numbers.

getClosestNumber(nums: Iterable<T>, target: number): T | undefined

Types

Go

PossibleNumbertype

Values that can be converted to a number.

number | string | Date