bs

byte-size

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

Showing:

Popularity

Downloads/wk

1.7M

GitHub Stars

45

Maintenance

Last Commit

2mos ago

Contributors

5

Package

Dependencies

0

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Reviews

Average Rating

5.0/52
Read All Reviews

Top Feedback

1Great Documentation
1Easy to Use

Readme

view on npm npm module downloads Gihub repo dependents Gihub package dependents Node.js CI Coverage Status 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.

ValueMetricMetric (octet)
1000kB kilobyteko kilooctet
1000^2MB megabyteMo megaoctet
1000^3GB gigabyteGo gigaoctet
1000^4TB terabyteTo teraoctet
1000^5PB petabytePo petaoctet
1000^6EB exabyteEo exaoctet
1000^7ZB zettabyteZo zettaoctet
1000^8YB yottabyteYo yottaoctet
ValueIECIEC (octet)
1024KiB kibibyteKio kibioctet
1024^2MiB mebibyteMio mebioctet
1024^3GiB gibibyteGio gibioctet
1024^4TiB tebibyteTio tebioctet
1024^5PiB pebibytePio pebioctet
1024^6EiB exbibyteEio exbioctet
1024^7ZiB zebibyteZio zebioctet
1024^8YiB yobibyteYio 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

ParamTypeDescription
bytesnumberThe bytes value to convert.
[options]objectOptional config.
[options.precision]numberNumber of decimal places. Defaults to 1.
[options.units]stringSpecify '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]objectAn object containing one or more custom unit lookup tables.
[options.toStringFn]functionA 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

ParamTypeDescription
optionsobjectA 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-21 Lloyd Brookes \75pound@gmail.com\.

Isomorphic test suite by test-runner and web-runner. Documented by jsdoc-to-markdown.

Rate & Review

Great Documentation1
Easy to Use1
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
omrilotan24 Ratings11 Reviews
☕ I woke up like this
September 13, 2020

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial