https://github.com/tsmx/human-readable
Easily create human-readable strings from byte sizes, e.g. 17238 --> 17.24 kB. Supports decimal (MB,GB,..) and binary (MiB, GiB,..) units as well as user-defined conversion from/to other sizes.
https://github.com/tsmx/human-readable
binary bytes conversion decimal filesize human-readable iec pretty-print si
Last synced: 5 months ago
JSON representation
Easily create human-readable strings from byte sizes, e.g. 17238 --> 17.24 kB. Supports decimal (MB,GB,..) and binary (MiB, GiB,..) units as well as user-defined conversion from/to other sizes.
- Host: GitHub
- URL: https://github.com/tsmx/human-readable
- Owner: tsmx
- License: mit
- Created: 2020-09-24T18:26:53.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-08-06T19:24:37.000Z (9 months ago)
- Last Synced: 2024-10-07T03:18:49.208Z (7 months ago)
- Topics: binary, bytes, conversion, decimal, filesize, human-readable, iec, pretty-print, si
- Language: JavaScript
- Homepage:
- Size: 593 KB
- Stars: 5
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [**@tsmx/human-readable**](https://github.com/tsmx/human-readable)
[](https://opensource.org/licenses/MIT)
[](https://img.shields.io/github/actions/workflow/status/tsmx/human-readable/git-build.yml?branch=master)
[](https://coveralls.io/github/tsmx/human-readable?branch=master)
> Easily create human-readable strings from byte sizes, e.g. `17238` → `17.24 kB`. Supports decimal (MB,GB,..) and binary (MiB, GiB,..) units as well as user-defined conversion from/to other sizes.
For details about the differences of decimal (SI) and binary (IEC) units please refer to [Wikipedia](https://en.wikipedia.org/wiki/Byte).
Also check out the [full documentation](https://tsmx.net/human-readable/). Type declarations for seamless usage in TypeScript projects are included. If you need to use this package on the client-side in the browser using plain JavaScript, refer to [this article](https://tsmx.net/npm-packages-browser/).
## Usage
```js
const hr = require('@tsmx/human-readable');
hr.fromBytes(17238);
// '17.24 kB'
hr.fromBytes(17238, { mode: 'IEC' });
// '16.83 KiB'
hr.fromBytes(17238, { numberOnly: true });
// '17.24'
hr.fromBytes(17238, { fixedPrecision: 1 });
// '17.2 kB'
hr.fromBytes(17238, { fullPrecision: true });
// '17.238 kB'
hr.fromTo(17, 'GBYTE', 'KBYTE');
// '17000000 kB'
hr.fromTo(17, 'GBYTE', 'KBYTE', { mode: 'IEC' });
// '17825792 KiB'
hr.availableSizes();
// [ 'BYTE', 'KBYTE', 'MBYTE', 'GBYTE', 'TBYTE', 'PBYTE' ]
```
## API
### fromBytes(bytes, options)
Automatically creates a human-readable string out of a given number of bytes. E.g. `71255` → `71.26 kB`
#### bytes
Type: `Number`
Amount of bytes.
#### options
Type: `Object`
Optional.
##### mode
Type: `String`
Default: none (use decimal mode)
Can be set to `IEC` to use binary conversion (factor 1.024) and units (KiB,MiB,...). If not set or to any other value, decimal conversion (factor 1.000) and units (kB, MB,...) are used.
##### numberOnly
Type: `Boolean`
Default: `false`
If set to true, conversion only returns the number and omits the unit. Overrides `noWhitespace`.
##### fixedPrecision
Type: `Number`
If set the returned number string is formatted to the given fixed decimal places. If not set, the default behaviour of the conversion is to use a dynamic number of decimal places from zero up to two.
##### fullPrecision
Type: `Boolean`
Default: `false`
If set to true, the returned number value will be presented with full available decimal places. Overrides `fixedPrecision`.
##### noWhitespace
Type: `Boolean`
Default: `false`
If set to true, the whitespace between the number and unit string is omitted. E.g. `10MB` instead of `10 MB`.
### fromTo(value, fromSize, toSize, options)
Converts a value from a given size unit to a human-readable string of the target size. E.g. converting Gigabytes to Megabytes.
#### value
Type: `Number`
The value to be converted.
#### fromSize
Type: `String`
The size `value` has. Must be one out of `availableSizes`.
#### toSize
Type: `String`
The size `value` should be converted to. Must be one out of `availableSizes`.
#### options
Type: `Object`
See options description under `fromBytes`.
### availableSizes()
Returns an array of strings of all available sizes.