🇮🇩 Indonesia NodeJS

📍 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

📋 Daftar Isi

✨ Fitur
📦 Instalasi
🚀 Penggunaan
📊 Struktur Data
🧪 Testing
⚡ Performance
🛠️ Development
🤝 Kontribusi
📄 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

# 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

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

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

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

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)

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

City (Kabupaten/Kota)

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)

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)

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

🧪 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

# 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

# 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

Cek existing issues terlebih dahulu
Buat issue baru dengan template bug report
Sertakan informasi detail dan langkah reproduksi

✨ Mengusulkan Fitur

Buat issue dengan label "feature request"
Jelaskan use case dan manfaat fitur
Diskusikan implementasi dengan maintainer

🔧 Pull Request

Fork repository
Buat branch untuk fitur/fix: git checkout -b feature/nama-fitur
Commit perubahan: git commit -m 'Add: fitur baru'
Push ke branch: git push origin feature/nama-fitur
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.

📌 Sumber Data

Wilayah
- Data wilayah Indonesia 2025 berasal dari Yonatan Yusak Lestari bisa lihat di repo ini 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 atau email ataupun buat issue di repo ini.
Kode Pos
- Kodepos.sql datanya dari w3appdev bisa lihat di repo ini, dengan sumber utama dari nomor.net.

🙏 Acknowledgments

Terinspirasi dari kebutuhan developer Indonesia
Terima kasih untuk semua contributors

📞 Support

📧 Email: d41113512@gmail.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

🇮🇩 Made with ❤️ for Indonesian Developers

Dibuat oleh M. Hamdani Ilham Latjoro

⭐ Jika project ini membantu, berikan star di GitHub! ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
data		data
dist		dist
scripts		scripts
src		src
test-project		test-project
types		types
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

dhank77/indonesia-nodejs

Folders and files

Latest commit

History

Repository files navigation