bytes-iec

library3.1.1jsnpmunverified

bytes-iec is a JavaScript and TypeScript utility library, currently at version 3.1.1, designed for parsing and formatting byte size strings. It converts human-readable strings like '1kB' or '2KiB' into their numeric byte equivalents (e.g., 1000, 2048) and vice-versa. As a fork of the popular `bytes` module, `bytes-iec` differentiates itself by offering comprehensive support for ISO/IEC 80000-13:2008 binary and decimal prefixes, including KiB, MiB, etc., and also includes a JEDEC compatibility mode for legacy definitions where metric units have binary values. A key feature is its default use of decimal metric units, which can be configured globally or per-call. The library is actively maintained, indicated by its recent version and clear feature set, and ships with TypeScript definitions, making it suitable for modern JavaScript and TypeScript projects in Node.js environments.

serialization

npm install bytes-iec

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BYTES-IEC

bytes-iec

serializationjavascriptv3.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bytes

✓ import bytes from 'bytes-iec';

✗ import { bytes } from 'bytes-iec';

The library primarily exports a default function/object for both CJS and ESM environments. Access `format` and `parse` methods directly from the imported `bytes` object.

bytes

✓ const bytes = require('bytes-iec');

CommonJS usage as shown in the package's README. The imported `bytes` object contains the `format` and `parse` methods.

Bytes

✓ import bytes, { Options, UnitType } from 'bytes-iec';

For TypeScript projects, types like `Options` and `UnitType` (referring to 'metric', 'binary', 'compatibility', 'jedec' strings) can be imported alongside the default export. There is no explicit 'Bytes' class or named export for the main utility functions, but types for options can be useful.

Demonstrates formatting byte values into human-readable strings and parsing strings back into numeric bytes, showcasing default decimal mode, explicit binary (IEC) mode, and JEDEC compatibility mode.

import bytes from 'bytes-iec'; // Format bytes to a human-readable string (defaults to decimal metric) const formattedDecimal = bytes.format(1000000); // 1 MB console.log(`1,000,000 bytes (decimal): ${formattedDecimal}`); // Format bytes using binary (IEC) units const formattedBinary = bytes.format(1048576, { mode: 'binary' }); // 1 MiB console.log(`1,048,576 bytes (binary): ${formattedBinary}`); // Parse a human-readable string to bytes (defaults to metric parsing) const parsedGB = bytes.parse('1GB'); // 1,000,000,000 console.log(`Parsed '1GB' (decimal): ${parsedGB} bytes`); // Parse a string using binary (IEC) units const parsedGiB = bytes.parse('1GiB', { mode: 'binary' }); // 1,073,741,824 console.log(`Parsed '1GiB' (binary): ${parsedGiB} bytes`); // Example with JEDEC (compatibility) mode - where kB, MB are binary const formattedJedec = bytes.format(1024 * 1024, { mode: 'jedec' }); // 1 MB (binary value) console.log(`1,048,576 bytes (JEDEC): ${formattedJedec}`); // Handle null/invalid inputs const invalidParse = bytes.parse('not-a-byte-string'); console.log(`Parsing 'not-a-byte-string': ${invalidParse}`);

Debug

Known issues

gotchaUnlike some operating systems or older byte utilities (e.g., the original `bytes` module), `bytes-iec` defaults to using decimal (SI) prefixes for metric units (e.g., 'kB' = 1000 bytes, 'MB' = 1,000,000 bytes) when parsing or formatting, unless explicitly overridden.

fix

To achieve binary (base-2) behavior, explicitly set the `mode` option to `'binary'` for IEC units (e.g., 'KiB', 'MiB') or `'jedec'` for compatibility mode where metric abbreviations ('kB', 'MB') represent binary values. Example: `bytes.format(1048576, { mode: 'binary' });` or `bytes.parse('1MB', { mode: 'jedec' });`

affects: >=1.0.0

gotchaWhen using JEDEC ('compatibility') mode, only specific lower units (kB, MB, GB, TB) are supported as binary values (1024-based). Units greater than Terabyte might not behave as expected or are not supported in this mode for compatibility reasons.

fix

For consistent binary prefix behavior across all magnitudes, prefer using `mode: 'binary'` which uses the standard IEC prefixes (KiB, MiB, GiB, etc.).

affects: >=1.0.0

gotchaThe `bytes.parse()` function explicitly rounds down partial bytes when a unit given has them (e.g., '1.5KB' would parse to 1000 if in decimal mode). This behavior might differ from expectations of rounding to the nearest whole byte.

fix

Be aware that fractional inputs are truncated. If precise fractional byte handling is needed, ensure input values are already in base bytes or handle rounding before parsing.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: bytes.format is not a function

The `bytes` variable was not correctly imported or required, or a named import was used for what is a default export.

fix

Ensure you are using `import bytes from 'bytes-iec';` for ESM or `const bytes = require('bytes-iec');` for CommonJS, as the library exports a default object containing the `format` and `parse` methods.

SyntaxError: Named export 'bytes' not found. The requested module 'bytes-iec' does not provide an export named 'bytes'

Attempted to import `bytes` as a named export (`import { bytes } from 'bytes-iec';`) when it is exported as a default.

fix

Change the import statement to `import bytes from 'bytes-iec';` to correctly import the default export.

Upgrade

Version history

3.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Saevon/bytes.js ↗

packagehttps://www.npmjs.com/package/bytes-iec ↗

homepagehttps://bytes-iec.js.org ↗