ByteSize API Reference

Constants

zero

Added in v4.0.0 Source

The byte size containing zero bytes.

Signature

declare const zero: ByteSize

Constructors

bytes

Added in v4.0.0 Source

Creates a byte size from a non-negative byte count.

Signature

declare function bytes(value: number | bigint): ByteSize

exabytes

Added in v4.0.0 Source

Creates a decimal exabyte value.

Signature

declare const exabytes: (value: number | bigint) => ByteSize

exbibytes

Added in v4.0.0 Source

Creates a binary exbibyte value.

Signature

declare const exbibytes: (value: number | bigint) => ByteSize

fromInput

Added in v4.0.0 Source

Decodes an input into a byte size, returning None for invalid input.

Signature

declare const fromInput: (input: Input) => Option.Option<ByteSize>

fromInputUnsafe

Added in v4.0.0 Source

Decodes a trusted input into a byte size and throws for invalid input.

Signature

declare function fromInputUnsafe(input: Input): ByteSize

fromString

Added in v4.0.0 Source

Parses a byte-size string, returning None for invalid syntax, unsupported units, or quantities that do not represent non-negative integral bytes.

Details

Accepts external strings and fractional quantities using the same syntax as fromStringUnsafe.

See

fromStringUnsafe for throwing validation

Signature

declare const fromString: (input: string) => Option.Option<ByteSize>

fromStringUnsafe

Added in v4.0.0 Source

Parses a byte-size string and throws for invalid syntax, unsupported units, or quantities that do not represent non-negative integral bytes.

Details

Accepts decimal fractions, canonical SI and IEC symbols, lowercase unit names, and whitespace around the quantity and unit. Parsing uses exact bigint arithmetic, including above the safe integer range.

See

fromString for non-throwing validation

Signature

declare function fromStringUnsafe(input: string): ByteSize

gibibytes

Added in v4.0.0 Source

Creates a binary gibibyte value.

Signature

declare const gibibytes: (value: number | bigint) => ByteSize

gigabytes

Added in v4.0.0 Source

Creates a decimal gigabyte value.

Signature

declare const gigabytes: (value: number | bigint) => ByteSize

kibibytes

Added in v4.0.0 Source

Creates a binary kibibyte value.

Signature

declare const kibibytes: (value: number | bigint) => ByteSize

kilobytes

Added in v4.0.0 Source

Creates a decimal kilobyte value.

Signature

declare const kilobytes: (value: number | bigint) => ByteSize

mebibytes

Added in v4.0.0 Source

Creates a binary mebibyte value.

Signature

declare const mebibytes: (value: number | bigint) => ByteSize

megabytes

Added in v4.0.0 Source

Creates a decimal megabyte value.

Signature

declare const megabytes: (value: number | bigint) => ByteSize

pebibytes

Added in v4.0.0 Source

Creates a binary pebibyte value.

Signature

declare const pebibytes: (value: number | bigint) => ByteSize

petabytes

Added in v4.0.0 Source

Creates a decimal petabyte value.

Signature

declare const petabytes: (value: number | bigint) => ByteSize

quettabytes

Added in v4.0.0 Source

Creates a decimal quettabyte value.

Signature

declare const quettabytes: (value: number | bigint) => ByteSize

ronnabytes

Added in v4.0.0 Source

Creates a decimal ronnabyte value.

Signature

declare const ronnabytes: (value: number | bigint) => ByteSize

tebibytes

Added in v4.0.0 Source

Creates a binary tebibyte value.

Signature

declare const tebibytes: (value: number | bigint) => ByteSize

terabytes

Added in v4.0.0 Source

Creates a decimal terabyte value.

Signature

declare const terabytes: (value: number | bigint) => ByteSize

yobibytes

Added in v4.0.0 Source

Creates a binary yobibyte value.

Signature

declare const yobibytes: (value: number | bigint) => ByteSize

yottabytes

Added in v4.0.0 Source

Creates a decimal yottabyte value.

Signature

declare const yottabytes: (value: number | bigint) => ByteSize

zebibytes

Added in v4.0.0 Source

Creates a binary zebibyte value.

Signature

declare const zebibytes: (value: number | bigint) => ByteSize

zettabytes

Added in v4.0.0 Source

Creates a decimal zettabyte value.

Signature

declare const zettabytes: (value: number | bigint) => ByteSize

Converting

format

Added in v4.0.0 Source

Formats a byte size with canonical decimal or binary unit symbols.

Signature

declare function format(self: ByteSize, options: FormatOptions): string

toNumber

Added in v4.0.0 Source

Converts a byte size to a safe integer, returning None when it is too large.

Signature

declare const toNumber: (self: ByteSize) => Option.Option<number>

toUnit

Added in v4.0.0 Source

Converts a byte size to an approximate number of the specified unit.

Signature

declare const toUnit: {
  (unit: Unit): (self: ByteSize) => number;
  (self: ByteSize, unit: Unit): number;
}

Getters

toBigInt

Added in v4.0.0 Source

Returns the exact byte count as a bigint.

Signature

declare function toBigInt(self: ByteSize): bigint

Guards

isByteSize

Added in v4.0.0 Source

Checks whether a value is a byte size.

Signature

declare function isByteSize(input: unknown): input is ByteSize

Instances

Equivalence

Added in v4.0.0 Source

Provides an equivalence for byte sizes.

Signature

declare const Equivalence: Equ.Equivalence<ByteSize>

Order

Added in v4.0.0 Source

Provides an order for byte sizes.

Signature

declare const Order: order.Order<ByteSize>

Math

CombinerMax

Added in v4.0.0 Source

Combiner that keeps the largest byte size.

Signature

declare const CombinerMax: Combiner.Combiner<ByteSize>

CombinerMin

Added in v4.0.0 Source

Combiner that keeps the smallest byte size.

Signature

declare const CombinerMin: Combiner.Combiner<ByteSize>

divide

Added in v4.0.0 Source

Divides a byte size by a positive integer, discarding any remainder.

Signature

declare const divide: {
  (divisor: number | bigint): (self: ByteSize) => Option<ByteSize>;
  (self: ByteSize, divisor: number | bigint): Option<ByteSize>;
}

ReducerSum

Added in v4.0.0 Source

Reducer that sums byte sizes from zero.

Signature

declare const ReducerSum: Reducer.Reducer<ByteSize>

subtract

Added in v4.0.0 Source

Subtracts byte sizes, returning None on underflow.

Signature

declare const subtract: {
  (that: ByteSize): (self: ByteSize) => Option<ByteSize>;
  (self: ByteSize, that: ByteSize): Option<ByteSize>;
}

sum

Added in v4.0.0 Source

Adds two byte sizes exactly.

Signature

declare const sum: {
  (that: ByteSize): (self: ByteSize) => ByteSize;
  (self: ByteSize, that: ByteSize): ByteSize;
}

times

Added in v4.0.0 Source

Multiplies a byte size by a non-negative integer scalar.

Signature

declare const times: {
  (multiplier: number | bigint): (self: ByteSize) => Option<ByteSize>;
  (self: ByteSize, multiplier: number | bigint): Option<ByteSize>;
}

Models

BinaryUnit type

Added in v4.0.0 Source

Canonical binary byte unit symbols.

Signature

type BinaryUnit = "B" | "KiB" | "MiB" | "GiB" | "TiB" | "PiB" | "EiB" | "ZiB" | "YiB"

ByteSize type

Added in v4.0.0 Source

Represents an exact, non-negative number of bytes.

Signature

type ByteSize = Brand.Branded<bigint, typeof TypeId>

DecimalUnit type

Added in v4.0.0 Source

Canonical decimal byte unit symbols.

Signature

type DecimalUnit = "B" | "kB" | "MB" | "GB" | "TB" | "PB" | "EB" | "ZB" | "YB" | "RB" | "QB"

FormatOptions type

Added in v4.0.0 Source

Options controlling compact byte-size formatting.

Signature

type FormatOptions = {
  readonly precision?: number;
  readonly trailingZeros?: boolean;
} & {
  readonly system?: "decimal";
  readonly unit?: DecimalUnit;
} | {
  readonly system?: "binary";
  readonly unit?: BinaryUnit;
}

Input type

Added in v4.0.0 Source

Values accepted by byte-size decoding operations.

Details

String inputs require a non-negative decimal integer without leading zeros, followed by a canonical unit symbol or lowercase unit name, optionally separated by one space. Numeric inputs are validated at runtime.

See

fromString for external strings and fractional quantities
fromStringUnsafe for throwing string validation

Signature

type Input = ByteSize | bigint | number | `${IntegerQuantity}${"" | " "}${InputUnit}`

Unit type

Added in v4.0.0 Source

Canonical decimal and binary byte unit symbols.

Signature

type Unit = DecimalUnit | BinaryUnit

Ordering

clamp

Added in v4.0.0 Source

Constrains a byte size to an inclusive range.

Signature

declare const clamp: {
  (options: {
    maximum: ByteSize;
    minimum: ByteSize;
  }): (self: ByteSize) => ByteSize;
  (self: ByteSize, options: {
    maximum: ByteSize;
    minimum: ByteSize;
  }): ByteSize;
}

max

Added in v4.0.0 Source

Returns the larger byte size.

Signature

declare const max: {
  (that: ByteSize): (self: ByteSize) => ByteSize;
  (self: ByteSize, that: ByteSize): ByteSize;
}

min

Added in v4.0.0 Source

Returns the smaller byte size.

Signature

declare const min: {
  (that: ByteSize): (self: ByteSize) => ByteSize;
  (self: ByteSize, that: ByteSize): ByteSize;
}

Predicates

between

Added in v4.0.0 Source

Returns whether a byte size is in an inclusive range.

Signature

declare const between: {
  (options: {
    maximum: ByteSize;
    minimum: ByteSize;
  }): (self: ByteSize) => boolean;
  (self: ByteSize, options: {
    maximum: ByteSize;
    minimum: ByteSize;
  }): boolean;
}

equals

Added in v4.0.0 Source

Checks whether two byte sizes contain the same count.

Signature

declare const equals: {
  (that: ByteSize): (self: ByteSize) => boolean;
  (self: ByteSize, that: ByteSize): boolean;
}

isGreaterThan

Added in v4.0.0 Source

Checks whether the first byte size is greater than the second.

Signature

declare const isGreaterThan: {
  (that: ByteSize): (self: ByteSize) => boolean;
  (self: ByteSize, that: ByteSize): boolean;
}

isGreaterThanOrEqualTo

Added in v4.0.0 Source

Checks whether the first byte size is at least the second.

Signature

declare const isGreaterThanOrEqualTo: {
  (that: ByteSize): (self: ByteSize) => boolean;
  (self: ByteSize, that: ByteSize): boolean;
}

isLessThan

Added in v4.0.0 Source

Checks whether the first byte size is less than the second.

Signature

declare const isLessThan: {
  (that: ByteSize): (self: ByteSize) => boolean;
  (self: ByteSize, that: ByteSize): boolean;
}

isLessThanOrEqualTo

Added in v4.0.0 Source

Checks whether the first byte size is at most the second.

Signature

declare const isLessThanOrEqualTo: {
  (that: ByteSize): (self: ByteSize) => boolean;
  (self: ByteSize, that: ByteSize): boolean;
}

isZero

Added in v4.0.0 Source

Checks whether a byte size is zero.

Signature

declare function isZero(self: ByteSize): boolean

Unsafe

subtractUnsafe

Added in v4.0.0 Source

Subtracts byte sizes and throws on underflow.

Signature

declare const subtractUnsafe: {
  (that: ByteSize): (self: ByteSize) => ByteSize;
  (self: ByteSize, that: ByteSize): ByteSize;
}

toNumberUnsafe

Added in v4.0.0 Source

Converts a byte size to a safe integer and throws when it is too large.

Signature

declare function toNumberUnsafe(self: ByteSize): number