filesize.js

filesize is a zero-dependency JavaScript library that converts numeric byte counts into human-readable strings like “1.02 kB” or “1 KiB”. It supports the SI, IEC, and JEDEC unit standards, handles bits as well as bytes, and offers locale-aware number formatting through the Intl API, plus BigInt input for extremely large values.

The library ships full TypeScript type definitions and works identically in Node.js and the browser. A partial() helper lets callers pre-configure a formatter once (for example, a fixed IEC/base-2 formatter) and reuse it, avoiding repeated option objects in hot code paths such as upload progress displays, log formatting, or disk-usage reports.

What You Get

• SI, IEC, and JEDEC unit standard support (kB vs KiB vs KB)
• Bits-mode formatting (bits: true) for network/bandwidth values
• Multiple output shapes — string, array, object, or exponent-only
• Locale-aware formatting via the Intl API, plus custom separators/spacers/symbols
• BigInt input support for values beyond Number.MAX_SAFE_INTEGER
• A partial() factory for pre-configured, reusable formatters

Common Use Cases

• Displaying upload/download progress in bytes transferred or bytes-per-second
• Formatting disk usage or file sizes in admin dashboards and file browsers
• Rendering bandwidth/network throughput in bits instead of bytes
• Localizing file size display for international user bases

Under The Hood

Architecture The library is a flat, purely functional module split across three files: filesize.js orchestrates a linear pipeline (validate input, resolve base configuration, calculate exponent, compute the optimized value, round, apply precision handling, resolve the unit symbol, decorate the result, format the output), helpers.js holds the individual pipeline steps as pure, independently testable functions, and constants.js centralizes lookup tables and unit-symbol strings. There is no internal state or class hierarchy; partial() is a thin closure that clones mutable option objects (via structuredClone with a JSON fallback) and returns a pre-bound formatter, keeping repeated calls free of shared-reference bugs.

Tech Stack filesize.js is written in vanilla ES modules with zero runtime dependencies. Its dev tooling is entirely modern and Rust-accelerated: Rollup (with @rollup/plugin-terser) builds ESM and CJS/UMD bundles, oxlint and oxfmt handle linting and formatting, Husky wires up git hooks, and auto-changelog generates the changelog. Tests run on Node’s built-in node:test runner with --experimental-test-coverage, with no external test framework. GitHub Actions CI targets Node 24.x, running the build and test suite on every PR, with Dependabot auto-merge for routine dependency bumps. TypeScript consumers are served by hand-authored .d.ts declaration files rather than a TypeScript source build.

Code Quality Three test files under tests/unit/ exercise the main API, the internal helpers, and a structuredClone fallback path specifically, and the project’s own coverage report and README badge claim 100% statement/branch/function/line coverage. Error handling is explicit rather than silent — invalid numeric input and invalid rounding methods both throw typed TypeErrors with clear messages. Every exported function carries JSDoc annotating parameters, return types, and thrown errors, naming is consistent and descriptive (calculateExponent, applyRounding, resolveSymbol), and linting/formatting are enforced in CI and via pre-commit hooks.

API Design The public surface is deliberately small: a single filesize(bytes, options) call returns a string by default, with an output option switching between string, array, object, and exponent-only shapes instead of requiring separate function calls. partial() gives a curried, pre-configured formatter for hot paths, avoiding repeated option-object allocation — a convenience many comparable byte-formatting libraries skip. Deep customization (custom symbols, separators, spacers, full-form pluralization, forced exponent, rounding method) lives behind one options object with sensible defaults, so the zero-config call filesize(1024) works out of the box while every knob remains reachable for advanced use.