JavaScript library to generate a human readable String describing the file size
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";
const size = partial({standard: "jedec"});
size(265318); // "259.1 KB"
{Number|String|BigInt} - The value to convert (required){Object} - Configuration object (optional){Number} - Number base, default is 10{Boolean} - Enables bit sizes, default is false{Number} - Specifies the symbol via exponent, e.g. 2 is MB for base 2, default is -1{Boolean} - Enables full form of unit of measure, default is false{Array} - Array of full form overrides, default is []{String|Boolean} - BCP 47 language tag to specify a locale, or true to use default locale, default is ""{Object} - Dictionary of options defined by ECMA-402 (Number.prototype.toLocaleString){String} - Output of function (array, exponent, object, or string), default is string{Boolean} - Decimal place end padding, default is false{Number} - Sets precision of numerical output, default is 0{Number} - Decimal place, default is 2{String} - Rounding method, can be round, floor, or ceil, default is round{String} - Decimal separator character, default is an empty string{String} - Character between the result and symbol, default is " "{String} - Standard unit of measure, can be iec, jedec, or si. Default is si (base 10){Object} - Dictionary of IEC/JEDEC symbols to replace for localizationThe 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"
}
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 |
-------------|---------|----------|---------|---------|-------------------
# Run all tests (linting + unit tests)
npm test
# Run only unit tests
npm run mocha
The test suite comprehensively covers:
filesize.js is optimized for high performance with comprehensive benchmarks covering various usage patterns:
| Scenario | Operations/sec | Notes |
|---|---|---|
| Basic conversion | ~16-27M ops/sec | Fastest operations (large numbers) |
| Small numbers | ~18-20M ops/sec | Consistent performance |
| With options | ~5-13M ops/sec | Depends on option complexity |
| Locale formatting | ~91K ops/sec | Most expensive operation |
| Stress testing | ~2-10M ops/sec | Handles edge cases gracefully |
Partial functions maintain excellent performance with minimal overhead:
Excellent Performance (>10M ops/sec)
Good Performance (1-10M ops/sec)
Use Sparingly (<100K ops/sec)
# 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.js
The latest version includes significant performance improvements:
Math.pow() calls)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 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()
Creates a pre-configured filesize function with options applied.
Parameters:
options {Object} - Configuration options to applyReturns: {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()
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"}); // 1
filesize(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 units
filesize(1024, {fullform: true}); // "1.02 kilobytes"
filesize(1024, {base: 2, fullform: true}); // "1 kibibyte"
// 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"
// 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 Π±Π°ΠΉΡΠΎΠ²"
// 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}); // "1.21 YB"
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"]
This project follows Node.js best practices and uses:
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
git checkout -b feature/amazing-feature)npm test)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)filesize.js includes an optimized development workflow with modern build tools:
npm run dev for automatic rebuilds during developmentnpm run build:analyzenpm run test:watchnpm run lint:fixBuild Output Analysis:
# Install dependencies
npm install
# Development mode with live rebuild
npm run dev
# Build distribution
npm run build
# Build with bundle size analysis
npm run build:analyze
# Live rebuild during development
npm run build:watch
# Run linting
npm run lint
# Auto-fix linting issues
npm run lint:fix
# Run tests
npm test
# Live testing during development
npm run test:watch
# Run only unit tests
npm run mocha
# Bundle size analysis
npm run analyze:size
# Benchmarking
npm run benchmark
npm run benchmark:basic
npm run benchmark:stress
Copyright (c) 2025 Jason Mulligan
Licensed under the BSD-3 license.
Similar to filesize, pretty-bytes converts byte values into a human-readable format. It focuses on simplicity and does not offer as many customization options as filesize, making it a good choice for straightforward use cases.
The bytes package also provides functionality for formatting byte sizes into human-readable strings. It offers a balance between simplicity and customization, with options to specify the number of decimal places and the units to use.
FAQs
JavaScript library to generate a human readable String describing the file size
We found that filesize demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.
Security News
Deno 2.6 introduces deno audit with a new --socket flag that plugs directly into Socket to bring supply chain security checks into the Deno CLI.
Security News
New DoS and source code exposure bugs in React Server Components and Next.js: whatβs affected and how to update safely.