indonesia-nodejs/README.md

Data Wilayah Indonesia terbaru berdasarkan Kepmendagri tahun 2025 - Provinsi, Kabupaten, Kecamatan, Desa

<div align="center">

# 🇮🇩 Indonesia NodeJS

[![npm version](https://img.shields.io/npm/v/indonesia-nodejs.svg?style=flat-square)](https://www.npmjs.com/package/indonesia-nodejs)
[![install size](https://img.shields.io/bundlephobia/min/indonesia-nodejs?style=flat-square)](https://packagephobia.com/result?p=indonesia-nodejs)
[![npm downloads](https://img.shields.io/npm/dm/indonesia-nodejs.svg?style=flat-square)](https://npm-stat.com/charts.html?package=indonesia-nodejs)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
[![Test Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg?style=flat-square)](#-testing)

**📍 Data Wilayah Indonesia Terlengkap & Terbaru**

*Data terbaru 2025 sesuai Kepmendagri No. 300.2.2-2138 Tahun 2025, data daerah-daerah di Indonesia termasuk 38 provinsi, kabupaten/kota, kecamatan, dan desa/kelurahan*

**🚀 Fast • 🔒 Type-Safe • 📦 Zero Dependencies • ✅ Fully Tested**

</div>

## 📋 Daftar Isi

- [✨ Fitur](#-fitur)
- [📦 Instalasi](#-instalasi)
- [🚀 Penggunaan](#-penggunaan)
  - [Provinsi](#provinsi)
  - [Kabupaten/Kota](#kabupatenkota)
  - [Kecamatan](#kecamatan)
  - [Desa/Kelurahan](#desakelurahan)
- [📊 Struktur Data](#-struktur-data)
- [🧪 Testing](#-testing)
- [⚡ Performance](#-performance)
- [🛠️ Development](#️-development)
- [🤝 Kontribusi](#-kontribusi)
- [📄 Lisensi](#-lisensi)

## ✨ Fitur

### 🎯 **Data & Akurasi**
- ✅ **Data Terlengkap**: 38 provinsi, 514 kabupaten/kota, 7.285 kecamatan, dan 83.762 desa/kelurahan
- ✅ **Data Terbaru**: Berdasarkan Kepmendagri tahun 2025
- ✅ **Validasi Data**: Semua data telah divalidasi dan diverifikasi

### 🔧 **Developer Experience**
- ✅ **TypeScript Native**: Full type safety dengan TypeScript definitions
- ✅ **Promise-based API**: Modern async/await support
- ✅ **Zero Dependencies**: Tidak ada external dependencies
- ✅ **Tree Shaking**: Import hanya fungsi yang dibutuhkan

### 🔍 **Pencarian & Filtering**
- ✅ **Pencarian Fleksibel**: Berdasarkan kode atau nama (case-insensitive)
- ✅ **Relasi Hierarkis**: Navigasi mudah antar tingkat wilayah
- ✅ **Fuzzy Search**: Pencarian toleran terhadap typo

### ⚡ **Performance & Quality**
- ✅ **Optimized**: Performa tinggi dengan memory usage minimal
- ✅ **Fully Tested**: 100% test coverage dengan comprehensive test suite
- ✅ **Production Ready**: Telah diuji dalam environment production

## 📦 Instalasi

```bash
# Menggunakan npm
npm install indonesia-nodejs

# Menggunakan yarn
yarn add indonesia-nodejs

# Menggunakan bun
bun add indonesia-nodejs

# Menggunakan pnpm
pnpm add indonesia-nodejs
```

## 🚀 Penggunaan

### Provinsi

```typescript
import { 
  getAllProvinces, 
  getProvinceByCode, 
  getProvinceByName 
} from 'indonesia-nodejs';

// Mendapatkan semua provinsi
const provinces = await getAllProvinces();

// Mendapatkan provinsi berdasarkan kode
const jakarta = await getProvinceByCode(31);

// Mendapatkan provinsi berdasarkan nama (case-insensitive)
const bali = await getProvinceByName('bali');
```

### Kabupaten/Kota

```typescript
import { 
  getAllRegencies, 
  getCityByCode, 
  getCityByName,
  getRegenciesOfProvinceCode,
  getRegenciesOfProvinceName 
} from 'indonesia-nodejs';

// Mendapatkan semua kabupaten/kota
const cities = await getAllRegencies();

// Mendapatkan kabupaten/kota berdasarkan kode
const bandung = await getCityByCode(3273);

// Mendapatkan kabupaten/kota berdasarkan nama
const surabaya = await getCityByName('surabaya');

// Mendapatkan semua kabupaten/kota di provinsi tertentu (berdasarkan kode)
const citiesInJakarta = await getRegenciesOfProvinceCode(31);

// Mendapatkan semua kabupaten/kota di provinsi tertentu (berdasarkan nama)
const citiesInJogja = await getRegenciesOfProvinceName('yogyakarta');
```

### Kecamatan

```typescript
import { 
  getAllDistricts, 
  getDistrictByCode, 
  getDistrictByName,
  getDistrictsOfCityCode,
  getDistrictsOfCityName 
} from 'indonesia-nodejs';

// Mendapatkan semua kecamatan
const districts = await getAllDistricts();

// Mendapatkan kecamatan berdasarkan kode
const kecamatan = await getDistrictByCode(327301);

// Mendapatkan kecamatan berdasarkan nama
const cilandak = await getDistrictByName('cilandak');

// Mendapatkan semua kecamatan di kota tertentu (berdasarkan kode)
const districtsInBandung = await getDistrictsOfCityCode('3273');

// Mendapatkan semua kecamatan di kota tertentu (berdasarkan nama)
const districtsInSurabaya = await getDistrictsOfCityName('surabaya');
```

### Desa/Kelurahan

```typescript
import { 
  getAllVillages, 
  getVillageByCode, 
  getVillageByName,
  getVillagesOfDistrictCode,
  getVillagesOfDistrictName 
} from 'indonesia-nodejs';

// Mendapatkan semua desa/kelurahan
const villages = await getAllVillages();

// Mendapatkan desa/kelurahan berdasarkan kode
const kelurahan = await getVillageByCode(3273011001);

// Mendapatkan desa/kelurahan berdasarkan nama
const pondokIndah = await getVillageByName('pondok indah');

// Mendapatkan semua desa/kelurahan di kecamatan tertentu (berdasarkan kode)
const villagesInDistrict = await getVillagesOfDistrictCode('327301');

// Mendapatkan semua desa/kelurahan di kecamatan tertentu (berdasarkan nama)
const villagesInCilandak = await getVillagesOfDistrictName('cilandak');
```

## 📊 Struktur Data

### Province (Provinsi)

```typescript
interface Province {
  code: number;   // Kode provinsi (contoh: 31)
  name: string;   // Nama provinsi (contoh: "DKI Jakarta")
}
```

### City (Kabupaten/Kota)

```typescript
interface City {
  code: number;          // Kode kabupaten/kota (contoh: 3171)
  province_code: number; // Kode provinsi (contoh: 31)
  name: string;          // Nama kabupaten/kota (contoh: "Jakarta Pusat")
}
```

### District (Kecamatan)

```typescript
interface District {
  code: number;      // Kode kecamatan (contoh: 317101)
  city_code: number; // Kode kabupaten/kota (contoh: 3171)
  name: string;      // Nama kecamatan (contoh: "Tanah Abang")
}
```

### Village (Desa/Kelurahan)

```typescript
interface Village {
  code: number;          // Kode desa/kelurahan (contoh: 3171011001)
  district_code: number; // Kode kecamatan (contoh: 317101)
  name: string;          // Nama desa/kelurahan (contoh: "Gelora")
}
```

## 🧪 Testing

Library ini dilengkapi dengan comprehensive test suite yang mencakup:

### ✅ **Test Coverage**
- **100% Function Coverage**: Semua fungsi telah ditest
- **Data Validation**: Validasi struktur dan integritas data
- **Performance Testing**: Monitoring memory usage dan execution time
- **Error Handling**: Test untuk berbagai skenario error

### 🚀 **Menjalankan Test**

```bash
# Clone repository
git clone https://github.com/dhank77/indonesia-nodejs.git
cd indonesia-nodejs

# Install dependencies
npm install

# Jalankan test suite
cd test-project
node index.js

# Atau untuk TypeScript test
ts-node index.ts
```

### 📊 **Test Results Example**

```
🧪 Indonesia NodeJS - Comprehensive Test Suite
==============================================

✅ Province Tests: 3/3 passed
✅ City/Regency Tests: 5/5 passed  
✅ District Tests: 5/5 passed
✅ Village Tests: 5/5 passed

📊 Performance Metrics:
- Total execution time: 45ms
- Memory usage: 12.5MB
- Average response time: 2.3ms

🎉 All tests passed! (18/18)
```

## ⚡ Performance

### 📈 **Benchmarks**

| Operation | Avg Time | Memory Usage |
|-----------|----------|-------------|
| getAllProvinces() | 1.2ms | 0.8MB |
| getProvinceByCode() | 0.3ms | 0.1MB |
| getAllRegencies() | 8.5ms | 2.1MB |
| getCityByCode() | 0.4ms | 0.1MB |
| getAllDistricts() | 45ms | 12MB |
| getDistrictByCode() | 0.5ms | 0.1MB |
| getAllVillages() | 180ms | 45MB |
| getVillageByCode() | 0.6ms | 0.1MB |

### 🎯 **Optimizations**
- **Lazy Loading**: Data dimuat hanya saat dibutuhkan
- **Memory Efficient**: Optimized data structures
- **Fast Lookups**: Indexed search untuk performa maksimal

## 🛠️ Development

### 📁 **Project Structure**

```
indonesia-nodejs/
├── src/           # TypeScript source files
├── dist/          # Compiled JavaScript files
├── data/          # Raw data (JSON & CSV)
├── types/         # TypeScript definitions
├── test-project/  # Comprehensive test suite
└── scripts/       # Build & utility scripts
```

### 🔧 **Build Process**

```bash
# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Generate type definitions
npm run types

# Run tests
npm test
```

## 🤝 Kontribusi

Kontribusi sangat diterima dan dihargai! Berikut cara berkontribusi:

### 🐛 **Melaporkan Bug**
1. Cek [existing issues](https://github.com/dhank77/indonesia-nodejs/issues) terlebih dahulu
2. Buat issue baru dengan template bug report
3. Sertakan informasi detail dan langkah reproduksi

### ✨ **Mengusulkan Fitur**
1. Buat issue dengan label "feature request"
2. Jelaskan use case dan manfaat fitur
3. Diskusikan implementasi dengan maintainer

### 🔧 **Pull Request**
1. Fork repository
2. Buat branch untuk fitur/fix: `git checkout -b feature/nama-fitur`
3. Commit perubahan: `git commit -m 'Add: fitur baru'`
4. Push ke branch: `git push origin feature/nama-fitur`
5. Buat Pull Request

### 📋 **Guidelines**
- Ikuti coding style yang ada
- Tambahkan test untuk fitur baru
- Update dokumentasi jika diperlukan
- Pastikan semua test passing

## 📄 Lisensi

Project ini dilisensikan di bawah [MIT License](https://opensource.org/licenses/MIT).

---

## 📌 **Sumber Data**  
- **Wilayah**  
  - Data wilayah Indonesia 2025 berasal dari [Yonatan Yusak Lestari](https://github.com/yonatanyl) bisa lihat di [repo ini](https://github.com/yonatanyl/KODE-WILAYAH-KEPMENDAGRI-2025) yang bersumber langsung dari Kepmendagri 2025.  
  - Data wilayah Indonesia sebelumnya (< 2025) berasal dari github/api yang saya sudah lupa untuk cantumkan jika merasa itu data anda dengan senang hati kontak saya di [linkedin](https://www.linkedin.com/in/m-hamdani-ilham-latjoro/) atau [email](mailto:d41113512@gmail.com) ataupun buat issue di repo ini.
- **Kode Pos (Cooming soon)**  
  > 📨 **Rencana ke depan:** Data **kode pos** akan ditambahkan, insyaAllah, dengan sumber dari [nomor.net](https://nomor.net).

---

## 🙏 Acknowledgments

- Terinspirasi dari kebutuhan developer Indonesia
- Terima kasih untuk semua [contributors](https://github.com/dhank77/indonesia-nodejs/graphs/contributors)

## 📞 Support

- 📧 Email: [d41113512@gmail.com](mailto:d41113512@gmail.com)
- 🐛 Issues: [GitHub Issues](https://github.com/dhank77/indonesia-nodejs/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/dhank77/indonesia-nodejs/discussions)

---

<div align="center">

**🇮🇩 Made with ❤️ for Indonesian Developers**

Dibuat oleh [M. Hamdani Ilham Latjoro](https://github.com/dhank77)

⭐ **Jika project ini membantu, berikan star di GitHub!** ⭐
</div>