@talismn/util 0.2.0 → 0.3.0

package/dist/declarations/src/addTrailingSlash.d.ts

@@ -0,0 +1 @@
+export declare const addTrailingSlash: (url: string) => string;

package/dist/declarations/src/convertAddress.d.ts

@@ -0,0 +1,7 @@
+/**
+ *
+ * @param address substrate SS58 address
+ * @param prefix prefix used to format the address
+ * @returns address encoded with supplied prefix
+ */
+export declare const convertAddress: (address: string, prefix: number | null) => string;

package/dist/declarations/src/decodeSs58Format.d.ts

@@ -0,0 +1 @@
+export declare const decodeSs58Format: (address?: string) => number | undefined;

package/dist/declarations/src/firstThenDebounce.d.ts

@@ -0,0 +1,8 @@
+import { OperatorFunction } from "rxjs";
+/**
+ * An rxjs operator which:
+ *
+ * 1. Emits the first value it receives from the source observable, then:
+ * 2. Debounces any future values by `timeout` ms.
+ */
+export declare const firstThenDebounce: <T>(timeout: number) => OperatorFunction<T, T>;

package/dist/declarations/src/formatPrice.d.ts

@@ -0,0 +1 @@
+export declare const formatPrice: (price: number, currency: string, compact: boolean) => string;

package/dist/declarations/src/index.d.ts

@@ -1,16 +1,28 @@
+export * from "./addTrailingSlash";
 export * from "./BigMath";
-export * from "./FunctionPropertyNames";
 export * from "./blake2Concat";
 export * from "./classNames";
+export * from "./convertAddress";
 export * from "./decodeAnyAddress";
+export * from "./decodeSs58Format";
 export * from "./deferred";
 export * from "./encodeAnyAddress";
+export * from "./firstThenDebounce";
 export * from "./formatDecimals";
+export * from "./formatPrice";
+export * from "./FunctionPropertyNames";
 export * from "./hasOwnProperty";
 export * from "./isArrayOf";
+export * from "./isBigInt";
+export * from "./isBooleanTrue";
 export * from "./isEthereumAddress";
+export * from "./isValidSubstrateAddress";
 export * from "./planckToTokens";
 export * from "./sleep";
 export * from "./throwAfter";
 export * from "./tokensToPlanck";
 export * from "./twox64Concat";
+export * from "./validateHexString";
+export * from "./normalizeAddress";
+export * from "./isAddressEqual";
+export * from "./isAscii";

package/dist/declarations/src/isAddressEqual.d.ts

@@ -0,0 +1 @@
+export declare const isAddressEqual: (address1: string, address2: string) => boolean;

package/dist/declarations/src/isAscii.d.ts

@@ -0,0 +1 @@
+export declare const isAscii: (str: string) => boolean;

package/dist/declarations/src/isBigInt.d.ts

@@ -0,0 +1 @@
+export declare const isBigInt: (value: unknown) => value is bigint;

package/dist/declarations/src/isBooleanTrue.d.ts

@@ -0,0 +1 @@
+export declare const isBooleanTrue: <T>(x: T | null | undefined) => x is T;

package/dist/declarations/src/isEthereumAddress.d.ts

@@ -1 +1 @@
-export declare const isEthereumAddress: (address: string) => boolean;
+export declare const isEthereumAddress: (address: string | undefined | null) => address is `0x${string}`;

package/dist/declarations/src/isValidSubstrateAddress.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Similar to isValidAddress but will not call isEthereumAddress under the hood
+ * @param address
+ * @param prefix if supplied, the method will also check the prefix
+ * @returns true if valid substrate (SS58) address, false otherwise
+ */
+export declare const isValidSubstrateAddress: (address: string, prefix?: number | null) => boolean;

package/dist/declarations/src/normalizeAddress.d.ts

@@ -0,0 +1 @@
+export declare const normalizeAddress: (address: string) => string;

package/dist/declarations/src/throwAfter.d.ts

@@ -1 +1 @@
-export declare const throwAfter: (ms: number, reason: string) => Promise<void>;
+export declare const throwAfter: (ms: number, reason: string) => Promise<never>;

package/dist/declarations/src/twox64Concat.d.ts

@@ -1,2 +1 @@
-/// <reference types="node" />
 export declare function twox64Concat(input: string | Buffer | Uint8Array): `0x${string}`;

package/dist/declarations/src/validateHexString.d.ts

@@ -0,0 +1,12 @@
+import { HexString } from "@polkadot/util/types";
+/**
+ * @name validateHexString
+ * @description Checks if a string is a hex string. Required to account for type differences between different polkadot libraries
+ * @param {string} str - string to check
+ * @returns {HexString} - boolean
+ * @example
+ * validateHexString("0x1234") // "0x1234"
+ * validateHexString("1234") // Error: Expected a hex string
+ * validateHexString(1234) // Error: Expected a string
+ **/
+export declare const validateHexString: (str: string) => HexString;

package/dist/talismn-util.cjs.dev.js

@@ -1,17 +1,23 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var util = require('@polkadot/util');
 var utilCrypto = require('@polkadot/util-crypto');
 var tailwindMerge = require('tailwind-merge');
 var keyring = require('@polkadot/keyring');
+var rxjs = require('rxjs');
 var BigNumber = require('bignumber.js');
 
-function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var BigNumber__default = /*#__PURE__*/_interopDefault(BigNumber);
 
+const addTrailingSlash = url => {
+  if (url.endsWith("/")) {
+    return url;
+  }
+  return `${url}/`;
+};
+
 /**
  * Javascript's `Math` library for `BigInt`.
  * Taken from https://stackoverflow.com/questions/51867270/is-there-a-library-similar-to-math-that-supports-javascript-bigint/64953280#64953280
@@ -46,6 +52,26 @@ function blake2Concat(input) {
 
 const classNames = tailwindMerge.twMerge;
 
+function encodeAnyAddress(key, ss58Format) {
+  try {
+    return keyring.encodeAddress(key, ss58Format);
+  } catch (error) {
+    if (typeof key !== "string") throw error;
+    if (!utilCrypto.isEthereumAddress(key)) throw error;
+    return utilCrypto.ethereumEncode(key);
+  }
+}
+
+/**
+ *
+ * @param address substrate SS58 address
+ * @param prefix prefix used to format the address
+ * @returns address encoded with supplied prefix
+ */
+const convertAddress = (address, prefix) => {
+  return encodeAnyAddress(address, prefix ?? undefined);
+};
+
 function decodeAnyAddress(encoded, ignoreChecksum, ss58Format) {
   try {
     return keyring.decodeAddress(encoded, ignoreChecksum, ss58Format);
@@ -56,6 +82,18 @@ function decodeAnyAddress(encoded, ignoreChecksum, ss58Format) {
   }
 }
 
+const decodeSs58Format = address => {
+  if (!address) return;
+  try {
+    utilCrypto.decodeAddress(address);
+    const decoded = utilCrypto.base58Decode(address);
+    const [,,, ss58Format] = utilCrypto.checkAddressChecksum(decoded);
+    return ss58Format;
+  } catch {
+    return; // invalid address
+  }
+};
+
 /**
  * In TypeScript, a deferred promise refers to a pattern that involves creating a promise that can be
  * resolved or rejected at a later point in time, typically by code outside of the current function scope.
@@ -91,15 +129,13 @@ function Deferred() {
   };
 }
 
-function encodeAnyAddress(key, ss58Format) {
-  try {
-    return keyring.encodeAddress(key, ss58Format);
-  } catch (error) {
-    if (typeof key !== "string") throw error;
-    if (!utilCrypto.isEthereumAddress(key)) throw error;
-    return utilCrypto.ethereumEncode(key);
-  }
-}
+/**
+ * An rxjs operator which:
+ *
+ * 1. Emits the first value it receives from the source observable, then:
+ * 2. Debounces any future values by `timeout` ms.
+ */
+const firstThenDebounce = timeout => source => rxjs.concat(source.pipe(rxjs.take(1)), source.pipe(rxjs.skip(1)).pipe(rxjs.debounceTime(timeout)));
 
 const MIN_DIGITS = 4; // less truncates more than what compact formating is
 const MAX_DECIMALS_FORMAT = 12;
@@ -116,7 +152,7 @@ const MAX_DECIMALS_FORMAT = 12;
 const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US") => {
   if (num === null || num === undefined) return "";
   if (digits < MIN_DIGITS) digits = MIN_DIGITS;
-  const value = new BigNumber__default["default"](num);
+  const value = new BigNumber__default.default(num);
   // very small numbers should display "< 0.0001"
   const minDisplayVal = 1 / Math.pow(10, digits);
   if (value.gt(0) && value.lt(minDisplayVal)) return `< ${formatDecimals(minDisplayVal)}`;
@@ -129,12 +165,12 @@ const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US"
   // to prevent JS default rounding, we will remove/truncate insignificant digits ourselves before formatting
   let truncatedValue = value;
   //remove insignificant fraction digits
-  const excessFractionDigitsPow10 = new BigNumber__default["default"](10).pow(digits > intDigits ? digits - intDigits : 0);
+  const excessFractionDigitsPow10 = new BigNumber__default.default(10).pow(digits > intDigits ? digits - intDigits : 0);
   truncatedValue = truncatedValue.multipliedBy(excessFractionDigitsPow10).integerValue().dividedBy(excessFractionDigitsPow10);
 
   //remove insignificant integer digits
-  const excessIntegerDigits = new BigNumber__default["default"](intDigits > digits ? intDigits - digits : 0);
-  const excessIntegerDigitsPow10 = new BigNumber__default["default"](10).pow(excessIntegerDigits);
+  const excessIntegerDigits = new BigNumber__default.default(intDigits > digits ? intDigits - digits : 0);
+  const excessIntegerDigitsPow10 = new BigNumber__default.default(10).pow(excessIntegerDigits);
   if (excessIntegerDigits.gt(0)) truncatedValue = truncatedValue.dividedBy(excessIntegerDigitsPow10).integerValue().multipliedBy(excessIntegerDigitsPow10);
 
   // format
@@ -147,6 +183,17 @@ const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US"
   }).format(truncatedValue.toNumber());
 };
 
+const formatPrice = (price, currency, compact) => {
+  return Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+    currencyDisplay: currency === "usd" ? "narrowSymbol" : "symbol",
+    maximumSignificantDigits: compact ? price < 1 ? 3 : 4 : undefined,
+    roundingPriority: compact ? "auto" : "morePrecision",
+    notation: compact && price >= 10_000 ? "compact" : "standard"
+  }).format(price);
+};
+
 function hasOwnProperty(obj, prop) {
   if (typeof obj !== "object") return false;
   if (obj === null) return false;
@@ -158,46 +205,129 @@ function isArrayOf(array, func) {
   return false;
 }
 
-const isEthereumAddress = address => address.startsWith("0x") && address.length === 42;
+const isBigInt = value => typeof value === "bigint";
+
+const isBooleanTrue = x => !!x;
+
+const isEthereumAddress = address => !!address && address.startsWith("0x") && address.length === 42;
+
+/**
+ * Similar to isValidAddress but will not call isEthereumAddress under the hood
+ * @param address
+ * @param prefix if supplied, the method will also check the prefix
+ * @returns true if valid substrate (SS58) address, false otherwise
+ */
+const isValidSubstrateAddress = (address, prefix) => {
+  try {
+    // attempt to encode, it will throw an error if address is invalid
+    const encoded = keyring.encodeAddress(address, prefix ?? undefined);
+
+    //if a prefix is supplied, check that reencoding using this prefix matches the input address
+    if (prefix !== undefined) return address === encoded;
+
+    //if no prefix supplied, the fact that decoding + encoding succeded indicates that the address is valid
+    return true;
+  } catch (error) {
+    // input is not a substrate (SS58) address
+    return false;
+  }
+};
 
 function planckToTokens(planck, tokenDecimals) {
   if (typeof planck !== "string" || typeof tokenDecimals !== "number") return;
   const base = 10;
   const exponent = -1 * tokenDecimals;
   const multiplier = base ** exponent;
-  return new BigNumber__default["default"](planck).multipliedBy(multiplier).toString(10);
+  return new BigNumber__default.default(planck).multipliedBy(multiplier).toString(10);
 }
 
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const sleep = ms => new Promise(resolve => {
+  if (process.env.NODE_ENV === "test") resolve();else setTimeout(resolve, ms);
+});
 
-const throwAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(reason), ms));
+const throwAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));
 
 function tokensToPlanck(tokens, tokenDecimals) {
   if (typeof tokens !== "string" || typeof tokenDecimals !== "number") return;
   const base = 10;
   const exponent = tokenDecimals;
   const multiplier = base ** exponent;
-  return new BigNumber__default["default"](tokens).multipliedBy(multiplier).toString(10);
+  return new BigNumber__default.default(tokens).multipliedBy(multiplier).toString(10);
 }
 
 const bitLength = 64;
 function twox64Concat(input) {
-  return util.u8aToHex(util.u8aConcat(utilCrypto.xxhashAsU8a(input, bitLength), util.u8aToU8a(input)));
+  const inputAsU8a = typeof input === "string" ? input : new Uint8Array(input);
+  return util.u8aToHex(util.u8aConcat(utilCrypto.xxhashAsU8a(inputAsU8a, bitLength), util.u8aToU8a(inputAsU8a)));
 }
 
+/**
+ * @name validateHexString
+ * @description Checks if a string is a hex string. Required to account for type differences between different polkadot libraries
+ * @param {string} str - string to check
+ * @returns {HexString} - boolean
+ * @example
+ * validateHexString("0x1234") // "0x1234"
+ * validateHexString("1234") // Error: Expected a hex string
+ * validateHexString(1234) // Error: Expected a string
+ **/
+const validateHexString = str => {
+  if (typeof str !== "string") {
+    throw new Error("Expected a string");
+  }
+  if (str.startsWith("0x")) {
+    return str;
+  }
+  throw new Error("Expected a hex string");
+};
+
+const CACHE = new Map();
+
+// Normalize an address in a way that it can be compared to other addresses that have also been normalized
+const normalizeAddress = address => {
+  try {
+    if (!CACHE.has(address)) CACHE.set(address, encodeAnyAddress(address));
+    return CACHE.get(address);
+  } catch (cause) {
+    throw new Error(`Unable to normalize address: ${address}`, {
+      cause
+    });
+  }
+};
+
+const isAddressEqual = (address1, address2) => {
+  return normalizeAddress(address1) === normalizeAddress(address2);
+};
+
+const isAscii = str => {
+  return [...str].every(char => char.charCodeAt(0) <= 127);
+};
+
 exports.BigMath = BigMath;
 exports.Deferred = Deferred;
 exports.MAX_DECIMALS_FORMAT = MAX_DECIMALS_FORMAT;
+exports.addTrailingSlash = addTrailingSlash;
 exports.blake2Concat = blake2Concat;
 exports.classNames = classNames;
+exports.convertAddress = convertAddress;
 exports.decodeAnyAddress = decodeAnyAddress;
+exports.decodeSs58Format = decodeSs58Format;
 exports.encodeAnyAddress = encodeAnyAddress;
+exports.firstThenDebounce = firstThenDebounce;
 exports.formatDecimals = formatDecimals;
+exports.formatPrice = formatPrice;
 exports.hasOwnProperty = hasOwnProperty;
+exports.isAddressEqual = isAddressEqual;
 exports.isArrayOf = isArrayOf;
+exports.isAscii = isAscii;
+exports.isBigInt = isBigInt;
+exports.isBooleanTrue = isBooleanTrue;
 exports.isEthereumAddress = isEthereumAddress;
+exports.isValidSubstrateAddress = isValidSubstrateAddress;
+exports.normalizeAddress = normalizeAddress;
 exports.planckToTokens = planckToTokens;
 exports.sleep = sleep;
 exports.throwAfter = throwAfter;
 exports.tokensToPlanck = tokensToPlanck;
 exports.twox64Concat = twox64Concat;
+exports.validateHexString = validateHexString;

package/dist/talismn-util.cjs.prod.js

@@ -1,17 +1,23 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var util = require('@polkadot/util');
 var utilCrypto = require('@polkadot/util-crypto');
 var tailwindMerge = require('tailwind-merge');
 var keyring = require('@polkadot/keyring');
+var rxjs = require('rxjs');
 var BigNumber = require('bignumber.js');
 
-function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var BigNumber__default = /*#__PURE__*/_interopDefault(BigNumber);
 
+const addTrailingSlash = url => {
+  if (url.endsWith("/")) {
+    return url;
+  }
+  return `${url}/`;
+};
+
 /**
  * Javascript's `Math` library for `BigInt`.
  * Taken from https://stackoverflow.com/questions/51867270/is-there-a-library-similar-to-math-that-supports-javascript-bigint/64953280#64953280
@@ -46,6 +52,26 @@ function blake2Concat(input) {
 
 const classNames = tailwindMerge.twMerge;
 
+function encodeAnyAddress(key, ss58Format) {
+  try {
+    return keyring.encodeAddress(key, ss58Format);
+  } catch (error) {
+    if (typeof key !== "string") throw error;
+    if (!utilCrypto.isEthereumAddress(key)) throw error;
+    return utilCrypto.ethereumEncode(key);
+  }
+}
+
+/**
+ *
+ * @param address substrate SS58 address
+ * @param prefix prefix used to format the address
+ * @returns address encoded with supplied prefix
+ */
+const convertAddress = (address, prefix) => {
+  return encodeAnyAddress(address, prefix ?? undefined);
+};
+
 function decodeAnyAddress(encoded, ignoreChecksum, ss58Format) {
   try {
     return keyring.decodeAddress(encoded, ignoreChecksum, ss58Format);
@@ -56,6 +82,18 @@ function decodeAnyAddress(encoded, ignoreChecksum, ss58Format) {
   }
 }
 
+const decodeSs58Format = address => {
+  if (!address) return;
+  try {
+    utilCrypto.decodeAddress(address);
+    const decoded = utilCrypto.base58Decode(address);
+    const [,,, ss58Format] = utilCrypto.checkAddressChecksum(decoded);
+    return ss58Format;
+  } catch {
+    return; // invalid address
+  }
+};
+
 /**
  * In TypeScript, a deferred promise refers to a pattern that involves creating a promise that can be
  * resolved or rejected at a later point in time, typically by code outside of the current function scope.
@@ -91,15 +129,13 @@ function Deferred() {
   };
 }
 
-function encodeAnyAddress(key, ss58Format) {
-  try {
-    return keyring.encodeAddress(key, ss58Format);
-  } catch (error) {
-    if (typeof key !== "string") throw error;
-    if (!utilCrypto.isEthereumAddress(key)) throw error;
-    return utilCrypto.ethereumEncode(key);
-  }
-}
+/**
+ * An rxjs operator which:
+ *
+ * 1. Emits the first value it receives from the source observable, then:
+ * 2. Debounces any future values by `timeout` ms.
+ */
+const firstThenDebounce = timeout => source => rxjs.concat(source.pipe(rxjs.take(1)), source.pipe(rxjs.skip(1)).pipe(rxjs.debounceTime(timeout)));
 
 const MIN_DIGITS = 4; // less truncates more than what compact formating is
 const MAX_DECIMALS_FORMAT = 12;
@@ -116,7 +152,7 @@ const MAX_DECIMALS_FORMAT = 12;
 const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US") => {
   if (num === null || num === undefined) return "";
   if (digits < MIN_DIGITS) digits = MIN_DIGITS;
-  const value = new BigNumber__default["default"](num);
+  const value = new BigNumber__default.default(num);
   // very small numbers should display "< 0.0001"
   const minDisplayVal = 1 / Math.pow(10, digits);
   if (value.gt(0) && value.lt(minDisplayVal)) return `< ${formatDecimals(minDisplayVal)}`;
@@ -129,12 +165,12 @@ const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US"
   // to prevent JS default rounding, we will remove/truncate insignificant digits ourselves before formatting
   let truncatedValue = value;
   //remove insignificant fraction digits
-  const excessFractionDigitsPow10 = new BigNumber__default["default"](10).pow(digits > intDigits ? digits - intDigits : 0);
+  const excessFractionDigitsPow10 = new BigNumber__default.default(10).pow(digits > intDigits ? digits - intDigits : 0);
   truncatedValue = truncatedValue.multipliedBy(excessFractionDigitsPow10).integerValue().dividedBy(excessFractionDigitsPow10);
 
   //remove insignificant integer digits
-  const excessIntegerDigits = new BigNumber__default["default"](intDigits > digits ? intDigits - digits : 0);
-  const excessIntegerDigitsPow10 = new BigNumber__default["default"](10).pow(excessIntegerDigits);
+  const excessIntegerDigits = new BigNumber__default.default(intDigits > digits ? intDigits - digits : 0);
+  const excessIntegerDigitsPow10 = new BigNumber__default.default(10).pow(excessIntegerDigits);
   if (excessIntegerDigits.gt(0)) truncatedValue = truncatedValue.dividedBy(excessIntegerDigitsPow10).integerValue().multipliedBy(excessIntegerDigitsPow10);
 
   // format
@@ -147,6 +183,17 @@ const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US"
   }).format(truncatedValue.toNumber());
 };
 
+const formatPrice = (price, currency, compact) => {
+  return Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+    currencyDisplay: currency === "usd" ? "narrowSymbol" : "symbol",
+    maximumSignificantDigits: compact ? price < 1 ? 3 : 4 : undefined,
+    roundingPriority: compact ? "auto" : "morePrecision",
+    notation: compact && price >= 10_000 ? "compact" : "standard"
+  }).format(price);
+};
+
 function hasOwnProperty(obj, prop) {
   if (typeof obj !== "object") return false;
   if (obj === null) return false;
@@ -158,46 +205,129 @@ function isArrayOf(array, func) {
   return false;
 }
 
-const isEthereumAddress = address => address.startsWith("0x") && address.length === 42;
+const isBigInt = value => typeof value === "bigint";
+
+const isBooleanTrue = x => !!x;
+
+const isEthereumAddress = address => !!address && address.startsWith("0x") && address.length === 42;
+
+/**
+ * Similar to isValidAddress but will not call isEthereumAddress under the hood
+ * @param address
+ * @param prefix if supplied, the method will also check the prefix
+ * @returns true if valid substrate (SS58) address, false otherwise
+ */
+const isValidSubstrateAddress = (address, prefix) => {
+  try {
+    // attempt to encode, it will throw an error if address is invalid
+    const encoded = keyring.encodeAddress(address, prefix ?? undefined);
+
+    //if a prefix is supplied, check that reencoding using this prefix matches the input address
+    if (prefix !== undefined) return address === encoded;
+
+    //if no prefix supplied, the fact that decoding + encoding succeded indicates that the address is valid
+    return true;
+  } catch (error) {
+    // input is not a substrate (SS58) address
+    return false;
+  }
+};
 
 function planckToTokens(planck, tokenDecimals) {
   if (typeof planck !== "string" || typeof tokenDecimals !== "number") return;
   const base = 10;
   const exponent = -1 * tokenDecimals;
   const multiplier = base ** exponent;
-  return new BigNumber__default["default"](planck).multipliedBy(multiplier).toString(10);
+  return new BigNumber__default.default(planck).multipliedBy(multiplier).toString(10);
 }
 
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const sleep = ms => new Promise(resolve => {
+  setTimeout(resolve, ms);
+});
 
-const throwAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(reason), ms));
+const throwAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));
 
 function tokensToPlanck(tokens, tokenDecimals) {
   if (typeof tokens !== "string" || typeof tokenDecimals !== "number") return;
   const base = 10;
   const exponent = tokenDecimals;
   const multiplier = base ** exponent;
-  return new BigNumber__default["default"](tokens).multipliedBy(multiplier).toString(10);
+  return new BigNumber__default.default(tokens).multipliedBy(multiplier).toString(10);
 }
 
 const bitLength = 64;
 function twox64Concat(input) {
-  return util.u8aToHex(util.u8aConcat(utilCrypto.xxhashAsU8a(input, bitLength), util.u8aToU8a(input)));
+  const inputAsU8a = typeof input === "string" ? input : new Uint8Array(input);
+  return util.u8aToHex(util.u8aConcat(utilCrypto.xxhashAsU8a(inputAsU8a, bitLength), util.u8aToU8a(inputAsU8a)));
 }
 
+/**
+ * @name validateHexString
+ * @description Checks if a string is a hex string. Required to account for type differences between different polkadot libraries
+ * @param {string} str - string to check
+ * @returns {HexString} - boolean
+ * @example
+ * validateHexString("0x1234") // "0x1234"
+ * validateHexString("1234") // Error: Expected a hex string
+ * validateHexString(1234) // Error: Expected a string
+ **/
+const validateHexString = str => {
+  if (typeof str !== "string") {
+    throw new Error("Expected a string");
+  }
+  if (str.startsWith("0x")) {
+    return str;
+  }
+  throw new Error("Expected a hex string");
+};
+
+const CACHE = new Map();
+
+// Normalize an address in a way that it can be compared to other addresses that have also been normalized
+const normalizeAddress = address => {
+  try {
+    if (!CACHE.has(address)) CACHE.set(address, encodeAnyAddress(address));
+    return CACHE.get(address);
+  } catch (cause) {
+    throw new Error(`Unable to normalize address: ${address}`, {
+      cause
+    });
+  }
+};
+
+const isAddressEqual = (address1, address2) => {
+  return normalizeAddress(address1) === normalizeAddress(address2);
+};
+
+const isAscii = str => {
+  return [...str].every(char => char.charCodeAt(0) <= 127);
+};
+
 exports.BigMath = BigMath;
 exports.Deferred = Deferred;
 exports.MAX_DECIMALS_FORMAT = MAX_DECIMALS_FORMAT;
+exports.addTrailingSlash = addTrailingSlash;
 exports.blake2Concat = blake2Concat;
 exports.classNames = classNames;
+exports.convertAddress = convertAddress;
 exports.decodeAnyAddress = decodeAnyAddress;
+exports.decodeSs58Format = decodeSs58Format;
 exports.encodeAnyAddress = encodeAnyAddress;
+exports.firstThenDebounce = firstThenDebounce;
 exports.formatDecimals = formatDecimals;
+exports.formatPrice = formatPrice;
 exports.hasOwnProperty = hasOwnProperty;
+exports.isAddressEqual = isAddressEqual;
 exports.isArrayOf = isArrayOf;
+exports.isAscii = isAscii;
+exports.isBigInt = isBigInt;
+exports.isBooleanTrue = isBooleanTrue;
 exports.isEthereumAddress = isEthereumAddress;
+exports.isValidSubstrateAddress = isValidSubstrateAddress;
+exports.normalizeAddress = normalizeAddress;
 exports.planckToTokens = planckToTokens;
 exports.sleep = sleep;
 exports.throwAfter = throwAfter;
 exports.tokensToPlanck = tokensToPlanck;
 exports.twox64Concat = twox64Concat;
+exports.validateHexString = validateHexString;

package/dist/talismn-util.esm.js

@@ -1,9 +1,17 @@
 import { u8aToHex, u8aConcat, u8aToU8a, hexToU8a } from '@polkadot/util';
-import { blake2AsU8a, isEthereumAddress as isEthereumAddress$1, ethereumEncode, xxhashAsU8a } from '@polkadot/util-crypto';
+import { blake2AsU8a, isEthereumAddress as isEthereumAddress$1, ethereumEncode, decodeAddress as decodeAddress$1, base58Decode, checkAddressChecksum, xxhashAsU8a } from '@polkadot/util-crypto';
 import { twMerge } from 'tailwind-merge';
-import { decodeAddress, encodeAddress } from '@polkadot/keyring';
+import { encodeAddress, decodeAddress } from '@polkadot/keyring';
+import { concat, take, skip, debounceTime } from 'rxjs';
 import BigNumber from 'bignumber.js';
 
+const addTrailingSlash = url => {
+  if (url.endsWith("/")) {
+    return url;
+  }
+  return `${url}/`;
+};
+
 /**
  * Javascript's `Math` library for `BigInt`.
  * Taken from https://stackoverflow.com/questions/51867270/is-there-a-library-similar-to-math-that-supports-javascript-bigint/64953280#64953280
@@ -38,6 +46,26 @@ function blake2Concat(input) {
 
 const classNames = twMerge;
 
+function encodeAnyAddress(key, ss58Format) {
+  try {
+    return encodeAddress(key, ss58Format);
+  } catch (error) {
+    if (typeof key !== "string") throw error;
+    if (!isEthereumAddress$1(key)) throw error;
+    return ethereumEncode(key);
+  }
+}
+
+/**
+ *
+ * @param address substrate SS58 address
+ * @param prefix prefix used to format the address
+ * @returns address encoded with supplied prefix
+ */
+const convertAddress = (address, prefix) => {
+  return encodeAnyAddress(address, prefix ?? undefined);
+};
+
 function decodeAnyAddress(encoded, ignoreChecksum, ss58Format) {
   try {
     return decodeAddress(encoded, ignoreChecksum, ss58Format);
@@ -48,6 +76,18 @@ function decodeAnyAddress(encoded, ignoreChecksum, ss58Format) {
   }
 }
 
+const decodeSs58Format = address => {
+  if (!address) return;
+  try {
+    decodeAddress$1(address);
+    const decoded = base58Decode(address);
+    const [,,, ss58Format] = checkAddressChecksum(decoded);
+    return ss58Format;
+  } catch {
+    return; // invalid address
+  }
+};
+
 /**
  * In TypeScript, a deferred promise refers to a pattern that involves creating a promise that can be
  * resolved or rejected at a later point in time, typically by code outside of the current function scope.
@@ -83,15 +123,13 @@ function Deferred() {
   };
 }
 
-function encodeAnyAddress(key, ss58Format) {
-  try {
-    return encodeAddress(key, ss58Format);
-  } catch (error) {
-    if (typeof key !== "string") throw error;
-    if (!isEthereumAddress$1(key)) throw error;
-    return ethereumEncode(key);
-  }
-}
+/**
+ * An rxjs operator which:
+ *
+ * 1. Emits the first value it receives from the source observable, then:
+ * 2. Debounces any future values by `timeout` ms.
+ */
+const firstThenDebounce = timeout => source => concat(source.pipe(take(1)), source.pipe(skip(1)).pipe(debounceTime(timeout)));
 
 const MIN_DIGITS = 4; // less truncates more than what compact formating is
 const MAX_DECIMALS_FORMAT = 12;
@@ -139,6 +177,17 @@ const formatDecimals = (num, digits = MIN_DIGITS, options = {}, locale = "en-US"
   }).format(truncatedValue.toNumber());
 };
 
+const formatPrice = (price, currency, compact) => {
+  return Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+    currencyDisplay: currency === "usd" ? "narrowSymbol" : "symbol",
+    maximumSignificantDigits: compact ? price < 1 ? 3 : 4 : undefined,
+    roundingPriority: compact ? "auto" : "morePrecision",
+    notation: compact && price >= 10_000 ? "compact" : "standard"
+  }).format(price);
+};
+
 function hasOwnProperty(obj, prop) {
   if (typeof obj !== "object") return false;
   if (obj === null) return false;
@@ -150,7 +199,33 @@ function isArrayOf(array, func) {
   return false;
 }
 
-const isEthereumAddress = address => address.startsWith("0x") && address.length === 42;
+const isBigInt = value => typeof value === "bigint";
+
+const isBooleanTrue = x => !!x;
+
+const isEthereumAddress = address => !!address && address.startsWith("0x") && address.length === 42;
+
+/**
+ * Similar to isValidAddress but will not call isEthereumAddress under the hood
+ * @param address
+ * @param prefix if supplied, the method will also check the prefix
+ * @returns true if valid substrate (SS58) address, false otherwise
+ */
+const isValidSubstrateAddress = (address, prefix) => {
+  try {
+    // attempt to encode, it will throw an error if address is invalid
+    const encoded = encodeAddress(address, prefix ?? undefined);
+
+    //if a prefix is supplied, check that reencoding using this prefix matches the input address
+    if (prefix !== undefined) return address === encoded;
+
+    //if no prefix supplied, the fact that decoding + encoding succeded indicates that the address is valid
+    return true;
+  } catch (error) {
+    // input is not a substrate (SS58) address
+    return false;
+  }
+};
 
 function planckToTokens(planck, tokenDecimals) {
   if (typeof planck !== "string" || typeof tokenDecimals !== "number") return;
@@ -160,9 +235,11 @@ function planckToTokens(planck, tokenDecimals) {
   return new BigNumber(planck).multipliedBy(multiplier).toString(10);
 }
 
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const sleep = ms => new Promise(resolve => {
+  if (process.env.NODE_ENV === "test") resolve();else setTimeout(resolve, ms);
+});
 
-const throwAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(reason), ms));
+const throwAfter = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));
 
 function tokensToPlanck(tokens, tokenDecimals) {
   if (typeof tokens !== "string" || typeof tokenDecimals !== "number") return;
@@ -174,7 +251,50 @@ function tokensToPlanck(tokens, tokenDecimals) {
 
 const bitLength = 64;
 function twox64Concat(input) {
-  return u8aToHex(u8aConcat(xxhashAsU8a(input, bitLength), u8aToU8a(input)));
+  const inputAsU8a = typeof input === "string" ? input : new Uint8Array(input);
+  return u8aToHex(u8aConcat(xxhashAsU8a(inputAsU8a, bitLength), u8aToU8a(inputAsU8a)));
 }
 
-export { BigMath, Deferred, MAX_DECIMALS_FORMAT, blake2Concat, classNames, decodeAnyAddress, encodeAnyAddress, formatDecimals, hasOwnProperty, isArrayOf, isEthereumAddress, planckToTokens, sleep, throwAfter, tokensToPlanck, twox64Concat };
+/**
+ * @name validateHexString
+ * @description Checks if a string is a hex string. Required to account for type differences between different polkadot libraries
+ * @param {string} str - string to check
+ * @returns {HexString} - boolean
+ * @example
+ * validateHexString("0x1234") // "0x1234"
+ * validateHexString("1234") // Error: Expected a hex string
+ * validateHexString(1234) // Error: Expected a string
+ **/
+const validateHexString = str => {
+  if (typeof str !== "string") {
+    throw new Error("Expected a string");
+  }
+  if (str.startsWith("0x")) {
+    return str;
+  }
+  throw new Error("Expected a hex string");
+};
+
+const CACHE = new Map();
+
+// Normalize an address in a way that it can be compared to other addresses that have also been normalized
+const normalizeAddress = address => {
+  try {
+    if (!CACHE.has(address)) CACHE.set(address, encodeAnyAddress(address));
+    return CACHE.get(address);
+  } catch (cause) {
+    throw new Error(`Unable to normalize address: ${address}`, {
+      cause
+    });
+  }
+};
+
+const isAddressEqual = (address1, address2) => {
+  return normalizeAddress(address1) === normalizeAddress(address2);
+};
+
+const isAscii = str => {
+  return [...str].every(char => char.charCodeAt(0) <= 127);
+};
+
+export { BigMath, Deferred, MAX_DECIMALS_FORMAT, addTrailingSlash, blake2Concat, classNames, convertAddress, decodeAnyAddress, decodeSs58Format, encodeAnyAddress, firstThenDebounce, formatDecimals, formatPrice, hasOwnProperty, isAddressEqual, isArrayOf, isAscii, isBigInt, isBooleanTrue, isEthereumAddress, isValidSubstrateAddress, normalizeAddress, planckToTokens, sleep, throwAfter, tokensToPlanck, twox64Concat, validateHexString };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talismn/util",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Talisman",
   "homepage": "https://talisman.xyz",
   "license": "GPL-3.0-or-later",
@@ -20,36 +20,38 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "test": "jest",
-    "lint": "eslint src --max-warnings 0",
-    "clean": "rm -rf dist && rm -rf .turbo rm -rf node_modules"
-  },
   "dependencies": {
-    "bignumber.js": "^9.1.1",
-    "tailwind-merge": "^1.13.2"
+    "bignumber.js": "^9.1.2",
+    "rxjs": "^7.8.1",
+    "tailwind-merge": "^2.5.4"
   },
   "devDependencies": {
-    "@polkadot/keyring": "^12.2.1",
-    "@polkadot/util": "^12.2.1",
-    "@polkadot/util-crypto": "^12.2.1",
-    "@talismn/eslint-config": "0.0.2",
-    "@talismn/tsconfig": "0.0.2",
-    "@types/jest": "^27.5.1",
-    "eslint": "^8.4.0",
-    "jest": "^28.1.0",
-    "ts-jest": "^28.0.2",
-    "typescript": "^4.6.4"
+    "@polkadot/keyring": "13.4.3",
+    "@polkadot/util": "13.4.3",
+    "@polkadot/util-crypto": "13.4.3",
+    "@types/jest": "^29.5.14",
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.3",
+    "@talismn/eslint-config": "0.0.3",
+    "@talismn/tsconfig": "0.0.2"
   },
   "peerDependencies": {
-    "@polkadot/keyring": "12.x",
-    "@polkadot/util": "12.x",
-    "@polkadot/util-crypto": "12.x"
+    "@polkadot/keyring": "*",
+    "@polkadot/util": "*",
+    "@polkadot/util-crypto": "*",
+    "rxjs": ">= 7.8.1"
   },
   "eslintConfig": {
     "root": true,
     "extends": [
       "@talismn/eslint-config/base"
     ]
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src --max-warnings 0",
+    "clean": "rm -rf dist .turbo node_modules"
   }
 }

package/CHANGELOG.md

@@ -1,76 +0,0 @@
-# @talismn/util
-
-## 0.2.0
-
-### Minor Changes
-
-- b920ab98: Added GPL licence
-- 7573864f: chore: remove dead code
-
-### Patch Changes
-
-- 2d0ae30b: fix: non-conflict tw class merging for classNames via twMerge
-
-## 0.1.9
-
-### Patch Changes
-
-- f7aca48b: eslint rules
-- 01bf239b: feat: crowdloan and nom pool balances
-- 48f0222e: fix: removed some explicit `any`s
-- 01bf239b: fix: packages publishing with incorrect interdependency versions
-
-## 0.1.8
-
-### Patch Changes
-
-- 3068bd60: feat: stale balances and exponential rpc backoff
-
-## 0.1.7
-
-### Patch Changes
-
-- c651551c: build: move `@polkadot` dependencies to `peerDependencies`
-
-## 0.1.6
-
-### Patch Changes
-
-- 8adc7f06: feat: switched build tool to preconstruct
-
-## 0.1.5
-
-### Patch Changes
-
-- 4aa691d: feat: new balance modules
-- a63dbb3: feat: formatDecimal allow for BigNumber amount
-
-## 0.1.4
-
-### Patch Changes
-
-- fix: a variety of improvements from the wallet integration
-
-## 0.1.3
-
-### Patch Changes
-
-- 5af305c: switched build output from esm to commonjs for ecosystem compatibility
-
-## 0.1.2
-
-### Patch Changes
-
-- 2ccd51b: feat: implemented @talismn/balances-substrate-native
-
-## 0.1.1
-
-### Patch Changes
-
-- Fixed publish config
-
-## 0.1.0
-
-### Minor Changes
-
-- 43c1a3a: Initial release