@provex/utils 1.0.16 → 1.2.4

package/dist/units.js

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Unit conversion and formatting utilities for token amounts.
+ *
+ * This module provides utilities for converting between human-readable amounts
+ * and blockchain-native bigint values, with support for:
+ * - Decimal precision (6 for USDC, 18 for ETH)
+ * - Thousands separators for display
+ * - Truncation and padding options
+ * - Number abbreviation (k, M, B, T)
+ *
+ * @remarks
+ * All amounts in smart contracts are stored as bigints without decimals.
+ * For example, 100 USDC = 100_000000n (6 decimals).
+ *
+ * @see {@link tokens} for token decimal configurations
+ * @see {@link currencies} for fiat currency decimals
+ */
+import { formatUnits as viemFormatUnits, parseUnits as viemParseUnits } from 'viem';
+/**
+ * Constant representing 1 ether in wei (10^18).
+ * Used for 18-decimal precision calculations.
+ */
+export const oneEther = 10n ** 18n;
+/**
+ * Add thousands separators to a number string for improved readability.
+ *
+ * @param numberString - The number string to format
+ * @param delimiter - The separator character (default: ',')
+ * @returns Formatted string with separators
+ *
+ * @example
+ * ```ts
+ * addThousandsSeparator('1234567.89')    // '1,234,567.89'
+ * addThousandsSeparator('1000', ' ')     // '1 000'
+ * ```
+ */
+export function addThousandsSeparator(numberString, delimiter = ',') {
+    let [integerPart, fractionalPart] = numberString.split('.');
+    integerPart = integerPart || '0';
+    fractionalPart = fractionalPart || '';
+    // Add thousands separators to integer part
+    const formattedInteger = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, delimiter);
+    // Return with fractional part if it exists
+    return fractionalPart ? `${formattedInteger}.${fractionalPart}` : formattedInteger;
+}
+/**
+ * Parse a human-readable amount string into a bigint.
+ * Handles thousands separators and decimal places.
+ *
+ * @param amount - Human-readable amount (e.g., '1,234.56')
+ * @param options - Parsing options with decimals and optional delimiter
+ * @returns BigInt representation of the amount
+ *
+ * @example
+ * ```ts
+ * // Parse USDC amount (6 decimals)
+ * parseUnits('100.50', { decimals: 6 })  // 100_500000n
+ *
+ * // Parse with thousands separator
+ * parseUnits('1,234.56', { decimals: 6 })  // 1_234_560000n
+ * ```
+ */
+export const parseUnits = (amount, options) => {
+    return viemParseUnits(amount.split(options.delimiter ?? ',').join(''), options.decimals);
+};
+/**
+ * Format a bigint amount as a human-readable string with configurable precision.
+ *
+ * @param amount - BigInt amount to format
+ * @param options - Formatting options
+ * @returns Formatted string with decimal point and thousands separators
+ *
+ * @example
+ * ```ts
+ * // Basic formatting
+ * formatUnits(100_500000n, { decimals: 6, padDecimals: 2 })  // '100.50'
+ *
+ * // With truncation
+ * formatUnits(100_123456n, { decimals: 6, truncateDecimals: 2 })  // '100.12'
+ *
+ * // With cutoff for small amounts
+ * formatUnits(100n, { decimals: 6, cutoff: 1000n })  // '<0.001'
+ * ```
+ */
+export function formatUnits(amount, options) {
+    const { decimals, truncateDecimals, padDecimals = 0, delimiter = ',', cutoff, roundUp = false } = options;
+    if (cutoff && amount < cutoff) {
+        return `<${formatUnits(cutoff, { ...options, truncateDecimals: 0, cutoff: undefined })}`;
+    }
+    if (roundUp && truncateDecimals !== undefined) {
+        // const minimumDecimal = decimals - truncateDecimals
+        const minimumDecimal = BigInt(decimals - truncateDecimals);
+        const minimalMod = amount % (10n ** minimumDecimal);
+        const halfMinimalDecimal = (10n ** minimumDecimal) / 2n;
+        if (minimalMod >= halfMinimalDecimal) {
+            amount = amount + (10n ** minimumDecimal) - minimalMod;
+        }
+    }
+    const formatted = viemFormatUnits(amount, decimals);
+    const [integerPart, fractionalPart = ''] = formatted.split('.');
+    // If truncateDecimals is specified, limit decimal places
+    let finalFractionalPart = fractionalPart;
+    if (truncateDecimals !== undefined) {
+        finalFractionalPart = fractionalPart.slice(0, truncateDecimals);
+    }
+    // Always pad to at least 2 decimal places (or padDecimals)
+    if (finalFractionalPart.length < padDecimals) {
+        finalFractionalPart = finalFractionalPart.padEnd(padDecimals, '0');
+    }
+    // If there are no decimals, still show .00
+    const numberString = `${integerPart}.${finalFractionalPart}`;
+    return addThousandsSeparator(numberString, delimiter);
+}
+/**
+ * Format a token amount for display with 2 decimal places.
+ * Convenience wrapper around formatUnits with truncateDecimals: 2.
+ *
+ * @param amount - BigInt amount to format
+ * @param options - Formatting options (truncateDecimals defaults to 2)
+ * @returns Formatted string with 2 decimal places
+ */
+export function formatTokenAmountForDisplay(amount, options) {
+    return formatUnits(amount, { truncateDecimals: 2, ...options });
+}
+/**
+ * Safely parse a string to an integer without using Number() constructor.
+ * Uses parseInt which is more predictable for integer-only parsing.
+ *
+ * @param value - String value to parse
+ * @returns Parsed integer or null if invalid
+ *
+ * @example
+ * ```ts
+ * parseIntegerSafe('123')     // 123
+ * parseIntegerSafe('123.45')  // 123 (truncates decimal)
+ * parseIntegerSafe('abc')     // null
+ * ```
+ */
+export function parseIntegerSafe(value) {
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? null : parsed;
+}
+// // Get display title for limits (shows original user limits on hover)
+// export function getLimitsDisplayTitle(deposit: { formattedMinAmount: string; formattedMaxAmount: string }): string {
+//   return `User set: ${deposit.formattedMinAmount} - ${deposit.formattedMaxAmount}`
+// }
+/**
+ * Convert a blockchain timestamp (Unix seconds) to a JavaScript Date object.
+ *
+ * @param timestamp - Unix timestamp in seconds (string, number, or bigint)
+ * @returns Date object, or null if timestamp is falsy
+ *
+ * @example
+ * ```ts
+ * timestampToDate(1704067200)      // Date: 2024-01-01T00:00:00.000Z
+ * timestampToDate('1704067200')    // Date: 2024-01-01T00:00:00.000Z
+ * timestampToDate(1704067200n)     // Date: 2024-01-01T00:00:00.000Z
+ * timestampToDate(null)            // null
+ * ```
+ */
+export function timestampToDate(timestamp) {
+    if (!timestamp)
+        return null;
+    // Convert seconds to milliseconds for Date constructor
+    const timestampMs = Number(timestamp) * 1000;
+    return new Date(timestampMs);
+}
+// export function formatTokenAmountForDisplay(amount: bigint, tokenInfo: TokenInfo): string {
+//   return formatUnits(amount, { decimals: tokenInfo.decimals })
+// }
+/**
+ * Format a token amount using the token's decimal configuration.
+ *
+ * @param token - Token info with decimals
+ * @param amount - BigInt amount to format, or null
+ * @param options - Optional formatting overrides
+ * @returns Formatted string, or null if amount is null
+ *
+ * @example
+ * ```ts
+ * const usdc = { decimals: 6, ... }
+ * formatAmount(usdc, 100_500000n)  // '100.50'
+ * formatAmount(usdc, null)         // null
+ * ```
+ */
+export const formatAmount = (token, amount, options = {}) => {
+    if (!amount)
+        return null;
+    const baseDecimals = Math.min(token.decimals - 4, 8);
+    // Show 4 decimal places for single-digit amounts so small differences are visible
+    const integerDigits = amount / (10n ** BigInt(token.decimals));
+    const truncateDecimals = integerDigits < 10n ? Math.min(baseDecimals + 2, token.decimals) : baseDecimals;
+    return formatUnits(amount, {
+        decimals: token.decimals,
+        truncateDecimals,
+        padDecimals: 2,
+        ...options,
+    });
+};
+/**
+ * Numeric abbreviation suffixes and their divisors.
+ * Used by abbreviateNumber() for compact number display.
+ */
+export const numericAbbreviations = [
+    { divisor: 1000000000000n, suffix: 'T' }, // Trillion
+    { divisor: 1000000000n, suffix: 'B' }, // Billion
+    { divisor: 1000000n, suffix: 'M' }, // Million
+    { divisor: 1000n, suffix: 'k' }, // Thousand
+];
+/**
+ * Formats a bigint value with a specific numeric abbreviation suffix
+ * @param value - The bigint value to format
+ * @param options - Configuration for formatting
+ * @returns Formatted string with suffix (e.g., "1.23k", "400M")
+ *
+ * @example
+ * formatWithAbbreviation(1234567n, { decimals: 2, divisor: 1_000n, suffix: 'k' }) // "1234.57k"
+ * formatWithAbbreviation(400000000n, { decimals: 2, divisor: 1_000_000n, suffix: 'M' }) // "400M"
+ */
+export function formatWithAbbreviation(value, options) {
+    const { decimals, divisor, suffix, maxDecimals = 2 } = options;
+    const isNegative = value < 0n;
+    const sign = isNegative ? '-' : '';
+    const absValue = isNegative ? -value : value;
+    // Convert to decimal first to preserve fractional parts, then divide
+    const valueAsDecimal = viemFormatUnits(absValue, decimals);
+    const divisorAsDecimal = Number(divisor);
+    const abbreviatedValue = parseFloat(valueAsDecimal) / divisorAsDecimal;
+    // Reduce decimal places for large abbreviated values unless caller set minDecimals
+    const minDec = options.minDecimals ?? 0;
+    let decimalPlaces = maxDecimals;
+    if (abbreviatedValue >= 100) {
+        decimalPlaces = Math.max(minDec, 0);
+    }
+    else if (abbreviatedValue >= 10) {
+        decimalPlaces = Math.max(minDec, Math.min(1, maxDecimals));
+    }
+    // Format with appropriate decimal places, removing trailing zeros after decimal point
+    let formatted = abbreviatedValue.toFixed(decimalPlaces);
+    // Only remove trailing zeros if there's a decimal point
+    if (formatted.includes('.')) {
+        formatted = formatted.replace(/\.?0+$/, '');
+    }
+    return `${sign}${formatted}${suffix}`;
+}
+/**
+ * Abbreviates large numbers using k, M, B, T suffixes
+ * @param value - The bigint value to abbreviate
+ * @param options - Optional configuration for decimal places and decimals precision
+ * @returns Abbreviated number string (e.g., "1.5k", "200k", "1.2M")
+ *
+ * @example
+ * abbreviateNumber(1500n, { decimals: 0 }) // "1.5k"
+ * abbreviateNumber(200000n, { decimals: 0 }) // "200k"
+ * abbreviateNumber(1234567n, { decimals: 0 }) // "1.23M"
+ * abbreviateNumber(1000000000n, { decimals: 0 }) // "1B"
+ * abbreviateNumber(123456n, { decimals: 2 }) // "1.23k" (if input is 1234.56 with 2 decimals)
+ */
+export function abbreviateNumber(value, options) {
+    const { decimals, maxDecimals = 2, minDecimals } = options;
+    const isNegative = value < 0n;
+    const absValue = isNegative ? -value : value;
+    const scale = 10n ** BigInt(decimals);
+    for (const { divisor, suffix } of numericAbbreviations) {
+        const threshold = divisor * scale;
+        if (absValue >= threshold) {
+            return formatWithAbbreviation(value, { decimals, divisor, suffix, maxDecimals, minDecimals });
+        }
+    }
+    // For values less than 1000, format normally without padding
+    // Only pad decimals if the value actually has fractional parts
+    const formattedValue = viemFormatUnits(absValue, decimals);
+    const [integerPart, fractionalPart = ''] = formattedValue.split('.');
+    // Remove trailing zeros from fractional part
+    const trimmedFractional = fractionalPart.replace(/0+$/, '');
+    // If no fractional part remains, return just the integer
+    const result = trimmedFractional ? `${integerPart}.${trimmedFractional}` : integerPart;
+    return isNegative ? `-${result}` : result;
+}

package/dist/units.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/units.test.js

@@ -0,0 +1,327 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { oneEther, addThousandsSeparator, parseUnits, formatUnits, formatTokenAmountForDisplay, parseIntegerSafe, timestampToDate, formatAmount, abbreviateNumber, formatWithAbbreviation, numericAbbreviations, } from './units.js';
+describe('abbreviateNumber', () => {
+    describe('with decimals: 0 (whole numbers)', () => {
+        it('should abbreviate thousands with k suffix', () => {
+            assert.equal(abbreviateNumber(1000n, { decimals: 0 }), '1k');
+            assert.equal(abbreviateNumber(1500n, { decimals: 0 }), '1.5k');
+            assert.equal(abbreviateNumber(5000n, { decimals: 0 }), '5k');
+            assert.equal(abbreviateNumber(10000n, { decimals: 0 }), '10k');
+            assert.equal(abbreviateNumber(15000n, { decimals: 0 }), '15k');
+            assert.equal(abbreviateNumber(100000n, { decimals: 0 }), '100k');
+            assert.equal(abbreviateNumber(200000n, { decimals: 0 }), '200k');
+            assert.equal(abbreviateNumber(400000n, { decimals: 0 }), '400k');
+            assert.equal(abbreviateNumber(999000n, { decimals: 0 }), '999k');
+        });
+        it('should abbreviate millions with M suffix', () => {
+            assert.equal(abbreviateNumber(1000000n, { decimals: 0 }), '1M');
+            assert.equal(abbreviateNumber(1234567n, { decimals: 0 }), '1.23M');
+            assert.equal(abbreviateNumber(10000000n, { decimals: 0 }), '10M');
+            assert.equal(abbreviateNumber(15500000n, { decimals: 0 }), '15.5M');
+            assert.equal(abbreviateNumber(100000000n, { decimals: 0 }), '100M');
+            assert.equal(abbreviateNumber(999000000n, { decimals: 0 }), '999M');
+        });
+        it('should abbreviate billions with B suffix', () => {
+            assert.equal(abbreviateNumber(1000000000n, { decimals: 0 }), '1B');
+            assert.equal(abbreviateNumber(1234567890n, { decimals: 0 }), '1.23B');
+            assert.equal(abbreviateNumber(10000000000n, { decimals: 0 }), '10B');
+            assert.equal(abbreviateNumber(100000000000n, { decimals: 0 }), '100B');
+        });
+        it('should abbreviate trillions with T suffix', () => {
+            assert.equal(abbreviateNumber(1000000000000n, { decimals: 0 }), '1T');
+            assert.equal(abbreviateNumber(1234567890123n, { decimals: 0 }), '1.23T');
+            assert.equal(abbreviateNumber(10000000000000n, { decimals: 0 }), '10T');
+        });
+        it('should handle values less than 1000 without abbreviation', () => {
+            assert.equal(abbreviateNumber(0n, { decimals: 0 }), '0');
+            assert.equal(abbreviateNumber(1n, { decimals: 0 }), '1');
+            assert.equal(abbreviateNumber(10n, { decimals: 0 }), '10');
+            assert.equal(abbreviateNumber(100n, { decimals: 0 }), '100');
+            assert.equal(abbreviateNumber(999n, { decimals: 0 }), '999');
+        });
+        it('should handle negative values', () => {
+            assert.equal(abbreviateNumber(-1000n, { decimals: 0 }), '-1k');
+            assert.equal(abbreviateNumber(-1500n, { decimals: 0 }), '-1.5k');
+            assert.equal(abbreviateNumber(-1000000n, { decimals: 0 }), '-1M');
+            assert.equal(abbreviateNumber(-100n, { decimals: 0 }), '-100');
+        });
+    });
+    describe('with decimals: 2 (e.g., USD cents)', () => {
+        it('should abbreviate thousands with k suffix', () => {
+            // 100000n with decimals:2 represents $1,000.00
+            assert.equal(abbreviateNumber(100000n, { decimals: 2 }), '1k');
+            assert.equal(abbreviateNumber(150000n, { decimals: 2 }), '1.5k');
+            assert.equal(abbreviateNumber(1000000n, { decimals: 2 }), '10k');
+            assert.equal(abbreviateNumber(10000000n, { decimals: 2 }), '100k');
+            assert.equal(abbreviateNumber(20000000n, { decimals: 2 }), '200k');
+            assert.equal(abbreviateNumber(40000000n, { decimals: 2 }), '400k');
+        });
+        it('should abbreviate millions with M suffix', () => {
+            // 100000000n with decimals:2 represents $1,000,000.00
+            assert.equal(abbreviateNumber(100000000n, { decimals: 2 }), '1M');
+            assert.equal(abbreviateNumber(123456700n, { decimals: 2 }), '1.23M');
+            assert.equal(abbreviateNumber(1000000000n, { decimals: 2 }), '10M');
+        });
+        it('should handle values less than 1000 without abbreviation', () => {
+            assert.equal(abbreviateNumber(0n, { decimals: 2 }), '0');
+            assert.equal(abbreviateNumber(100n, { decimals: 2 }), '1');
+            assert.equal(abbreviateNumber(1000n, { decimals: 2 }), '10');
+            assert.equal(abbreviateNumber(10000n, { decimals: 2 }), '100');
+            assert.equal(abbreviateNumber(99900n, { decimals: 2 }), '999');
+        });
+    });
+    describe('with decimals: 6 (e.g., USDC)', () => {
+        it('should abbreviate thousands with k suffix', () => {
+            // 1000000000n with decimals:6 represents 1,000 USDC
+            assert.equal(abbreviateNumber(1000000000n, { decimals: 6 }), '1k');
+            assert.equal(abbreviateNumber(1500000000n, { decimals: 6 }), '1.5k');
+            assert.equal(abbreviateNumber(10000000000n, { decimals: 6 }), '10k');
+            assert.equal(abbreviateNumber(100000000000n, { decimals: 6 }), '100k');
+        });
+        it('should abbreviate millions with M suffix', () => {
+            assert.equal(abbreviateNumber(1000000000000n, { decimals: 6 }), '1M');
+            assert.equal(abbreviateNumber(1234567000000n, { decimals: 6 }), '1.23M');
+        });
+    });
+    describe('maxDecimals option', () => {
+        it('should respect maxDecimals for small abbreviated values', () => {
+            assert.equal(abbreviateNumber(1234n, { decimals: 0, maxDecimals: 3 }), '1.234k');
+            assert.equal(abbreviateNumber(1234n, { decimals: 0, maxDecimals: 1 }), '1.2k');
+            assert.equal(abbreviateNumber(1234n, { decimals: 0, maxDecimals: 0 }), '1k');
+        });
+        it('should use fewer decimals for larger abbreviated values', () => {
+            // >= 100: no decimals
+            assert.equal(abbreviateNumber(123456n, { decimals: 0, maxDecimals: 2 }), '123k');
+            // >= 10: max 1 decimal
+            assert.equal(abbreviateNumber(12345n, { decimals: 0, maxDecimals: 2 }), '12.3k');
+            // < 10: max 2 decimals (default)
+            assert.equal(abbreviateNumber(1234n, { decimals: 0, maxDecimals: 2 }), '1.23k');
+        });
+    });
+});
+describe('formatWithAbbreviation', () => {
+    it('should format with specific divisor and suffix', () => {
+        assert.equal(formatWithAbbreviation(100000n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '100k');
+        assert.equal(formatWithAbbreviation(1234567n, { decimals: 0, divisor: 1000000n, suffix: 'M' }), '1.23M');
+        assert.equal(formatWithAbbreviation(5000000n, { decimals: 0, divisor: 1000000n, suffix: 'M' }), '5M');
+    });
+    it('should allow forcing a specific abbreviation', () => {
+        // Force display as thousands even though it's a million
+        assert.equal(formatWithAbbreviation(1000000n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '1000k');
+    });
+    it('should handle negative values', () => {
+        assert.equal(formatWithAbbreviation(-100000n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '-100k');
+    });
+    it('should use 1 decimal for values between 10-99', () => {
+        // 50_000 / 1000 = 50, which is between 10-99
+        assert.equal(formatWithAbbreviation(50000n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '50k');
+        // 15_500 / 1000 = 15.5
+        assert.equal(formatWithAbbreviation(15500n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '15.5k');
+    });
+    it('should use 0 decimals for values >= 100', () => {
+        // 150_000 / 1000 = 150
+        assert.equal(formatWithAbbreviation(150000n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '150k');
+    });
+    it('should handle values without decimal point', () => {
+        // When result has no fractional part
+        assert.equal(formatWithAbbreviation(1000n, { decimals: 0, divisor: 1000n, suffix: 'k' }), '1k');
+    });
+});
+describe('numericAbbreviations', () => {
+    it('should export the abbreviations array', () => {
+        assert.equal(numericAbbreviations.length, 4);
+        assert.equal(numericAbbreviations[0].suffix, 'T');
+        assert.equal(numericAbbreviations[1].suffix, 'B');
+        assert.equal(numericAbbreviations[2].suffix, 'M');
+        assert.equal(numericAbbreviations[3].suffix, 'k');
+    });
+    it('should have correct divisors', () => {
+        assert.equal(numericAbbreviations[0].divisor, 1000000000000n);
+        assert.equal(numericAbbreviations[1].divisor, 1000000000n);
+        assert.equal(numericAbbreviations[2].divisor, 1000000n);
+        assert.equal(numericAbbreviations[3].divisor, 1000n);
+    });
+});
+describe('oneEther', () => {
+    it('should equal 10^18', () => {
+        assert.equal(oneEther, 10n ** 18n);
+        assert.equal(oneEther, 1000000000000000000n);
+    });
+});
+describe('addThousandsSeparator', () => {
+    it('should add commas to large numbers', () => {
+        assert.equal(addThousandsSeparator('1000'), '1,000');
+        assert.equal(addThousandsSeparator('1000000'), '1,000,000');
+        assert.equal(addThousandsSeparator('1234567890'), '1,234,567,890');
+    });
+    it('should handle small numbers without separators', () => {
+        assert.equal(addThousandsSeparator('0'), '0');
+        assert.equal(addThousandsSeparator('1'), '1');
+        assert.equal(addThousandsSeparator('100'), '100');
+        assert.equal(addThousandsSeparator('999'), '999');
+    });
+    it('should preserve decimal parts', () => {
+        assert.equal(addThousandsSeparator('1000.50'), '1,000.50');
+        assert.equal(addThousandsSeparator('1234567.89'), '1,234,567.89');
+    });
+    it('should handle numbers with only decimal part', () => {
+        assert.equal(addThousandsSeparator('.50'), '0.50');
+    });
+    it('should use custom delimiter', () => {
+        assert.equal(addThousandsSeparator('1000000', ' '), '1 000 000');
+        assert.equal(addThousandsSeparator('1000000', '.'), '1.000.000');
+    });
+    it('should handle empty integer part', () => {
+        assert.equal(addThousandsSeparator(''), '0');
+    });
+});
+describe('parseUnits', () => {
+    it('should parse string amount to bigint', () => {
+        assert.equal(parseUnits('1', { decimals: 6 }), 1000000n);
+        assert.equal(parseUnits('1.5', { decimals: 6 }), 1500000n);
+        assert.equal(parseUnits('100', { decimals: 6 }), 100000000n);
+    });
+    it('should handle comma-separated values', () => {
+        assert.equal(parseUnits('1,000', { decimals: 6 }), 1000000000n);
+        assert.equal(parseUnits('1,234,567', { decimals: 6 }), 1234567000000n);
+    });
+    it('should handle custom delimiter', () => {
+        assert.equal(parseUnits('1.000', { decimals: 6, delimiter: '.' }), 1000000000n);
+    });
+    it('should handle zero', () => {
+        assert.equal(parseUnits('0', { decimals: 6 }), 0n);
+    });
+});
+describe('formatUnits', () => {
+    it('should format bigint to string with decimals', () => {
+        const result = formatUnits(1000000n, { decimals: 6 });
+        assert.equal(result, '1');
+    });
+    it('should truncate decimals', () => {
+        const result = formatUnits(1234567n, { decimals: 6, truncateDecimals: 2 });
+        assert.equal(result, '1.23');
+    });
+    it('should pad decimals', () => {
+        const result = formatUnits(1000000n, { decimals: 6, padDecimals: 2 });
+        assert.equal(result, '1.00');
+    });
+    it('should show cutoff indicator for small values', () => {
+        const result = formatUnits(100n, { decimals: 6, cutoff: 1000n });
+        assert.ok(result.startsWith('<'));
+    });
+    it('should not show cutoff indicator when value equals cutoff', () => {
+        const result = formatUnits(1000n, { decimals: 6, cutoff: 1000n });
+        assert.ok(!result.startsWith('<'));
+    });
+    it('should not show cutoff indicator when value exceeds cutoff', () => {
+        const result = formatUnits(2000n, { decimals: 6, cutoff: 1000n });
+        assert.ok(!result.startsWith('<'));
+    });
+    it('should round up when enabled', () => {
+        const result = formatUnits(1555000n, { decimals: 6, truncateDecimals: 2, roundUp: true });
+        assert.equal(result, '1.56');
+    });
+    it('should not round up values below halfway', () => {
+        const result = formatUnits(1544000n, { decimals: 6, truncateDecimals: 2, roundUp: true });
+        assert.equal(result, '1.54');
+    });
+    it('should not round when roundUp is true but truncateDecimals is undefined', () => {
+        const result = formatUnits(1555555n, { decimals: 6, roundUp: true });
+        // Without truncateDecimals, rounding is skipped
+        assert.ok(result.includes('1.555555') || result === '1.555555');
+    });
+    it('should use default padDecimals of 0', () => {
+        // Don't pass padDecimals - should default to 0
+        const result = formatUnits(1000000n, { decimals: 6 });
+        assert.equal(result, '1');
+    });
+    it('should use default delimiter of comma', () => {
+        // Don't pass delimiter - should default to ','
+        const result = formatUnits(1234567000000n, { decimals: 6 });
+        assert.ok(result.includes(','));
+    });
+    it('should use default roundUp of false', () => {
+        // Don't pass roundUp - should default to false (no rounding)
+        const result = formatUnits(1559000n, { decimals: 6, truncateDecimals: 2 });
+        assert.equal(result, '1.55'); // Truncated, not rounded
+    });
+    it('should not round when roundUp is false', () => {
+        const result = formatUnits(1559000n, { decimals: 6, truncateDecimals: 2, roundUp: false });
+        assert.equal(result, '1.55');
+    });
+    it('should use custom delimiter', () => {
+        const result = formatUnits(1234567000000n, { decimals: 6, delimiter: ' ' });
+        assert.ok(result.includes(' '));
+    });
+});
+describe('formatTokenAmountForDisplay', () => {
+    it('should format with 2 decimal truncation by default', () => {
+        const result = formatTokenAmountForDisplay(1234567n, { decimals: 6 });
+        assert.equal(result, '1.23');
+    });
+    it('should allow overriding truncateDecimals', () => {
+        const result = formatTokenAmountForDisplay(1234567n, { decimals: 6, truncateDecimals: 4 });
+        assert.equal(result, '1.2345');
+    });
+});
+describe('parseIntegerSafe', () => {
+    it('should parse valid integers', () => {
+        assert.equal(parseIntegerSafe('0'), 0);
+        assert.equal(parseIntegerSafe('1'), 1);
+        assert.equal(parseIntegerSafe('123'), 123);
+        assert.equal(parseIntegerSafe('-456'), -456);
+    });
+    it('should return null for invalid inputs', () => {
+        assert.equal(parseIntegerSafe('abc'), null);
+        assert.equal(parseIntegerSafe(''), null);
+        assert.equal(parseIntegerSafe('NaN'), null);
+    });
+    it('should truncate decimal values to integer', () => {
+        assert.equal(parseIntegerSafe('123.456'), 123);
+        assert.equal(parseIntegerSafe('99.99'), 99);
+    });
+});
+describe('timestampToDate', () => {
+    it('should convert seconds timestamp to Date', () => {
+        const timestamp = 1704067200; // 2024-01-01 00:00:00 UTC
+        const date = timestampToDate(timestamp);
+        assert.ok(date instanceof Date);
+        assert.equal(date?.getUTCFullYear(), 2024);
+        assert.equal(date?.getUTCMonth(), 0); // January
+        assert.equal(date?.getUTCDate(), 1);
+    });
+    it('should handle string timestamps', () => {
+        const date = timestampToDate('1704067200');
+        assert.ok(date instanceof Date);
+        assert.equal(date?.getUTCFullYear(), 2024);
+    });
+    it('should handle bigint timestamps', () => {
+        const date = timestampToDate(1704067200n);
+        assert.ok(date instanceof Date);
+        assert.equal(date?.getUTCFullYear(), 2024);
+    });
+    it('should return null for null/undefined input', () => {
+        assert.equal(timestampToDate(null), null);
+        assert.equal(timestampToDate(undefined), null);
+    });
+    it('should return null for zero timestamp', () => {
+        assert.equal(timestampToDate(0), null);
+    });
+});
+describe('formatAmount', () => {
+    const mockToken = { decimals: 6, symbol: 'USDC' };
+    it('should format amount with token decimals', () => {
+        const result = formatAmount(mockToken, 1234567n);
+        assert.ok(result);
+        assert.equal(result, '1.23');
+    });
+    it('should return null for null amount', () => {
+        assert.equal(formatAmount(mockToken, null), null);
+    });
+    it('should allow overriding options', () => {
+        const result = formatAmount(mockToken, 1234567n, { truncateDecimals: 4 });
+        assert.ok(result);
+        assert.equal(result, '1.2345');
+    });
+});