indokit/README.md

Utility TypeScript untuk format & validasi data Indonesia (Rupiah, NIK, phone, slug, dsb.)

# Apa itu Indokit?

Indokit adalah library TypeScript (Support JS) untuk format & validasi data Indonesia. Definisikan fungsi yang kamu butuhkan dan gunakan dengan mudah. Kamu akan mendapat hasil yang sudah divalidasi dan type-safe!
Ini baru rilis pertama jadi masih sangat sederhana belum sempurna. Namun, sudah cukup bagus untuk kebutuhan dasar.


```typescript
import { formatRupiah, terbilang, isValidNIK } from "indokit";

// format mata uang
formatRupiah(1500000); // "Rp 1.500.000,00"

// konversi angka ke kata-kata
terbilang(1500); // "seribu lima ratus"

// validasi NIK
isValidNIK("1234567890123456"); // true
```

## Fitur

- Zero external dependencies
- Kecil: bundle core hanya ~7kb (gzipped)
- TypeScript-first dengan full type definitions
- Interface yang sederhana
- 100% test coverage

## Instalasi

```bash
pnpm add indokit
npm install indokit
yarn add indokit
```

## Penggunaan Dasar

Sebelum menggunakan, kamu perlu import fungsi yang dibutuhkan:

```typescript
import {
  formatRupiah,
  terbilang,
  isValidNIK,
  isValidPhone,
  formatTanggalID,
  randomString,
} from "indokit";
```

### Format Rupiah

Gunakan `formatRupiah` untuk mengkonversi angka ke format mata uang Rupiah Indonesia.

```typescript
formatRupiah(1000); // "Rp 1.000,00"
formatRupiah(1500000); // "Rp 1.500.000,00"
formatRupiah(-500000); // "-Rp 500.000,00"
formatRupiah(1000.5); // "Rp 1.000,50"
```

### Terbilang (Angka ke Kata)

Fungsi `terbilang` mengkonversi angka menjadi kata-kata dalam bahasa Indonesia.

```typescript
terbilang(1500); // "seribu lima ratus"
terbilang(-500); // "minus lima ratus"
terbilang("1000"); // "seribu" (mendukung string)
terbilang("  123  "); // "seratus dua puluh tiga" (auto-trim)
```

### Handling Error

Ketika input tidak valid, fungsi `terbilang` akan throw `TypeError` dengan pesan yang jelas:

```typescript
try {
  terbilang("abc");
} catch (err) {
  console.log(err.message); // "terbilang: input tidak boleh berupa huruf"
}

try {
  terbilang(1.5);
} catch (err) {
  console.log(err.message); // "terbilang: input harus berupa bilangan bulat"
}
```

### Validasi NIK

Gunakan `isValidNIK` untuk memvalidasi format NIK:

```typescript
isValidNIK("1234567890123456"); // true
isValidNIK("123456789012345"); // false (kurang dari 16 digit)
isValidNIK("123456789012345a"); // false (mengandung huruf)
```

### Validasi Nomor HP

Fungsi `isValidPhone` mendukung berbagai format nomor HP Indonesia:

```typescript
isValidPhone("08123456789"); // true
isValidPhone("+628123456789"); // true
isValidPhone("628123456789"); // true
isValidPhone("07123456789"); // false (tidak dimulai dengan 8)
```

### Format Tanggal Indonesia

Konversi tanggal ke format bahasa Indonesia:

```typescript
formatTanggalID("2023-08-17"); // "17 Agustus 2023"
formatTanggalID(new Date("2023-12-25")); // "25 Desember 2023"
formatTanggalID(1692230400000); // "17 Agustus 2023"
```

### Random String

Generate string acak untuk berbagai keperluan:

```typescript
randomString(8); // "aB3xY9Zk"
randomString(16); // "mN8pQ2rS7tU4vW6x"
randomString(0); // ""
```

## Error Handling

Semua fungsi di Indokit memiliki error handling yang konsisten. Ketika terjadi error, kamu akan mendapat `TypeError` dengan pesan yang jelas:

```typescript
// Contoh berbagai error yang mungkin terjadi
terbilang(null); // TypeError: input tidak boleh null atau undefined
terbilang("123abc"); // TypeError: input tidak boleh mengandung campuran huruf dan angka
formatRupiah(NaN); // TypeError: formatRupiah: angka must be a number
randomString(-1); // TypeError: randomString: length must be a non-negative integer
```

## TypeScript Support

Indokit ditulis dalam TypeScript dan menyediakan type definitions yang lengkap:

```typescript
import { formatRupiah, terbilang } from "indokit";

// TypeScript akan otomatis mendeteksi tipe return
const rupiah: string = formatRupiah(1000);
const kata: string = terbilang(1500);

// Error akan muncul saat compile time jika tipe salah
formatRupiah("1000"); // ❌ TypeScript error
```

## License
MIT License - lihat file [LICENSE](LICENSE) untuk detail lengkap.

**Nashih Amin**
- GitHub: [@nashihamm](https://github.com/nashihamm)
- LinkedIn: [Nashih Amin](https://www.linkedin.com/in/nashihamm)
- Instagram: [@nashihamm](https://instagram.com/nashihamm)