🛠️ std-toolkitjs

A comprehensive, lightweight utility toolkit for modern backend developers.

🌟 Features

• 📍 Smart Thai Address Parser: Automatically extract and structure Thai addresses from raw strings.

  • 🌐 Multilingual Support: Supports both Thai and English (e.g., "Bangkok" or "กรุงเทพฯ").
  • 🛠️ Deep Parsing: Extracts House No, Moo, Soi, Road, Sub-district, District, Province, and Zipcode.
  • 🧠 Auto-Correction: Built-in Fuzzy Matching (Levenshtein) to fix typos in province names.
  • 📊 Confidence Scoring: Returns a confidence level (0.0 - 1.0) based on data accuracy.
  • 📂 Batch File Processing: Parse directly from an array of strings or specific object keys.

• ⚖️ Inheritance (Fara'id): Advanced Islamic inheritance calculation supporting Asl al-Mas'alah and Tas'hih (Integer correction).

• 📁 File Management: Unified metadata extraction from Local paths, URLs, or Base64, with built-in toBase64 conversion.

• 📍 Location Module: Thai administrative region helpers (6-region standard) with smart prefix handling (จังหวัด, จ.).

• 🐘 Eloquent-style Collection: Powerful array manipulation using SQL-like operators (whereOp, orderBy, groupBy, etc.).

• 📅 Thai Date: Localized Buddhist Era (พ.ศ.) formatting and diffForHumans relative time support.

• 💰 Finance & BahtText: Precise VAT calculations and official Thai Baht text conversion (e.g., "หนึ่งร้อยบาทถ้วน").

• 🆔 Validation: Robust validators for Thai National ID (Check-digit) and Phone numbers (Mobile/Landline).

• 📡 Response Helper: Standardized API response wrappers with built-in pagination logic.

• 📦 Dual Build: Native support for ES Modules (ESM) and CommonJS (CJS).

🚀 Installation

npm install std-toolkitjs

📖 Quick Start

📍 Smart Thai Address Parser

Address Parser

import { parseThaiAddress } from "std-toolkitjs";

// Support for Thai Language
const thAddress =
  "123/45 ม.6 ซ.สุขุมวิท 23 ต.คลองเตยเหนือ เขตวัฒนา กรงเทพ 10110";
const resultTH = parseThaiAddress(thAddress);

console.log(resultTH.province); // "กรุงเทพมหานคร" (Auto-corrected)
console.log(resultTH.isBangkok); // true
console.log(resultTH.confidence); // 1.0 (if matched with Master Data)

// Support for English Language
const enAddress = "99/1 Moo 2, Sam Sen Nai, Phaya Thai, Bangkok 10400";
const resultEN = parseThaiAddress(enAddress);

console.log(resultEN.district); // "Phaya Thai"
console.log(resultEN.zipcode); // "10400"

Batch File Processing

import { parseAddressesFromFile } from "std-toolkitjs";

// 1. Parse from JSON (Array of Strings)
// Supports: ["address 1", "address 2"]
const jsonList = parseAddressesFromFile("./data/customers.json");

// 2. Parse from JSON (Array of Objects)
// Supports: [{"raw_text": "address 1"}, {"raw_text": "address 2"}]
// Pass the key name as the second argument
const jsonObjects = parseAddressesFromFile("./data/orders.json", "raw_text");

// 3. Parse from SQL Dump
// Automatically extracts string values from INSERT INTO statements
const sqlData = parseAddressesFromFile("./backup/database.sql");

// 4. Parse from Plain Text or CSV
// Reads file line by line
const txtData = parseAddressesFromFile("./logs/shipping_labels.txt");

// Example: Filtering high-confidence results
const validAddresses = sqlData.filter((addr) => addr.confidence > 0.8);
console.log(`Successfully parsed ${validAddresses.length} addresses.`);

⚖️ 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));

📁 File Management

import { getFileInfo, formatBytes, fileToBase64 } from "std-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,..."

📍 Location & Geography

Helpers for Thai administrative regions based on the national 6-region standard.

import {
  getRegionByProvince,
  getProvincesByRegion,
  getAllRegions,
} from "std-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: 'ภาคกลาง' }, ...]

🐘 Eloquent-style Collection

Manage arrays with a fluent, SQL-like interface.

import { collect } from 'std-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();

📅 Date Management

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

import { toThaiDate, diffForHumans, calculateAge } from 'std-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

💰 Finance & VAT

Handle Thai tax logic with precision.

import { excludeVat, includeVat, bahtText } from 'std-toolkitjs';

// Extract VAT from total
excludeVat(107); // { amount: 100, vat: 7, total: 107 }

// Convert number to Thai Baht text
bahtText(120.50); // "หนึ่งร้อยยี่สิบบาทห้าสิบสตางค์"

🆔 Validation

Ready-to-use validators for Thai-specific formats.

import { validateThaiId, validateThaiPhone } from 'std-toolkitjs';

validateThaiId('1100123456789'); // true/false (Check digit algorithm)
validateThaiPhone('021234567');   // true (Landline)
validateThaiPhone('0812345678');  // true (Mobile)

🛠️ Technical Details

• Environment: Node.js 16+

• Languages: Written in TypeScript

• Module Support:

  • ESM (Modern):

    import { excludeVat } from "std-toolkitjs";
    // or import everything
    import * as toolkitjs from "std-toolkitjs";

  • CommonJS (Legacy/Node default):

    const { excludeVat } = require("std-toolkitjs");
    // or import everything
    const toolkitjs = require("std-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.