filesize

A lightweight, zero-dependency JavaScript utility that converts bytes to human-readable strings. Built for client and server applications that need to display file sizes — from download counters to disk-usage reports.

Why filesize?

• Zero dependencies — no install weight, no supply-chain surface.
• 100% test coverage — every line, branch, and function is tested.
• TypeScript ready — full type definitions for options and return types.
• Three unit standards — SI, IEC, and JEDEC, each with its own symbols.
• Localization — Intl-based formatting for any locale.
• BigInt support — sizes beyond Number.MAX_SAFE_INTEGER.
• Functional API — partial() creates reusable, immutable formatters.
• Client & server — ships ESM, CJS, and UMD builds.

Installation

npm install filesize

Usage

import {filesize, partial} from "filesize";

filesize(1024); // "1.02 kB"
filesize(265318); // "265.32 kB"
filesize(1024, {standard: "iec"}); // "1 KiB"
filesize(1024, {bits: true}); // "8.19 kbit"

Partial application

partial() returns a pre-configured formatter with frozen options. Use it when you format many values with the same settings — it avoids re-parsing options on every call.

import {partial} from "filesize";

const formatBinary = partial({standard: "iec"});
formatBinary(1024); // "1 KiB"
formatBinary(1048576); // "1 MiB"

Standards

filesize supports three unit standards. They differ in two ways: the base (1000 or 1024) and the unit symbols.

When you set standard, the base is implied and base is ignored. base is only consulted when standard is not set.

Options

round controls decimal places; precision controls significant digits. When precision is greater than 0, it takes precedence over round.

Output formats

// String (default)
filesize(1536); // "1.54 kB"

// Array: [value, symbol]
filesize(1536, {output: "array"}); // [1.54, "kB"]

// Object: {value, symbol, exponent, unit}
filesize(1536, {output: "object"});
// {value: 1.54, symbol: "kB", exponent: 1, unit: "kB"}

// Exponent: the unit index
filesize(1536, {output: "exponent"}); // 1

Examples

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

// Full unit names
filesize(1024, {fullform: true}); // "1.02 kilobytes"
filesize(1024, {base: 2, fullform: true}); // "1 kibibyte"

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

// Padding
filesize(1536, {round: 3, pad: true}); // "1.536 kB"

// Significant digits
filesize(1536, {precision: 3}); // "1.54 kB"

// Locale
filesize(265318, {locale: "de"}); // "265,32 kB"

// Custom symbols
filesize(1, {symbols: {B: "Б"}}); // "1 Б"

// BigInt
filesize(BigInt(1024)); // "1.02 kB"

// Negative numbers
filesize(-1024); // "-1.02 kB"

Error handling

filesize() throws a TypeError for invalid input.

try {
  filesize("invalid");
} catch (error) {
  // TypeError: "Invalid number"
}

try {
  filesize(1024, {roundingMethod: "invalid"});
} catch (error) {
  // TypeError: "Invalid rounding method"
}

Invalid input includes non-numeric values, NaN, Infinity, and BigInt values that overflow Number.MAX_SAFE_INTEGER.

TypeScript

Fully typed with definitions included:

import {filesize, partial} from "filesize";

const result: string = filesize(1024);
const formatted: {value: number; symbol: string; exponent: number; unit: string} = filesize(1024, {output: "object"});

const formatter: (arg: number | bigint) => string = partial({standard: "iec"});

Testing

npm test              # Run all tests (lint + node:test)
npm run test:watch    # Live test watching

100% test coverage with 255 tests:

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |     100 |      100 |     100 |     100 |                   
 constants.js |     100 |      100 |     100 |     100 |                   
 filesize.js  |     100 |      100 |     100 |     100 |                   
 helpers.js   |     100 |      100 |     100 |     100 |                   
--------------|---------|----------|---------|---------|-------------------

Development

npm install         # Install dependencies
npm run dev         # Build distributions in watch mode
npm run build       # Build distributions
npm run lint        # Check code style
npm run fix         # Auto-fix linting issues

Project structure

filesize.js/
├── src/
│   ├── filesize.js      # Main implementation (286 lines)
│   ├── helpers.js       # Helper functions (538 lines)
│   └── constants.js     # Constants (82 lines)
├── tests/
│   └── unit/
├── dist/                # Built distributions
└── types/               # TypeScript definitions

Performance

• Basic conversions: ~16-27M ops/sec
• With options: ~5-13M ops/sec
• Locale formatting: ~91K ops/sec (use sparingly)

Optimization tips:

1. Cache partial() formatters for reuse
2. Avoid locale formatting in performance-critical code
3. Use object output for fastest structured data access

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Changelog

See CHANGELOG.md for a history of changes.

License

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