Utils

A collection of reusable utilities for manipulating data.

Install

First, we will install @w3ux/utils as a dependency in our project.

npm

npm i @w3ux/utils

Base Utils

A collection of utilities for manipulating data.

camelize

Converts a string of text to camelCase.

@param (string) str The string to become camelCase.
@returns (string) The input string, but camelCased.

camelize("hello_world") // helloWorld
camelize("hello world") // helloWorld
camelize("  leadingWhitespace") // leadingWhitespace
camelize("   multiple   spaces   ") // multipleSpaces
camelize("HeLLo WoRLD") // heLLoWoRld

ellipsisFn

Receives an address and creates ellipsis on the given string, based on parameters.

@param (string) str The string to apply the ellipsis on.
@param (number) amount The amount of characters that the ellipsis will be.

const address = "234CHvWmTuaVtkJpLS9oxuhFd3HamcEMrfFAPYoFaetEZmY7";
 
// How many characters to show after Ellipsis (placed at the start)
ellipsisFn(address, 4, "start") // ...ZmY7
// How many characters to show before Ellipsis (placed on the end)
ellipsisFn(address, 4, "end") // 234C...
 
// How many characters to show after Ellipsis (placed at the start)
ellipsisFn("Some random value", 8, "start");// ...dom value
// How many characters to show before Ellipsis (placed on the end)
ellipsisFn("Some random value", 8, "end") // Some ran...
 
ellipsisFn(address, 4) // 234C...ZmY7
ellipsisFn(address, 10) // 234CHvWmTu...oFaetEZmY7
 
// amount defaults to 6
ellipsisFn(address) // 234CHv...tEZmY7
 
// (fallbacks to minimum, of 4)
ellipsisFn(address, 2) // 234C...ZmY7
 
// (fallbacks to maximum acceptable when too large: string.length / 2 - 3)
ellipsisFn(address, 100) // 234C...ZmY7

maxBigInt

Finds the maximum value among a list of BigInt values.

@param {...bigint} values A list of BigInt values to compare.
@returns {bigint} The largest BigInt value in the provided list.

maxBigInt(10n, 50n, 30n, 100n, 20n) // 100n
maxBigInt(-10n, -50n, -30n, -100n, -20n) // -10n
maxBigInt(42n) // 42n
maxBigInt(-1000n, 500n, -200n, 1000n) // 1000n

minBigInt

Finds the minimum value among a list of BigInt values.

@param {...bigint} values A list of BigInt values to compare.
@returns {bigint} The smallest BigInt value in the provided list.

minBigInt(10n, 50n, 30n, 100n, 20n) 10n
minBigInt(-10n, -50n, -30n, -100n, -20n) -100n
minBigInt(42n) 42n
minBigInt(-1000n, 500n, -200n, 1000n) -1000n

minDecimalPlaces

Forces a number to have at least the provided decimal places.

@param {string | number | BigInt} val The input number, which can be a string with or without commas, a number, or a BigInt..
@param {number} minDecimals The minimum number of decimal places to enforce.
@returns {string} The formatted number as a string, padded with zeros if needed to meet minDecimals, retaining commas if originally provided. If val is invalid, returns "0".

minDecimalPlaces("10.5", 4) // "10.5000"
minDecimalPlaces("8.123456789", 5) // "8.123456789"
minDecimalPlaces("42", 3) // "42.000"
minDecimalPlaces("0", 2) // "0.00"
minDecimalPlaces("-123.0000", 4) // "-123.0000"
minDecimalPlaces("8,452", 5) // "8,452.00000"
minDecimalPlaces("8.123456789", 5) // "8.123456789"
minDecimalPlaces("8.1", 3) // "8.100"
minDecimalPlaces("8.123", 3) // "8.123"
minDecimalPlaces("1,234.5", 3) // "1,234.500"
minDecimalPlaces(1234.5, 2) // "1234.50"
minDecimalPlaces(123456789n, 5) // "123456789.00000"
minDecimalPlaces("0", 4) // "0.0000"
minDecimalPlaces(100000000000000000000n, 3) // "100000000000000000000.000"
minDecimalPlaces("100,000,000,000,000,000,000", 3) // "100,000,000,000,000,000,000.000"
minDecimalPlaces("invalid", 2) // "0"

pageFromUri

Use url variables to load the default components upon the first page visit.

@param (string) pathname The url that we want to get the page from.
@param (string) fallback Fallback string in case the url is wrong or empty.
@returns (string) The value of the trimmed url.

pageFromUri("/products/detail", "home") // detail
 
// note the extra space at the end of the pathname
pageFromUri("/products/detail ", "home") // detail
pageFromUri("", "home"); // home
pageFromUri("/categories/", "home") // home
pageFromUri("/about us", "home") // about us
pageFromUri("/products/detail#section", "home") // detail#section

rmCommas

Removes the commas from a string.

@param (string) str The url that we want to get the page from.
@returns (string) The result of the fn.

const result = rmCommas("1,000,000"); // 1000000

shuffle

Shuffle a set of objects.

@param (array[object]) array An array of objects.
@returns (array[object]) The input array of objects but shuffled.

shuffle([1, 2, 3, 4, 5]) // [2, 5, 1, 3, 4] (or some other shuffled result)
shuffle([]) // []
shuffle([42]) // [42]

Unit Utils

A collection of utilities for manipulating chain units.

planckToUnit

Converts an on-chain balance value from planck to a decimal value in token units.

@param {number | BigInt | string} val The balance value in planck. Accepts a number,
@param {number} units The number of decimal places in the token unit (10^units planck per 1 token).
@returns {string} The equivalent token unit value as a decimal string.

Examples:

planckToUnit(10000000n, 6) // "10.000000"
planckToUnit("10000000", 6) // "10.000000"
planckToUnit(10000000, 6) // "10.000000"
planckToUnit(10n, 10) // "0.0000000010"
planckToUnit("10,000,000", 2) // "0"
planckToUnit("invalid&#l-", 2) // "0"
planckToUnit("10000000", 6) // "10.000000"
planckToUnit(10000000n, -2) // "10000000"

unitToPlanck

Converts a token unit value to an integer value in planck.

@param {string | number | BigInt} val The token unit value to convert. Accepts a string, number, or BigInt.
@param {number} units The number of decimal places for conversion (10^units planck per 1 token).
@returns {BigInt} The equivalent value in planck as a BigInt.

Examples

unitToPlanck(5n, 8) // 500000000n
unitToPlanck("5", 6) // 5000000n
unitToPlanck(5, 4) // 50000n
unitToPlanck("10", 6) // 10000000n
unitToPlanck(42, 0) // 42n
unitToPlanck("100000", -6) // 0n
unitToPlanck("", 8) // 0n
unitToPlanck("invalid&#l-", 4) // 0n
 
// Valid when unit value is decimals + 1.
unitToPlanck("0.0001", 4) // 1n
 
// Invalid when units are smaller than decimals - returns zero.
unitToPlanck("0.0001", 3) // 0n