1 | # Bytes utility
|
2 |
|
3 | [![NPM Version][npm-image]][npm-url]
|
4 | [![NPM Downloads][downloads-image]][downloads-url]
|
5 | [![Build Status][ci-image]][ci-url]
|
6 | [![Test Coverage][coveralls-image]][coveralls-url]
|
7 |
|
8 | Utility to parse a string bytes (ex: `1TB`) to bytes (`1099511627776`) and vice-versa.
|
9 |
|
10 | ## Installation
|
11 |
|
12 | This is a [Node.js](https://nodejs.org/en/) module available through the
|
13 | [npm registry](https://www.npmjs.com/). Installation is done using the
|
14 | [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
15 |
|
16 | ```bash
|
17 | $ npm install bytes
|
18 | ```
|
19 |
|
20 | ## Usage
|
21 |
|
22 | ```js
|
23 | var bytes = require('bytes');
|
24 | ```
|
25 |
|
26 | #### bytes(number|string value, [options]): number|string|null
|
27 |
|
28 | Default export function. Delegates to either `bytes.format` or `bytes.parse` based on the type of `value`.
|
29 |
|
30 | **Arguments**
|
31 |
|
32 | | Name | Type | Description |
|
33 | |---------|----------|--------------------|
|
34 | | value | `number`|`string` | Number value to format or string value to parse |
|
35 | | options | `Object` | Conversion options for `format` |
|
36 |
|
37 | **Returns**
|
38 |
|
39 | | Name | Type | Description |
|
40 | |---------|------------------|-------------------------------------------------|
|
41 | | results | `string`|`number`|`null` | Return null upon error. Numeric value in bytes, or string value otherwise. |
|
42 |
|
43 | **Example**
|
44 |
|
45 | ```js
|
46 | bytes(1024);
|
47 | // output: '1KB'
|
48 |
|
49 | bytes('1KB');
|
50 | // output: 1024
|
51 | ```
|
52 |
|
53 | #### bytes.format(number value, [options]): string|null
|
54 |
|
55 | Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is
|
56 | rounded.
|
57 |
|
58 | **Arguments**
|
59 |
|
60 | | Name | Type | Description |
|
61 | |---------|----------|--------------------|
|
62 | | value | `number` | Value in bytes |
|
63 | | options | `Object` | Conversion options |
|
64 |
|
65 | **Options**
|
66 |
|
67 | | Property | Type | Description |
|
68 | |-------------------|--------|-----------------------------------------------------------------------------------------|
|
69 | | decimalPlaces | `number`|`null` | Maximum number of decimal places to include in output. Default value to `2`. |
|
70 | | fixedDecimals | `boolean`|`null` | Whether to always display the maximum number of decimal places. Default value to `false` |
|
71 | | thousandsSeparator | `string`|`null` | Example of values: `' '`, `','` and `'.'`... Default value to `''`. |
|
72 | | unit | `string`|`null` | The unit in which the result will be returned (B/KB/MB/GB/TB). Default value to `''` (which means auto detect). |
|
73 | | unitSeparator | `string`|`null` | Separator to use between number and unit. Default value to `''`. |
|
74 |
|
75 | **Returns**
|
76 |
|
77 | | Name | Type | Description |
|
78 | |---------|------------------|-------------------------------------------------|
|
79 | | results | `string`|`null` | Return null upon error. String value otherwise. |
|
80 |
|
81 | **Example**
|
82 |
|
83 | ```js
|
84 | bytes.format(1024);
|
85 | // output: '1KB'
|
86 |
|
87 | bytes.format(1000);
|
88 | // output: '1000B'
|
89 |
|
90 | bytes.format(1000, {thousandsSeparator: ' '});
|
91 | // output: '1 000B'
|
92 |
|
93 | bytes.format(1024 * 1.7, {decimalPlaces: 0});
|
94 | // output: '2KB'
|
95 |
|
96 | bytes.format(1024, {unitSeparator: ' '});
|
97 | // output: '1 KB'
|
98 | ```
|
99 |
|
100 | #### bytes.parse(string|number value): number|null
|
101 |
|
102 | Parse the string value into an integer in bytes. If no unit is given, or `value`
|
103 | is a number, it is assumed the value is in bytes.
|
104 |
|
105 | Supported units and abbreviations are as follows and are case-insensitive:
|
106 |
|
107 | * `b` for bytes
|
108 | * `kb` for kilobytes
|
109 | * `mb` for megabytes
|
110 | * `gb` for gigabytes
|
111 | * `tb` for terabytes
|
112 | * `pb` for petabytes
|
113 |
|
114 | The units are in powers of two, not ten. This means 1kb = 1024b according to this parser.
|
115 |
|
116 | **Arguments**
|
117 |
|
118 | | Name | Type | Description |
|
119 | |---------------|--------|--------------------|
|
120 | | value | `string`|`number` | String to parse, or number in bytes. |
|
121 |
|
122 | **Returns**
|
123 |
|
124 | | Name | Type | Description |
|
125 | |---------|-------------|-------------------------|
|
126 | | results | `number`|`null` | Return null upon error. Value in bytes otherwise. |
|
127 |
|
128 | **Example**
|
129 |
|
130 | ```js
|
131 | bytes.parse('1KB');
|
132 | // output: 1024
|
133 |
|
134 | bytes.parse('1024');
|
135 | // output: 1024
|
136 |
|
137 | bytes.parse(1024);
|
138 | // output: 1024
|
139 | ```
|
140 |
|
141 | ## License
|
142 |
|
143 | [MIT](LICENSE)
|
144 |
|
145 | [ci-image]: https://badgen.net/github/checks/visionmedia/bytes.js/master?label=ci
|
146 | [ci-url]: https://github.com/visionmedia/bytes.js/actions?query=workflow%3Aci
|
147 | [coveralls-image]: https://badgen.net/coveralls/c/github/visionmedia/bytes.js/master
|
148 | [coveralls-url]: https://coveralls.io/r/visionmedia/bytes.js?branch=master
|
149 | [downloads-image]: https://badgen.net/npm/dm/bytes
|
150 | [downloads-url]: https://npmjs.org/package/bytes
|
151 | [npm-image]: https://badgen.net/npm/v/bytes
|
152 | [npm-url]: https://npmjs.org/package/bytes
|