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

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.

Signature

type Input = ByteSize | bigint | number | string

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