@magnaboy/unit-types

Byte counts, durations, sample rates, frame rates, capacity reservations and basis points as separate types. A byte count cannot be passed where a frame rate is required, and the arithmetic stays on the type.

Install

npm i @magnaboy/unit-types

Requires Node 25+ and ESM. No runtime dependencies.

import { ByteCount, Duration, FrameRate, SAMPLE_RATE } from '@magnaboy/unit-types';

const budget = ByteCount.kib(256);
const frame = FrameRate.new(30).time(FrameIndex.new(1));
const samples = SAMPLE_RATE.wholeMillis(10);

Values that can exceed Number.MAX_SAFE_INTEGER are bigint. Constructors also accept a safe integer. Duration stores nanoseconds. clockMillis is the conversion into the millisecond control clock.

milliseconds, seconds, minutes, hours and days build a Duration from a number. A whole count is exact; a fractional count rounds to the nearest millisecond, so seconds(1.1) is 1100ms. asMillisNumber() and asSecsNumber() read whole units back as a number (throwing past Number.MAX_SAFE_INTEGER), and asSecsF64() keeps the fraction.

BasisPoints holds hundredths of a percent as a u32; BasisPoints.PER_WHOLE is 10_000. ratio() gives the fraction, of(amount) takes a truncated bigint share, and complement() gives the rest of the whole.

Percent holds a non-negative number percentage; Percent.WHOLE is 100% and values above it scale up. factor() gives the multiplier, of(value) and floorOf(value) take a share of a number, plus and saturatingSub build modified percentages, and complement() gives the rest of the whole.