{"id":10602,"library":"bytes-iec","title":"bytes-iec: Byte Unit Conversion Utility","description":"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.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/Saevon/bytes.js","tags":["javascript","byte","bytes","utility","parse","parser","convert","converter","iec"],"install":[{"cmd":"npm install bytes-iec","lang":"bash","label":"npm"},{"cmd":"yarn add bytes-iec","lang":"bash","label":"yarn"},{"cmd":"pnpm add bytes-iec","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { bytes } from 'bytes-iec';","symbol":"bytes","correct":"import bytes from 'bytes-iec';"},{"note":"CommonJS usage as shown in the package's README. The imported `bytes` object contains the `format` and `parse` methods.","symbol":"bytes","correct":"const bytes = require('bytes-iec');"},{"note":"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.","symbol":"Bytes","correct":"import bytes, { Options, UnitType } from 'bytes-iec';"}],"quickstart":{"code":"import bytes from 'bytes-iec';\n\n// Format bytes to a human-readable string (defaults to decimal metric)\nconst formattedDecimal = bytes.format(1000000); // 1 MB\nconsole.log(`1,000,000 bytes (decimal): ${formattedDecimal}`);\n\n// Format bytes using binary (IEC) units\nconst formattedBinary = bytes.format(1048576, { mode: 'binary' }); // 1 MiB\nconsole.log(`1,048,576 bytes (binary): ${formattedBinary}`);\n\n// Parse a human-readable string to bytes (defaults to metric parsing)\nconst parsedGB = bytes.parse('1GB'); // 1,000,000,000\nconsole.log(`Parsed '1GB' (decimal): ${parsedGB} bytes`);\n\n// Parse a string using binary (IEC) units\nconst parsedGiB = bytes.parse('1GiB', { mode: 'binary' }); // 1,073,741,824\nconsole.log(`Parsed '1GiB' (binary): ${parsedGiB} bytes`);\n\n// Example with JEDEC (compatibility) mode - where kB, MB are binary\nconst formattedJedec = bytes.format(1024 * 1024, { mode: 'jedec' }); // 1 MB (binary value)\nconsole.log(`1,048,576 bytes (JEDEC): ${formattedJedec}`);\n\n// Handle null/invalid inputs\nconst invalidParse = bytes.parse('not-a-byte-string');\nconsole.log(`Parsing 'not-a-byte-string': ${invalidParse}`);","lang":"typescript","description":"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."},"warnings":[{"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' });`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For consistent binary prefix behavior across all magnitudes, prefer using `mode: 'binary'` which uses the standard IEC prefixes (KiB, MiB, GiB, etc.).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `bytes` variable was not correctly imported or required, or a named import was used for what is a default export.","error":"TypeError: bytes.format is not a function"},{"fix":"Change the import statement to `import bytes from 'bytes-iec';` to correctly import the default export.","cause":"Attempted to import `bytes` as a named export (`import { bytes } from 'bytes-iec';`) when it is exported as a default.","error":"SyntaxError: Named export 'bytes' not found. The requested module 'bytes-iec' does not provide an export named 'bytes'"}],"ecosystem":"npm"}