npm package: @promporn/shared-utils
Description: Lightweight utility library used across internal and external projects
Latest version: 1.2.1

# shared-utils

A lightweight, reusable utility library for internal and external projects.

## Install

## Utils Documentation

### General Utilities

#### `capitalize(str: string): string`
**วัตถุประสงค์:** แปลงตัวอักษรตัวแรกของสตริงให้เป็นตัวพิมพ์ใหญ่

**พารามิเตอร์:**
- `str` (string) - สตริงที่ต้องการแปลง

**ค่าที่ส่งกลับ:** สตริงที่มีตัวอักษรตัวแรกเป็นตัวพิมพ์ใหญ่

**ตัวอย่าง:**
```typescript
capitalize("hello") // "Hello"
capitalize("world") // "World"
capitalize("")      // ""
```

---

#### `classNames(...args: any[]): string`
**วัตถุประสงค์:** รวมชื่อคลาส CSS เข้าด้วยกันแบบมีเงื่อนไข สนับสนุนสตริง อาร์เรย์ และอ็อบเจ็กต์

**พารามิเตอร์:**
- `...args` - สตริง อาร์เรย์ หรืออ็อบเจ็กต์ที่ต้องการรวม

**ค่าที่ส่งกลับ:** สตริงของชื่อคลาส CSS ที่คั่นด้วยช่องว่าง

**ตัวอย่าง:**
```typescript
classNames("btn", "btn-primary")                           // "btn btn-primary"
classNames("btn", { "btn-active": true, "btn-disabled": false })  // "btn btn-active"
classNames(["p-2", "m-1"], "text-center")                 // "p-2 m-1 text-center"
classNames("active", null, undefined, false)              // "active"
```

---

#### `split(value: any, separator?: string | RegExp, limit?: number): string[]`
**วัตถุประสงค์:** แบ่งสตริงเป็นอาร์เรย์โดยใช้ตัวคั่น สนับสนุนการจัดการค่า null/undefined

**พารามิเตอร์:**
- `value` - ค่าที่ต้องการแบ่ง (จะถูกแปลงเป็นสตริง)
- `separator?` (string | RegExp) - ตัวคั่น (ถ้าไม่ระบุ จะส่งคืนสตริงทั้งหมดในอาร์เรย์)
- `limit?` (number) - จำนวนการแบ่งสูงสุด

**ค่าที่ส่งกลับ:** อาร์เรย์ของสตริง

**ตัวอย่าง:**
```typescript
split("a,b,c", ",")         // ["a", "b", "c"]
split("hello world", " ")   // ["hello", "world"]
split(123, ",")             // ["123"]
split(null)                 // [""]
split("a-b-c", "-", 2)      // ["a", "b"]
```

---

#### `unescape(str: string): string`
**วัตถุประสงค์:** แปลง HTML entities ให้เป็นตัวอักษรปกติ

**พารามิเตอร์:**
- `str` (string) - สตริง HTML ที่มี entities

**ค่าที่ส่งกลับ:** สตริงที่ถูกแปลงจาก HTML entities

**รองรับ HTML Entities:**
- `&amp;` → `&`
- `&lt;` → `<`
- `&gt;` → `>`
- `&quot;` → `"`
- `&#39;` → `'`

**ตัวอย่าง:**
```typescript
unescape("&lt;div&gt;")                    // "<div>"
unescape("&quot;Hello&quot;")              // ""Hello""
unescape("Tom &amp; Jerry")                // "Tom & Jerry"
unescape("I&#39;m learning")              // "I'm learning"
```

---

### String Utilities

#### `camelCase(value: string): string`
**วัตถุประสงค์:** แปลงสตริงเป็นรูปแบบ camelCase (ตัวอักษรแรกเป็นตัวพิมพ์เล็ก)

**พารามิเตอร์:**
- `value` (string) - สตริงต้นทาง

**ค่าที่ส่งกลับ:** สตริงในรูปแบบ camelCase

**ตัวอย่าง:**
```typescript
camelCase("hello_world")        // "helloWorld"
camelCase("hello-world")        // "helloWorld"
camelCase("hello world")        // "helloWorld"
camelCase("HelloWorld")         // "helloWorld"
camelCase("HELLO_WORLD")        // "helloWorld"
```

---

#### `kebabCase(value: string): string`
**วัตถุประสงค์:** แปลงสตริงเป็นรูปแบบ kebab-case (คั่นด้วยขีด)

**พารามิเตอร์:**
- `value` (string) - สตริงต้นทาง

**ค่าที่ส่งกลับ:** สตริงในรูปแบบ kebab-case

**ตัวอย่าง:**
```typescript
kebabCase("helloWorld")         // "hello-world"
kebabCase("hello_world")        // "hello-world"
kebabCase("hello world")        // "hello-world"
kebabCase("HelloWorld")         // "hello-world"
```

---

#### `toString(value: any): string`
**วัตถุประสงค์:** แปลงค่าใดๆ ให้เป็นสตริง พร้อมจัดการพิเศษสำหรับอาร์เรย์

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการแปลง

**ค่าที่ส่งกลับ:** สตริง

**ตัวอย่าง:**
```typescript
toString(123)                   // "123"
toString(true)                  // "true"
toString([1, 2, 3])             // "1,2,3"
toString(null)                  // ""
toString(undefined)             // ""
toString({ name: "John" })      // "[object Object]"
```

---

#### `trim(value: any): string`
**วัตถุประสงค์:** ลบช่องว่างจากทั้งสองด้านของสตริง

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตัด (จะถูกแปลงเป็นสตริง)

**ค่าที่ส่งกลับ:** สตริงที่ลบช่องว่างแล้ว

**ตัวอย่าง:**
```typescript
trim("  hello  ")                // "hello"
trim("  world")                  // "world"
trim("test  ")                   // "test"
trim(123)                         // "123"
```

---

#### `trimStart(value: any): string`
**วัตถุประสงค์:** ลบช่องว่างจากด้านเริ่มต้น (ซ้าย) ของสตริง

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตัด (จะถูกแปลงเป็นสตริง)

**ค่าที่ส่งกลับ:** สตริงที่ลบช่องว่างจากด้านเริ่มต้นแล้ว

**ตัวอย่าง:**
```typescript
trimStart("  hello world  ")     // "hello world  "
trimStart("   test")             // "test"
trimStart("no spaces")           // "no spaces"
```

---

#### `trimEnd(value: any): string`
**วัตถุประสงค์:** ลบช่องว่างจากด้านสิ้นสุด (ขวา) ของสตริง

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตัด (จะถูกแปลงเป็นสตริง)

**ค่าที่ส่งกลับ:** สตริงที่ลบช่องว่างจากด้านสิ้นสุดแล้ว

**ตัวอย่าง:**
```typescript
trimEnd("  hello world  ")       // "  hello world"
trimEnd("test   ")              // "test"
trimEnd("no spaces")            // "no spaces"
```

---

#### `upperCase(value: string): string`
**วัตถุประสงค์:** แปลงสตริงเป็นตัวอักษรพิมพ์ใหญ่ โดยแทนที่ขีดเส้นและเครื่องหมายขีดเล็บด้วยช่องว่าง

**พารามิเตอร์:**
- `value` (string) - สตริงต้นทาง

**ค่าที่ส่งกลับ:** สตริงที่ประกอบด้วยตัวอักษรพิมพ์ใหญ่

**ตัวอย่าง:**
```typescript
upperCase("helloWorld")         // "HELLO WORLD"
upperCase("hello_world")        // "HELLO WORLD"
upperCase("hello-world")        // "HELLO WORLD"
```

---

### Type Checking Utilities

#### `isArray(value: any): value is any[]`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นอาร์เรย์หรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็นอาร์เรย์ `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isArray([1, 2, 3])              // true
isArray("hello")                // false
isArray({ length: 1 })          // false
```

---

#### `isBoolean(value: any): value is boolean`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นค่าบูลีน (`true` หรือ `false`) หรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็นบูลีน `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isBoolean(true)                 // true
isBoolean(false)                // true
isBoolean(1)                    // false
isBoolean("true")               // false
```

---

#### `isDate(value: any): value is Date`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นวัตถุ Date ที่ถูกต้องหรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็น Date ที่ถูกต้อง `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isDate(new Date())              // true
isDate(new Date("invalid"))     // false
isDate("2024-01-01")            // false
isDate(12345)                   // false
```

---

#### `isEmpty(value: any): boolean`
**วัตถุประสงค์:** ตรวจสอบว่าค่าว่างเปล่าหรือไม่ (รองรับ null, undefined, สตริง, อาร์เรย์, และอ็อบเจ็กต์)

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าว่างเปล่า `false` ถ้าไม่ว่างเปล่า

**ตัวอย่าง:**
```typescript
isEmpty(null)                   // true
isEmpty(undefined)              // true
isEmpty("")                     // true
isEmpty([])                     // true
isEmpty({})                     // true
isEmpty("hello")                // false
isEmpty([1, 2, 3])              // false
isEmpty({ name: "John" })       // false
```

---

#### `isFunction(value: any): value is Function`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นฟังก์ชันหรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็นฟังก์ชัน `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isFunction(() => {})            // true
isFunction(function() {})       // true
isFunction(Math.max)            // true
isFunction("hello")             // false
isFunction(123)                 // false
```

---

#### `isNil(value: any): value is null | undefined`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็น `null` หรือ `undefined` หรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็น null หรือ undefined `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isNil(null)                     // true
isNil(undefined)                // true
isNil(0)                        // false
isNil("")                       // false
isNil(false)                    // false
```

---

#### `isNumber(value: any): value is number`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นตัวเลขที่ถูกต้องหรือไม่ (ไม่รวม NaN)

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็นตัวเลขที่ถูกต้อง `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isNumber(123)                   // true
isNumber(45.67)                 // true
isNumber(NaN)                   // false
isNumber("123")                 // false
isNumber(Infinity)              // true
```

---

#### `isObject(value: any): value is object`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นอ็อบเจ็กต์หรือไม่ (ไม่รวม null แต่รวมอาร์เรย์)

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็นอ็อบเจ็กต์ `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isObject({})                    // true
isObject({ name: "John" })      // true
isObject([1, 2, 3])             // true
isObject(new Date())            // true
isObject(null)                  // false
isObject("hello")               // false
```

---

#### `isPlainObject(value: any): value is Record<string, any>`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นอ็อบเจ็กต์ธรรมดา (plain object) หรือไม่ (ไม่รวม Date, Array, regex เป็นต้น)

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็น plain object `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isPlainObject({})               // true
isPlainObject({ name: "John" }) // true
isPlainObject(new Date())       // false
isPlainObject([1, 2, 3])        // false
isPlainObject("hello")          // false
```

---

#### `isRegExp(value: any): value is RegExp`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นนิพจน์ทั่วไป (RegExp) หรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็น RegExp `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isRegExp(/hello/)               // true
isRegExp(new RegExp("test"))    // true
isRegExp("/hello/")             // false
isRegExp("hello")               // false
```

---

#### `isString(value: any): value is string`
**วัตถุประสงค์:** ตรวจสอบว่าค่าเป็นสตริงหรือไม่

**พารามิเตอร์:**
- `value` (any) - ค่าที่ต้องการตรวจสอบ

**ค่าที่ส่งกลับ:** `true` ถ้าเป็นสตริง `false` ถ้าไม่ใช่

**ตัวอย่าง:**
```typescript
isString("hello")               // true
isString("")                    // true
isString(123)                   // false
isString(new String("hello"))   // true
```

---

## Usage Example

```typescript
import {
  capitalize,
  classNames,
  camelCase,
  kebabCase,
  isString,
  isEmpty,
  trim,
} from "@shared/utils";

// String operations
const name = capitalize("john");           // "John"
const className = classNames("btn", { "btn-active": true }); // "btn btn-active"

// Case conversions
const camelCased = camelCase("hello-world");  // "helloWorld"
const kebabCased = kebabCase("helloWorld");   // "hello-world"

// Type checking
if (isString(value)) {
  const trimmed = trim(value);
}

// Validation
if (!isEmpty(data)) {
  processData(data);
}
```