format-byte-size/README.md

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

# ⚠️ 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


[![npm version](https://badge.fury.io/js/format-byte-size.svg)](https://badge.fury.io/js/format-byte-size)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/format-byte-size)](https://bundlephobia.com/package/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

```bash
npm install format-byte-size
```

## Usage

### Basic Usage

```typescript
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

```typescript
// 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

```typescript
// 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

```typescript
// 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.