byte-size

What is byte-size?

The byte-size npm package is a utility for converting bytes into human-readable format. It helps in formatting byte values into strings with appropriate units (e.g., KB, MB, GB) and provides options for customization.

What are byte-size's main functionalities?

Basic Conversion

This feature allows you to convert a byte value into a human-readable format. In this example, 1024 bytes are converted to 1 KB.

const byteSize = require('byte-size');
const result = byteSize(1024);
console.log(result); // { value: 1, unit: 'KB', long: '1 kilobyte' }

Custom Units

This feature allows you to specify custom units for the conversion. In this example, 1500 bytes are converted to 1.46 KiB using IEC units.

const byteSize = require('byte-size');
const result = byteSize(1500, { units: 'iec' });
console.log(result); // { value: 1.46, unit: 'KiB', long: '1.46 kibibytes' }

Decimal Places

This feature allows you to set the number of decimal places for the conversion. In this example, 123456789 bytes are converted to 117.74 MB with 2 decimal places.

const byteSize = require('byte-size');
const result = byteSize(123456789, { precision: 2 });
console.log(result); // { value: 117.74, unit: 'MB', long: '117.74 megabytes' }

Other packages similar to byte-size

filesize

The filesize package is another utility for converting bytes into human-readable strings. It offers more customization options compared to byte-size, such as different rounding methods and support for various notations (e.g., binary, decimal).

pretty-bytes

The pretty-bytes package is a lightweight utility for converting bytes to a human-readable string. It is simpler and more straightforward than byte-size, focusing on ease of use and minimal configuration.

bytes

The bytes package provides utilities for parsing and formatting byte values. It is more versatile than byte-size, offering both conversion to human-readable strings and parsing from strings back to byte values.

README

Upgraders, please check the release notes.

byte-size

An isomorphic, load-anywhere function to convert a bytes value (e.g. 3456) to a human-readable string ('3.5 kB'). Choose between metric or IEC units (summarised below) or specify your own custom units.

Value	Metric	Metric (octet)
1000	kB kilobyte	ko kilooctet
1000^2	MB megabyte	Mo megaoctet
1000^3	GB gigabyte	Go gigaoctet
1000^4	TB terabyte	To teraoctet
1000^5	PB petabyte	Po petaoctet
1000^6	EB exabyte	Eo exaoctet
1000^7	ZB zettabyte	Zo zettaoctet
1000^8	YB yottabyte	Yo yottaoctet

Value	IEC	IEC (octet)
1024	KiB kibibyte	Kio kibioctet
1024^2	MiB mebibyte	Mio mebioctet
1024^3	GiB gibibyte	Gio gibioctet
1024^4	TiB tebibyte	Tio tebioctet
1024^5	PiB pebibyte	Pio pebioctet
1024^6	EiB exbibyte	Eio exbioctet
1024^7	ZiB zebibyte	Zio zebioctet
1024^8	YiB yobibyte	Yio yobioctet

Synopsis

By default, byteSize converts the input number to a human readable string with metric units and a precision of 1.

> const byteSize = require('byte-size')

> byteSize(1580)
{ value: '1.6', unit: 'kB', long: 'kilobytes' }

The object returned by byteSize defines a toString method therefore can be used directly in string context.

> `Filesize: ${byteSize(12400)}`
'Filesize: 12.4 kB'

Override the default toString behaviour by setting options.toStringFn.

> function toStringFn () {
  return `**${this.value}${this.unit}**`
}

> `Filesize: ${byteSize(12400, { toStringFn })}`
'Filesize: **12.4kB**'

Beside the default of metric, there are three other built-in units available: metric_octet, iec and iec_octet.

> byteSize(1580, { units: 'iec' })
{ value: '1.5', unit: 'KiB', long: 'kibibytes' }

> byteSize(1580, { units: 'iec_octet' })
{ value: '1.5', unit: 'Kio', long: 'kibioctets' }

> byteSize(1580, { units: 'metric_octet' })
{ value: '1.6', unit: 'ko', long: 'kilooctets' }

You can adjust the precision.

> byteSize(1580, { units: 'iec', precision: 3 })
{ value: '1.543', unit: 'KiB', long: 'kibibytes' }

> byteSize(1580, { units: 'iec', precision: 0 })
{ value: '2', unit: 'KiB', long: 'kibibytes' }

Define custom units by passing an object containing one or more additional conversion tables to options.customUnits. In options.units, specify the name of a property from the customUnits object.

> const customUnits = {
  simple: [
    { from: 0   , to: 1e3 , unit: ''  },
    { from: 1e3 , to: 1e6 , unit: 'K', long: 'thousand' },
    { from: 1e6 , to: 1e9 , unit: 'Mn', long: 'million' },
    { from: 1e9 , to: 1e12, unit: 'Bn', long: 'billion' }
  ]
}

> const { value, unit } = byteSize(10000, { customUnits, units: 'simple' })

> `${value}${unit}`
'10.0K'

Override the built-in defaults for the duration of the process by passing an options object to byteSize.defaultOptions(). This results in cleaner code in cases where byteSize is used often with the same options.

> byteSize.defaultOptions({
  units: 'simple',
  precision: 2,
  customUnits: {
    simple: [
      { from: 0, to: 1e3, unit: '' },
      { from: 1e3, to: 1e6, unit: 'k' },
      { from: 1e6, to: 1e9, unit: 'm' },
      { from: 1e9, to: 1e12, unit: 'bn' },
    ]
  },
  toStringFn: function () {
    return this.value + this.unit
  }
})

> [2400, 16400, 3991200].map(byteSize).join(', ')
'2.40k, 16.40k, 3.99m'

byte-size

• byte-size
  • byteSize(bytes, [options]) ⇒ object ⏏
    • .defaultOptions(options)

byteSize(bytes, [options]) ⇒ object ⏏

Returns an object with the spec { value: string, unit: string, long: string }. The returned object defines a toString method meaning it can be used in any string context.

Kind: Exported function

Param	Type	Description
bytes	number	The bytes value to convert.
[options]	object	Optional config.
[options.precision]	number	Number of decimal places. Defaults to 1.
[options.units]	string	Specify 'metric', 'iec', 'metric_octet', 'iec_octet' or the name of a property from the custom units table in options.customUnits. Defaults to metric.
[options.customUnits]	object	An object containing one or more custom unit lookup tables.
[options.toStringFn]	function	A toString function to override the default.
[options.locale]	string | Array.<string>	Node >=13 or modern browser only - on earlier platforms this option is ignored. The locale to use for number formatting (e.g. 'de-DE'). Defaults to your system locale. Passed directed into Intl.NumberFormat().

byteSize.defaultOptions(options)

Set the default byteSize options for the duration of the process.

Kind: static method of byteSize

Param	Type	Description
options	object	A byteSize options object.

Load anywhere

This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.

Node.js (CommonJS):

const byteSize = require('byte-size')

Node.js (ECMAScript Module):

import byteSize from 'byte-size'

Within a modern browser ECMAScript Module:

import byteSize from './node_modules/byte-size/index.js'

Browser global (adds window.byteSize):

<script src="./node_modules/byte-size/dist/index.js"></script>

---

© 2014-24 Lloyd Brookes <[e-mail]>.

Tested by test-runner. Documented by jsdoc-to-markdown.