0
# Pretty Bytes
1

2
Pretty Bytes is a lightweight JavaScript/TypeScript library that converts numeric byte values into human-readable string representations with appropriate unit suffixes. It provides comprehensive formatting options including binary vs decimal prefixes, bit vs byte units, localization support, and customizable precision control.
3

4
## Package Information
5

6
- **Package Name**: pretty-bytes
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install pretty-bytes`
10

11
## Core Imports
12

13
```typescript
14
import prettyBytes from "pretty-bytes";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const prettyBytes = require("pretty-bytes");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import prettyBytes from "pretty-bytes";
27

28
// Basic byte conversion
29
prettyBytes(1337);
30
//=> '1.34 kB'
31

32
prettyBytes(100);
33
//=> '100 B'
34

35
// Large numbers with BigInt support
36
prettyBytes(10n ** 16n);
37
//=> '10 PB'
38

39
// Display with units of bits
40
prettyBytes(1337, {bits: true});
41
//=> '1.34 kbit'
42

43
// Display file size differences with signed numbers
44
prettyBytes(42, {signed: true});
45
//=> '+42 B'
46

47
// Localized output using German locale
48
prettyBytes(1337, {locale: 'de'});
49
//=> '1,34 kB'
50

51
// Binary prefixes for memory amounts
52
prettyBytes(1024, {binary: true});
53
//=> '1 KiB'
54

55
// Custom precision control
56
prettyBytes(1900, {maximumFractionDigits: 1});
57
//=> '1.9 kB'
58

59
// No space between number and unit
60
prettyBytes(1920, {space: false});
61
//=> '1.92kB'
62
```
63

64
## Capabilities
65

66
### Byte Conversion Function
67

68
Converts bytes to a human readable string with comprehensive formatting options.
69

70
```typescript { .api }
71
/**
72
 * Convert bytes to a human readable string: 1337 → 1.34 kB
73
 * @param number - The number to format (supports number and bigint)
74
 * @param options - Optional configuration object
75
 * @returns Formatted string with number and unit suffix
76
 * @throws TypeError for non-finite numbers or invalid input types
77
 */
78
function prettyBytes(
79
  number: number | bigint,
80
  options?: Options
81
): string;
82
```
83

84
**Parameters:**
85

86
- `number`: The numeric value to format. Accepts both regular JavaScript numbers and BigInt values for handling very large numbers
87
- `options`: Optional configuration object controlling formatting behavior
88

89
**Returns:** A formatted string containing the number with appropriate unit suffix (B, kB, MB, GB, etc.)
90

91
**Throws:** `TypeError` when:
92
- Input is not a finite number (NaN, Infinity, -Infinity)  
93
- Input is not a number or bigint (strings, booleans, null, undefined, objects)
94

95
**Usage Examples:**
96

97
```typescript
98
// Basic conversions
99
prettyBytes(0);           //=> '0 B'
100
prettyBytes(999);         //=> '999 B' 
101
prettyBytes(1001);        //=> '1 kB'
102
prettyBytes(1e16);        //=> '10 PB'
103
prettyBytes(1e30);        //=> '1000000 YB'
104

105
// BigInt support for very large numbers
106
prettyBytes(0n);          //=> '0 B'
107
prettyBytes(10n ** 16n);  //=> '10 PB'
108
prettyBytes(10n ** 30n);  //=> '1000000 YB'
109

110
// Negative numbers
111
prettyBytes(-999);        //=> '-999 B'
112
prettyBytes(-1001);       //=> '-1 kB'
113

114
// Decimal values
115
prettyBytes(0.4);         //=> '0.4 B'
116
prettyBytes(10.1);        //=> '10.1 B'
117
```
118

119
## Options Interface
120

121
Complete configuration options for customizing byte formatting behavior.
122

123
```typescript { .api }
124
interface Options {
125
  /** Include plus sign for positive numbers. Zero displays with space for alignment */
126
  readonly signed?: boolean;
127
  
128
  /** Localization settings for number formatting */
129
  readonly locale?: boolean | string | readonly string[] | undefined;
130
  
131
  /** Format as bits instead of bytes */
132
  readonly bits?: boolean;
133
  
134
  /** Use binary prefixes (KiB, MiB) instead of SI prefixes (kB, MB) */ 
135
  readonly binary?: boolean;
136
  
137
  /** Minimum number of fraction digits to display */
138
  readonly minimumFractionDigits?: number;
139
  
140
  /** Maximum number of fraction digits to display */
141
  readonly maximumFractionDigits?: number;
142
  
143
  /** Put space between number and unit */
144
  readonly space?: boolean;
145
}
146
```
147

148
### signed Option
149

150
Include plus sign for positive numbers. When the value is exactly zero, a space character is prepended instead for better alignment.
151

152
- **Type**: `boolean`
153
- **Default**: `false`
154

155
```typescript
156
prettyBytes(42, {signed: true});    //=> '+42 B' (space: true is default)
157
prettyBytes(-13, {signed: true});   //=> '-13 B'  
158
prettyBytes(0, {signed: true});     //=> ' 0 B' (leading space for alignment)
159
```
160

161
### locale Option
162

163
Controls number localization using BCP 47 language tags. Only the number and decimal separator are localized - unit titles remain in English.
164

165
- **Type**: `boolean | string | readonly string[]`
166
- **Default**: `false` (no localization)
167

168
**Values:**
169
- `false`: No localization
170
- `true`: Use system/browser default locale
171
- `string`: BCP 47 language tag (e.g., 'de', 'en', 'fr')
172
- `string[]`: Array of BCP 47 language tags with fallbacks
173
- `undefined`: Same behavior as `false` (no localization)
174

175
```typescript
176
prettyBytes(1337, {locale: 'de'});                    //=> '1,34 kB'
177
prettyBytes(1337, {locale: 'en'});                    //=> '1.34 kB'
178
prettyBytes(1e30, {locale: 'de'});                    //=> '1.000.000 YB'
179
prettyBytes(1337, {locale: ['unknown', 'de', 'en']}); //=> '1,34 kB'
180
prettyBytes(1337, {locale: true});                    //=> '1.34 kB' (system locale)
181
prettyBytes(1337, {locale: undefined});               //=> '1.34 kB' (no localization)
182
```
183

184
### bits Option
185

186
Format the number as bits instead of bytes. Useful for bit rates and network speeds.
187

188
- **Type**: `boolean`
189
- **Default**: `false`
190

191
```typescript
192
prettyBytes(1337, {bits: true});    //=> '1.34 kbit'
193
prettyBytes(1e16, {bits: true});    //=> '10 Pbit'
194
prettyBytes(999, {bits: true});     //=> '999 b'
195
```
196

197
### binary Option
198

199
Use binary prefixes (base-2, powers of 1024) instead of SI prefixes (base-10, powers of 1000). Recommended for memory amounts but not file sizes as per industry standards.
200

201
- **Type**: `boolean`
202
- **Default**: `false`
203

204
**Binary prefixes**: B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB (base-1024)
205
**SI prefixes**: B, kB, MB, GB, TB, PB, EB, ZB, YB (base-1000)
206

207
```typescript
208
prettyBytes(1000, {binary: true});   //=> '1000 B'
209
prettyBytes(1024, {binary: true});   //=> '1 KiB'
210
prettyBytes(1e16, {binary: true});   //=> '8.88 PiB'
211

212
// Combined with bits option
213
prettyBytes(1025, {bits: true, binary: true}); //=> '1 kibit'
214
```
215

216
### minimumFractionDigits Option
217

218
The minimum number of fraction digits to display. Works with JavaScript's `toLocaleString` method.
219

220
- **Type**: `number`
221
- **Default**: `undefined`
222

223
When neither `minimumFractionDigits` nor `maximumFractionDigits` are set, the default behavior rounds to 3 significant digits.
224

225
```typescript
226
prettyBytes(1900, {minimumFractionDigits: 3}); //=> '1.900 kB'
227
prettyBytes(1900);                             //=> '1.9 kB'
228
prettyBytes(1000, {minimumFractionDigits: 1}); //=> '1.0 kB'
229
```
230

231
### maximumFractionDigits Option
232

233
The maximum number of fraction digits to display. Works with JavaScript's `toLocaleString` method.
234

235
- **Type**: `number`  
236
- **Default**: `undefined`
237

238
When neither `minimumFractionDigits` nor `maximumFractionDigits` are set, the default behavior rounds to 3 significant digits.
239

240
```typescript
241
prettyBytes(1920, {maximumFractionDigits: 1}); //=> '1.9 kB'
242
prettyBytes(1920);                             //=> '1.92 kB'
243
prettyBytes(1111, {maximumFractionDigits: 2}); //=> '1.11 kB'
244

245
// Combined minimum and maximum
246
prettyBytes(1000, {
247
  minimumFractionDigits: 1,
248
  maximumFractionDigits: 3
249
}); //=> '1.0 kB'
250
```
251

252
### space Option
253

254
Controls whether to put a space between the number and unit.
255

256
- **Type**: `boolean`
257
- **Default**: `true`
258

259
```typescript
260
prettyBytes(1920, {space: false}); //=> '1.92kB'
261
prettyBytes(1920);                 //=> '1.92 kB' (space: true is default)
262
prettyBytes(42, {signed: true, space: false}); //=> '+42B'
263
prettyBytes(0, {signed: true, space: false});  //=> ' 0B' (leading space preserved)
264
```
265

266
## Error Handling
267

268
The function validates input and throws descriptive errors for invalid data:
269

270
```typescript
271
// These will throw TypeError
272
prettyBytes('');                    // string input
273
prettyBytes('1');                   // string input  
274
prettyBytes(Number.NaN);           // NaN
275
prettyBytes(Number.POSITIVE_INFINITY); // Infinity
276
prettyBytes(Number.NEGATIVE_INFINITY); // -Infinity
277
prettyBytes(true);                 // boolean
278
prettyBytes(null);                 // null
279
prettyBytes(undefined);            // undefined
280
```
281

282
Error message format: `"Expected a finite number, got <type>: <value>"`
283

284
## Unit Systems
285

286
Pretty Bytes supports multiple unit systems depending on the `bits` and `binary` options:
287

288
### Byte Units (default)
289
**SI Prefixes (decimal, base-1000)**: B, kB, MB, GB, TB, PB, EB, ZB, YB
290
**Binary Prefixes (base-1024)**: B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB
291

292
### Bit Units (bits: true)  
293
**SI Prefixes (decimal, base-1000)**: b, kbit, Mbit, Gbit, Tbit, Pbit, Ebit, Zbit, Ybit
294
**Binary Prefixes (base-1024)**: b, kibit, Mibit, Gibit, Tibit, Pibit, Eibit, Zibit, Yibit
295

296
## Advanced Usage Patterns
297

298
### Handling Very Large Numbers
299

300
```typescript
301
// BigInt for numbers beyond JavaScript's safe integer limit
302
const veryLarge = 9007199254740991n * 1000000n;
303
prettyBytes(veryLarge); //=> Appropriate unit conversion
304

305
// Scientific notation
306
prettyBytes(1e30);      //=> '1000000 YB'
307
prettyBytes(827_181 * 1e26); //=> '82718100 YB'
308
```
309

310
### Localization with Different Regions
311

312
```typescript
313
// German formatting
314
prettyBytes(1e30, {locale: 'de'}); //=> '1.000.000 YB'
315

316
// English formatting  
317
prettyBytes(1e30, {locale: 'en'}); //=> '1,000,000 YB'
318

319
// Fallback locale handling
320
prettyBytes(1001, {locale: ['unknown', 'de', 'en']}); //=> '1 kB'
321
```
322

323
### Memory vs File Size Formatting
324

325
```typescript
326
// File sizes (use SI prefixes - default)
327
prettyBytes(1000);                  //=> '1 kB'
328
prettyBytes(1000000);               //=> '1 MB' 
329

330
// Memory amounts (use binary prefixes)
331
prettyBytes(1024, {binary: true});  //=> '1 KiB'
332
prettyBytes(1048576, {binary: true}); //=> '1 MiB'
333
```
334

335
### Network/Speed Formatting
336

337
```typescript
338
// Bit rates for network speeds
339
prettyBytes(1000000, {bits: true}); //=> '1 Mbit'
340
prettyBytes(1000, {bits: true});    //=> '1 kbit'
341

342
// Data transfer amounts
343
prettyBytes(1337, {signed: true});  //=> '+1.34 kB' (positive transfer)
344
prettyBytes(-1337, {signed: true}); //=> '-1.34 kB' (negative transfer)
345
```