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

/**
 * Modul generator NIK (Nomor Induk Kependudukan).
 *
 * Menyediakan fungsi {@link generateNIK} untuk membuat NIK yang valid
 * secara format, baik full random maupun dengan parameter tertentu
 * (wilayah, gender, tanggal lahir).
 *
 * NIK yang dihasilkan valid secara **format** — semua aturan digit terpenuhi —
 * tapi **bukan** NIK asli milik orang sungguhan. Cocok untuk testing,
 * seeding database, atau demo.
 *
 * @module generate
 *
 * @example
 * ```typescript
 * import { generateNIK } from 'nik-id/generate';
 *
 * // Full random
 * const nik1 = generateNIK();
 *
 * // Perempuan lahir 25 Agustus 1985
 * const nik2 = generateNIK({ gender: "F", birthDate: new Date("1985-08-25") });
 *
 * // Wilayah spesifik
 * const nik3 = generateNIK({
 *   provinceCode: "32",
 *   regencyCode: "3204",
 *   districtCode: "320407",
 * });
 * ```
 */

/**
 * Generate NIK (Nomor Induk Kependudukan) yang valid secara format.
 *
 * Semua parameter opsional — yang tidak diisi akan di-random.
 * NIK yang dihasilkan memenuhi semua aturan format:
 * - Kode provinsi dalam range 11-97
 * - Tanggal lahir valid secara kalender
 * - Gender tercermin di encoding DD (perempuan: DD + 40)
 * - Sequence number dalam range 0001-9999
 *
 * **Catatan:** NIK ini bukan data asli — hanya valid secara format,
 * cocok untuk testing dan demo.
 *
 * @param options - Opsi untuk men-generate NIK (semua opsional)
 * @returns String NIK 16 digit yang valid secara format
 * @throws {Error} Jika `provinceCode` di luar range 11-97
 * @throws {Error} Jika `regencyCode` tidak diawali `provinceCode`
 * @throws {Error} Jika `districtCode` tidak diawali `regencyCode`
 *
 * @example
 * ```typescript
 * // Full random
 * generateNIK();
 * // "3204071508900123"
 *
 * // Gender spesifik
 * generateNIK({ gender: "F" });
 * // "xxxxxx5508900456" (DD + 40 untuk perempuan)
 *
 * // Tanggal lahir spesifik
 * generateNIK({ birthDate: new Date("1985-08-25") });
 * // "xxxxxx2508850789"
 *
 * // Gender dan tanggal lahir
 * generateNIK({ gender: "F", birthDate: new Date("1985-08-25") });
 * // "xxxxxx6508850234" (25 + 40 = 65 untuk perempuan)
 *
 * // Wilayah lengkap
 * generateNIK({
 *   provinceCode: "32",
 *   regencyCode: "3204",
 *   districtCode: "320407",
 * });
 * // "3204071508900001"
 * ```
 */
declare function generateNIK(options?: GenerateOptions): string;

export { generateNIK };