@maz-ui/utils

JavaScript/TypeScript utility functions for the Maz-UI ecosystem - String manipulation, date formatting, debouncing, throttling, and more.

Installation

``bash
npm install @maz-ui/utils
`

Features

- String utilities - Case conversion, normalization, and manipulation
- Date and number formatting - Localized formatting with internationalization support
- Performance utilities - Debouncing, throttling, and optimization helpers
- Browser utilities - Client/server detection, user visibility, and environment checks
- TypeScript helpers - Advanced type utilities for better type safety
- Phone number formatting - International phone number utilities
- Currency formatting - Multi-currency formatting support
- Validation utilities - Deep equality checks and data validation
- DOM utilities - Script loading, textarea autogrow, and swipe handling

Usage

$3

`typescript
import { camelCase, debounce, formatDate } from '@maz-ui/utils'

// String utilities
const camelCased = camelCase('hello-world') // 'helloWorld'

// Date formatting
const formatted = formatDate(new Date(), 'en-US') // '12/25/2023'

// Performance utilities
const debouncedFn = debounce(() => console.log('Called!'), 300)
`

$3

`typescript
// Import TypeScript helpers
import type { DeepPartial } from '@maz-ui/utils/ts-helpers/DeepPartial'
// Import specific helpers
import { camelCase } from '@maz-ui/utils/helpers/camelCase'
import { debounce } from '@maz-ui/utils/helpers/debounce'
import { formatDate } from '@maz-ui/utils/helpers/formatDate'
`

Available Utilities

$3

- camelCase - Convert strings to camelCase
- capitalize - Capitalize first letter of strings
- kebabCase - Convert strings to kebab-case
- pascalCase - Convert strings to PascalCase
- snakeCase - Convert strings to snake_case
- normalizeString - Normalize strings for comparison

$3

- formatDate - Format dates with locale support
- formatNumber - Format numbers with locale support
- formatCurrency - Format currency values with locale support

$3

- debounce - Debounce function calls
- debounceCallback - Debounce with callback support
- debounceId - Debounce with unique identifiers
- throttle - Throttle function calls
- throttleId - Throttle with unique identifiers

$3

- isClient - Check if running in client environment
- isServer - Check if running in server environment
- isStandaloneMode - Check if app is in standalone mode
- userVisibility - Track user visibility state
- getBrowserLocale - Get browser locale settings

$3

- isEqual - Deep equality comparison
- checkAvailability - Check resource availability
- truthyFilter - Filter truthy values from arrays

$3

- scriptLoader - Dynamic script loading
- TextareaAutogrow - Automatic textarea height adjustment
- swipeHandler - Touch swipe gesture handling
- idleTimeout - Idle state management

$3

- formatPhoneNumber - Format international phone numbers
- countryCodeToUnicodeFlag - Convert country codes to flag emojis
- getCountryFlagUrl - Get country flag image URLs
- fetchLocaleIp - Fetch user locale from IP

$3

- sleep - Promise-based delay utility
- getErrorMessage - Extract error messages safely

TypeScript Helpers

Advanced type utilities for enhanced TypeScript development:

- DeepPartial - Make all properties optional recursively
- DeepKeyOf - Get all nested keys of an object type
- FlattenObjectKeys - Flatten object keys to dot notation
- GenericInstanceType - Extract instance type from constructor
- InferMaybeRef - Infer type from Vue ref or regular value

`typescript
import type { DeepKeyOf, DeepPartial } from '@maz-ui/utils'

interface User {
profile: {
name: string
email: string
}
}

type PartialUser = DeepPartial // All properties optional
type UserKeys = DeepKeyOf // 'profile' | 'profile.name' | 'profile.email'
`

Performance Examples

`typescript
import { debounce, throttle } from '@maz-ui/utils'

// Debounce search input
const debouncedSearch = debounce((query: string) => {
performSearch(query)
}, 300)

// Throttle scroll events
const throttledScroll = throttle(() => {
updateScrollPosition()
}, 16)
`

Formatting Examples

`typescript
import { formatCurrency, formatDate, formatPhoneNumber } from '@maz-ui/utils'

// Currency formatting
const price = formatCurrency(1234.56, 'USD', 'en-US') // '$1,234.56'

// Date formatting
const date = formatDate(new Date(), 'fr-FR') // '25/12/2023'

// Phone formatting
const phone = formatPhoneNumber('+33123456789', 'international')
``

Requirements

- Node.js >= 18.0.0
- TypeScript support included
- Tree-shakeable for optimal bundle size

Contributing

Contributions are welcome! Please ensure:

- New utilities follow existing patterns
- TypeScript types are properly defined
- Unit tests are included
- Documentation is updated accordingly

License

MIT License - see LICENSE file for details.