bytes

library0.0.1.dev4jsnpmunverified

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.

data

npm install bytes

github ↗package ↗

INSTALL

IMPORT

SIG · BYTES

bytes

datajavascriptv0.0.1.dev4

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

✗ import { bytes } from 'bytes';

The main `bytes` function is the default export. Access `format` and `parse` as properties: `bytes.format` and `bytes.parse`.

bytes.format

✓ import bytes from 'bytes'; const formatted = bytes.format(1024);

✗ import { format } from 'bytes'; const formatted = format(1024);

`format` is a property of the default `bytes` export, not a top-level named export. Direct destructuring won't work.

bytes.parse

✓ const bytes = require('bytes'); const parsed = bytes.parse('1KB');

✗ const { parse } = require('bytes'); const parsed = parse('1KB');

`parse` is a property of the module's default export in CommonJS, not a direct named export unless explicitly configured.

Demonstrates parsing byte strings to numbers, formatting numbers to byte strings, and using specific `format` and `parse` functions with various options and error handling.

import bytes from 'bytes'; // Parse a human-readable string to its byte equivalent const oneKilobyte = bytes('1KB'); console.log(`'1KB' parses to: ${oneKilobyte} bytes`); // Expected: 1024 // Format a number of bytes into a human-readable string const formattedMegaBytes = bytes(1024 * 1024 * 5.5); console.log(`5.5MB (raw bytes) formats to: ${formattedMegaBytes}`); // Expected: '5.5MB' // Using bytes.format with options const bigNumber = 1000 * 1000 * 1000 * 1.2345; const formattedWithDecimal = bytes.format(bigNumber, { decimalPlaces: 3, unit: 'GB', unitSeparator: ' ' }); console.log(`1.2345GB with options: ${formattedWithDecimal}`); // Expected: '1.235 GB' // Using bytes.parse directly const twoPetabytes = bytes.parse('2PB'); console.log(`'2PB' parses to: ${twoPetabytes} bytes`); // Handling invalid input const invalidParse = bytes.parse('not a byte string'); console.log(`Parsing invalid string returns: ${invalidParse}`); // Expected: null

Debug

Known issues

gotchaThe `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.

fix

Always be mindful of the base (1024) when using this library. Do not use it if a base-10 (1000) conversion is required.

affects: >=1.0.0

gotchaThe `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.

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 */ }`

affects: >=1.0.0

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

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.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: bytes is not a function

Attempting to call `bytes` as a function after an incorrect named import in ESM, or if the `require` result was not the function itself.

fix

Ensure you are importing the default export correctly: `import bytes from 'bytes';` (ESM) or `const bytes = require('bytes');` (CommonJS).

ReferenceError: require is not defined

Using `require()` in a modern ES module environment without appropriate Babel or TypeScript configuration, or without setting `"type": "commonjs"` in `package.json`.

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.

TypeError: Cannot read properties of undefined (reading 'format')

This usually occurs when `bytes` itself is `undefined` because of a failed or incorrect import, meaning `bytes.format` cannot be accessed.

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

Upgrade

Version history

0.0.1.dev4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

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

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