Repository files navigation

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.

npm install filesize

import{filesize}from"filesize";filesize(265318,{standard:"jedec"});// "259.1 KB"

const{filesize}=require("filesize");filesize(1024);// "1.02 kB"

import{partial}from"filesize";constsize=partial({standard:"jedec"});size(265318);// "259.1 KB"

• input{Number|String|BigInt} - The value to convert (required)
• options{Object} - Configuration object (optional)

• base{Number} - Number base, default is10
• bits{Boolean} - Enablesbit sizes, default isfalse
• exponent{Number} - Specifies the symbol via exponent, e.g.2 isMB for 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, ortrue to 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 theresult andsymbol, 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

The function validates input and throwsTypeError for invalid values:

// Invalid input will throw TypeErrortry{filesize("invalid");}catch(error){console.error(error.message);// "Invalid input"}try{filesize(NaN);}catch(error){console.error(error.message);// "Invalid input"}

filesize.js maintains100% 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 |-------------|---------|----------|---------|---------|-------------------

# Run all tests (linting + unit tests)npmtest# Run only unit testsnpm run mocha

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

filesize.js is optimized for high performance with comprehensive benchmarks covering various usage patterns:

• filesize(0): 18.6M ops/sec
• filesize(512): 20.3M ops/sec
• filesize(1024): 18.7M ops/sec
• filesize(1048576): 23.5M ops/sec
• filesize(1073741824): 23.6M ops/sec
• filesize(1099511627776): 26.9M ops/sec
• With bits=true: 16.8M ops/sec
• With standard="iec": 16.6M ops/sec
• With round=4: 13.4M ops/sec

• bits=true: 12.5M ops/sec
• pad=true: 5.6M ops/sec
• locale="en-US": 91K ops/sec (significant overhead)
• standard="iec": 8.8M ops/sec
• standard="jedec": 9.0M ops/sec
• output="array": 10.2M ops/sec
• output="object": 9.2M ops/sec
• fullform=true: 7.8M ops/sec
• precision=3: 6.3M ops/sec
• separator=",": 7.2M ops/sec

• Edge cases: 2.3M ops/sec (90% success rate)
• Very large numbers: 4.6M ops/sec (100% success)
• Very small numbers: 10.4M ops/sec (100% success)
• Negative numbers: 5.4M ops/sec (100% success)
• Random options: 2.3M ops/sec (100% success)
• BigInt values: 3.7M ops/sec (100% success)
• Memory pressure: 49K ops/sec (100% success)
• Error conditions: 715K ops/sec (~40% success rate)

Partial functions maintain excellent performance with minimal overhead:

• Acceptable overhead: 1.1-1.4x slower for most configurations
• Locale partials: Significant overhead (~180x slower) due to locale formatting
• Creation cost: Amortized across multiple uses

Excellent Performance (>10M ops/sec)

• Basic conversions with minimal options
• Large number processing (1TB+ values)
• Standard output formats (string, array, object)
• IEC and JEDEC standards

Good Performance (1-10M ops/sec)

• Complex option combinations
• Precision and rounding operations
• Fullform output
• Stress test scenarios

Use Sparingly (<100K ops/sec)

• Locale formatting (significant overhead ~91K ops/sec)
• Memory pressure conditions

1. Cache partial functions for repeated operations with same options
2. Avoid locale formatting in performance-critical code
3. Use object output for fastest structured data
4. Batch similar operations together
5. Profile your specific usage patterns

# Run all benchmarkscd benchmarks&& node index.js# Run specific benchmarknode benchmarks/basic-performance.js# With garbage collection (more accurate)node --expose-gc benchmarks/index.js

The latest version includes significant performance improvements:

• Pre-computed lookup tables for Math operations (eliminates expensiveMath.pow() calls)
• Optimized base/standard logic with reduced branching
• Fast path for zero values with minimal computation
• Cached object property access to reduce repeated lookups
• Improved mathematical operations with conditional calculations

Overall performance improvement: 30-70% faster across common use cases while maintaining full backward compatibility.

Benchmarks run on macOS ARM64, Node.js v24.8.0, 12 CPU cores, 24GB RAM (5-run averages)

Converts a numeric value to a human-readable file size string.

Parameters:

• input{Number|String|BigInt} - The value to convert
• options{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()

Creates a pre-configured filesize function with options applied.

Parameters:

• options{Object} - Configuration options to apply

Returns:{Function} - New function with options pre-applied

constformatBinary=partial({base:2,standard:"iec"});formatBinary(1048576);// "1 MiB"constformatBits=partial({bits:true});formatBits(1024);// "8.19 kbit"

See also: filesize()

filesize(265318);// "265.32 kB"filesize(265318,{separator:","});// "265,32 kB"

filesize(265318,{output:"array"});// [265.32, "kB"]filesize(1024,{output:"array",base:2});// [1, "KiB"]

filesize(265318,{output:"object"});// {value: 265.32, symbol: "kB", exponent: 1, unit: "kB"}

filesize(1024,{output:"exponent"});// 1filesize(1048576,{output:"exponent",base:2});// 2

filesize(1000);// "1 kB" (base 10)filesize(1000000);// "1 MB"

filesize(1024,{standard:"iec",base:2});// "1 KiB"filesize(1048576,{standard:"iec",base:2});// "1 MiB"

filesize(1024,{standard:"jedec"});// "1 KB"filesize(1048576,{standard:"jedec"});// "1 MB"

import{filesize}from"filesize";filesize(500);// "500 B"filesize(1024);// "1.02 kB"filesize(265318);// "265.32 kB"filesize(265318,{round:0});// "265 kB"

// 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"

filesize(500,{bits:true});// "4 kbit"filesize(1024,{bits:true});// "8.19 kbit"filesize(1024,{bits:true,base:2});// "8 Kibit"

// Full form unitsfilesize(1024,{fullform:true});// "1.02 kilobytes"filesize(1024,{base:2,fullform:true});// "1 kibibyte"// Custom separators and spacingfilesize(265318,{separator:","});// "265,32 kB"filesize(265318,{spacer:""});// "265.32kB"// Precision and paddingfilesize(1536,{round:3,pad:true});// "1.536 kB"filesize(1536,{precision:3});// "1.54 kB"

// German localefilesize(265318,{locale:"de"});// "265,32 kB"// Custom symbolsfilesize(1,{symbols:{B:"Б"}});// "1 Б"// Custom full formsfilesize(12,{fullform:true,fullforms:["байтов"]});// "12 байтов"

// Specific exponentfilesize(1024,{exponent:0});// "1024 B"filesize(1024,{exponent:1});// "1.02 kB"// BigInt supportfilesize(BigInt(1024),{standard:"jedec"});// "1 KB"// Extreme precision for very large numbersfilesize(Math.pow(1024,8),{precision:3});// "1.21 YB"

import{partial}from"filesize";// Create specialized formattersconstformatBinary=partial({base:2,standard:"iec"});constformatBits=partial({bits:true});constformatPrecise=partial({round:3,pad:true});constformatGerman=partial({locale:"de"});// Use throughout applicationformatBinary(1048576);// "1 MiB"formatBits(1024);// "8.19 kbit"formatPrecise(1536);// "1.536 kB"formatGerman(265318);// "265,32 kB"// Method chaining equivalentconstsizes=[1024,2048,4096];sizes.map(formatBinary);// ["1 KiB", "2 KiB", "4 KiB"]

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

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 scripts

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

filesize.js includes an optimized development workflow with modern build tools:

• 🔄 Live Reload: Usenpm run dev for automatic rebuilds during development
• 📊 Bundle Analysis: Monitor build sizes withnpm run build:analyze
• ⚡ Fast Testing: Live test running withnpm run test:watch
• 🔧 Auto-fixing: Automatic linting fixes withnpm run lint:fix
• 📈 Performance: Optimized Rollup configuration with enhanced tree shaking

Build Output Analysis:

• Minified ES Module: ~1.8KB (gzipped)
• UMD Bundle: ~1.9KB (gzipped)
• Comprehensive source maps included

# Install dependenciesnpm install# Development mode with live rebuildnpm run dev# Build distributionnpm run build# Build with bundle size analysisnpm run build:analyze# Live rebuild during developmentnpm run build:watch# Run lintingnpm run lint# Auto-fix linting issuesnpm run lint:fix# Run testsnpmtest# Live testing during developmentnpm run test:watch# Run only unit testsnpm run mocha# Bundle size analysisnpm run analyze:size# Benchmarkingnpm run benchmarknpm run benchmark:basicnpm run benchmark:stress

Copyright (c) 2025 Jason Mulligan
Licensed under the BSD-3 license.