npm package: @siamcse/utils
Description: Utility functions for number formatting, file handling, string manipulation, and more — optimized for React + TypeScript apps.
Author: Abu Siam
Latest version: 1.1.0

# 📦 @siamcse/utils

A lightweight, reusable TypeScript utility library containing common helper functions used across multiple Next.js and TypeScript projects.

This package includes:

🎨 Tailwind Class Merging (cn)

🔤 String helpers

🔢 Number + Large Number Formatters

📁 File size + MIME type utilities

📞 Phone number formatter

🗺 Map ⇄ JSON helpers

⏳ Delay helper

🔗 Link extractor

Perfect for Next.js, React, Node, or any TypeScript project.

## 🚀 Installation

```bash
npm install @siamcse/utils
```

**Note:** `clsx` and `tailwind-merge` are included as dependencies and will be installed automatically. They are used by the `cn` function for Tailwind class merging.

## 📘 Usage

### ✅ Tailwind Class Utility (cn)

```typescript
import {cn} from '@siamcse/utils'

const buttonClass = cn('px-4 py-2 font-medium', 'bg-blue-600 hover:bg-blue-700', 'rounded-md')
```

### 🔤 String Helpers

```typescript
import {lowercaseFirstLetter, uppercaseFirstLetter, separateCamelCase, extractInitials, extractLink} from '@siamcse/utils'

lowercaseFirstLetter('Hello') // "hello"
uppercaseFirstLetter('hello') // "Hello"
separateCamelCase('userNameID') // "user Name ID"
extractInitials('John Doe') // "JD"

extractLink('Check this https://example.com now')
// { link: "https://example.com", text: "Check this now" }
```

### 🔢 Number Helpers

```typescript
import {formatNumberWithCommas, formatToTwoDecimal, formatLargeNumber, parseLargeNumber, formatNumberWithSuffix, convertMBToBytes, formatFileSize} from '@siamcse/utils'

formatToTwoDecimal(10.55) // "10.55"
formatNumberWithCommas(1234567) // "1,234,567.00"

formatLargeNumber(1200) // "1.2K"
formatLargeNumber(1500000) // "1.5M"

parseLargeNumber('2.5K') // 2500
parseLargeNumber('1.5M') // 1500000

formatNumberWithSuffix(2500) // { formattedValue: "2.5", suffix: "K" }

convertMBToBytes(5) // 5242880 (5MB in bytes)
formatFileSize(2048) // "2 KB"
```

### 📞 US Phone Number Formatter

```typescript
import {formatUSPhoneNumber} from '@siamcse/utils'

formatUSPhoneNumber('1234567890') // "123 456 7890"
```

### 🗺 Map Helpers

```typescript
import {mapToJSON, jsonToMap} from '@siamcse/utils'

const map = new Map([
  ['a', 1],
  ['b', 2],
])
const json = mapToJSON(map) // '[["a",1],["b",2]]'

jsonToMap(json) // Map { "a" => 1, "b" => 2 }
```

### 📁 File Utilities

**Get MIME type:**

```typescript
import {getMimeType} from '@siamcse/utils'

getMimeType('file.pdf') // "application/pdf"
getMimeType('file.xlsx') // Excel MIME type
```

**Separate CamelCase:**

```typescript
separateCamelCase('accountBalanceUSD')
// "account Balance USD"
```

### ⏳ Delay Helper

```typescript
import {delay} from '@siamcse/utils'

await delay(1000) // waits 1 second
```

## 📚 Full API List

### 🔤 String helpers

- `lowercaseFirstLetter(str)`
- `uppercaseFirstLetter(str)`
- `separateCamelCase(str)`
- `extractInitials(name)`
- `extractLink(text)`
- `cn(...classNames)`

### 🔢 Number helpers

- `formatToTwoDecimal(value)`
- `formatNumberWithCommas(num)`
- `formatLargeNumber(num)`
- `parseLargeNumber(str)`
- `formatNumberWithSuffix(value)`
- `convertMBToBytes(mb)`
- `formatFileSize(bytes)`

### 📞 Phone

- `formatUSPhoneNumber(number)`

### 🗺 Map utilities

- `mapToJSON(map)`
- `jsonToMap(json)`

### 📁 File utilities

- `getMimeType(filename)`

### ⏳ Delay

- `delay(ms)`

## 📄 License

MIT License

© 2025 — Maintained by @siamcse