@xcelsior/utils

A collection of commonly used utility functions for TypeScript projects.

Installation

pnpm add @xcelsior/utils

Features

Date Utilities

Functions for date manipulation and formatting:

import { formatDate, parseDate } from '@xcelsior/utils';

// Format a date
formatDate(new Date(), 'yyyy-MM-dd'); // '2024-03-20'

// Parse a date string
parseDate('2024-03-20', 'yyyy-MM-dd'); // Date object

Formatters

String and number formatting utilities:

import { formatNumber, formatCurrency } from '@xcelsior/utils';

formatNumber(1234.567, 2); // '1,234.57'
formatCurrency(1234.567, 'USD'); // '$1,234.57'

Object Utilities

Functions for object manipulation:

import { deepMerge, pick, omit } from '@xcelsior/utils';

// Deep merge objects
deepMerge({ a: 1 }, { b: 2 }); // { a: 1, b: 2 }

// Pick specific properties
pick({ a: 1, b: 2, c: 3 }, ['a', 'b']); // { a: 1, b: 2 }

// Omit specific properties
omit({ a: 1, b: 2, c: 3 }, ['c']); // { a: 1, b: 2 }

Promise Utilities

Helper functions for working with promises:

import { retry, timeout } from '@xcelsior/utils';

// Retry a function
await retry(async () => {
  // Your async operation
}, { attempts: 3 });

// Add timeout to a promise
await timeout(promise, 5000); // Rejects if promise takes longer than 5 seconds

API Reference

Date Functions

• formatDate(date: Date, format: string): string
• parseDate(dateString: string, format: string): Date
• addDays(date: Date, days: number): Date
• isValidDate(date: any): boolean

Formatter Functions

• formatNumber(value: number, decimals?: number): string
• formatCurrency(value: number, currency: string): string
• formatPercentage(value: number): string

Object Functions

• deepMerge<T>(...objects: Partial<T>[]): T
• pick<T>(obj: T, keys: (keyof T)[]): Partial<T>
• omit<T>(obj: T, keys: (keyof T)[]): Partial<T>
• isEqual(a: any, b: any): boolean

Promise Functions

• retry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>
• timeout<T>(promise: Promise<T>, ms: number): Promise<T>
• sleep(ms: number): Promise<void>

Contributing

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. Run tests: pnpm test
5. Submit a pull request

License

MIT