bytesize

A tiny, zero-dependency byte-size humanizer and parser for Node.js. Turn 1500000 into "1.5 MB" (or "1.43 MiB"), and turn "1024 KiB" back into 1048576. No node_modules, no network, one file.

Install

npm install @verifyhash/bytesize

Published as @verifyhash/bytesize; source lives in the verifyhash/libs monorepo. Zero runtime dependencies — you can also vendor the folder directly.

Who it's for

Anyone who prints file sizes, download counts, memory usage, or bandwidth in a CLI, log line, dashboard, or web UI — and wants the number to be correct, not just pretty. It mirrors the ergonomics of the popular bytes / pretty-bytes / filesize packages but ships with no dependencies, so it adds nothing to your install tree or audit surface.

Decimal vs. binary — the distinction that trips everyone up

There are two unit systems for data sizes, and they disagree:

| System | Base | Prefixes | 1 k… equals | |---------------|------|---------------------|---------------| | decimal (SI) | 1000 | kB, MB, GB, TB, … | 1000 bytes | | binary (IEC) | 1024 | KiB, MiB, GiB, … | 1024 bytes |

Concretely: 1 kB = 1000 bytes, but 1 KiB = 1024 bytes. They are not interchangeable, and the gap grows with size — at the tera level the two systems differ by about 10%.

Which should you use?

• Storage vendors, networking, and most public-facing text use decimal (SI). A "500 GB" drive holds 500 × 10⁹ bytes. This is bytesize's default.
• RAM, and the numbers most operating-system tools report (e.g. ls -lh, Linux free) are powers of two and are correctly written with IEC binary units (MiB, GiB). Windows confusingly labels 1024-based values with SI symbols like "MB" — that historical mislabeling is exactly why the IEC MiB/GiB symbols exist.

bytesize lets you pick explicitly with standard: 'decimal' (default) or standard: 'binary', so you never ship an ambiguous number.

Install / use

It's a single self-contained file — copy index.js into your project, or require it directly.

const { format, parse } = require('./index.js');

format(1500000)                        // '1.5 MB'   (decimal is the default)
format(1500000, { standard: 'binary' })// '1.43 MiB'
format(1073741824, { standard: 'binary' }) // '1 GiB'
format(0)                              // '0 B'
format(-2048, { standard: 'binary' })  // '-2 KiB'

parse('1.5 GB')   // 1500000000   (SI)
parse('1024KiB')  // 1048576      (IEC, no space needed)
parse('1.5mb')    // 1500000      (case-insensitive)
parse('4096')     // 4096         (a bare number is bytes)

API

format(bytes, opts?) -> string

Humanize a finite number of bytes (may be zero or negative).

• opts.standard — 'decimal' (default, base 1000, kB/MB/GB…) or 'binary' (base 1024, KiB/MiB/GiB…).
• opts.precision — maximum number of decimal places, default 2. Trailing zeros are trimmed, so 1000 → "1 kB", not "1.00 kB".
• opts.unit — force a specific unit symbol (e.g. 'MB', 'KiB') instead of auto-selecting. The forced unit determines its own base, so format(2048, { unit: 'KiB' }) → "2 KiB" regardless of standard.

Without a forced unit, it chooses the largest unit that keeps the mantissa ≥ 1 — so 1500000 decimal renders as MB, not kB or GB. Units are supported through YB / YiB; values larger than the top unit stay in that unit rather than overflowing.

parse(str) -> number

Parse a human string back to a number of bytes. Accepts both SI ('1.5 GB') and IEC ('1024KiB') units, is case-insensitive ('1.5mb', '1 gib'), and tolerant of spacing ('1024 KiB' or '1024KiB'). A bare number ('4096') or an explicit B/bytes unit is treated as bytes. Negative and scientific notation ('-2 KiB', '1e3 kB') are accepted. Unknown units or non-numeric input throw.

Note: parse returns the exact mathematical value, which can be fractional — e.g. parse('1.44 MiB') is 1509949.44, not a rounded integer. Round to an integer yourself if your domain requires whole bytes.

Honest limits

• parse does not guess the intended standard from ambiguous casing: MB always means 1,000,000 and MiB always means 1,048,576. There is no "Windows-style MB = 1024²" mode, because guessing there is how bugs happen.
• format returns a plain ASCII string (space between number and unit); it does not localize decimal separators or thousands grouping.
• Very large magnitudes rely on JavaScript number (IEEE-754 double), so precision degrades past 2⁵³ bytes (~9 PB). Beyond that the unit is still correct but the low digits are not exact. BigInt is not supported.

Running the tests

One command, plain Node assert, no test framework:

node test/index.test.js

It exits 0 when everything passes and prints a per-test log. Coverage includes both standards, precision/rounding, forced units, edge units (bytes and PiB/YB), zero and negative values, case/spacing-tolerant parsing, and format → parse → format round-trip stability across a range of values.

License

MIT.