npm package: @kimmylps_dev/toolkitjs
Description: A comprehensive utility toolkit for Thai backend developers
Author: Kimmy Lps
Latest version: 1.3.0

# 🛠️ @kimmylps_dev/toolkitjs

A comprehensive, lightweight utility toolkit for modern backend developers.

[![npm version](https://img.shields.io/npm/v/@kimmylps_dev/toolkitjs.svg)](https://www.npmjs.com/package/@kimmylps_dev/toolkitjs)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()

## 🌟 Features

- 💰 **Finance**: Easy VAT calculation (Include/Exclude) and Thai Baht rounding.
- 🆔 **Validation**: Robust Thai National ID and Phone number (Mobile/Landline) validators.
- 🐘 **Eloquent-style Collection**: Powerful array manipulation with SQL-like operators (`where`, `orderBy`, `groupBy`, `limit`, `etc.`).
- ✍️ **BahtText**: Convert numbers to Thai Baht text (e.g., "หนึ่งร้อยบาทถ้วน").
- 📅 **Thai Date**: Format dates to Thai (Buddhist Era) and `diffForHumans` support (i18n).
- 📡 **Response Helper**: Standardized API response formatting with Pagination support.
- 📦 **Dual Build**: Supports both **ES Modules (ESM)** and **CommonJS (CJS)**.
- 📍 **Location Module**: Added `getProvincesByRegion` and `getRegionByProvince` helpers with smart prefix handling (จังหวัด, จ.).

## 📄 Changelog

Check out the [CHANGELOG.md](./CHANGELOG.md) for full details on every release.

## 🚀 Installation

```bash
npm install @kimmylps_dev/toolkitjs
```

## 📖 Quick Start

### 1. 📅 Date Management (in v1.1.0+)

Effortlessly handle Buddhist Era (พ.ศ.) and human-readable relative time.

```JavaScript
import { toThaiDate, diffForHumans, calculateAge } from '@kimmylps_dev/toolkitjs';

// Format to Thai Date string
toThaiDate(new Date(), { format: 'full', showTime: true });
// "9 กุมภาพันธ์ พ.ศ. 2569 เวลา 22:30 น."

// Relative Time (Supports 'th' and 'en')
diffForHumans('2026-02-09T20:00:00', 'en'); // "3 hours ago"
diffForHumans('2026-02-08T10:00:00', 'th'); // "เมื่อวานนี้"

// Age calculation
calculateAge('1995-05-20'); // 30
```

### 2. 🐘 Eloquent-style Collection

Manage arrays with a fluent, SQL-like interface.

```JavaScript
import { collect } from '@kimmylps_dev/toolkitjs';

const data = [
    { id: 1, category: 'electronics', price: 5000 },
    { id: 2, category: 'books', price: 200 },
    { id: 3, category: 'electronics', price: 1500 },
];

const result = collect(data)
    .whereOp('category', '===', 'electronics')
    .whereOp('price', '>', 1000)
    .orderBy('price', 'desc')
    .select('id', 'price')
    .all();
```

### 3. 💰 Finance & VAT

Handle Thai tax logic with precision.

```JavaScript
import { excludeVat, includeVat, bahtText } from '@kimmylps_dev/toolkitjs';

// Extract VAT from total
excludeVat(107); // { amount: 100, vat: 7, total: 107 }

// Convert number to Thai Baht text
bahtText(120.50); // "หนึ่งร้อยยี่สิบบาทห้าสิบสตางค์"
```

### 4. 🆔 Thai Validation

Ready-to-use validators for Thai-specific formats.

```JavaScript
import { validateThaiId, validateThaiPhone } from '@kimmylps_dev/toolkitjs';

validateThaiId('1100123456789'); // true/false (Check digit algorithm)
validateThaiPhone('021234567');   // true (Landline)
validateThaiPhone('0812345678');  // true (Mobile)
```

### 5.📍 Location & Geography

Helpers for Thai administrative regions based on the national 6-region standard.

```javascript
import {
  getRegionByProvince,
  getProvincesByRegion,
  getAllRegions,
} from "@kimmylps_dev/toolkitjs";

// 1. Get region from province name (Smart prefix handling)
getRegionByProvince("จ.เชียงใหม่"); // 'Northern'
getRegionByProvince("จังหวัดชลบุรี"); // 'Eastern'

// 2. Get all provinces in a specific region
getProvincesByRegion("Southern");
// ['กระบี่', 'ชุมพร', 'ตรัง', ...]

// 3. Get all regions for UI Dropdowns/Filters
getAllRegions();
// [{ id: 'Northern', name: 'ภาคเหนือ' }, { id: 'Central', name: 'ภาคกลาง' }, ...]
```

### 6. 📁 File Management

```javascript
import { getFileInfo, formatBytes, fileToBase64 } from "@kimmylps_dev/toolkitjs";

// 1. Get Comprehensive File Info (Path, URL, or Base64)
const info = getFileInfo("https://example.com/images/profile.jpg?v=1");
// { name: 'profile', extension: 'jpg', size: 0, sizeFormatted: '0 Bytes', ... }

// 2. Format Bytes to Human Readable String
formatBytes(1548576); // "1.48 MB"

// 3. Convert Local File or URL to Base64 (Async)
const base64 = await fileToBase64("./path/to/image.png");
// "data:image/png;base64,..."

const urlBase64 = await fileToBase64("https://example.com/logo.svg");
// "data:image/svg+xml;base64,..."
```

### 7. ⚖️ Inheritance (Fara'id)
Calculate Islamic inheritance with Asl al-Mas'alah and Tas'hih.

```javascript
const result = calculateFaraid({ wife: true, sons: 2 });
console.log(formatFaraidSummary(result));
```

## 🛠️ Technical Details

- **Environment**: Node.js 16+

- **Languages**: Written in TypeScript

- **Module Support**:
  - **ESM** (Modern):

    ```javascript
    import { excludeVat } from "@kimmylps_dev/toolkitjs";
    // or import everything
    import * as toolkitjs from "@kimmylps_dev/toolkitjs";
    ```

  - **CommonJS** (Legacy/Node default):
    ```javascript
    const { excludeVat } = require("@kimmylps_dev/toolkitjs");
    // or import everything
    const toolkitjs = require("@kimmylps_dev/toolkitjs");
    ```

- **Type Safety**: Full TypeScript definitions included.

## 🤝 Contributing

1. **Fork** the repository.

2. **Clone** your fork (`git clone ...`).

3. **Create** a new branch (`git checkout -b feature/AmazingFeature`).

4. **Commit** your changes (`git commit -m 'Add some feature'`).

5. **Push** to the branch (`git push origin feature/AmazingFeature`).

6. **Open** a Pull Request.

## 📄 License

This project is licensed under the **MIT License.**

## ✉️ Contact

- **GitHub**: [KimmyLps](https://github.com/KimmyLps)

- **Email**: kimmylps.dev@gmail.com

---

Developed with ❤️ by Thai developers for the developer community.