houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
164 lines (163 loc) • 5.18 kB
TypeScript
/**
* @module FormatUtils
* @description A comprehensive collection of utility functions for formatting data, text, numbers, and dates.
* @example
* ```typescript
* import { FormatUtils } from 'houser-js-utils';
*
* // Format phone number
* const phone = FormatUtils.formatPhoneNumber('1234567890'); // "(123) 456-7890"
*
* // Format currency
* const price = FormatUtils.formatCurrency(1234.56); // "$1,234.56"
*
* // Format file size
* const size = FormatUtils.formatFileSize(1048576); // "1.0 MB"
* ```
*/
export declare const FormatUtils: {
/**
* Formats an address into a comma-separated string.
*
* @param address - The address object to format
* @param address.street - Street address
* @param address.city - City name
* @param address.state - State or province
* @param address.zip - ZIP or postal code
* @param address.country - Country name
* @returns The formatted address string
*
* @example
* ```typescript
* const address = {
* street: "123 Main St",
* city: "Springfield",
* state: "IL",
* zip: "62701"
* };
* const formatted = FormatUtils.formatAddress(address);
* // "123 Main St, Springfield, IL, 62701"
* ```
*/
formatAddress: (address: {
street?: string;
city?: string;
state?: string;
zip?: string;
country?: string;
}) => string;
/**
* Formats a credit card number by adding spaces every 4 digits.
*
* @param cardNumber - The card number to format
* @returns The formatted card number with spaces
*
* @example
* ```typescript
* const card = FormatUtils.formatCreditCard("4111111111111111");
* // "4111 1111 1111 1111"
* ```
*/
formatCreditCard: (cardNumber: string) => string;
/**
* Formats a number as currency using the Intl.NumberFormat API.
*
* @param amount - The amount to format
* @param currency - The currency code (e.g., 'USD', 'EUR', 'GBP')
* @param locale - The locale to use for formatting
* @returns The formatted currency string
*
* @example
* ```typescript
* const price = FormatUtils.formatCurrency(99.99, "USD", "en-US");
* // "$99.99"
*
* const euros = FormatUtils.formatCurrency(99.99, "EUR", "de-DE");
* // "99,99 €"
* ```
*/
formatCurrency: (amount: number, currency?: string, locale?: string) => string;
/**
* Formats a file size in bytes to a human-readable string.
*
* @param bytes - The size in bytes
* @param decimals - Number of decimal places to show
* @returns The formatted file size with appropriate unit
*
* @example
* ```typescript
* const size = FormatUtils.formatFileSize(1024); // "1 KB"
* const size2 = FormatUtils.formatFileSize(1024 * 1024, 1); // "1.0 MB"
* ```
*/
formatFileSize: (bytes: number, decimals?: number) => string;
/**
* Formats a number with commas as thousands separators.
*
* @param num - Number to format
* @returns Formatted number string with commas
*
* @example
* ```typescript
* const num = FormatUtils.formatNumber(1000000); // "1,000,000"
* ```
*/
formatNumber: (num: number) => string;
/**
* Formats a number as a percentage.
*
* @param value - The value to format
* @param decimals - Number of decimal places to show
* @returns The formatted percentage string
*
* @example
* ```typescript
* const percent = FormatUtils.formatPercent(75.5); // "75.5%"
* ```
*/
formatPercent: (value: number, decimals?: number) => string;
/**
* Formats a phone number according to the specified format.
*
* @param phone - The phone number to format
* @param format - The format to use ('US' or 'EU')
* @returns The formatted phone number
*
* @example
* ```typescript
* const usPhone = FormatUtils.formatPhoneNumber("1234567890", "US");
* // "(123) 456-7890"
*
* const euPhone = FormatUtils.formatPhoneNumber("1234567890", "EU");
* // "12 34 56 78 90"
* ```
*/
formatPhoneNumber: (phone: string, format?: "US" | "EU") => string;
/**
* Formats a duration in milliseconds to a human-readable string.
*
* @param ms - The duration in milliseconds
* @param format - The format to use ('short' or 'long')
* @returns The formatted duration string
*
* @example
* ```typescript
* const short = FormatUtils.formatDuration(3661000, "short"); // "1h"
* const long = FormatUtils.formatDuration(3661000, "long");
* // "1 hour, 1 minute, 1 second"
* ```
*/
formatDuration: (ms: number, format?: "short" | "long") => string;
/**
* Formats a social security number with hyphens.
*
* @param ssn - The SSN to format
* @returns The formatted SSN
*
* @example
* ```typescript
* const ssn = FormatUtils.formatSSN("123456789"); // "123-45-6789"
* ```
*/
formatSSN: (ssn: string) => string;
};