Merge pull request #2 from w3ux/rb-refresh-utils

feat: Refresh utils docs and add BigInt functions

docs/pages/library/utils.mdx

@@ -37,29 +37,23 @@ A collection of utilities for manipulating data.
 
 Converts a string of text to camelCase.
 
-- `@param (string)` string to become camelCase.
-- `@returns (string)` the input string, but camelCased.
+- `@param (string) str` The string to become camelCase.
+- `@returns (string)` The input string, but camelCased.
 
 ```tsx
 camelize("hello_world") // helloWorld
 camelize("hello world") // helloWorld
 camelize("  leadingWhitespace") // leadingWhitespace
 camelize("   multiple   spaces   ") // multipleSpaces
-
-camelize(HeLLo WoRLD) // heLLoWoRld 
-// This is due to the fact that Capital letters identify as "beginning of a word")
-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)` The string to apply the ellipsis on.
-- `@param (number)` The amount of characters that the ellipsis will be.
+- `@param (string) str` The string to apply the ellipsis on.
+- `@param (number) amount` The amount of characters that the ellipsis will be.
 
 ```tsx
 const address = "234CHvWmTuaVtkJpLS9oxuhFd3HamcEMrfFAPYoFaetEZmY7";
@@ -74,31 +68,6 @@ 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...
 
-// position defaults to "center"
-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
-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...
-
-// position defaults to "center"
 ellipsisFn(address, 4) // 234C...ZmY7
 ellipsisFn(address, 10) // 234CHvWmTu...oFaetEZmY7
 
@@ -112,70 +81,68 @@ ellipsisFn(address, 2) // 234C...ZmY7
 ellipsisFn(address, 100) // 234C...ZmY7
 ```
 
-### greaterThanZero
+### maxBigInt
 
-Returns whether a BigNumber is greater than zero.
+Finds the maximum value among a list of `BigInt` values.
 
-- `@param (BigNumber)` the input to check against.
-- `@returns (boolean)` the result of the fn.
+- `@param {...bigint} values` A list of BigInt values to compare.
+- `@returns {bigint}` The largest BigInt value in the provided list.
 
 ```tsx
-greaterThanZero(new BigNumber("10")) // true
-greaterThanZero(new BigNumber("0")) // false
-greaterThanZero(new BigNumber("-5")) // false
-greaterThanZero(new BigNumber("999999999999999999999999999")) // true
-greaterThanZero(new BigNumber("-999999999999999999999999999")) // false
-greaterThanZero(new BigNumber("10")) // true
-greaterThanZero(new BigNumber("0")) // false
-greaterThanZero(new BigNumber("-5")) // false
-greaterThanZero(new BigNumber("999999999999999999999999999")) // true
-greaterThanZero(new BigNumber("-999999999999999999999999999")) // false
+maxBigInt(10n, 50n, 30n, 100n, 20n) // 100n
+maxBigInt(-10n, -50n, -30n, -100n, -20n) // -10n
+maxBigInt(42n) // 42n
+maxBigInt(-1000n, 500n, -200n, 1000n) // 1000n
 ```
 
-### isNotZero
+### minBigInt
 
-Returns whether a BigNumber is zero.
+Finds the minimum value among a list of `BigInt` values.
 
-- `@param (BigNumber)` the input to check against.
-- `@returns (boolean)` the result of the fn.
-```
+ - `@param {...bigint} values` A list of BigInt values to compare.
+ - `@returns {bigint}` The smallest BigInt value in the provided list.
 
 ```tsx
-isNotZero(new BigNumber("10")) // true
-isNotZero(new BigNumber("0")) // false
-isNotZero(new BigNumber("-5")) // true
-isNotZero(new BigNumber("999999999999999999999999999")) // true
-isNotZero(new BigNumber("-999999999999999999999999999")) // true
-isNotZero(new BigNumber("10")) // true
-isNotZero(new BigNumber("0")) // false
-isNotZero(new BigNumber("-5")) // true
-isNotZero(new BigNumber("999999999999999999999999999")) // true
-isNotZero(new BigNumber("-999999999999999999999999999")) // true
+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)` string that we want to update the decimal places.
-- `@param (number)` number of decimals to be adjusted.
+- `@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".
 
 ```tsx
-const val = "10.5";
-const minDecimals = 4;
-fn.minDecimalPlaces(val, minDecimals);// 10.5000
-const val = "10.5";
-const minDecimals = 4;
-fn.minDecimalPlaces(val, minDecimals);// 10.5000
+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
+### pageFromUri
 
 Use url variables to load the default components upon the first page visit.
 
-- `@param (string)` the url that we want to get the page from.
-- `@param (string)` fallback string in case the url is wrong or empty.
-- `@returns (string)` the value of the trimmed url.
+- `@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.
 
 ```tsx
 pageFromUri("/products/detail", "home") // detail
@@ -185,37 +152,26 @@ 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
-pageFromUri("/products/detail", "home") // detail
-
-// attention on 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
+pageFromUri("/products/detail#section", "home") // detail#section
 ```
 
 ### rmCommas
 
 Removes the commas from a string.
 
-- `@param (string)` the url that we want to get the page from.
-- `@returns (string)` the result of the fn.
+- `@param (string) str` The url that we want to get the page from.
+- `@returns (string)` The result of the fn.
 
 ```tsx
-const inputValue = "1,000,000";
-const result = fn.rmCommas(inputValue); // 1000000
-const inputValue = "1,000,000";
-const result = fn.rmCommas(inputValue); // 1000000
+const result = rmCommas("1,000,000"); // 1000000
 ```
 
 ### shuffle
 
 Shuffle a set of objects.
 
-- `@param (array[object])` an array of objects.
-- `@returns (array[object])` the input array of objects but shuffled.
+- `@param (array[object]) array` An array of objects.
+- `@returns (array[object])` The input array of objects but shuffled.
 
 ```tsx
 shuffle([1, 2, 3, 4, 5]) // [2, 5, 1, 3, 4] (or some other shuffled result)
@@ -229,68 +185,42 @@ A collection of utilities for manipulating chain units.
 
 ### planckToUnit
 
-Converts an on chain balance value in BigNumber planck to a decimal value in token unit. (1 token = 10^units planck).
-
-- `@param (BigNumber)` The Planck in BigNumber.
-- `@param (number)` the units.
-- `@returns (BigNumber)` the decimal value in token unit.
-
-#### Examples:
-
-```tsx
-const inputValue = new BigNumber("10000000");
-const units = 6;
-fn.planckToUnit(inputValue, units); // 10.000000
-
-const inputValue = new BigNumber("10000000");
-const units = 6;
-fn.planckToUnit(inputValue, units); // 10.000000
-```
-
-### transformToBaseUnit
-
-Transforms a given estimated fee value from its current representation to its base unit representation, considering the provided chain decimals. The function is designed to handle cases where the chain decimals are either greater or less than the length of the estimated fee.
+Converts an on-chain balance value from planck to a decimal value in token units.
 
-- `@param (string)` The estimated fee value that needs to be transformed to its base unit representation.
-- `@param (number)` The number of decimal places used by the blockchain.
-- `@returns (string)` the result of the functions.
+- `@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:
 
 ```tsx
-transformToBaseUnit("275002583", 9) // 0.275002583
-transformToBaseUnit("275002583", 20) // 0.0000000000275002583
-transformToBaseUnit("23", 9) // 0.00000023
-transformToBaseUnit("23", 18) // 0.00000000000000023
-transformToBaseUnit((20 * 10 ** 7).toString(), 18) // 0.000000002
-transformToBaseUnit((235 * 10 ** 7).toString(), 9) // 2.35
-transformToBaseUnit("0", 9) //  0
-transformToBaseUnit("0.0000", 20) // 0
-transformToBaseUnit("275002583", 9) // 0.275002583
-transformToBaseUnit("275002583", 20) // 0.0000000000275002583
-transformToBaseUnit("23", 9) // 0.00000023
-transformToBaseUnit("23", 18) // 0.00000000000000023
-transformToBaseUnit((20 * 10 ** 7).toString(), 18) // 0.000000002
-transformToBaseUnit((235 * 10 ** 7).toString(), 9) // 2.35
-transformToBaseUnit("0", 9) //  0
-transformToBaseUnit("0.0000", 20) // 0
+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 balance in token unit to an equivalent value in planck by applying the chain decimals ποιντ. (1 token = 10^units planck).
+Converts a token unit value to an integer value in planck.
 
-- `@param (string)` token balance.
-- `@param (number)` the units.
-- `@returns (BigNumber)` value in planck with applied the chain decimals.
+ - `@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
 
 ```tsx
-const inputValue = "10";
-const units = 6;
-fn.unitToPlanck(inputValue, units); // 10000000
-const inputValue = "10";
-const units = 6;
-fn.unitToPlanck(inputValue, units); // 10000000
+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
 ```