Skip to content
/ byte-size Public

Isomorphic function to convert a bytes value (e.g. 3456) to a human-readable string ('3.5 kB')

License

Notifications You must be signed in to change notification settings

75lb/byte-size

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

96 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

view on npm npm module downloads Gihub repo dependents Gihub package dependents Node.js CI js-standard-style

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

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-25 Lloyd Brookes <opensource@75lb.com>.

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