{"id":15090,"library":"bytes","title":"Bytes Utility for Node.js","description":"The `bytes` package (current stable version 3.1.2) is a focused JavaScript utility designed for converting human-readable byte strings (e.g., \"1KB\", \"5.5GB\") into their numerical byte equivalents, and vice-versa. It provides a simple, unified API that delegates to a `format` function for converting numbers to strings and a `parse` function for converting strings or numbers to bytes. A key differentiator is its strict adherence to powers of two for unit conversions (e.g., 1KB equals 1024 bytes), which is critical for accurate storage and memory calculations, distinguishing it from decimal-based systems. While major releases are not frequent, the library is stable and widely used, typically receiving updates for bug fixes or minor enhancements. It supports various units including B, KB, MB, GB, TB, and PB, and offers formatting options such as decimal places, thousands separators, and custom unit separators.","status":"active","version":"3.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/visionmedia/bytes.js","tags":["javascript","byte","bytes","utility","parse","parser","convert","converter"],"install":[{"cmd":"npm install bytes","lang":"bash","label":"npm"},{"cmd":"yarn add bytes","lang":"bash","label":"yarn"},{"cmd":"pnpm add bytes","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The main `bytes` function is the default export. Access `format` and `parse` as properties: `bytes.format` and `bytes.parse`.","wrong":"import { bytes } from 'bytes';","symbol":"bytes","correct":"import bytes from 'bytes';"},{"note":"`format` is a property of the default `bytes` export, not a top-level named export. Direct destructuring won't work.","wrong":"import { format } from 'bytes';\nconst formatted = format(1024);","symbol":"bytes.format","correct":"import bytes from 'bytes';\nconst formatted = bytes.format(1024);"},{"note":"`parse` is a property of the module's default export in CommonJS, not a direct named export unless explicitly configured.","wrong":"const { parse } = require('bytes');\nconst parsed = parse('1KB');","symbol":"bytes.parse","correct":"const bytes = require('bytes');\nconst parsed = bytes.parse('1KB');"}],"quickstart":{"code":"import bytes from 'bytes';\n\n// Parse a human-readable string to its byte equivalent\nconst oneKilobyte = bytes('1KB');\nconsole.log(`'1KB' parses to: ${oneKilobyte} bytes`); // Expected: 1024\n\n// Format a number of bytes into a human-readable string\nconst formattedMegaBytes = bytes(1024 * 1024 * 5.5);\nconsole.log(`5.5MB (raw bytes) formats to: ${formattedMegaBytes}`); // Expected: '5.5MB'\n\n// Using bytes.format with options\nconst bigNumber = 1000 * 1000 * 1000 * 1.2345;\nconst formattedWithDecimal = bytes.format(bigNumber, { decimalPlaces: 3, unit: 'GB', unitSeparator: ' ' });\nconsole.log(`1.2345GB with options: ${formattedWithDecimal}`); // Expected: '1.235 GB'\n\n// Using bytes.parse directly\nconst twoPetabytes = bytes.parse('2PB');\nconsole.log(`'2PB' parses to: ${twoPetabytes} bytes`);\n\n// Handling invalid input\nconst invalidParse = bytes.parse('not a byte string');\nconsole.log(`Parsing invalid string returns: ${invalidParse}`); // Expected: null","lang":"javascript","description":"Demonstrates parsing byte strings to numbers, formatting numbers to byte strings, and using specific `format` and `parse` functions with various options and error handling."},"warnings":[{"fix":"Always be mindful of the base (1024) when using this library. Do not use it if a base-10 (1000) conversion is required.","message":"The `bytes` utility strictly uses powers of two (1024) for unit conversions (e.g., 1KB = 1024B, 1MB = 1024KB). This is crucial for storage and memory contexts but differs from decimal (1000) systems often seen in networking or marketing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always check the return value for `null` after calling `bytes()`, `bytes.parse()`, or `bytes.format()` to ensure a valid conversion occurred: `const value = bytes('invalid'); if (value === null) { /* handle error */ }`","message":"The `bytes()` function (and `bytes.parse()`, `bytes.format()`) returns `null` for invalid input instead of throwing an error. Developers must explicitly check for `null` to handle parsing or formatting failures gracefully.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Remove `unit: 'b'` from your `bytes.format` options. The function will automatically format values in bytes if they are less than 1KB. For values requiring a specific unit, use 'KB', 'MB', etc., but 'B' will be inferred.","message":"In version 3.0.0, the `bytes.format()` method no longer accepts 'b' as a specific unit in the `unit` option. It now auto-detects the most appropriate unit. To format a value strictly in bytes, ensure `unit` is not set or the value is small enough to naturally format as bytes.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are importing the default export correctly: `import bytes from 'bytes';` (ESM) or `const bytes = require('bytes');` (CommonJS).","cause":"Attempting to call `bytes` as a function after an incorrect named import in ESM, or if the `require` result was not the function itself.","error":"TypeError: bytes is not a function"},{"fix":"For ESM projects, use `import bytes from 'bytes';`. If you must use `require` in an ESM file, consider converting the file to CommonJS or using a build tool that handles CJS-ESM interoperability.","cause":"Using `require()` in a modern ES module environment without appropriate Babel or TypeScript configuration, or without setting `\"type\": \"commonjs\"` in `package.json`.","error":"ReferenceError: require is not defined"},{"fix":"Verify that `import bytes from 'bytes';` or `const bytes = require('bytes');` correctly assigns the module to the `bytes` variable before attempting to call its properties like `format` or `parse`.","cause":"This usually occurs when `bytes` itself is `undefined` because of a failed or incorrect import, meaning `bytes.format` cannot be accessed.","error":"TypeError: Cannot read properties of undefined (reading 'format')"}],"ecosystem":"npm"}