Installation

npm install filesize

Usage

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";constsize=partial({standard:"jedec"});size(265318);// "259.1 KB"

Parameters

Options Object

Input Validation

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

Testing

-------------|---------|----------|---------|---------|-------------------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)npmtest# Run only unit testsnpm run mocha

Test Coverage

Performance Benchmarks

🚀 Performance Overview

📊 Detailed Benchmark Results

Basic Performance

Options Performance Impact

Stress Test Results

Partial Function Performance

💡 Performance Insights

🎯 Optimization Tips

Running Benchmarks

# 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

API Reference

Functions

filesize(input, options)

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

partial(options)

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

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"});// 1filesize(1048576,{output:"exponent",base:2});// 2

Standards 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 unitsfilesize(1024,{fullform:true});// "1.02 kilobytes"filesize(1024,{base:2,fullform:true});// "1 kibibytes"// 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"

Localization

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

Advanced Usage

// 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});// "1208925819614629174706176 YB"

Partial Application Patterns

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

Development

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 scripts

Contributing

Development Commands

# Install dependenciesnpm install# Run lintingnpm run lint# Run testsnpmtest# Build distributionnpm run build# Run all checks (lint + test)npm run ci

License