@damarkuncoro/posindonesia

Library TypeScript berperforma tinggi untuk mencari Kodepos Indonesia berdasarkan database statis internal. Mendukung pencarian fuzzy, pencarian terstruktur, dan pemuatan data yang sangat efisien (Lazy Loading).

Fitur Utama 🚀

• Hybrid Search: Pilih antara pencarian Local (offline & super cepat) atau Remote (real-time dari situs resmi).
• Offline-First: Tidak memerlukan koneksi internet untuk pencarian data lokal (~80.000+ data).
• Fuzzy Search: Cerdas menangani typo menggunakan Fuse.js (Mode Local).
• Inverted Index: Pencarian kata kunci instan dengan performa tinggi.
• Lazy Loading: Hanya memuat data provinsi yang dibutuhkan untuk menghemat RAM.
• Structured Search: Pencarian spesifik berdasarkan Provinsi, Kota, Kecamatan, atau Desa.
• CLI Tool: Cari kodepos langsung dari terminal.

Instalasi

npm install @damarkuncoro/posindonesia

Penggunaan (Library)

1. Pencarian Cepat (Rekomendasi)

Gunakan fungsi search global yang sudah dioptimalkan dengan cache internal.

import { search, searchByCode } from '@damarkuncoro/posindonesia';

// 🔍 Pencarian Lokal (Default, Offline, Super Cepat)
const localResults = await search(['Gambir', 'Jakarta Pusat']);

// 🌐 Pencarian Remote (Real-time dari situs Pos Indonesia)
const remoteResults = await search('Gambir', { source: 'remote' });

// 🧠 Pencarian Fuzzy (menangani typo: 'Gmbir' -> 'Gambir')
const fuzzy = await search('Gmbir', { useFuzzy: true });

// 📍 Pencarian Terstruktur (Structured)
const structured = await search({ 
  village: 'Gambir', 
  city: 'Jakarta Pusat' 
});

// ⚡ Pencarian Spesifik Provinsi (Nama atau Kode)
const byProvince = await search('Bandung', { province: 'Jawa Barat' });

// 🔢 Pencarian berdasarkan Kodepos (Instan/Indexed)
const byCode = await searchByCode('10110');

2. Penggunaan Advanced (Repository & Custom Data)

Untuk skenario yang lebih kompleks, seperti menggunakan sumber data Anda sendiri (misal: dari database), Anda dapat menyuntikkan DataProvider custom ke dalam TsPostalCodeRepository.

import { 
  TsPostalCodeRepository, 
  SearchPostalCode, 
  type DataProvider, 
  type PostalCodeData 
} from '@damarkuncoro/posindonesia';

// 1. Buat DataProvider Anda sendiri
class MyDbProvider implements DataProvider {
  async getAll(): Promise<PostalCodeData[]> {
    // Logika untuk mengambil data dari database Anda
    return []; 
  }
  async getByProvince(provinceCode: string): Promise<PostalCodeData[]> {
    // Logika untuk mengambil data provinsi tertentu dari DB
    return [];
  }
}

// 2. Suntikkan ke Repository
const myProvider = new MyDbProvider();
const repo = new TsPostalCodeRepository({ dataProvider: myProvider });

const searchUseCase = new SearchPostalCode(repo);
const results = await searchUseCase.execute(['Bandung']);

Penggunaan (CLI)

Anda dapat menggunakan library ini langsung dari terminal tanpa menulis kode.

# Setelah package di-publish ke npm:
npx @damarkuncoro/posindonesia search "Jakarta Pusat"

# Atau dengan cara lain:
npx posindonesia search "Jakarta Pusat"

Pengembangan (CLI Lokal)

Untuk pengembangan lokal atau sebelum package di-publish ke npm:

# Build terlebih dahulu
npm run build

# Cara 1: Langsung jalankan binary hasil build
node lib/esm/cli.js search "Jakarta Pusat" --remote

# Cara 2: Menggunakan tsx (tanpa build)
npx tsx src/cli.ts search "Jakarta Pusat" --remote

Contoh Penggunaan CLI

# Mencari berdasarkan kata kunci (Mode Lokal)
npx tsx src/cli.ts search "Gambir Jakarta"

# Mencari secara real-time dari situs resmi
npx tsx src/cli.ts search "Gambir" --remote

# Mencari dengan filter provinsi dan mode fuzzy
npx tsx src/cli.ts search "Gmbir" -p 31 --fuzzy

# Mencari berdasarkan kode postal
npx tsx src/cli.ts code 10110 --remote

Skema Data

Setiap hasil pencarian mengembalikan array objek PostalCode dengan struktur:

{
  province: string;       // Nama Provinsi
  provinceCode: string;   // Kode Kemendagri Provinsi
  city: string;           // Nama Kabupaten/Kota
  cityCode: string;       // Kode Kemendagri Kabupaten/Kota
  district: string;       // Nama Kecamatan
  districtCode: string;   // Kode Kemendagri Kecamatan
  village: string;        // Nama Desa/Kelurahan
  villageCode: string;    // Kode Kemendagri Desa/Kelurahan
  postalCode: string;     // Kodepos (5 digit)
}

Pengembangan

npm install
npm test            # Menjalankan unit tests
npm run lint        # Memeriksa standar kode
npm run build       # Build library (ESM & CJS)

Lisensi

MIT