npm package: @hahapermutize/string-utils
Description: String utility functions for formatting numbers, money, dates, and addresses
Latest version: 1.0.6

# @hahapermutize/string-utils

[![npm](https://img.shields.io/npm/v/@hahapermutize/string-utils)](https://www.npmjs.com/package/@hahapermutize/string-utils)
[![yarn](https://img.shields.io/npm/v/@hahapermutize/string-utils?label=yarn&color=2c8ebb)](https://yarnpkg.com/package/@hahapermutize/string-utils)
[![GitHub](https://img.shields.io/github/stars/Permutize/string-utils?style=social)](https://github.com/Permutize/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

```bash
npm install @hahapermutize/string-utils
```

## Usage

### Basic Usage

```typescript
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:

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:**

```typescript
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:

```typescript
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`):

```typescript
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:

```typescript
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

```bash
npm test
npm run test:watch
npm run test:coverage
```

### Linting and Formatting

```bash
npm run lint
npm run lint:fix
npm run format
npm run format:check
```

### Building

```bash
npm run build
```

## Dependencies

-   `lodash`: For utility functions
-   `moment`: For date manipulation

## License

MIT