bytes-iec: Byte Unit Conversion Utility

Common errors

• TypeError: bytes.format is not a function

  cause 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'

  cause 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.

Warnings

• gotcha Unlike 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' });`
• gotcha When 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.).
• gotcha The `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.

Install

• npm install bytes-iec npm
• yarn add bytes-iec yarn
• pnpm add bytes-iec pnpm

Imports

• bytes
  wrong:

  import { bytes } from 'bytes-iec';

  correct:

  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.

Quickstart

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}`);