⚠️ DEPRECATED

This package is no longer maintained.

Please use html-entities instead. See: https://www.npmjs.com/package/html-entities

Original README below:

format-byte-size

A TypeScript library to format byte values into human-readable strings and parse them back.

Features

• 🎯 Format bytes to human-readable strings (e.g., "1.23 MB", "512 KiB")
• 🔄 Parse human-readable strings back to numeric byte values
• 📊 Support for both decimal (KB, MB, GB) and binary (KiB, MiB, GiB) units
• 🎨 Customizable formatting options (decimal places, spacing, fixed decimals)
• 📦 Zero runtime dependencies
• 🌳 Tree-shakeable ESM and CommonJS builds
• 💪 Full TypeScript support with strict typing
• ✅ Thoroughly tested

Installation

npm install format-byte-size

Usage

Basic Usage

import { formatBytes, parseBytes } from 'format-byte-size';

// Format bytes to human-readable strings
formatBytes(1234); // "1.23 KB"
formatBytes(1234567890); // "1.23 GB"
formatBytes(1024); // "1.02 KB"

// Parse human-readable strings to bytes
parseBytes('1.23 KB'); // 1230
parseBytes('512 MiB'); // 536870912
parseBytes('1GB'); // 1000000000

Formatting Options

// Use binary units (base 1024)
formatBytes(1024, { useBinary: true }); // "1 KiB"
formatBytes(1048576, { useBinary: true }); // "1 MiB"

// Control decimal places
formatBytes(1234, { decimalPlaces: 0 }); // "1 KB"
formatBytes(1234, { decimalPlaces: 3 }); // "1.234 KB"

// Always show fixed decimal places
formatBytes(1000, { fixedDecimals: true }); // "1.00 KB"
formatBytes(1500, { fixedDecimals: true }); // "1.50 KB"

// Remove space between number and unit
formatBytes(1234, { includeUnitSpace: false }); // "1.23KB"

// Combine multiple options
formatBytes(1536, {
  useBinary: true,
  decimalPlaces: 1,
  fixedDecimals: true,
  includeUnitSpace: false,
}); // "1.5KiB"

Parsing Examples

// Parse various formats
parseBytes('100'); // 100 (plain number)
parseBytes('100B'); // 100
parseBytes('100 bytes'); // 100
parseBytes('1.5 KB'); // 1500
parseBytes('1.5KB'); // 1500 (no space)
parseBytes('1kb'); // 1000 (case insensitive)
parseBytes('1 KiB'); // 1024 (binary unit)

// Invalid inputs return null
parseBytes('abc'); // null
parseBytes(''); // null
parseBytes('1.2.3MB'); // null

Understanding Decimal vs Binary Units

This library supports both decimal (base 1000) and binary (base 1024) units:

Decimal Units (Base 1000)

• Used by hard drive manufacturers and in networking
• 1 KB = 1,000 bytes
• 1 MB = 1,000,000 bytes
• 1 GB = 1,000,000,000 bytes

Binary Units (Base 1024)

• Used by operating systems for RAM and file sizes
• 1 KiB = 1,024 bytes
• 1 MiB = 1,048,576 bytes
• 1 GiB = 1,073,741,824 bytes

// Decimal units (default)
formatBytes(1000); // "1 KB"
formatBytes(1000000); // "1 MB"

// Binary units
formatBytes(1024, { useBinary: true }); // "1 KiB"
formatBytes(1048576, { useBinary: true }); // "1 MiB"

API Reference

formatBytes(bytes: number, options?: FormatBytesOptions): string

Formats a number of bytes into a human-readable string.

Parameters:

• bytes - The number of bytes to format
• options - Optional formatting configuration

Options:

• decimalPlaces (default: 2) - Number of decimal places to include
• useBinary (default: false) - Use binary (KiB, MiB) vs decimal (KB, MB) units
• fixedDecimals (default: false) - Always show the specified decimal places
• includeUnitSpace (default: true) - Include space between number and unit

Returns: A human-readable string representation

Throws: TypeError if input is not a number

parseBytes(sizeString: string): number | null

Parses a human-readable byte string into a number of bytes.

Parameters:

• sizeString - The string to parse (e.g., "512KB", "1.5 GiB")

Returns: The number of bytes, or null if unparseable

Throws: TypeError if input is not a string

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.