Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

ByteSize unstable

Represents exact, non-negative, integral byte counts.

Decimal units use powers of 1,000 and binary units use powers of 1,024.

56 exports Since v4.0.0 Source

Constants

zero

unstable
Since v4.0.0

The byte size containing zero bytes.

Signature

declare const zero: ByteSize

Constructors

bytes

unstable
Since v4.0.0

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

Signature

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

exabytes

unstable
Since v4.0.0

Creates a decimal exabyte value.

Signature

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

exbibytes

unstable
Since v4.0.0

Creates a binary exbibyte value.

Signature

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

fromInput

unstable
Since v4.0.0

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

Signature

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

fromInputUnsafe

unstable
Since v4.0.0

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

Signature

declare function fromInputUnsafe(input: Input): ByteSize

fromString

unstable
Since v4.0.0

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

Signature

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

fromStringUnsafe

unstable
Since v4.0.0

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

Signature

declare function fromStringUnsafe(input: string): ByteSize

gibibytes

unstable
Since v4.0.0

Creates a binary gibibyte value.

Signature

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

gigabytes

unstable
Since v4.0.0

Creates a decimal gigabyte value.

Signature

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

kibibytes

unstable
Since v4.0.0

Creates a binary kibibyte value.

Signature

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

kilobytes

unstable
Since v4.0.0

Creates a decimal kilobyte value.

Signature

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

mebibytes

unstable
Since v4.0.0

Creates a binary mebibyte value.

Signature

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

megabytes

unstable
Since v4.0.0

Creates a decimal megabyte value.

Signature

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

pebibytes

unstable
Since v4.0.0

Creates a binary pebibyte value.

Signature

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

petabytes

unstable
Since v4.0.0

Creates a decimal petabyte value.

Signature

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

quettabytes

unstable
Since v4.0.0

Creates a decimal quettabyte value.

Signature

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

ronnabytes

unstable
Since v4.0.0

Creates a decimal ronnabyte value.

Signature

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

tebibytes

unstable
Since v4.0.0

Creates a binary tebibyte value.

Signature

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

terabytes

unstable
Since v4.0.0

Creates a decimal terabyte value.

Signature

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

yobibytes

unstable
Since v4.0.0

Creates a binary yobibyte value.

Signature

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

yottabytes

unstable
Since v4.0.0

Creates a decimal yottabyte value.

Signature

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

zebibytes

unstable
Since v4.0.0

Creates a binary zebibyte value.

Signature

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

zettabytes

unstable
Since v4.0.0

Creates a decimal zettabyte value.

Signature

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

Converting

format

unstable
Since v4.0.0

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

Signature

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

toNumber

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Returns the exact byte count as a bigint.

Signature

declare function toBigInt(self: ByteSize): bigint

Guards

isByteSize

unstable
Since v4.0.0

Checks whether a value is a byte size.

Signature

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

Instances

Equivalence

unstable
Since v4.0.0

Provides an equivalence for byte sizes.

Signature

declare const Equivalence: Equ.Equivalence<ByteSize>

Order

unstable
Since v4.0.0

Provides an order for byte sizes.

Signature

declare const Order: order.Order<ByteSize>

Math

CombinerMax

unstable
Since v4.0.0

Combiner that keeps the largest byte size.

Signature

declare const CombinerMax: Combiner.Combiner<ByteSize>

CombinerMin

unstable
Since v4.0.0

Combiner that keeps the smallest byte size.

Signature

declare const CombinerMin: Combiner.Combiner<ByteSize>

divide

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Reducer that sums byte sizes from zero.

Signature

declare const ReducerSum: Reducer.Reducer<ByteSize>

subtract

unstable
Since v4.0.0

Subtracts byte sizes, returning None on underflow.

Signature

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

sum

unstable
Since v4.0.0

Adds two byte sizes exactly.

Signature

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

times

unstable
Since v4.0.0

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 unstable
Since v4.0.0

Canonical binary byte unit symbols.

Signature

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

ByteSize

type unstable
Since v4.0.0

Represents an exact, non-negative number of bytes.

Signature

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

DecimalUnit

type unstable
Since v4.0.0

Canonical decimal byte unit symbols.

Signature

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

FormatOptions

type unstable
Since v4.0.0

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 unstable
Since v4.0.0

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

Signature

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

Unit

type unstable
Since v4.0.0

Canonical decimal and binary byte unit symbols.

Signature

type Unit = DecimalUnit | BinaryUnit

Ordering

clamp

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Returns the larger byte size.

Signature

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

min

unstable
Since v4.0.0

Returns the smaller byte size.

Signature

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

Predicates

between

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Checks whether two byte sizes contain the same count.

Signature

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

isGreaterThan

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

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

unstable
Since v4.0.0

Checks whether a byte size is zero.

Signature

declare function isZero(self: ByteSize): boolean

Unsafe

subtractUnsafe

unstable
Since v4.0.0

Subtracts byte sizes and throws on underflow.

Signature

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

toNumberUnsafe

unstable
Since v4.0.0

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

Signature

declare function toNumberUnsafe(self: ByteSize): number