byte-size-parser

npm install @ferrow/byte-size-parser

Parse byte sizes with explicit binary/decimal distinction; KB vs KiB; format bytes back.

Quick Start

import { parse, format } from "byte-size-parser";

// Parse with explicit unit clarity
parse("1 KB");           // 1000 (decimal)
parse("1 KiB");          // 1024 (binary)
parse("1.5 GB");         // 1500000000

// Format back
format(1500000000);                        // "1.5 GB" (decimal)
format(1500000000, { binary: true });     // "1.4 GiB" (binary)

API

parse(input: string, opts?: ParseOptions): number

Parse byte size to bytes. Supports:

• Bare numbers: "1000000" → 1000000 bytes
• Decimal (1000-based): "1.5 GB", "512 KB"
• Binary (1024-based): "1 KiB", "512 MiB", "1.5 GiB"

Unit precision:

• Decimal: B, KB, MB, GB, TB, PB
• Binary: B, KiB, MiB, GiB, TiB, PiB

Aliases: "k"/"kb"/"kilobyte" → KB, "m"/"mb"/"megabyte" → MB, "kib"/"kibibyte" → KiB, etc.

Options:

• defaultBinary?: boolean — Treat ambiguous aliases as binary (default: false)

Throws Error on invalid format.

format(bytes: number, opts?: FormatOptions): string

Format bytes to human-readable size.

Options:

• binary?: boolean — Use binary units (KiB, MiB) instead of decimal (default: false)
• precision?: number — Decimal places (default: 2), trailing zeros stripped

Limitations

• No locale-specific formatting (no commas/spaces as thousands separator)
• No support for units beyond PiB
• "K/M/G" alone interpreted as decimal (KB/MB/GB) by default

---

Part of the ferrow-toolkit collection · Sponsored by Ferrow