human-format

What is human-format?

The human-format npm package is designed to help format numbers into human-readable strings. It is particularly useful for converting large numbers into more digestible formats, such as converting bytes into kilobytes, megabytes, etc., or formatting large numbers with appropriate suffixes.

What are human-format's main functionalities?

Formatting Numbers with Suffixes

This feature allows you to format large numbers with appropriate suffixes like 'K' for thousands, 'M' for millions, etc. The code sample demonstrates how to format the number 1234567 into '1.23M'.

const humanFormat = require('human-format');

const formattedNumber = humanFormat(1234567);
console.log(formattedNumber); // Output: '1.23M'

Formatting Bytes

This feature is specifically for formatting byte values into human-readable strings with appropriate units like KB, MB, GB, etc. The code sample shows how to format 1234567890 bytes into '1.23GB'.

const humanFormat = require('human-format');

const formattedBytes = humanFormat.bytes(1234567890);
console.log(formattedBytes); // Output: '1.23GB'

Custom Units

This feature allows you to define custom units and scales for formatting. The code sample demonstrates how to create a custom unit 'banana' and format the number 1234567 into '1.23Mbanana'.

const humanFormat = require('human-format');

const customUnits = new humanFormat.Scale({
  'unit': 'banana',
  'base': 1000,
  'prefixes': {
    '': 1,
    'k': 1000,
    'M': 1000000
  }
});

const formattedCustom = humanFormat(1234567, { scale: customUnits });
console.log(formattedCustom); // Output: '1.23Mbanana'

Other packages similar to human-format

numeral

The numeral package is a library for formatting and manipulating numbers. It provides a wide range of formatting options, including currency, percentages, and more. Compared to human-format, numeral offers more comprehensive number formatting capabilities but may be more complex to use for simple human-readable formatting.

filesize

The filesize package is specifically designed for formatting file sizes into human-readable strings. It supports various units like bytes, kilobytes, megabytes, etc. While it is similar to the bytes formatting feature of human-format, filesize is more specialized and offers more options for file size formatting.

pretty-bytes

The pretty-bytes package is a simple utility for converting bytes into a human-readable string. It is lightweight and easy to use, making it a good alternative for those who only need to format byte values. Compared to human-format, pretty-bytes is more focused and has fewer features but is very straightforward for its specific use case.

README

human-format

Converts a number to/from a human readable string: 1337 ↔ 1.34kB

Installation

Node & Browserify/Webpack

Installation of the npm package:

> npm install --save human-format

Then require the package:

var humanFormat = require("human-format");

Browser

You can directly use the build provided at unpkg.com:

<script src="https://unpkg.com/human-format@1/index.js"></script>

Usage

Formatting

humanFormat(1337);
//=> '1.34 k'

// The maximum number of decimals can be changed.
humanFormat(1337, {
  maxDecimals: 1,
});
//=> '1.3 k'

// maxDecimals can be set to auto, so that there is 1 decimal between -10 and 10 excluded and none out of this interval.
humanFormat(1337, {
  maxDecimals: "auto",
});
//=> '1.3 k'

humanFormat(13337, {
  maxDecimals: "auto",
});
//=> '13 k'

// A fixed number of decimals can be set.
humanFormat(1337, {
  decimals: 4,
});
//=> '1.3370 k'

// Units and scales can be specified.
humanFormat(65536, {
  scale: "binary",
  unit: "B",
});
//=> 64 kiB

// There is a helper for this.
humanFormat.bytes(65536);
//=> 64 kiB

// A custom separator can be specified.
humanFormat(1337, {
  separator: " - ",
});
//=> 1.34 - k

// Custom scales can be created!
var timeScale = new humanFormat.Scale({
  seconds: 1,
  minutes: 60,
  hours: 3600,
  days: 86400,
  months: 2592000,
});
humanFormat(26729235, { scale: timeScale });
//=> 10.31 months

// Helper when the scale is regular, i.e. prefixes are powers of a constant factor
var binaryScale = humanFormat.Scale.create(["", "Ki", "Mi", "Gi", "Ti"], 1024);
humanFormat(173559053, { scale: binaryScale });
//=> 165.52 Mi

// You can force a prefix to be used.
humanFormat(100, { unit: "m", prefix: "k" });
//=> 0.1 km

// You can access the raw result.
humanFormat.raw(100, { prefix: "k" });
//=> {
//   prefix: 'k',
//   value: 0.09999999999999999 // Close value, not rounded.
// }

Parsing

humanFormat.parse("1.34 kiB", { scale: "binary" });
//=> 1372.16

// Fallbacks when possible if the prefix is incorrectly cased.
humanFormat.parse("1 g");
// => 1000000000

// You can access the raw result.
humanFormat.parse.raw("1.34 kB");
//=> {
//  factor: 1000,
//  prefix: 'k',
//  unit: 'B',
//  value: 1.34
//}

Contributions

Contributions are very welcomed, either on the documentation or on the code.

You may:

• report any issue you've encountered;
• fork and create a pull request.

Contributors:

• @djulien
• @qrohlf
• @Itay289
• @sweetpi

License

ISC © Julien Fontanet