tessl/npm-pretty-bytes

Convert bytes to a human readable string with appropriate unit suffixes

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Pretty Bytes

Name: tessl/npm-pretty-bytes
Author: tessl

Pretty Bytes is a lightweight JavaScript/TypeScript library that converts numeric byte values into human-readable string representations with appropriate unit suffixes. It provides comprehensive formatting options including binary vs decimal prefixes, bit vs byte units, localization support, and customizable precision control.

Package Information

Package Name: pretty-bytes
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install pretty-bytes

Core Imports

import prettyBytes from "pretty-bytes";

For CommonJS:

const prettyBytes = require("pretty-bytes");

Basic Usage

import prettyBytes from "pretty-bytes";

// Basic byte conversion
prettyBytes(1337);
//=> '1.34 kB'

prettyBytes(100);
//=> '100 B'

// Large numbers with BigInt support
prettyBytes(10n ** 16n);
//=> '10 PB'

// Display with units of bits
prettyBytes(1337, {bits: true});
//=> '1.34 kbit'

// Display file size differences with signed numbers
prettyBytes(42, {signed: true});
//=> '+42 B'

// Localized output using German locale
prettyBytes(1337, {locale: 'de'});
//=> '1,34 kB'

// Binary prefixes for memory amounts
prettyBytes(1024, {binary: true});
//=> '1 KiB'

// Custom precision control
prettyBytes(1900, {maximumFractionDigits: 1});
//=> '1.9 kB'

// No space between number and unit
prettyBytes(1920, {space: false});
//=> '1.92kB'

Capabilities

Byte Conversion Function

Converts bytes to a human readable string with comprehensive formatting options.

/**
 * Convert bytes to a human readable string: 1337 → 1.34 kB
 * @param number - The number to format (supports number and bigint)
 * @param options - Optional configuration object
 * @returns Formatted string with number and unit suffix
 * @throws TypeError for non-finite numbers or invalid input types
 */
function prettyBytes(
  number: number | bigint,
  options?: Options
): string;

Parameters:

number: The numeric value to format. Accepts both regular JavaScript numbers and BigInt values for handling very large numbers
options: Optional configuration object controlling formatting behavior

Returns: A formatted string containing the number with appropriate unit suffix (B, kB, MB, GB, etc.)

Throws: TypeError when:

Input is not a finite number (NaN, Infinity, -Infinity)
Input is not a number or bigint (strings, booleans, null, undefined, objects)

Usage Examples:

// Basic conversions
prettyBytes(0);           //=> '0 B'
prettyBytes(999);         //=> '999 B' 
prettyBytes(1001);        //=> '1 kB'
prettyBytes(1e16);        //=> '10 PB'
prettyBytes(1e30);        //=> '1000000 YB'

// BigInt support for very large numbers
prettyBytes(0n);          //=> '0 B'
prettyBytes(10n ** 16n);  //=> '10 PB'
prettyBytes(10n ** 30n);  //=> '1000000 YB'

// Negative numbers
prettyBytes(-999);        //=> '-999 B'
prettyBytes(-1001);       //=> '-1 kB'

// Decimal values
prettyBytes(0.4);         //=> '0.4 B'
prettyBytes(10.1);        //=> '10.1 B'

Options Interface

Complete configuration options for customizing byte formatting behavior.

interface Options {
  /** Include plus sign for positive numbers. Zero displays with space for alignment */
  readonly signed?: boolean;
  
  /** Localization settings for number formatting */
  readonly locale?: boolean | string | readonly string[] | undefined;
  
  /** Format as bits instead of bytes */
  readonly bits?: boolean;
  
  /** Use binary prefixes (KiB, MiB) instead of SI prefixes (kB, MB) */ 
  readonly binary?: boolean;
  
  /** Minimum number of fraction digits to display */
  readonly minimumFractionDigits?: number;
  
  /** Maximum number of fraction digits to display */
  readonly maximumFractionDigits?: number;
  
  /** Put space between number and unit */
  readonly space?: boolean;
}

signed Option

Include plus sign for positive numbers. When the value is exactly zero, a space character is prepended instead for better alignment.

Type: boolean
Default: false

prettyBytes(42, {signed: true});    //=> '+42 B' (space: true is default)
prettyBytes(-13, {signed: true});   //=> '-13 B'  
prettyBytes(0, {signed: true});     //=> ' 0 B' (leading space for alignment)

locale Option

Controls number localization using BCP 47 language tags. Only the number and decimal separator are localized - unit titles remain in English.

Type: boolean | string | readonly string[]
Default: false (no localization)

Values:

false: No localization
true: Use system/browser default locale
string: BCP 47 language tag (e.g., 'de', 'en', 'fr')
string[]: Array of BCP 47 language tags with fallbacks
undefined: Same behavior as false (no localization)

prettyBytes(1337, {locale: 'de'});                    //=> '1,34 kB'
prettyBytes(1337, {locale: 'en'});                    //=> '1.34 kB'
prettyBytes(1e30, {locale: 'de'});                    //=> '1.000.000 YB'
prettyBytes(1337, {locale: ['unknown', 'de', 'en']}); //=> '1,34 kB'
prettyBytes(1337, {locale: true});                    //=> '1.34 kB' (system locale)
prettyBytes(1337, {locale: undefined});               //=> '1.34 kB' (no localization)

bits Option

Format the number as bits instead of bytes. Useful for bit rates and network speeds.

Type: boolean
Default: false

prettyBytes(1337, {bits: true});    //=> '1.34 kbit'
prettyBytes(1e16, {bits: true});    //=> '10 Pbit'
prettyBytes(999, {bits: true});     //=> '999 b'

binary Option

Use binary prefixes (base-2, powers of 1024) instead of SI prefixes (base-10, powers of 1000). Recommended for memory amounts but not file sizes as per industry standards.

Type: boolean
Default: false

Binary prefixes: B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB (base-1024) SI prefixes: B, kB, MB, GB, TB, PB, EB, ZB, YB (base-1000)

prettyBytes(1000, {binary: true});   //=> '1000 B'
prettyBytes(1024, {binary: true});   //=> '1 KiB'
prettyBytes(1e16, {binary: true});   //=> '8.88 PiB'

// Combined with bits option
prettyBytes(1025, {bits: true, binary: true}); //=> '1 kibit'

minimumFractionDigits Option

The minimum number of fraction digits to display. Works with JavaScript's toLocaleString method.

Type: number
Default: undefined

When neither minimumFractionDigits nor maximumFractionDigits are set, the default behavior rounds to 3 significant digits.

prettyBytes(1900, {minimumFractionDigits: 3}); //=> '1.900 kB'
prettyBytes(1900);                             //=> '1.9 kB'
prettyBytes(1000, {minimumFractionDigits: 1}); //=> '1.0 kB'

maximumFractionDigits Option

The maximum number of fraction digits to display. Works with JavaScript's toLocaleString method.

Type: number
Default: undefined

When neither minimumFractionDigits nor maximumFractionDigits are set, the default behavior rounds to 3 significant digits.

prettyBytes(1920, {maximumFractionDigits: 1}); //=> '1.9 kB'
prettyBytes(1920);                             //=> '1.92 kB'
prettyBytes(1111, {maximumFractionDigits: 2}); //=> '1.11 kB'

// Combined minimum and maximum
prettyBytes(1000, {
  minimumFractionDigits: 1,
  maximumFractionDigits: 3
}); //=> '1.0 kB'

space Option

Controls whether to put a space between the number and unit.

Type: boolean
Default: true

prettyBytes(1920, {space: false}); //=> '1.92kB'
prettyBytes(1920);                 //=> '1.92 kB' (space: true is default)
prettyBytes(42, {signed: true, space: false}); //=> '+42B'
prettyBytes(0, {signed: true, space: false});  //=> ' 0B' (leading space preserved)

Error Handling

The function validates input and throws descriptive errors for invalid data:

// These will throw TypeError
prettyBytes('');                    // string input
prettyBytes('1');                   // string input  
prettyBytes(Number.NaN);           // NaN
prettyBytes(Number.POSITIVE_INFINITY); // Infinity
prettyBytes(Number.NEGATIVE_INFINITY); // -Infinity
prettyBytes(true);                 // boolean
prettyBytes(null);                 // null
prettyBytes(undefined);            // undefined

Error message format: "Expected a finite number, got <type>: <value>"

Unit Systems

Pretty Bytes supports multiple unit systems depending on the bits and binary options:

Byte Units (default)

SI Prefixes (decimal, base-1000): B, kB, MB, GB, TB, PB, EB, ZB, YB Binary Prefixes (base-1024): B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB

Bit Units (bits: true)

SI Prefixes (decimal, base-1000): b, kbit, Mbit, Gbit, Tbit, Pbit, Ebit, Zbit, Ybit Binary Prefixes (base-1024): b, kibit, Mibit, Gibit, Tibit, Pibit, Eibit, Zibit, Yibit

Advanced Usage Patterns

Handling Very Large Numbers

// BigInt for numbers beyond JavaScript's safe integer limit
const veryLarge = 9007199254740991n * 1000000n;
prettyBytes(veryLarge); //=> Appropriate unit conversion

// Scientific notation
prettyBytes(1e30);      //=> '1000000 YB'
prettyBytes(827_181 * 1e26); //=> '82718100 YB'

Localization with Different Regions

// German formatting
prettyBytes(1e30, {locale: 'de'}); //=> '1.000.000 YB'

// English formatting  
prettyBytes(1e30, {locale: 'en'}); //=> '1,000,000 YB'

// Fallback locale handling
prettyBytes(1001, {locale: ['unknown', 'de', 'en']}); //=> '1 kB'

Memory vs File Size Formatting

// File sizes (use SI prefixes - default)
prettyBytes(1000);                  //=> '1 kB'
prettyBytes(1000000);               //=> '1 MB' 

// Memory amounts (use binary prefixes)
prettyBytes(1024, {binary: true});  //=> '1 KiB'
prettyBytes(1048576, {binary: true}); //=> '1 MiB'

Network/Speed Formatting

// Bit rates for network speeds
prettyBytes(1000000, {bits: true}); //=> '1 Mbit'
prettyBytes(1000, {bits: true});    //=> '1 kbit'

// Data transfer amounts
prettyBytes(1337, {signed: true});  //=> '+1.34 kB' (positive transfer)
prettyBytes(-1337, {signed: true}); //=> '-1.34 kB' (negative transfer)

Install with Tessl CLI

npx tessl i tessl/npm-pretty-bytes

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/pretty-bytes@7.0.x
Publish Source: CLI
Badge