mirror of
https://github.com/nodejs/node.git
synced 2025-05-16 08:52:55 +00:00
2e54524955
PR-URL: https://github.com/nodejs/node/pull/35474 Reviewed-By: Ruy Adorno <ruyadorno@github.com> Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org> Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Shelley Vohr <codebytere@gmail.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
165 lines
5.3 KiB
Handlebars
165 lines
5.3 KiB
Handlebars
[](https://www.npmjs.org/package/byte-size)
|
|
[](https://www.npmjs.org/package/byte-size)
|
|
[](https://github.com/75lb/byte-size/network/dependents?dependent_type=REPOSITORY)
|
|
[](https://github.com/75lb/byte-size/network/dependents?dependent_type=PACKAGE)
|
|
[](https://travis-ci.org/75lb/byte-size)
|
|
[](https://coveralls.io/github/75lb/byte-size)
|
|
[](https://github.com/feross/standard)
|
|
|
|
***Upgraders, please check the [release notes](https://github.com/75lb/byte-size/releases).***
|
|
|
|
# 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](https://en.wikipedia.org/wiki/Gigabyte) (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.
|
|
|
|
```js
|
|
> 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.
|
|
|
|
```js
|
|
> `Filesize: ${byteSize(12400)}`
|
|
'Filesize: 12.4 kB'
|
|
```
|
|
|
|
Override the default `toString` behaviour by setting [`options.toStringFn`](#bytesizebytes-options--object-).
|
|
|
|
```js
|
|
> 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`.
|
|
|
|
```js
|
|
> 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`.
|
|
|
|
```js
|
|
> 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.
|
|
|
|
```js
|
|
> 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.
|
|
|
|
```js
|
|
> 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'
|
|
```
|
|
|
|
{{>main}}
|
|
|
|
## 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:
|
|
|
|
```js
|
|
const byteSize = require('byte-size')
|
|
```
|
|
|
|
Within Node.js with ECMAScript Module support enabled:
|
|
|
|
```js
|
|
import byteSize from 'byte-size'
|
|
```
|
|
|
|
Within a modern browser ECMAScript Module:
|
|
|
|
```js
|
|
import byteSize from './node_modules/byte-size/index.mjs'
|
|
```
|
|
|
|
Old browser (adds `window.byteSize`):
|
|
|
|
```html
|
|
<script nomodule src="./node_modules/byte-size/dist/index.js"></script>
|
|
```
|
|
|
|
* * *
|
|
|
|
© 2014-20 Lloyd Brookes \<75pound@gmail.com\>.
|
|
|
|
Isomorphic test suite by [test-runner](https://github.com/test-runner-js/test-runner) and [web-runner](https://github.com/test-runner-js/web-runner). Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).
|