🛠️ @kimmylps_dev/toolkitjs

A comprehensive, lightweight utility toolkit for modern backend developers.

🌟 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 for full details on every release.

🚀 Installation

npm install @kimmylps_dev/toolkitjs

📖 Quick Start

1. 📅 Date Management (in v1.1.0+)

Effortlessly handle Buddhist Era (พ.ศ.) and human-readable relative time.

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.

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.

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.

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.

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

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.

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):

    import { excludeVat } from "@kimmylps_dev/toolkitjs";
    // or import everything
    import * as toolkitjs from "@kimmylps_dev/toolkitjs";

  • CommonJS (Legacy/Node default):

    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

• Email: [email protected]

Developed with ❤️ by Thai developers for the developer community.