avoidworkfilesize.js
A lightweight, high-performance file size utility for JavaScript that converts bytes to human-readable strings. Works in both Node.js and browser environments with comprehensive format support.
Installation
npm install filesizeUsage
ES Modules
import {filesize} from "filesize";
filesize(265318, {standard: "jedec"}); // "259.1 KB"CommonJS
const {filesize} = require("filesize");
filesize(1024); // "1.02 kB"Partial Application
import {partial} from "filesize";
const size = partial({standard: "jedec"});
size(265318); // "259.1 KB"Parameters
- input
{Number|String|BigInt}- The value to convert (required) - options
{Object}- Configuration object (optional)
Options Object
- base
{Number}- Number base, default is10 - bits
{Boolean}- Enablesbitsizes, default isfalse - exponent
{Number}- Specifies the symbol via exponent, e.g.2isMBfor base 2, default is-1 - fullform
{Boolean}- Enables full form of unit of measure, default isfalse - fullforms
{Array}- Array of full form overrides, default is[] - locale
{String|Boolean}- BCP 47 language tag to specify a locale, ortrueto use default locale, default is"" - localeOptions
{Object}- Dictionary of options defined by ECMA-402 (Number.prototype.toLocaleString) - output
{String}- Output of function (array,exponent,object, orstring), default isstring - pad
{Boolean}- Decimal place end padding, default isfalse - precision
{Number}- Sets precision of numerical output, default is0 - round
{Number}- Decimal place, default is2 - roundingMethod
{String}- Rounding method, can beround,floor, orceil, default isround - separator
{String}- Decimal separator character, default is an empty string - spacer
{String}- Character between theresultandsymbol, default is" " - standard
{String}- Standard unit of measure, can beiec,jedec, orsi. Default issi(base 10) - symbols
{Object}- Dictionary of IEC/JEDEC symbols to replace for localization
Input Validation
The function validates input and throws TypeError for invalid values:
// Invalid input will throw TypeError
try {
filesize("invalid");
} catch (error) {
console.error(error.message); // "Invalid input"
}
try {
filesize(NaN);
} catch (error) {
console.error(error.message); // "Invalid input"
}Testing
filesize.js maintains 100% test coverage across all metrics with a comprehensive test suite of 47 test cases:
-------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------|---------|----------|---------|---------|-------------------
All files | 100 | 100 | 100 | 100 |
filesize.js | 100 | 100 | 100 | 100 |
-------------|---------|----------|---------|---------|-------------------Running Tests
# Run all tests (linting + unit tests)
npm test
# Run only unit tests
npm run mochaTest Coverage
The test suite comprehensively covers:
- Basic functionality: Core conversion logic and edge cases
- Output formats: All output types (string, array, object, exponent)
- Standards support: IEC, JEDEC, and SI standards with different bases
- Bit conversion: Bits vs bytes with auto-increment logic
- Precision handling: Rounding methods and decimal precision
- Localization: Locale formatting and custom symbols
- Error handling: Invalid inputs and boundary conditions
- Partial functions: All option combinations with curried functions
Performance Benchmarks
filesize.js is optimized for high performance with comprehensive benchmarks covering various usage patterns:
🚀 Performance Overview
| Scenario | Operations/sec | Notes |
|---|---|---|
| Basic conversion | ~8-19M ops/sec | Fastest operations (small numbers) |
| Large numbers | ~8-15M ops/sec | Consistent performance |
| With options | ~2-8M ops/sec | Depends on option complexity |
| Locale formatting | ~85K ops/sec | Most expensive operation |
| Partial functions | ~6-8M ops/sec | ~10-20% overhead, amortized |
📊 Detailed Benchmark Results
Basic Performance
- filesize(0): 18.8M ops/sec
- filesize(1024): 14.5M ops/sec
- filesize(1GB): 8.5M ops/sec
- With bits=true: 13.1M ops/sec
- With standard="iec": 7.9M ops/sec
- With fullform=true: 6.6M ops/sec
- Object output: 9.0M ops/sec
Options Performance Impact
- Default options: 6.4M ops/sec (baseline)
- bits=true: 1.66x slower
- pad=true: 2.74x slower
- locale="en-US": 75x slower (significant overhead)
- standard="iec": 1.12x slower
- output="object": 0.96x faster
- Complex combinations: 1.6-2.1x slower
Stress Test Results
- Edge cases: 2.0M ops/sec (90% success rate)
- Very large numbers: 3.7M ops/sec (100% success)
- BigInt values: 2.8M ops/sec (100% success)
- Memory pressure: 48K ops/sec (100% success)
- Performance consistency: 84.7% (10 runs average)
Partial Function Performance
- Direct calls: 8.0M ops/sec (baseline)
- Simple partial: 6.7M ops/sec (1.20x slower)
- Complex partial: 5.6M ops/sec (1.42x slower)
- Partial with locale: 84K ops/sec (95x slower)
💡 Performance Insights
Excellent Performance (>1M ops/sec)
- Basic conversions with minimal options
- Standard output formats (string, array, object)
- IEC and JEDEC standards
Good Performance (100K-1M ops/sec)
- Complex option combinations
- Precision and rounding operations
- Fullform output
Use Sparingly (<100K ops/sec)
- Locale formatting (significant overhead)
- Complex locale configurations
🎯 Optimization Tips
- Cache partial functions for repeated operations with same options
- Avoid locale formatting in performance-critical code
- Use object output for fastest structured data
- Batch similar operations together
- Profile your specific usage patterns
Running Benchmarks
# Run all benchmarks
cd benchmarks && node index.js
# Run specific benchmark
node benchmarks/basic-performance.js
# With garbage collection (more accurate)
node --expose-gc benchmarks/index.jsBenchmarks run on macOS ARM64, Node.js v23.10.0, 12 CPU cores, 24GB RAM
API Reference
Functions
filesize(input, options)
Converts a numeric value to a human-readable file size string.
Parameters:
input{Number|String|BigInt}- The value to convertoptions{Object}- Configuration options (optional)
Returns: {String|Array|Object|Number} - Formatted size based on output option
filesize(500); // "500 B"
filesize(1024, {base: 2}); // "1 KiB"
filesize(265318, {output: "array"}); // [265.32, "kB"]See also: partial()
partial(options)
Creates a pre-configured filesize function with options applied.
Parameters:
options{Object}- Configuration options to apply
Returns: {Function} - New function with options pre-applied
const formatBinary = partial({base: 2, standard: "iec"});
formatBinary(1048576); // "1 MiB"
const formatBits = partial({bits: true});
formatBits(1024); // "8.19 kbit"See also: filesize()
Output Formats
String Output (default)
filesize(265318); // "265.32 kB"
filesize(265318, {separator: ","}); // "265,32 kB"Array Output
filesize(265318, {output: "array"}); // [265.32, "kB"]
filesize(1024, {output: "array", base: 2}); // [1, "KiB"]Object Output
filesize(265318, {output: "object"});
// {value: 265.32, symbol: "kB", exponent: 1, unit: "kB"}Exponent Output
filesize(1024, {output: "exponent"}); // 1
filesize(1048576, {output: "exponent", base: 2}); // 2Standards Support
SI (International System of Units) - Default
filesize(1000); // "1 kB" (base 10)
filesize(1000000); // "1 MB"IEC (International Electrotechnical Commission)
filesize(1024, {standard: "iec", base: 2}); // "1 KiB"
filesize(1048576, {standard: "iec", base: 2}); // "1 MiB"JEDEC (Joint Electron Device Engineering Council)
filesize(1024, {standard: "jedec"}); // "1 KB"
filesize(1048576, {standard: "jedec"}); // "1 MB"Examples
Basic Usage
import {filesize} from "filesize";
filesize(500); // "500 B"
filesize(1024); // "1.02 kB"
filesize(265318); // "265.32 kB"
filesize(265318, {round: 0}); // "265 kB"Binary Formats
// IEC binary prefixes (KiB, MiB, GiB)
filesize(1024, {base: 2, standard: "iec"}); // "1 KiB"
filesize(1048576, {base: 2, standard: "iec"}); // "1 MiB"
// JEDEC binary format (KB, MB, GB with binary calculation)
filesize(1024, {standard: "jedec"}); // "1 KB"
filesize(265318, {standard: "jedec"}); // "259.1 KB"Bits vs Bytes
filesize(500, {bits: true}); // "4 kbit"
filesize(1024, {bits: true}); // "8.19 kbit"
filesize(1024, {bits: true, base: 2}); // "8 kibit"Custom Formatting
// Full form units
filesize(1024, {fullform: true}); // "1.02 kilobytes"
filesize(1024, {base: 2, fullform: true}); // "1 kibibytes"
// Custom separators and spacing
filesize(265318, {separator: ","}); // "265,32 kB"
filesize(265318, {spacer: ""}); // "265.32kB"
// Precision and padding
filesize(1536, {round: 3, pad: true}); // "1.536 kB"
filesize(1536, {precision: 3}); // "1.54 kB"Localization
// German locale
filesize(265318, {locale: "de"}); // "265,32 kB"
// Custom symbols
filesize(1, {symbols: {B: "Б"}}); // "1 Б"
// Custom full forms
filesize(12, {fullform: true, fullforms: ["байтов"]}); // "12 байтов"Advanced Usage
// Specific exponent
filesize(1024, {exponent: 0}); // "1024 B"
filesize(1024, {exponent: 1}); // "1.02 kB"
// BigInt support
filesize(BigInt(1024), {standard: "jedec"}); // "1 KB"
// Extreme precision for very large numbers
filesize(Math.pow(1024, 8), {precision: 3}); // "1208925819614629174706176 YB"Partial Application Patterns
import {partial} from "filesize";
// Create specialized formatters
const formatBinary = partial({base: 2, standard: "iec"});
const formatBits = partial({bits: true});
const formatPrecise = partial({round: 3, pad: true});
const formatGerman = partial({locale: "de"});
// Use throughout application
formatBinary(1048576); // "1 MiB"
formatBits(1024); // "8.19 kbit"
formatPrecise(1536); // "1.536 kB"
formatGerman(265318); // "265,32 kB"
// Method chaining equivalent
const sizes = [1024, 2048, 4096];
sizes.map(formatBinary); // ["1 KiB", "2 KiB", "4 KiB"]Development
This project follows Node.js best practices and uses:
- ES Modules for modern JavaScript
- Mocha for testing with comprehensive coverage
- ESLint for code quality and consistency
- Rollup for building distributions
- TypeScript definitions for type safety
Project Structure
filesize.js/
├── src/
│ ├── filesize.js # Main implementation
│ └── constants.js # Unit definitions and constants
├── tests/
│ └── unit/
│ └── filesize.test.js # Comprehensive test suite
├── types/
│ ├── filesize.d.ts # TypeScript definitions
│ └── constants.d.ts # Constants type definitions
└── package.json # Dependencies and scriptsContributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Write tests for your changes
- Ensure all tests pass (
npm test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Commands
# Install dependencies
npm install
# Run linting
npm run lint
# Run tests
npm test
# Build distribution
npm run build
# Run all checks (lint + test)
npm run ciLicense
Copyright (c) 2025 Jason Mulligan
Licensed under the BSD-3 license.