@hahapermutize/string-utils

String utility functions for formatting numbers, money, dates, and addresses. This package provides a unified implementation of string utilities used across HaHa projects.

Installation

npm install @hahapermutize/string-utils

Usage

Basic Usage

import {
    formatNumber,
    formatMoney,
    getCurrencySymbol,
    toLocaleDateString,
    toLocaleTimeString,
    toLocaleDateTimeString,
    toDayOfWeek,
    convertTimestampToDateIfNeeds,
    isEqualCaseInsensitive,
    formatWalletAddress,
} from '@hahapermutize/string-utils';

// Format numbers (truncates, not rounds)
formatNumber(1234.56719); // "1,234.567"
formatNumber(12345.67812); // "12,345.67"

// Format very small numbers with subscript notation (3+ leading zeros)
formatNumber(0.000123); // "0.0₃123"
formatNumber(0.00000001942323); // "0.0₇1942"

// Format money (truncates, not rounds)
formatMoney(1234.999999); // "$1,234.99"
formatMoney(1234.56); // "$1,234.56"
formatMoney(1000000); // "$1.00 Million"

// Format money with custom currency and locale
formatMoney(1234.56, { currency: 'EUR', locale: 'en-US' }); // "€1,234.56"

// Format very small amounts with subscript notation
formatMoney(0.000123456); // "$0.0₃1234"
formatMoney(0.000000123456); // "$0.0₆1234"

// Get currency symbol
getCurrencySymbol('USD'); // "$"
getCurrencySymbol('EUR', 'en-US'); // "€"

// Format dates
toLocaleDateString(new Date('2024-01-15T10:30:00Z')); // "Jan 15, 2024"
toLocaleDateString(new Date('2024-01-15T10:30:00Z'), 'vi-VN'); // "15 thg 1, 2024"
toLocaleTimeString(new Date()); // "3:45 PM"
toLocaleDateTimeString(new Date()); // "Jan 15, 2024, 3:45:30 PM"
toDayOfWeek(new Date()); // "Monday"

// Convert timestamp to date string
convertTimestampToDateIfNeeds('1705320000'); // "Jan 15, 2024, 12:00:00 AM"

// Case insensitive comparison
isEqualCaseInsensitive('Hello', 'hello'); // true

// Format wallet address
formatWalletAddress('0x1234567890abcdef1234567890abcdef12345678'); // "0x1234...5678"
formatWalletAddress('0x1234567890abcdef1234567890abcdef12345678', 6); // "0x123456...345678"

Advanced Configuration

For custom logging:

import { setLogger } from '@hahapermutize/string-utils';

setLogger({
    log: (message, ...optionalParams) => {
        // Your custom logging implementation
        console.log(message, ...optionalParams);
    },
});

API Reference

formatNumber(num: number, options?: { locale?: string; subscript?: boolean }): string

Formats a number with appropriate decimal places based on its magnitude. Values are truncated (not rounded) to the specified decimal places.

• num: The number to format
• options.locale: Optional locale string (default: 'en-US')
• options.subscript: Whether to use subscript notation for very small numbers (default: true)

Features:

• Automatically formats large numbers with suffixes (Million, Billion, Trillion, Quadrillion)
• Uses subscript notation for very small numbers (≥3 leading zeros), e.g., 0.0₇1942 for 0.00000001942
• Truncates values instead of rounding
• Locale-aware formatting (e.g., uses comma as decimal separator for German locale)

Examples:

formatNumber(1234.56719); // "1,234.567" (truncated)
formatNumber(0.000123); // "0.0₃123"
formatNumber(1000000); // "1.00 Million"
formatNumber(1234.567, { locale: 'de-DE' }); // "1.234,567"
formatNumber(0.000123, { subscript: false }); // "0.000123" (no subscript)

formatMoney(number: number, options?: { currency?: string; locale?: string; subscript?: boolean }): string

Formats a number as currency with appropriate decimal places. Values are truncated (not rounded).

• number: The number to format
• options.currency: Currency code (default: 'USD')
• options.locale: Optional locale string (default: 'en-US')
• options.subscript: Whether to use subscript notation for very small numbers (default: true)

Examples:

formatMoney(1234.999999); // "$1,234.99" (truncated)
formatMoney(1234.56, { currency: 'EUR', locale: 'en-US' }); // "€1,234.56"
formatMoney(1000000); // "$1.00 Million"
formatMoney(0.000123456); // "$0.0₃1234" (with subscript)
formatMoney(0.000123456, { subscript: false }); // "$0.000123" (no subscript)

getCurrencySymbol(currency?: string, locale?: string): string

Gets the currency symbol for a given currency code.

• currency: Currency code (default: 'USD')
• locale: Optional locale string (default: 'en-US')

Examples:

getCurrencySymbol('USD'); // "$"
getCurrencySymbol('EUR', 'en-US'); // "€"

toLocaleDateString(date: Date, locale?: string): string

Formats a date as a localized date string (e.g., "Jan 15, 2024").

• date: The date to format
• locale: Optional locale string (default: 'en-US')

Examples:

toLocaleDateString(new Date('2024-01-15T10:30:00Z')); // "Jan 15, 2024"
toLocaleDateString(new Date('2024-01-15T10:30:00Z'), 'vi-VN'); // "15 thg 1, 2024"

toLocaleTimeString(date: Date, locale?: string): string

Formats a date as a localized time string (e.g., "3:45 PM").

• date: The date to format
• locale: Optional locale string (default: 'en-US')

toLocaleDateTimeString(date: Date, locale?: string): string

Formats a date as a localized date and time string (e.g., "Jan 15, 2024, 3:45:30 PM").

• date: The date to format
• locale: Optional locale string (default: 'en-US')

toDayOfWeek(date: Date, locale?: string): string

Gets the day of the week as a localized string (e.g., "Monday").

• date: The date to format
• locale: Optional locale string (default: 'en-US')

convertTimestampToDateIfNeeds(text: string, locale?: string): string

Converts a timestamp string to a formatted date string if it's a valid timestamp (within 50 years from now), otherwise returns the original text.

• text: The text that might be a timestamp
• locale: Optional locale string (default: 'en-US')

isEqualCaseInsensitive(value1?: string | null, value2?: string | null): boolean

Compares two strings case-insensitively.

• value1: First string to compare
• value2: Second string to compare

formatWalletAddress(address: string, value?: number): string

Formats a wallet address by showing the first and last N characters with ellipsis in between.

• address: The address string to format
• value: Number of characters to show at the start and end (default: 4)

Examples:

formatWalletAddress('0x1234567890abcdef1234567890abcdef12345678'); // "0x1234...5678"
formatWalletAddress('0x1234567890abcdef1234567890abcdef12345678', 6); // "0x123456...345678"

Key Features

Truncation vs Rounding

All number formatting functions (formatNumber, formatMoney) truncate values instead of rounding them:

formatNumber(1234.56719); // "1,234.567" (not "1,234.568")
formatMoney(1234.999999); // "$1,234.99" (not "$1,235.00")

Subscript Notation for Very Small Numbers

Numbers with 3 or more leading zeros after the decimal point are displayed using subscript notation (can be disabled with subscript: false):

formatNumber(0.000123); // "0.0₃123" (3 leading zeros)
formatNumber(0.00000001942323); // "0.0₇1942" (7 leading zeros)
formatNumber(0.0000000000000000000123456); // "0.0₂₀1234" (20 leading zeros)
formatMoney(0.000123456); // "$0.0₃1234" (currency with subscript)

The subscript notation supports any number of leading zeros and shows up to 4 significant digits. It works for both formatNumber and formatMoney functions.

Locale Support

All formatting functions support locale parameters for internationalization:

formatNumber(1234.567, { locale: 'de-DE' }); // "1.234,567" (German locale)
formatMoney(1234.56, { currency: 'EUR', locale: 'de-DE' }); // "1.234,56 €"
toLocaleDateString(new Date('2024-01-15'), 'vi-VN'); // "15 thg 1, 2024"

Development

Running Tests

npm test
npm run test:watch
npm run test:coverage

Linting and Formatting

npm run lint
npm run lint:fix
npm run format
npm run format:check

Building

npm run build

Dependencies

• lodash: For utility functions
• moment: For date manipulation

License

MIT