import { ValidationResult } from './types.cjs';

/**
 * Modul validasi NIK (Nomor Induk Kependudukan).
 *
 * Menyediakan fungsi {@link validateNIK} untuk mengecek apakah sebuah string
 * merupakan NIK yang valid secara format. Validasi dilakukan secara bertahap:
 * tipe data → panjang → isi digit → kode provinsi → tanggal lahir → nomor urut.
 *
 * Modul ini **tidak** memvalidasi apakah kode wilayah benar-benar terdaftar
 * di database Kemendagri — hanya format dan range yang dicek. Untuk resolve
 * nama wilayah dari kode, gunakan package `kode-wilayah-id`.
 *
 * @module validate
 *
 * @example
 * ```typescript
 * import { validateNIK } from 'nik-id/validate';
 *
 * const result = validateNIK("3204076508850001");
 * if (result.valid) {
 *   console.log("NIK valid!");
 * } else {
 *   console.log(result.error);
 * }
 * ```
 */

/**
 * Validasi format NIK (Nomor Induk Kependudukan).
 *
 * Melakukan pengecekan bertahap terhadap string NIK:
 *
 * 1. **Tipe data** — input harus berupa `string`
 * 2. **Panjang** — harus tepat 16 karakter
 * 3. **Format** — harus semua digit angka (0-9)
 * 4. **Kode provinsi** — 2 digit pertama harus dalam range 11-97
 * 5. **Tanggal lahir** — digit 7-12 harus membentuk tanggal yang valid
 *    (DD 01-31 untuk laki-laki, 41-71 untuk perempuan; MM 01-12; YY 00-99)
 * 6. **Nomor urut** — digit 13-16 tidak boleh `0000`
 *
 * Validasi berhenti di error pertama yang ditemukan (fail-fast).
 *
 * @param nik - String yang akan divalidasi sebagai NIK
 * @returns {@link ValidationResult} — `{ valid: true }` kalau valid,
 *          `{ valid: false, error: "..." }` kalau tidak
 *
 * @example
 * ```typescript
 * // NIK valid
 * validateNIK("3204076508850001");
 * // { valid: true }
 *
 * // Input bukan string
 * validateNIK(12345 as any);
 * // { valid: false, error: "NIK harus berupa string" }
 *
 * // Panjang salah
 * validateNIK("123");
 * // { valid: false, error: "NIK harus 16 digit" }
 *
 * // Mengandung huruf
 * validateNIK("320407650885000A");
 * // { valid: false, error: "NIK hanya boleh berisi angka" }
 *
 * // Kode provinsi di luar range
 * validateNIK("0004076508850001");
 * // { valid: false, error: "Kode provinsi tidak valid" }
 *
 * // Tanggal tidak ada di kalender
 * validateNIK("3204073102850001");  // 31 Februari
 * // { valid: false, error: "Tanggal lahir tidak valid" }
 *
 * // Nomor urut 0000
 * validateNIK("3204076508850000");
 * // { valid: false, error: "Nomor urut tidak valid" }
 * ```
 */
declare function validateNIK(nik: string): ValidationResult;

export { validateNIK };