file-size-formatter

A comprehensive TypeScript/JavaScript library for formatting file sizes with customizable options and full type safety.

Features

• 🔢 Dual Unit Systems: Support for both binary (1024-based) and decimal (1000-based) units
• 🎯 Full TypeScript Support: Complete type definitions with IntelliSense
• 🎨 Highly Customizable: Precision, spacing, unit names, constraints, and more
• 📦 Multiple Formats: CommonJS and ES Module builds
• 🧪 Well Tested: Comprehensive test coverage
• 🚀 Zero Dependencies: Lightweight and fast
• 📖 Detailed Results: Get both formatted strings and detailed breakdown

Installation

npm install file-size-formatter

Quick Start

import { formatFileSize } from 'file-size-formatter';

// Basic usage
console.log(formatFileSize(1024)); // "1 KiB"
console.log(formatFileSize(1000000)); // "976.56 KiB"

// With decimal system
console.log(formatFileSize(1000000, { unitSystem: 'decimal' })); // "1 MB"

API Reference

formatFileSize(bytes, options?)

Simple function to format bytes into a human-readable string.

import { formatFileSize } from 'file-size-formatter';

formatFileSize(1536); // "1.5 KiB"
formatFileSize(1536, { precision: 0 }); // "2 KiB"
formatFileSize(1536, { unitSystem: 'decimal' }); // "1.54 KB"

formatFileSizeDetailed(bytes, options?)

Returns detailed information about the formatting result.

import { formatFileSizeDetailed } from 'file-size-formatter';

const result = formatFileSizeDetailed(1024);
console.log(result);
// {
//   value: "1 KiB",
//   number: 1,
//   unit: "KiB",
//   bytes: 1024
// }

FileSizeFormatter Class

For advanced usage with persistent configuration.

import { FileSizeFormatter } from 'file-size-formatter';

const formatter = new FileSizeFormatter({
  unitSystem: 'decimal',
  precision: 1,
  spacer: ' ',
});

console.log(formatter.format(1500000).value); // "1.5 MB"

// Update options
formatter.setOptions({ precision: 0 });
console.log(formatter.format(1500000).value); // "2 MB"

Configuration Options

interface FormatOptions {
  // Unit system: 'binary' (1024-based) or 'decimal' (1000-based)
  unitSystem?: 'binary' | 'decimal';
  
  // Number of decimal places (default: 2)
  precision?: number;
  
  // String between number and unit (default: ' ')
  spacer?: string;
  
  // Use full unit names like "kilobytes" instead of "KB"
  fullNames?: boolean;
  
  // Don't use units smaller than this
  minUnit?: string;
  
  // Don't use units larger than this  
  maxUnit?: string;
  
  // Custom unit names
  customUnits?: {
    binary?: Partial<Record<BinaryUnit, string>>;
    decimal?: Partial<Record<DecimalUnit, string>>;
  };
}

Examples

Different Unit Systems

const bytes = 1048576;

// Binary system (default) - uses 1024
formatFileSize(bytes); // "1 MiB"

// Decimal system - uses 1000
formatFileSize(bytes, { unitSystem: 'decimal' }); // "1.05 MB"

Precision Control

const bytes = 1536;

formatFileSize(bytes, { precision: 0 }); // "2 KiB"
formatFileSize(bytes, { precision: 1 }); // "1.5 KiB"
formatFileSize(bytes, { precision: 3 }); // "1.5 KiB"

Full Unit Names

formatFileSize(1024, { fullNames: true }); // "1 kibibytes"
formatFileSize(1000, { 
  unitSystem: 'decimal', 
  fullNames: true 
}); // "1 kilobytes"

Custom Unit Names

formatFileSize(1024, {
  customUnits: {
    binary: {
      KiB: 'KB',
      MiB: 'MB',
      GiB: 'GB'
    }
  }
}); // "1 KB"

Unit Constraints

// Don't go below KB
formatFileSize(500, { 
  unitSystem: 'decimal',
  minUnit: 'KB' 
}); // "0.5 KB"

// Don't go above MB
formatFileSize(5000000000, { 
  unitSystem: 'decimal',
  maxUnit: 'MB' 
}); // "5000 MB"

Custom Spacing

formatFileSize(1024, { spacer: '' }); // "1KiB"
formatFileSize(1024, { spacer: ' - ' }); // "1 - KiB"

TypeScript Support

The library is written in TypeScript and provides complete type definitions:

import { 
  FormatOptions, 
  FormatResult, 
  UnitSystem,
  BinaryUnit,
  DecimalUnit
} from 'file-size-formatter';

// All types are available for use in your code
const options: FormatOptions = {
  unitSystem: 'binary',
  precision: 2
};

const result: FormatResult = formatFileSizeDetailed(1024, options);

Browser Support

This library works in all modern browsers and Node.js environments. It's compiled to ES5 for broad compatibility while maintaining modern ES module support.

Contributing

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

1. Add tests for any new features
2. Update documentation
3. Follow the existing code style
4. Ensure all tests pass

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the library
npm run build

# Lint code
npm run lint

# Format code
npm run format

License

MIT © [Your Name]

Changelog

1.0.0

• Initial release
• Binary and decimal unit system support
• Comprehensive TypeScript types
• Full customization options
• Zero dependencies