@stellar-expert/formatter 2.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 StellarExpert Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @stellar-expert/formatter
+
+## Installation
+
+```
+ "dependencies": {
+    "@stellar-expert/formatter": "github:stellar-expert/formatter#v2.0.0",
+    ...
+  }
+}
+```
+
+## Usage
+
+### Stroops representation
+
+`fromStroops(valueInStroops)` - Convert value in stroops (Int64 amount) to the normal string representation
+
+`toStroops(value)` - Convert arbitrary stringified amount to Int64 representation
+
+### Number formatting
+
+`formatWithPrecision(value, precision = 7, separator = ',')` - Format a number with specified precision and decimals separator
+
+`formatWithAutoPrecision(value, separator = ',')` - Format a number using automatically determined precision and decimals separator
+
+`formatWithAbbreviation(value, decimals = 2)` - Convert a number to a human-readable format using abbreviation
+
+`formatWithGrouping(value, group)` - Format a number with rounding to specific precision group
+
+`formatPrice(value, significantDigits = 4)` - Format a number as price with specified significant digits precision
+
+`adjustPrecision(amount)` - Format amount according to default Stellar precision
+
+`approximatePrice(price)` - Convert rational price representation to float-point number
+
+`isValidInt64Amount(value, denominate = true, nonZero = false)` - Check if a provided value can be safely used as token amount in Stellar
+operations
+
+### String truncation
+
+`shortenString(value, symbols = 8)` - Truncate strings longer than N symbols replacing characters in the middle with ellipsis
+
+`stripTrailingZeros(value)` - Remove trailing zero symbols from a formatted numeric string
+
+### Date formatting
+
+`normalizeDate(date, autoUnixFormatDetection = true)` - Convert any timestamp representation to a valid date format
+
+`toUnixTimestamp(date)` - Convert date to a numeric UNIX timestamp representation
+
+`formatDateUTC(date)` - Convert date to ISO-like human-readable format
+
+## Testing
+
+Run `jest` with `--experimental-vm-modules` NodeJS flag.

package/index.js

@@ -0,0 +1,10 @@
+export * from './src/numeric-format.js'
+export * from './src/timestamp-format.js'
+export * from './src/approximation.js'
+export * from './src/truncation.js'
+export * from './src/stroops.js'
+
+//changes
+//formatLongHex -> shortenString
+//adjustAmount -> adjustPrecision
+//formatCurrency deprecated

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@stellar-expert/formatter",
+  "version": "2.3.0",
+  "description": "Formatting utils and common formats for numeric, string, timestamp and binary data",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "sideEffects": false,
+  "scripts": {
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stellar-expert/formatter.git"
+  },
+  "author": "orbitlens <orbit@stellar.expert>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/stellar-expert/formatter/issues"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/src/approximation.js

@@ -0,0 +1,14 @@
+/**
+ * Convert rational price representation to Number
+ * @param {{n: Number, d: Number}|Number|String} price
+ * @return {Number}
+ */
+export function approximatePrice(price) {
+    if (!price)
+        return 0
+    if (price.n)
+        return price.n / price.d
+    if (typeof price === 'string')
+        return parseFloat(price)
+    return price
+}

package/src/numeric-format.js

@@ -0,0 +1,163 @@
+import {stripTrailingZeros} from './truncation.js'
+import {toStroops} from './stroops.js'
+
+function addDecimalsSeparators(value, separator = ',', trimTrailingZeros = true) {
+    //TODO: use Bignumber.toFormat() method instead
+    //split numeric to parts
+    let [int, reminder] = value.split('.')
+    let res = ''
+    //split digit groups
+    while (int.length > 3) {
+        res = separator + int.substring(int.length - 3) + res
+        int = int.substring(0, int.length - 3)
+    }
+    //strip negative sign
+    if (int === '-') {
+        res = res.substring(1)
+    }
+    res = int + res
+    if (reminder) {
+        res += '.' + reminder
+    }
+    if (trimTrailingZeros) {
+        res = stripTrailingZeros(res)
+    }
+    return res
+}
+
+/**
+ * Check if a provided value can be safely used as token amount in Stellar operations
+ * @param {String} value
+ * @param {Boolean} denominate
+ * @param {Boolean} nonZero
+ * @return {Boolean}
+ */
+export function isValidInt64Amount(value, denominate = true, nonZero = false) {
+    try {
+        const parsed = denominate ?
+            toStroops(value) :
+            BigInt(value)
+        if (nonZero) {
+            if (parsed <= 0n)
+                return false
+        } else {
+            if (parsed < 0n)
+                return false
+        }
+        return parsed <= 9223372036854775807n
+    } catch (e) {
+        return false
+    }
+}
+
+/**
+ * Format a number with specified precision and decimals separator
+ * @param {String|Number|BigInt} value - Numeric value to format
+ * @param {Number} [precision] - Desired precision (7 digits by default)
+ * @param {String} [separator] - Decimals separator
+ * @return {String}
+ */
+export function formatWithPrecision(value, precision = 7, separator = ',') {
+    return addDecimalsSeparators(setPrecision(value, precision), separator, true)
+}
+
+/**
+ * Format a number using automatically determined precision
+ * @param {String|Number} value - Numeric value to format
+ * @param {String} [separator] - Decimals separator
+ * @return {String}
+ */
+export function formatWithAutoPrecision(value, separator = ',') {
+    if (!value)
+        return '0'
+    const p = Math.ceil(Math.log10(parseFloat(value)))
+    let reminderPrecision = p > 1 ?
+        (3 - p) :
+        (Math.abs(p) + 2)
+    if (reminderPrecision < 0) {
+        reminderPrecision = 0
+    }
+    return formatWithPrecision(value, reminderPrecision, separator)
+}
+
+/**
+ * Convert a number to a human-readable format using abbreviation
+ * @param {Number} value - Value to format
+ * @param {Number} [decimals] - Precision of the abbreviated string to retain
+ * @return {String}
+ */
+export function formatWithAbbreviation(value, decimals = 2) {
+    let abs = Math.abs(value)
+    const tier = Math.log10(abs) / 3 | 0
+
+    if (tier <= 0)
+        return formatWithAutoPrecision(value)
+
+    const suffix = ['', 'K', 'M', 'G', 'T', 'P'][tier]
+    abs = stripTrailingZeros((abs / Math.pow(10, tier * 3)).toFixed(decimals))
+    return `${value < 0 ? '-' : ''}${abs || '0'}${suffix}`
+}
+
+/**
+ * Format a number with rounding to specific precision group
+ * @param {String|Number|BigInt} value - Value to format
+ * @param {Number} group - Logarithmic group rate for rounding
+ * @return {String}
+ */
+export function formatWithGrouping(value, group) {
+    if (!value)
+        return '0'
+    const precision = (group >= 1 || group === 0) ?
+        0 :
+        Math.abs(Math.log10(group))
+    if (group >= 1) {
+        value = Math.ceil(value / group) * group
+    }
+    return formatWithPrecision(value, precision)
+}
+
+/**
+ * Format a number as price with specified significant digits precision
+ * @param {String|Number|Bignumber} value - Value to format
+ * @param {Number} significantDigits - Significant digits for automatic formatting
+ * @return {String}
+ */
+export function formatPrice(value, significantDigits = 4) {
+    const primitive = (typeof value === 'number') ?
+        value.toFixed(7) :
+        value.toString()
+    const [int, fract] = primitive.split('.')
+    if (int.replace('-', '') !== '0') {
+        significantDigits -= int.length
+        if (significantDigits < 0) {
+            significantDigits = 0
+        }
+    } else {
+        if (!(fract > 0))
+            return '0'
+        significantDigits = Math.max(Math.ceil(Math.abs(Math.log10(parseFloat('.' + fract)))), significantDigits)
+    }
+    return formatWithPrecision(value, significantDigits, '')
+}
+
+/**
+ * Format amount according to default Stellar precision
+ * @param {Number|String} amount - Value to format
+ * @return {String}
+ */
+export function adjustPrecision(amount = '0') {
+    return stripTrailingZeros(setPrecision(amount, 7))
+}
+
+function setPrecision(amount, precision) {
+    if (typeof amount === 'number') {
+        amount = amount.toFixed(precision)
+    } else {
+        amount = amount.toString()
+        const sidx = amount.indexOf('.')
+        if (sidx >= 0) {
+            amount = amount.slice(0, sidx + precision + 1)
+        }
+    }
+    return amount
+}

package/src/stroops.js

@@ -0,0 +1,65 @@
+import {stripTrailingZeros} from './truncation.js'
+
+/**
+ * Convert value in stroops (Int64 amount) to the normal string representation
+ * @param {String|Number|BigInt} valueInStroops
+ * @return {String}
+ */
+export function fromStroops(valueInStroops) {
+    try {
+        let parsed = typeof valueInStroops === 'bigint' ?
+            valueInStroops :
+            BigInt(valueInStroops.toString().replace(/\.\d*/,''))
+        let negative = false
+        if (parsed < 0n) {
+            negative = true
+            parsed *= -1n
+        }
+        const int = parsed / 10000000n
+        const fract = parsed % 10000000n
+        let res = int.toString()
+        if (fract) {
+            res += '.' + fract.toString().padStart(7, '0')
+        }
+        if (negative) {
+            res = '-' + res
+        }
+        return stripTrailingZeros(res)
+    } catch (e) {
+        return '0'
+    }
+}
+
+
+/**
+ * Convert arbitrary stringified amount to int64 representation
+ * @param {String|Number} value
+ * @return {BigInt}
+ */
+export function toStroops(value) {
+    if (!value)
+        return 0n
+    if (typeof value === 'number') {
+        value = value.toFixed(7)
+    }
+    if (typeof value !== 'string' || !/^-?[\d.,]+$/.test(value))
+        return 0n //invalid format
+    try {
+        let [int, decimal = '0'] = value.split('.', 2)
+        let negative = false
+        if (int.startsWith('-')) {
+            negative = true
+            int = int.slice(1)
+        }
+        let res = BigInt(int) * 10000000n + BigInt(decimal.slice(0, 7).padEnd(7, '0'))
+        if (negative) {
+            res *= -1n
+            if (res < -0x8000000000000000n) //overflow
+                return 0n
+        } else if (res > 0xFFFFFFFFFFFFFFFFn) //overflow
+            return 0n
+        return res
+    } catch (e) {
+        return 0n
+    }
+}

package/src/timestamp-format.js

@@ -0,0 +1,52 @@
+/**
+ * Convert any timestamp representation to a valid date format
+ * @param {Date|String|Number} date - Date to parse
+ * @param {Boolean} [autoUnixFormatDetection] - Intelligent guess for dates already represented as UNIX timestamp (true by default)
+ * @return {Date} Parsed date
+ */
+export function normalizeDate(date, autoUnixFormatDetection = true) {
+    //try parse string representation
+    if (typeof date === 'string') {
+        if (!/^\d+$/.test(date)) {
+            if (!date.endsWith('Z')) {
+                date += 'Z'
+            }
+            date = new Date(date)
+        } else {
+            date = parseInt(date)
+        }
+    }
+    //parse numeric representation
+    if (typeof date === 'number') {
+        //input resembles a UNIX timestamp
+        if (date < 2147483648 && autoUnixFormatDetection) {
+            date *= 1000
+        }
+        date = new Date(date)
+    }
+    //check validity
+    if (!(date instanceof Date) || isNaN(date.valueOf()))
+        throw new Error('Invalid timestamp ' + date)
+    return date
+}
+
+/**
+ * Convert date to a numeric UNIX timestamp representation
+ * @param {Date|String|Number} date - Date to convert
+ * @return {Number} UNIX timestamp
+ */
+export function toUnixTimestamp(date) {
+    return Math.floor(normalizeDate(date).getTime() / 1000)
+}
+
+/**
+ * Convert date to ISO-like human-readable format
+ * @param {Date|String|Number} date - Date to convert
+ * @return {String}
+ */
+export function formatDateUTC(date) {
+    return normalizeDate(date)
+        .toISOString()
+        .replace(/(T|\.\d+Z)/g, ' ') // make it more human friendly
+        .trim()
+}

package/src/truncation.js

@@ -0,0 +1,29 @@
+/**
+ * Remove trailing zero symbols from a formatted numeric string
+ * @param {String} value
+ * @return {String}
+ */
+export function stripTrailingZeros(value) {
+    if (typeof value !== 'string')
+        return value
+    let [int, reminder] = value.split('.')
+    if (!reminder)
+        return int
+    reminder = reminder.replace(/0+$/, '')
+    if (!reminder.length)
+        return int
+    return int + '.' + reminder
+}
+
+/**
+ * Truncate strings longer than N symbols replacing characters in the middle with ellipsis
+ * @param {String} value - Original string
+ * @param {Number} [symbols] - Maximum string length
+ * @return {String}
+ */
+export function shortenString(value, symbols = 8) {
+    if (!value || value.length <= symbols)
+        return value
+    const affixLength = Math.max(2, Math.floor(symbols / 2))
+    return value.substring(0, affixLength) + '…' + value.substring(value.length - affixLength)
+}