number-slayer
At a glance
range(7, 22, 3) // --> [7, 10, 13, 16, 19]
addCommasToNumber(-43000000.25) // --> '-43,000,000.25'
roundThousands(27743000.21) // --> 30000000
zeroPad(4, 2, 3) // --> '04.000'
toPrecision(3.141592653589793, 3) // --> 3.142
randomInt(79, 83) // --> 82
countIntDigits(123456789) // --> 9
isNumber(98.3) // --> true
modulus(-5, 3) // --> 1
nthRoot(8, 3) // --> 2
gcd(12, 18) // --> 6
bin(-36) // --> '-0b100100'
int('-0b100100') // --> -36
enToFaNumber(1234567890) // --> '۱۲۳۴۵۶۷۸۹۰'
toFaPercent(47) // --> '٪ ۴۷'
// ...
About
This is a very tiny tree-shakable number-utilities library designed for JavaScript/TypeScript projects. It is a collection of functions that are used to perform common daily tasks with numbers, including numbers generation (both random and non-random), rounding to a specific number of decimal places, converting numbers to formatted strings, etc.
number-slayer:
- has no dependencies
- is written in TypeScript
- is lightweight (<2kb gzipped)
- supports both ESM and CJS outputs
- is compatible with both Node.js and browsers
- is modular, functional, tree-shakable and easy to use
- is developed by TDD approach and is fully tested and documented
Installation
npm install number-slayer
# or
yarn add number-slayer
Usage
import { addCommasToNumber } from 'number-slayer';
// or if you are using commonjs:
// const addCommasToNumber = require('number-slayer/dist/index.cjs').addCommasToNumber;
const number = addCommasToNumber(1234567890);
console.log(number); // --> '1,234,567,890'
Quick Guide
- General utils
-
Counting utils
- countFloatDigits - returns the number of digits in the decimal part of a number
- countIntDigits - returns the number of digits in the integer part of a number
- countWithZeros - returns 1 if the argument is number or truthy
-
Transformation utils
- addCommasToNumber - seperates a number by every 3 digits
- avoidMinusZero - converts negative zero to zero
- roundFloat - rounds a real number to a certain number of decimal places
- roundThousands - rounds a real number to a certain multiple of 10
- toPrecision - rounds a number to a specific number of decimal places
- zeroPad - pads a number with leading or trailing zeros of a specific length
-
Validation utils
- isNumber - returns true if the argument is a real number
- isBigNumber - returns true if the argument number out of the bounds of +-Number.MAX_SAFE_INTEGER
- isFloat - returns true if the argument is a float number
- Mathematical utils
- Binary conversion utils
-
Persian language helper utils - number helper utils for the Persian language
-
faToEnNumber - converts a Persian number to English
(e.g. '۱۲۳' to '123')
-
enToFaNumber - converts an English number to Persian
(e.g. '123' to '۱۲۳')
-
toFaPercent - converts a number to Persian percent
(e.g. '50' to '٪ ۵۰')
-
faToEnNumber - converts a Persian number to English
-
Fun utils
-
rollDice - returns a random dice number
🎲 -
rollMultipleDices - returns a series of random dice numbers
🎲 🎲 🎲 🎲
-
rollDice - returns a random dice number
Detailed Examples
⚙️ General utils
randomInt
returns a random integer number between (and including) the given min
& max
values
import { randomInt } from 'number-slayer';
console.log(randomInt(1, 10)); // random number between 1 and 10. e.g. 5
console.log(randomInt(10, 1)); // is the same as randomInt(1, 10)
range
creates an array of numbers from the starting number up to the ending number (exclusive) with arbitrary step (default is 1).
import { range } from 'number-slayer';
const numbers = range(3, 10); //-> [3, 4, 5, 6, 7, 8, 9]
const numbers2 = range(25, 32, 2); //-> [25, 27, 29, 31]
split
splits a float into a whole number and a fractional part (sum of the two parts is equal to the original number). returns an array with the two parts.
import { split } from 'number-slayer';
const num = split(1.23456789); // -> [1, 0.23456789]
⚙️ Counting utils
countFloatDigits
returns the number of decimal places in a float number.
import { countFloatDigits } from 'number-slayer';
countFloatDigits(-43.156) // -> 3
countIntDigits
returns the number of digits in the integer part of a number
import { countIntDigits } from 'number-slayer';
const ints = countIntDigits(-198989.999); // -> 6
countWithZeros
can be used as a callback function when trying to count digits and truthy values in an array (counts zero as well). the return value of this function is either 1 or 0;
import { countWithZeros } from 'number-slayer';
const mixedArray = [null, undefined, 0, "0", 6, "345", "-12", ""];
const passList = mixedArray.filter(countWithZeros); // -> [0, "0", 6, "345", "-12"]
console.log(passList.length); // 5
⚙️ Transformation utils
addCommasToNumber
seperates the integer part of a number with commas every three digits. the delimiter can be defined as a custom string as well.
import { addCommasToNumber } from 'number-slayer';
const n1 = addCommasToNumber(1234567890) // -> "1,234,567,890"
const n2 = addCommasToNumber(-5589.43, "'") // -> "-5'589.43"
avoidMinusZero
converts -0 to 0, else returns the non-zero number.
import { avoidMinusZero } from 'number-slayer';
const n1 = avoidMinusZero(0) // -> 0
const n2 = avoidMinusZero(-0) // -> 0
const n3 = avoidMinusZero(1) // -> 1
const n4 = avoidMinusZero(-1) // -> -1
roundFloat
rounds a float number to the given number of decimal places. it takes three arguements:
-
num
(required) number to be rounded -
precision
(optional. default: 14) number of decimal digits from right not to be rounded/floored/ceild -
format
(optional. default: "round") number-cutting strategy. can be: `"round" | "floor" | "ceil"
import { roundFloat } from 'number-slayer';
roundFloat(1.23456789, 3); // -> 1.235
roundFloat(1.23456789, 2, "floor"); // -> 1.23
roundThousands
rounds a real number to a certain multiple of 10. it takes three arguements:
-
num
(required) number to be rounded -
precision
(optional. default: 1) number of digits from left not to be rounded/floored/ceild -
format
(optional. default: "round") number-cutting strategy. can be:"round" | "floor" | "ceil"
import { roundThousands } from 'number-slayer';
roundThousands(1462621.12158); // -> 1000000
roundThousands(1462621.12158, 3, 'ceil'); // -> 1470000
toPrecision
rounds a number to the given precision decimals.
also returns non-numeric values as they are without returning NaN
stuff or throwing errors.
import { toPrecision } from 'number-slayer';
console.log(toPrecision('foo')); // 'foo'
console.log(toPrecision(5.2341)); // 5.2341
console.log(toPrecision(48.23416789, 3)); // 48.234
NOTE: JavaScript has a similar method: toPrecision, which doesn't work like this.
zeroPad
pads a number with leading or trailing zeros of a specific length (can be used for both the integer and decimal parts).
arguments:
-
num
(required) number to be padded -
int
(optional) length of the desired string for the integer part of the number(defaults to 2)
-
dec
(optional) length of the desired string for the decimal part of the number -
addSign
(optional) if true, the positive sign of the number will also be added to the beginning of the resulting string- if the argument number is a positive signed number-string, the sign will be added to the beginning of the resulting string (default behavior)
- NOTE: the negative sign will be added regardless of the value of this argument
import { zeroPad } from 'number-slayer';
console.log(zeroPad(1)); // '01'
console.log(zeroPad(1, 3)); // '001'
console.log(zeroPad(1, 3, 2)); // '001.00'
console.log(zeroPad(-47.8, 3, 2)); // '-047.80'
console.log(zeroPad('+47.8', 3, 2)); // '+047.80'
console.log(zeroPad(47.8, 3, 2)); // '047.80'
console.log(zeroPad(47.8, 3, 2, true)); // '+047.80'
⚙️ Validation utils
isNumber
checks if the given argument is a real number. returns true if the argument is a real number, false otherwise.
import { isNumber } from 'number-slayer';
console.log(isNumber({})); // false
console.log(isNumber(-1.1)); // true
console.log(isNumber(undefined)); // false
console.log(isNumber(1 / Math.sqrt(Math.PI))); // true
isBigNumber
checks if the number is out of +-MAX_SAFE_INTEGER bounds. returns true if the argument number is too big for calculations.
import { isBigNumber } from 'number-slayer';
isBigNumber(Number.MIN_SAFE_INTEGER - 1); // -> true
isBigNumber(9100000000000000); // -> true
isFloat
checks if the given argument is a float number. returns true if the argument is a float number, false otherwise.
import { isFloat } from 'number-slayer';
console.log(isFloat(-1.1)); // true
console.log(isFloat(12.0)); // false
console.log(isFloat(1 / Math.sqrt(Math.PI))); // true
⚙️ Mathematical utils
modulus
returns the positive remainder of a division, no matter the sign of the dividend.
import { modulus } from 'number-slayer';
const simpleModulus = -5 % 3; // -> -2
const numberSlayerModulus = modulus(-5, 3); // -> 1
// 1 is the same as -2 + 3
nthRoot
returns the nth root of a number.
- (e.g: 2nd root of a number is the square root of the number.)
- (e.g: 3rd root of a number is the cube root of the number.)
import { nthRoot } from 'number-slayer';
const num = nthRoot(64, 3); // -> 4
const num3 = nthRoot(2, 2); // -> 1.4142135623730951
gcd
returns the Greatest Common Divisor of the argument numbers
import { gcd } from 'number-slayer';
const num = gcd(12, 18, 36) // -> 6
lcm
returns the Least Common Multiple of the argument numbers
import { lcm } from 'number-slayer';
const num = lcm(12, 18, 36) // -> 36
⚙️ Binary conversion utils
int
converts a binary number to integer. 👇🏻
bin
converts an integer number to binary (the result will always start with the prefix 0b
. this is similar to Python's bin
function).
import { int, bin } from 'number-slayer';
console.log(int('100100')); // 36
console.log(int('0b100100')); // 36
console.log(bin(36)); // '0b100100'
console.log(bin(-36)); // '-0b100100'
⚙️ Persian language helper utils
faToEnNumber
converts a Persian number to English (ignores non-numeric characters).
import { faToEnNumber } from 'number-slayer';
console.log(faToEnNumber('۱۲۳۴۵۶۷۸۹۰')); // '1234567890'
console.log(faToEnNumber('He knows -25.48 is -۲۵.۴۸')); // 'He knows -25.48 is -25.48'
enToFaNumber
converts an English number to Persian (ignores non-numeric characters).
import { enToFaNumber } from 'number-slayer';
console.log(enToFaNumber(-123.66)); // '-۱۲۳.۶۶'
console.log(enToFaNumber('مبلغ 25000 تومان')); // 'مبلغ ۲۵۰۰۰ تومان'
toFaPercent
converts a number to Persian percent.
import { toFaPercent } from 'number-slayer';
console.log(toFaPercent(50)); // '٪ ۵۰'
⚙️ Fun utils
rollDice
returns a random 1
to 6
) 👇🏻
rollMultipleDices
returns an array of random dice numbers
import { rollDice, rollMultipleDices } from 'number-slayer';
console.log(rollDice()); // a random dice number: e.g. 6
console.log(rollMultipleDices(4)); // a list of random dice numbers: e.g. [4, 1, 6, 3]
Want More Examples?
see the tests folder for more detailed examples.
Contributing
Please feel free to open an issue or create a pull request to add a new feature or fix a bug. (see contributing for more details)
License
The MIT License (MIT)
© (2021 - Present) Sina Khodabandehloo