file-size-humanizer

Convert bytes into human-readable formats with both binary (1024-based) and decimal (1000-based) interpretations.

Features

• Decimal Units: KB, MB, GB, TB (1000-based)
• Binary Units: KiB, MiB, GiB, TiB (1024-based)
• Flexible Output: Get both interpretations or choose one
• Customizable Precision: Control decimal places
• Zero Dependencies: Pure JavaScript implementation

Installation

npm install file-size-humanizer

Usage

Basic Usage

const { humanize, format } = require('file-size-humanizer');

// Get both decimal and binary interpretations
const result = humanize(1048576);
console.log(result);
// {
//   bytes: 1048576,
//   decimal: { value: 1.05, unit: 'MB', string: '1.05 MB' },
//   binary: { value: 1, unit: 'MiB', string: '1 MiB' }
// }

// Quick format (decimal by default)
console.log(format(1048576)); // "1.05 MB"

// Format with binary units
console.log(format(1048576, { binary: true })); // "1 MiB"

API

humanize(bytes, decimals = 2)

Returns an object with both decimal and binary representations.

Parameters:

• bytes (number): The number of bytes to convert
• decimals (number): Number of decimal places (default: 2)

Returns: Object with bytes, decimal, and binary properties

humanize(1024);
// {
//   bytes: 1024,
//   decimal: { value: 1.02, unit: 'KB', string: '1.02 KB' },
//   binary: { value: 1, unit: 'KiB', string: '1 KiB' }
// }

format(bytes, options = {})

Returns a formatted string.

Parameters:

• bytes (number): The number of bytes to convert
• options (object):
  • binary (boolean): Use binary units if true (default: false)
  • decimals (number): Number of decimal places (default: 2)

Returns: Formatted string

format(1500000); // "1.5 MB"
format(1500000, { binary: true }); // "1.43 MiB"
format(1500000, { decimals: 1 }); // "1.5 MB"

toDecimal(bytes, decimals = 2)

Convert to decimal units (1000-based).

Returns: Object with value and unit

toDecimal(1000000); // { value: 1, unit: 'MB' }

toBinary(bytes, decimals = 2)

Convert to binary units (1024-based).

Returns: Object with value and unit

toBinary(1048576); // { value: 1, unit: 'MiB' }

Understanding Binary vs Decimal

• Decimal (1000-based): KB, MB, GB - Used by hard drive manufacturers and in SI units
• Binary (1024-based): KiB, MiB, GiB - Used by operating systems and reflects actual binary computation

Example

1 KB = 1,000 bytes
1 KiB = 1,024 bytes

1 MB = 1,000,000 bytes
1 MiB = 1,048,576 bytes

1 GB = 1,000,000,000 bytes
1 GiB = 1,073,741,824 bytes

Examples

See example.js for more usage examples.

node example.js

Testing

npm test

License

MIT License - see LICENSE file for details