byte-size - npm Package Compare versions

Comparing version 6.0.0 to 6.1.0

dist/index.js

@@ -5,56 +5,6 @@ (function (global, factory) {
   (global = global || self, global.byteSize = factory());
-}(this, function () { 'use strict';
+}(this, (function () { 'use strict';
 
   /**
-   * An isomorphic, load-anywhere function to convert a bytes or octets value (e.g. `34565346`) to a human-readable string (`34.6 MB`). Choose between [metric or IEC units](https://en.wikipedia.org/wiki/Gigabyte), summarised below.
-   *
-   * Value | Metric
-   * ----- | -------------
-   * 1000  | kB  kilobyte
-   * 1000^2 | MB  megabyte
-   * 1000^3 | GB  gigabyte
-   * 1000^4 | TB  terabyte
-   * 1000^5 | PB  petabyte
-   * 1000^6 | EB  exabyte
-   * 1000^7 | ZB  zettabyte
-   * 1000^8 | YB  yottabyte
-   *
-   * Value | IEC
-   * ----- | ------------
-   * 1024  | KiB kibibyte
-   * 1024^2 | MiB mebibyte
-   * 1024^3 | GiB gibibyte
-   * 1024^4 | TiB tebibyte
-   * 1024^5 | PiB pebibyte
-   * 1024^6 | EiB exbibyte
-   * 1024^7 | ZiB zebibyte
-   * 1024^8 | YiB yobibyte
-   *
-   * Value | Metric (octet)
-   * ----- | -------------
-   * 1000  | ko  kilooctet
-   * 1000^2 | Mo  megaoctet
-   * 1000^3 | Go  gigaoctet
-   * 1000^4 | To  teraoctet
-   * 1000^5 | Po  petaoctet
-   * 1000^6 | Eo  exaoctet
-   * 1000^7 | Zo  zettaoctet
-   * 1000^8 | Yo  yottaoctet
-   *
-   * Value | IEC (octet)
-   * ----- | ------------
-   * 1024  | Kio kilooctet
-   * 1024^2 | Mio mebioctet
-   * 1024^3 | Gio gibioctet
-   * 1024^4 | Tio tebioctet
-   * 1024^5 | Pio pebioctet
-   * 1024^6 | Eio exbioctet
-   * 1024^7 | Zio zebioctet
-   * 1024^8 | Yio yobioctet
-   *
    * @module byte-size
-   * @example
-   * ```js
-   * const byteSize = require('byte-size')
-   * ```
    */
@@ -64,41 +14,75 @@
     constructor (bytes, options) {
-      options = options || {};
-      options.units = options.units || 'metric';
-      options.precision = typeof options.precision === 'undefined' ? 1 : options.precision;
+      options = Object.assign({
+        units: 'metric',
+        precision: 1
+      }, options);
 
-      const table = [
-        { expFrom: 0, expTo: 1, metric: 'B', iec: 'B', metric_octet: 'o', iec_octet: 'o' },
-        { expFrom: 1, expTo: 2, metric: 'kB', iec: 'KiB', metric_octet: 'ko', iec_octet: 'Kio' },
-        { expFrom: 2, expTo: 3, metric: 'MB', iec: 'MiB', metric_octet: 'Mo', iec_octet: 'Mio' },
-        { expFrom: 3, expTo: 4, metric: 'GB', iec: 'GiB', metric_octet: 'Go', iec_octet: 'Gio' },
-        { expFrom: 4, expTo: 5, metric: 'TB', iec: 'TiB', metric_octet: 'To', iec_octet: 'Tio' },
-        { expFrom: 5, expTo: 6, metric: 'PB', iec: 'PiB', metric_octet: 'Po', iec_octet: 'Pio' },
-        { expFrom: 6, expTo: 7, metric: 'EB', iec: 'EiB', metric_octet: 'Eo', iec_octet: 'Eio' },
-        { expFrom: 7, expTo: 8, metric: 'ZB', iec: 'ZiB', metric_octet: 'Zo', iec_octet: 'Zio' },
-        { expFrom: 8, expTo: 9, metric: 'YB', iec: 'YiB', metric_octet: 'Yo', iec_octet: 'Yio' }
-      ];
+      const tables = {
+        metric: [
+          { from: 0   , to: 1e3 , unit: 'B' , long: 'bytes' },
+          { from: 1e3 , to: 1e6 , unit: 'kB', long: 'kilobytes' },
+          { from: 1e6 , to: 1e9 , unit: 'MB', long: 'megabytes' },
+          { from: 1e9 , to: 1e12, unit: 'GB', long: 'gigabytes' },
+          { from: 1e12, to: 1e15, unit: 'TB', long: 'terabytes' },
+          { from: 1e15, to: 1e18, unit: 'PB', long: 'petabytes' },
+          { from: 1e18, to: 1e21, unit: 'EB', long: 'exabytes' },
+          { from: 1e21, to: 1e24, unit: 'ZB', long: 'zettabytes' },
+          { from: 1e24, to: 1e27, unit: 'YB', long: 'yottabytes' },
+        ],
+        metric_octet: [
+          { from: 0   , to: 1e3 , unit: 'o' , long: 'octets' },
+          { from: 1e3 , to: 1e6 , unit: 'ko', long: 'kilooctets' },
+          { from: 1e6 , to: 1e9 , unit: 'Mo', long: 'megaoctets' },
+          { from: 1e9 , to: 1e12, unit: 'Go', long: 'gigaoctets' },
+          { from: 1e12, to: 1e15, unit: 'To', long: 'teraoctets' },
+          { from: 1e15, to: 1e18, unit: 'Po', long: 'petaoctets' },
+          { from: 1e18, to: 1e21, unit: 'Eo', long: 'exaoctets' },
+          { from: 1e21, to: 1e24, unit: 'Zo', long: 'zettaoctets' },
+          { from: 1e24, to: 1e27, unit: 'Yo', long: 'yottaoctets' },
+        ],
+        iec: [
+          { from: 0                , to: Math.pow(1024, 1), unit: 'B'  , long: 'bytes' },
+          { from: Math.pow(1024, 1), to: Math.pow(1024, 2), unit: 'KiB', long: 'kibibytes' },
+          { from: Math.pow(1024, 2), to: Math.pow(1024, 3), unit: 'MiB', long: 'mebibytes' },
+          { from: Math.pow(1024, 3), to: Math.pow(1024, 4), unit: 'GiB', long: 'gibibytes' },
+          { from: Math.pow(1024, 4), to: Math.pow(1024, 5), unit: 'TiB', long: 'tebibytes' },
+          { from: Math.pow(1024, 5), to: Math.pow(1024, 6), unit: 'PiB', long: 'pebibytes' },
+          { from: Math.pow(1024, 6), to: Math.pow(1024, 7), unit: 'EiB', long: 'exbibytes' },
+          { from: Math.pow(1024, 7), to: Math.pow(1024, 8), unit: 'ZiB', long: 'zebibytes' },
+          { from: Math.pow(1024, 8), to: Math.pow(1024, 9), unit: 'YiB', long: 'yobibytes' },
+        ],
+        iec_octet: [
+          { from: 0                , to: Math.pow(1024, 1), unit: 'o'  , long: 'octets' },
+          { from: Math.pow(1024, 1), to: Math.pow(1024, 2), unit: 'Kio', long: 'kibioctets' },
+          { from: Math.pow(1024, 2), to: Math.pow(1024, 3), unit: 'Mio', long: 'mebioctets' },
+          { from: Math.pow(1024, 3), to: Math.pow(1024, 4), unit: 'Gio', long: 'gibioctets' },
+          { from: Math.pow(1024, 4), to: Math.pow(1024, 5), unit: 'Tio', long: 'tebioctets' },
+          { from: Math.pow(1024, 5), to: Math.pow(1024, 6), unit: 'Pio', long: 'pebioctets' },
+          { from: Math.pow(1024, 6), to: Math.pow(1024, 7), unit: 'Eio', long: 'exbioctets' },
+          { from: Math.pow(1024, 7), to: Math.pow(1024, 8), unit: 'Zio', long: 'zebioctets' },
+          { from: Math.pow(1024, 8), to: Math.pow(1024, 9), unit: 'Yio', long: 'yobioctets' },
+        ],
+      };
+      Object.assign(tables, options.customUnits);
 
-      const base = options.units === 'metric' || options.units === 'metric_octet' ? 1000 : 1024;
       const prefix = bytes < 0 ? '-' : '';
       bytes = Math.abs(bytes);
-
-      for (let i = 0; i < table.length; i++) {
-        const lower = Math.pow(base, table[i].expFrom);
-        const upper = Math.pow(base, table[i].expTo);
-        if (bytes >= lower && bytes < upper) {
-          const units = table[i][options.units];
-          if (i === 0) {
-            this.value = prefix + bytes;
-            this.unit = units;
-            return
-          } else {
-            this.value = prefix + (bytes / lower).toFixed(options.precision);
-            this.unit = units;
-            return
-          }
+      const table = tables[options.units];
+      if (table) {
+        const units = table.find(u => bytes >= u.from && bytes < u.to);
+        if (units) {
+          const value = units.from === 0
+            ? prefix + bytes
+            : prefix + (bytes / units.from).toFixed(options.precision);
+          this.value = value;
+          this.unit = units.unit;
+          this.long = units.long;
+        } else {
+          this.value = prefix + bytes;
+          this.unit = '';
+          this.long = '';
         }
+      } else {
+        throw new Error(`Invalid units specified: ${options.units}`)
       }
-
-      this.value = prefix + bytes;
-      this.unit = '';
     }
@@ -112,37 +96,10 @@
   /**
-   * @param {number} - the bytes value to convert.
-   * @param [options] {object} - optional config.
-   * @param [options.precision=1] {number} - number of decimal places.
-   * @param [options.units=metric] {string} - select `'metric'`, `'iec'`, `'metric_octet'` or `'iec_octet'` units.
-   * @returns {{ value: string, unit: string}}
+   * 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.
+   * @param {number} - The bytes value to convert.
+   * @param [options] {object} - Optional config.
+   * @param [options.precision=1] {number} - Number of decimal places.
+   * @param [options.units=metric] {string} - Specify `'metric'`, `'iec'`, `'metric_octet'`, `'iec_octet'` or the name of a property from the custom units table in `options.customUnits`.
+   * @param [options.customUnits] {object} - An object containing one or more custom unit lookup tables.
+   * @returns {object}
    * @alias module:byte-size
-   * @example
-   * ```js
-   * > const byteSize = require('byte-size')
-   *
-   * > byteSize(1580)
-   * { value: '1.6', unit: 'kB' }
-   *
-   * > byteSize(1580, { units: 'iec' })
-   * { value: '1.5', unit: 'KiB' }
-   *
-   * > byteSize(1580, { units: 'iec', precision: 3 })
-   * { value: '1.543', unit: 'KiB' }
-   *
-   * > byteSize(1580, { units: 'iec', precision: 0 })
-   * { value: '2', unit: 'KiB' }
-   *
-   * > byteSize(1580, { units: 'metric_octet' })
-   * { value: '1.6', unit: 'ko' }
-   *
-   * > byteSize(1580, { units: 'iec_octet' })
-   * { value: '1.5', unit: 'Kio' }
-   *
-   * > byteSize(1580, { units: 'iec_octet' }).toString()
-   * '1.5 Kio'
-   *
-   * > const { value, unit }  = byteSize(1580, { units: 'iec_octet' })
-   * > `${value} ${unit}`
-   * '1.5 Kio'
-   * ```
    */
@@ -155,2 +112,2 @@ function byteSize (bytes, options) {
 
-}));
+})));

package.json

@@ -11,3 +11,3 @@ {
   ],
-  "version": "6.0.0",
+  "version": "6.1.0",
   "main": "dist/index.js",
@@ -36,12 +36,18 @@ "license": "MIT",
     "test": "npm run dist && test-runner test.js",
-    "docs": "jsdoc2md -t README.hbs dist/index.js > README.md; echo",
-    "cover": "istanbul cover ./node_modules/.bin/test-runner test.js && cat coverage/lcov.info | ./node_modules/.bin/coveralls",
+    "docs": "jsdoc2md -t README.hbs dist/index.js > README.md",
+    "cover": "nyc npm test && nyc report --reporter=text-lcov | coveralls",
     "dist": "rollup -f umd -n byteSize -o dist/index.js index.mjs"
   },
   "devDependencies": {
-    "coveralls": "^3.0.6",
-    "jsdoc-to-markdown": "^5.0.1",
-    "rollup": "^1.21.4",
+    "coveralls": "^3.0.7",
+    "jsdoc-to-markdown": "^5.0.2",
+    "nyc": "^14.1.1",
+    "rollup": "^1.25.2",
     "test-runner": "^0.6.0"
+  },
+  "standard": {
+    "ignore": [
+      "dist"
+    ]
   }
 }

README.md

@@ -8,99 +8,110 @@ [![view on npm](https://img.shields.io/npm/v/byte-size.svg)](https://www.npmjs.org/package/byte-size)
 
-<a name="module_byte-size"></a>
+***Upgraders, please check the [release notes](https://github.com/75lb/byte-size/releases).***
 
-## byte-size
-An isomorphic, load-anywhere function to convert a bytes or octets value (e.g. `34565346`) to a human-readable string (`34.6 MB`). Choose between [metric or IEC units](https://en.wikipedia.org/wiki/Gigabyte), summarised below.
+# byte-size
 
-Value | Metric
------ | -------------
-1000  | kB  kilobyte
-1000^2 | MB  megabyte
-1000^3 | GB  gigabyte
-1000^4 | TB  terabyte
-1000^5 | PB  petabyte
-1000^6 | EB  exabyte
-1000^7 | ZB  zettabyte
-1000^8 | YB  yottabyte
+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 | IEC
------ | ------------
-1024  | KiB kibibyte
-1024^2 | MiB mebibyte
-1024^3 | GiB gibibyte
-1024^4 | TiB tebibyte
-1024^5 | PiB pebibyte
-1024^6 | EiB exbibyte
-1024^7 | ZiB zebibyte
-1024^8 | YiB yobibyte
+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 | Metric (octet)
------ | -------------
-1000  | ko  kilooctet
-1000^2 | Mo  megaoctet
-1000^3 | Go  gigaoctet
-1000^4 | To  teraoctet
-1000^5 | Po  petaoctet
-1000^6 | Eo  exaoctet
-1000^7 | Zo  zettaoctet
-1000^8 | 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 |
 
-Value | IEC (octet)
------ | ------------
-1024  | Kio kilooctet
-1024^2 | Mio mebioctet
-1024^3 | Gio gibioctet
-1024^4 | Tio tebioctet
-1024^5 | Pio pebioctet
-1024^6 | Eio exbioctet
-1024^7 | Zio zebioctet
-1024^8 | Yio yobioctet
+## Synopsis
 
-**Example**  
+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')
+> const byteSize = require('byte-size')
+
+> byteSize(1580)
+{ value: '1.6', unit: 'kB', long: 'kilobytes' }
 ```
-<a name="exp_module_byte-size--byteSize"></a>
 
-### byteSize(bytes, [options]) ⇒ <code>Object</code> ⏏
-**Kind**: Exported function  
+The object returned by `byteSize` defines a `toString` method therefore can be used directly in string context.
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| bytes | <code>number</code> |  | the bytes value to convert. |
-| [options] | <code>object</code> |  | optional config. |
-| [options.precision] | <code>number</code> | <code>1</code> | number of decimal places. |
-| [options.units] | <code>string</code> | <code>&quot;metric&quot;</code> | select `'metric'`, `'iec'`, `'metric_octet'` or `'iec_octet'` units. |
-
-**Example**  
 ```js
-> const byteSize = require('byte-size')
+> `Filesize: ${byteSize(12400)}`
+'Filesize: 12.4 kB'
+```
 
-> byteSize(1580)
-{ value: '1.6', unit: 'kB' }
+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' }
+{ 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' }
+{ value: '1.543', unit: 'KiB', long: 'kibibytes' }
 
 > byteSize(1580, { units: 'iec', precision: 0 })
-{ value: '2', unit: 'KiB' }
+{ value: '2', unit: 'KiB', long: 'kibibytes' }
+```
 
-> byteSize(1580, { units: 'metric_octet' })
-{ value: '1.6', unit: 'ko' }
+Define custom units by passing an object containing one or more additional conversion tables to `options.customUnits`.
 
-> byteSize(1580, { units: 'iec_octet' })
-{ value: '1.5', unit: 'Kio' }
+```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' }
+  ]
+}
 
-> byteSize(1580, { units: 'iec_octet' }).toString()
-'1.5 Kio'
+> const { value, unit } = byteSize(10000, { customUnits, units: 'simple' })
 
-> const { value, unit }  = byteSize(1580, { units: 'iec_octet' })
-> `${value} ${unit}`
-'1.5 Kio'
+> `${value}${unit}`
+'10.0K'
 ```
 
-### Load anywhere
+<a name="module_byte-size"></a>
 
+## byte-size
+<a name="exp_module_byte-size--byteSize"></a>
+
+### byteSize(bytes, [options]) ⇒ <code>object</code> ⏏
+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 | Default | Description |
+| --- | --- | --- | --- |
+| bytes | <code>number</code> |  | The bytes value to convert. |
+| [options] | <code>object</code> |  | Optional config. |
+| [options.precision] | <code>number</code> | <code>1</code> | Number of decimal places. |
+| [options.units] | <code>string</code> | <code>&quot;metric&quot;</code> | Specify `'metric'`, `'iec'`, `'metric_octet'`, `'iec_octet'` or the name of a property from the custom units table in `options.customUnits`. |
+| [options.customUnits] | <code>object</code> |  | An object containing one or more custom unit lookup tables. |
+
+
+## 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.
@@ -107,0 +118,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

21420

increased by26.52%

Number of lines in readme file

145

increased by8.21%

Worsened metrics

Dev dependency count

5

increased by25%

Lines of code

196

decreased by-29.5%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes