npm package: @sk2you/custom-utils
Description: A collection of utility functions for TypeScript projects
Author: Suraj HeadsUp
Latest version: 1.0.7

# JavaScript/TypeScript Utility Functions

This repository contains a collection of useful JavaScript/TypeScript utility functions for common tasks like date formatting, pagination, and number formatting.

## Table of Contents

- [Installation](#installation)
- [Functions](#functions)
  - [Date Formatting](#date-formatting)
  - [Pagination](#pagination)
  - [Number to Words](#number-to-words)
  - [Number Formatting](#number-formatting)
- [Usage Examples](#usage-examples)
- [License](#license)

## Installation

```bash
# Using npm
npm install @yourpackage/utils

# Using yarn
yarn add @yourpackage/utils
```

## Functions

### Date Formatting

Format UNIX timestamps into readable date strings with customizable options.

```typescript
getFormattedDate(
  UNIX_timestamp: number | string, 
  types: string[], 
  symbol = '-', 
  timeSeparator = ':', 
  timeFormat = '24', 
  monthName = false, 
  includeDay = true
): string
```

#### Parameters:

- **UNIX_timestamp**: The UNIX timestamp to format
- **types**: Array of elements to include (`'day'`, `'date'`, `'month'`, `'year'`, `'hour'`, `'minute'`, `'second'`, `'period'`)
- **symbol**: Symbol to use as separator between date elements (default: `-`)
- **timeSeparator**: Symbol to use as separator between time elements (default: `:`)
- **timeFormat**: `'12'` for 12-hour format with am/pm, `'24'` for 24-hour format (default: `'24'`)
- **monthName**: Whether to show month as name (Jan, Feb) instead of number (default: `false`)
- **includeDay**: Whether to include the day name (SUN, MON, etc.) (default: `true`)

### Pagination

Calculate page count based on pagination parameters.

```typescript
GetPageCount(pagination: PaginationParams, index: number): number
```

#### Parameters:

- **pagination**: Object containing `limit` and `page` properties
- **index**: Current index

### Number to Words

Convert numbers to their word representation with support for both Western and Indian number systems.

```typescript
numberToWords(num: number, useIndianSystem = false): string
```

#### Parameters:

- **num**: The number to convert to words
- **useIndianSystem**: Whether to use Indian number naming (lakh, crore) (default: `false`)

### Number Formatting

Format numbers with Indian numbering system separators.

```typescript
formatNumberWithIndianSeparators(
  num: number | string, 
  separator = ',', 
  includeWords = false
): string
```

#### Parameters:

- **num**: The number to format
- **separator**: The separator character (default: `,`)
- **includeWords**: Whether to include the Indian names (lakh, crore) in parentheses (default: `false`)

## Usage Examples

### Date Formatting

```typescript
import { getFormattedDate } from '@yourpackage/utils';

// Basic date formatting
const timestamp = 1618990800000; // April 21, 2021
const formattedDate = getFormattedDate(timestamp, ['date', 'month', 'year']);
console.log(formattedDate); // "21-04-2021"

// With month names and custom separator
const prettyDate = getFormattedDate(timestamp, ['date', 'month', 'year'], '/', undefined, undefined, true);
console.log(prettyDate); // "21/Apr/2021"

// With time
const dateTime = getFormattedDate(timestamp, ['date', 'month', 'year', 'hour', 'minute'], '-', ':', '12', true);
console.log(dateTime); // "21-Apr-2021 12:00"
```

### Pagination

```typescript
import { GetPageCount } from '@yourpackage/utils';

const pagination = { limit: 10, page: 2 };
const itemIndex = 3;

const pageCount = GetPageCount(pagination, itemIndex);
console.log(pageCount); // 14 (10 + 3 + 1)
```

### Number to Words

```typescript
import { numberToWords } from '@yourpackage/utils';

// Western system
console.log(numberToWords(123)); // "one hundred twenty-three"
console.log(numberToWords(1000000)); // "one million"

// Indian system
console.log(numberToWords(100000, true)); // "one lakh"
console.log(numberToWords(10000000, true)); // "one crore"
```

### Number Formatting

```typescript
import { formatNumberWithIndianSeparators } from '@yourpackage/utils';

// Basic formatting
console.log(formatNumberWithIndianSeparators(123456)); // "1,23,456"
console.log(formatNumberWithIndianSeparators(10000000)); // "1,00,00,000"

// With Indian number names
console.log(formatNumberWithIndianSeparators(100000, ',', true)); // "1,00,000 (1 lakh)"
console.log(formatNumberWithIndianSeparators(20000000, ',', true)); // "2,00,00,000 (2 crores)"
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.