GitHub - avoidwork/filesize.js: JavaScript library to generate a human readable String describing the file size

A lightweight, high-performance file size utility that converts bytes to human-readable strings. Zero dependencies. 100% test coverage.

Why filesize?

Zero dependencies - Pure JavaScript, no external packages
100% test coverage - Reliable, well-tested codebase
TypeScript ready - Full type definitions included
Multiple standards - SI, IEC, and JEDEC support
Localization - Intl API for international formatting
BigInt support - Handle extremely large file sizes
Functional API - Partial application for reusable formatters
Browser & Node.js - Works everywhere

Installation

TypeScript

Fully typed with TypeScript 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' });

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

import {partial} from "filesize";

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

Options

Option	Type	Default	Description
`bits`	boolean	`false`	Calculate bits instead of bytes
`base`	number	`-1`	Number base (2 for binary, 10 for decimal, -1 for auto)
`round`	number	`2`	Decimal places to round
`locale`	string\|boolean	`""`	Locale for formatting, `true` for system locale
`localeOptions`	Object	`{}`	Additional locale options
`separator`	string	`""`	Custom decimal separator
`spacer`	string	`" "`	Value-unit separator
`symbols`	Object	`{}`	Custom unit symbols
`standard`	string	`""`	Unit standard (`si`, `iec`, `jedec`)
`output`	string	`"string"`	Output format (`string`, `array`, `object`, `exponent`)
`fullform`	boolean	`false`	Use full unit names
`fullforms`	Array	`[]`	Custom full unit names
`exponent`	number	`-1`	Force specific exponent (-1 for auto)
`roundingMethod`	string	`"round"`	Math method (`round`, `floor`, `ceil`)
`precision`	number	`0`	Significant digits (0 for auto)
`pad`	boolean	`false`	Pad decimal places

Output Formats

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

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

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

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

Standards

// SI (default, base 10)
filesize(1000); // "1 kB"

// IEC (binary, requires base: 2)
filesize(1024, {base: 2, standard: "iec"}); // "1 KiB"

// JEDEC (binary calculation, traditional symbols)
filesize(1024, {standard: "jedec"}); // "1 KB"

Examples

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

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

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

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

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

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

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

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

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

Error Handling

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

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

Testing

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

100% test coverage with 149 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         # Development mode with live reload
npm run build       # Build distributions
npm run lint        # Check code style
npm run lint:fix    # Auto-fix linting issues

Project Structure

filesize.js/
├── src/
│   ├── filesize.js      # Main implementation (285 lines)
│   ├── helpers.js       # Helper functions (215 lines)
│   └── constants.js     # Constants (81 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:

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

Browser Usage

<script src="https://cdn.jsdelivr.net/npm/filesize@11/dist/filesize.umd.min.js"></script>
<script>
  filesize(1024); // "1.02 kB"
</script>