nik-id 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sumitro Aji Prabowo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,492 @@
+# nik-id
+
+[![npm version](https://img.shields.io/npm/v/nik-id.svg)](https://www.npmjs.com/package/nik-id)
+[![CI](https://github.com/sumitroajiprabowo/nik-id/actions/workflows/ci.yml/badge.svg)](https://github.com/sumitroajiprabowo/nik-id/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/nik-id)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://www.npmjs.com/package/nik-id)
+
+Parser, validator, dan generator **NIK** (Nomor Induk Kependudukan) Indonesia.
+
+TypeScript-first, zero dependencies, 100% test coverage, dual ESM+CJS, tree-shakeable.
+
+```bash
+npm install nik-id
+```
+
+Tidak perlu database, API call, atau file eksternal. Cukup install dan langsung pakai.
+
+## Fitur
+
+- **Validasi format** -- cek apakah NIK valid (panjang, digit, provinsi, tanggal lahir, nomor urut)
+- **Parse komponen** -- ekstrak kode wilayah, tanggal lahir, gender, dan nomor urut dari NIK
+- **Generate NIK** -- buat NIK yang valid secara format untuk testing, seeding, atau demo
+- **Discriminated union** -- return type aman di-narrow pakai `result.valid` (TypeScript-friendly)
+- **Error bahasa Indonesia** -- semua pesan error dalam bahasa Indonesia
+- **Tree-shakeable** -- import hanya fungsi yang dibutuhkan via sub-path
+- **TypeScript-first** -- strict types, auto-complete di IDE
+- **Dual ESM + CJS** -- support semua environment (browser, Node.js, Bun, Deno)
+- **Zero dependencies** -- tidak ada dependency runtime sama sekali
+- **100% coverage** -- statements, branches, functions, lines
+
+## Struktur NIK
+
+NIK (Nomor Induk Kependudukan) adalah nomor identitas penduduk Indonesia yang terdiri dari **16 digit angka**:
+
+```
+3204 07 650885 0001
+│    │  │      └── Nomor urut registrasi (4 digit, 0001-9999)
+│    │  └── Tanggal lahir DDMMYY — perempuan: DD + 40 (jadi 41-71)
+│    └── Kode kecamatan (2 digit, format Kemendagri)
+└── Kode kabupaten/kota (4 digit, format Kemendagri)
+```
+
+| Posisi | Digit | Keterangan | Contoh |
+|--------|-------|------------|--------|
+| 1-2 | 2 digit | Kode provinsi Kemendagri (11-97) | `32` = Jawa Barat |
+| 3-4 | 2 digit | Kode kabupaten/kota | `04` = Kab. Bandung |
+| 5-6 | 2 digit | Kode kecamatan | `07` = Nagreg |
+| 7-8 | 2 digit | Tanggal lahir (DD), perempuan +40 | `65` = tanggal 25 (perempuan) |
+| 9-10 | 2 digit | Bulan lahir (MM) | `08` = Agustus |
+| 11-12 | 2 digit | Tahun lahir (YY) | `85` = 1985 |
+| 13-16 | 4 digit | Nomor urut registrasi | `0001` |
+
+**Catatan penting:**
+- NIK menggunakan kode **Kemendagri** (Kementerian Dalam Negeri), bukan BPS
+- Perempuan: tanggal lahir ditambah 40 (DD 01-31 → DD 41-71)
+- Tahun 2 digit: disambiguasi berdasarkan tahun sekarang (YY > sekarang → 1900+YY, else 2000+YY)
+
+## Quick Start
+
+```typescript
+import { validateNIK, parseNIK, generateNIK } from 'nik-id';
+
+// Validasi — cek apakah NIK valid
+const valid = validateNIK("3204076508850001");
+console.log(valid); // { valid: true }
+
+// Parse — ekstrak semua komponen
+const parsed = parseNIK("3204076508850001");
+if (parsed.valid) {
+  console.log(parsed.provinceCode);    // "32"
+  console.log(parsed.regencyCode);     // "3204"
+  console.log(parsed.districtCode);    // "320407"
+  console.log(parsed.gender);          // "F"
+  console.log(parsed.birthDate);       // Date: 1985-08-25
+  console.log(parsed.sequenceNumber);  // "0001"
+}
+
+// Generate — buat NIK untuk testing
+const nik = generateNIK({ gender: "F", birthDate: new Date("1985-08-25") });
+console.log(nik); // "xxxxxx6508850001" (wilayah random)
+```
+
+## API Reference
+
+### `validateNIK(nik: string): ValidationResult`
+
+Validasi format NIK secara bertahap (fail-fast). Return discriminated union:
+
+```typescript
+import { validateNIK } from 'nik-id';
+// atau: import { validateNIK } from 'nik-id/validate';
+
+// NIK valid
+validateNIK("3204076508850001");
+// → { valid: true }
+
+// 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 (31 Februari)
+validateNIK("3204073102850001");
+// → { valid: false, error: "Tanggal lahir tidak valid" }
+
+// Nomor urut 0000
+validateNIK("3204076508850000");
+// → { valid: false, error: "Nomor urut tidak valid" }
+```
+
+### `parseNIK(nik: string): NIKResult`
+
+Parse NIK menjadi komponen-komponennya. Memvalidasi terlebih dahulu — kalau tidak valid, return error.
+
+```typescript
+import { parseNIK } from 'nik-id';
+// atau: import { parseNIK } from 'nik-id/parse';
+
+const result = parseNIK("3204076508850001");
+if (result.valid) {
+  console.log(result.nik);             // "3204076508850001"
+  console.log(result.provinceCode);    // "32"       — Jawa Barat
+  console.log(result.regencyCode);     // "3204"     — Kab. Bandung
+  console.log(result.districtCode);    // "320407"   — Nagreg
+  console.log(result.gender);          // "F"        — Perempuan
+  console.log(result.birthDate);       // Date: 1985-08-25
+  console.log(result.sequenceNumber);  // "0001"
+} else {
+  console.log(result.error);
+}
+```
+
+**Komponen yang diekstrak:**
+
+| Field | Tipe | Keterangan | Contoh |
+|-------|------|------------|--------|
+| `nik` | `string` | NIK asli yang di-parse | `"3204076508850001"` |
+| `provinceCode` | `string` | Kode provinsi Kemendagri (2 digit) | `"32"` |
+| `regencyCode` | `string` | Kode kabupaten/kota Kemendagri (4 digit) | `"3204"` |
+| `districtCode` | `string` | Kode kecamatan Kemendagri (6 digit) | `"320407"` |
+| `birthDate` | `Date` | Tanggal lahir (object Date) | `Date(1985-08-25)` |
+| `gender` | `"M" \| "F"` | Jenis kelamin | `"F"` |
+| `sequenceNumber` | `string` | Nomor urut registrasi (4 digit) | `"0001"` |
+
+### `generateNIK(options?: GenerateOptions): string`
+
+Generate NIK yang valid secara format. Semua parameter opsional — yang tidak diisi akan di-random.
+
+```typescript
+import { generateNIK } from 'nik-id';
+// atau: import { generateNIK } from 'nik-id/generate';
+
+// Full random
+generateNIK();
+
+// Gender spesifik
+generateNIK({ gender: "F" });
+generateNIK({ gender: "M" });
+
+// Tanggal lahir spesifik
+generateNIK({ birthDate: new Date("1985-08-25") });
+
+// Gender + tanggal lahir
+generateNIK({ gender: "F", birthDate: new Date("1985-08-25") });
+
+// Wilayah spesifik (harus konsisten dari provinsi ke kecamatan)
+generateNIK({
+  provinceCode: "32",
+  regencyCode: "3204",
+  districtCode: "320407",
+});
+
+// Semua opsi sekaligus
+generateNIK({
+  provinceCode: "32",
+  regencyCode: "3204",
+  districtCode: "320407",
+  gender: "F",
+  birthDate: new Date("1985-08-25"),
+});
+```
+
+**Opsi yang tersedia:**
+
+| Opsi | Tipe | Keterangan |
+|------|------|------------|
+| `provinceCode` | `string?` | Kode provinsi Kemendagri (2 digit, 11-97) |
+| `regencyCode` | `string?` | Kode kabupaten/kota (4 digit, harus match provinsi) |
+| `districtCode` | `string?` | Kode kecamatan (6 digit, harus match kabupaten) |
+| `gender` | `"M" \| "F"?` | Jenis kelamin |
+| `birthDate` | `Date?` | Tanggal lahir (kalau tidak diisi, random 1950-2005) |
+
+**Error yang di-throw:**
+
+```typescript
+// Kode provinsi di luar range
+generateNIK({ provinceCode: "99" });
+// → Error: "Kode provinsi tidak valid (harus 11-97)"
+
+// Kode kabupaten tidak cocok dengan provinsi
+generateNIK({ provinceCode: "32", regencyCode: "3301" });
+// → Error: 'Kode kabupaten/kota "3301" tidak sesuai dengan kode provinsi "32"'
+
+// Kode kecamatan tidak cocok dengan kabupaten
+generateNIK({ provinceCode: "32", regencyCode: "3204", districtCode: "320501" });
+// → Error: 'Kode kecamatan "320501" tidak sesuai dengan kode kabupaten/kota "3204"'
+```
+
+> **Catatan:** NIK yang dihasilkan valid secara **format** tapi **bukan** NIK asli milik orang sungguhan. Cocok untuk testing, seeding database, atau demo.
+
+## Validasi yang Dilakukan
+
+`validateNIK` dan `parseNIK` melakukan pengecekan bertahap (fail-fast — berhenti di error pertama):
+
+| # | Pengecekan | Detail |
+|---|-----------|--------|
+| 1 | **Tipe data** | Input harus bertipe `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** | DD (01-31 atau 41-71), MM (01-12), valid di kalender |
+| 6 | **Nomor urut** | Digit 13-16 tidak boleh `0000` |
+
+> **Catatan:** Validasi bersifat **format-only**. Package ini tidak mengecek apakah kode wilayah benar-benar terdaftar di database Kemendagri. Untuk lookup nama wilayah, gunakan package [`kode-wilayah-id`](https://www.npmjs.com/package/kode-wilayah-id).
+
+### Error Messages
+
+Semua pesan error dalam Bahasa Indonesia:
+
+| Error | Penyebab | Contoh Input |
+|-------|----------|-------------|
+| `NIK harus berupa string` | Input bukan bertipe string | `12345`, `null`, `undefined` |
+| `NIK harus 16 digit` | Panjang bukan 16 karakter | `"123"`, `""` |
+| `NIK hanya boleh berisi angka` | Mengandung karakter non-digit | `"320407650885000A"` |
+| `Kode provinsi tidak valid` | 2 digit pertama di luar range 11-97 | `"0004076508850001"` |
+| `Tanggal lahir tidak valid` | Tanggal/bulan invalid atau tidak ada di kalender | `"3204073102850001"` |
+| `Nomor urut tidak valid` | 4 digit terakhir adalah `0000` | `"3204076508850000"` |
+
+## Tree-shaking / Sub-path Imports
+
+Import hanya fungsi yang dibutuhkan — bundler hanya include kode yang di-import:
+
+```typescript
+// Hanya validasi
+import { validateNIK } from 'nik-id/validate';
+
+// Hanya parsing
+import { parseNIK } from 'nik-id/parse';
+
+// Hanya generator
+import { generateNIK } from 'nik-id/generate';
+
+// Types only (zero runtime)
+import type { NIKResult, ValidationResult, GenerateOptions } from 'nik-id/types';
+
+// Atau import semua sekaligus
+import { validateNIK, parseNIK, generateNIK } from 'nik-id';
+```
+
+### Bundle Size
+
+Package ini sangat ringan karena zero dependencies dan hanya berisi logika validasi:
+
+| Import | Ukuran (minified) |
+|--------|-------------------|
+| `nik-id/validate` | ~1.8 KB |
+| `nik-id/parse` | ~2.8 KB |
+| `nik-id/generate` | ~2.3 KB |
+| `nik-id` (full) | ~5.2 KB |
+
+## Integrasi dengan kode-wilayah-id
+
+Package ini **tidak** menyertakan data wilayah — hanya mengembalikan kode Kemendagri. Untuk resolve ke nama wilayah, gunakan package [`kode-wilayah-id`](https://www.npmjs.com/package/kode-wilayah-id):
+
+```bash
+npm install kode-wilayah-id
+```
+
+```typescript
+import { parseNIK } from 'nik-id';
+import {
+  getProvinceByKemendagriCode,
+  getRegencyByKemendagriCode,
+  getDistrictByKemendagriCode,
+} from 'kode-wilayah-id';
+
+const result = parseNIK("3204076508850001");
+if (result.valid) {
+  const province = getProvinceByKemendagriCode(result.provinceCode);
+  const regency = getRegencyByKemendagriCode(result.regencyCode);
+  const district = getDistrictByKemendagriCode(result.districtCode);
+
+  console.log(province?.name); // "JAWA BARAT"
+  console.log(regency?.name);  // "KAB. BANDUNG"
+  console.log(district?.name); // "NAGREG"
+}
+```
+
+## Discriminated Union Pattern
+
+Return type `parseNIK` dan `validateNIK` menggunakan discriminated union — TypeScript bisa narrow type otomatis berdasarkan `result.valid`:
+
+```typescript
+import { parseNIK } from 'nik-id';
+import type { NIKResult, NIKValid, NIKInvalid } from 'nik-id/types';
+
+const result: NIKResult = parseNIK(input);
+
+if (result.valid) {
+  // TypeScript tahu ini NIKValid — semua field tersedia
+  console.log(result.provinceCode);  // ✅ string
+  console.log(result.gender);        // ✅ "M" | "F"
+  console.log(result.birthDate);     // ✅ Date
+} else {
+  // TypeScript tahu ini NIKInvalid — hanya error
+  console.log(result.error);         // ✅ string
+  // console.log(result.gender);     // ❌ compile error!
+}
+```
+
+Pattern yang sama berlaku untuk `validateNIK`:
+
+```typescript
+import { validateNIK } from 'nik-id';
+
+const result = validateNIK(input);
+if (result.valid) {
+  // ValidationValid — tidak ada field lain
+  console.log("NIK valid!");
+} else {
+  // ValidationInvalid — ada field error
+  console.log(result.error);
+}
+```
+
+## Contoh Penggunaan
+
+Lihat folder [`examples/`](examples/) untuk contoh lengkap di berbagai framework dan runtime:
+
+| Framework | File | Fitur |
+|-----------|------|-------|
+| **Node.js** | [`node.ts`](examples/node.ts) | Basic usage — validasi, parse, generate |
+| **React** | [`react.tsx`](examples/react.tsx) | Form validasi KTP dengan feedback real-time |
+| **Next.js** | [`nextjs.tsx`](examples/nextjs.tsx) | API route + server component |
+| **Express** | [`express.ts`](examples/express.ts) | REST API endpoint validasi NIK |
+| **Hono** | [`hono.ts`](examples/hono.ts) | Lightweight REST API validasi NIK |
+| **Bun** | [`bun.ts`](examples/bun.ts) | Native Bun HTTP server |
+| **Deno** | [`deno.ts`](examples/deno.ts) | Native Deno server |
+
+```bash
+# Jalankan contoh Node.js
+npx tsx examples/node.ts
+```
+
+## Types
+
+Semua type tersedia di `nik-id/types`:
+
+```typescript
+import type {
+  NIKValid,
+  NIKInvalid,
+  NIKResult,
+  ValidationValid,
+  ValidationInvalid,
+  ValidationResult,
+  GenerateOptions,
+} from 'nik-id/types';
+```
+
+### NIKResult (parseNIK)
+
+```typescript
+// Hasil valid
+interface NIKValid {
+  valid: true;
+  nik: string;              // "3204076508850001"
+  provinceCode: string;     // "32"
+  regencyCode: string;      // "3204"
+  districtCode: string;     // "320407"
+  birthDate: Date;          // Date(1985-08-25)
+  gender: "M" | "F";       // "F"
+  sequenceNumber: string;   // "0001"
+}
+
+// Hasil invalid
+interface NIKInvalid {
+  valid: false;
+  error: string;            // "NIK harus 16 digit"
+}
+
+type NIKResult = NIKValid | NIKInvalid;
+```
+
+### ValidationResult (validateNIK)
+
+```typescript
+interface ValidationValid {
+  valid: true;
+}
+
+interface ValidationInvalid {
+  valid: false;
+  error: string;
+}
+
+type ValidationResult = ValidationValid | ValidationInvalid;
+```
+
+### GenerateOptions (generateNIK)
+
+```typescript
+interface GenerateOptions {
+  provinceCode?: string;    // "32" (2 digit, 11-97)
+  regencyCode?: string;     // "3204" (4 digit, harus match provinsi)
+  districtCode?: string;    // "320407" (6 digit, harus match kabupaten)
+  gender?: "M" | "F";      // Jenis kelamin
+  birthDate?: Date;         // Tanggal lahir (default: random 1950-2005)
+}
+```
+
+## Encoding Tanggal Lahir
+
+NIK meng-encode tanggal lahir dalam 6 digit (posisi 7-12) dengan format DDMMYY:
+
+### Gender dan DD
+
+| Gender | Range DD | Contoh | Arti |
+|--------|----------|--------|------|
+| Laki-laki | 01-31 | DD=`15` | Lahir tanggal 15 |
+| Perempuan | 41-71 | DD=`65` | Lahir tanggal 25 (65-40=25) |
+| Invalid | 00, 32-40, 72-99 | -- | Tidak valid |
+
+### Disambiguasi Tahun (YY)
+
+Karena NIK hanya menyimpan 2 digit tahun, perlu disambiguasi:
+
+| YY | Tahun sekarang (2 digit) | Hasil | Logika |
+|----|--------------------------|-------|--------|
+| 85 | 26 | 1985 | 85 > 26 → 1900 + 85 |
+| 02 | 26 | 2002 | 02 ≤ 26 → 2000 + 02 |
+| 26 | 26 | 2026 | 26 ≤ 26 → 2000 + 26 |
+| 27 | 26 | 1927 | 27 > 26 → 1900 + 27 |
+| 00 | 26 | 2000 | 00 ≤ 26 → 2000 + 00 |
+| 99 | 26 | 1999 | 99 > 26 → 1900 + 99 |
+
+## Kode Wilayah Kemendagri
+
+NIK menggunakan kode wilayah format Kemendagri (bukan BPS):
+
+| Level | Panjang | Contoh | Keterangan |
+|-------|---------|--------|------------|
+| Provinsi | 2 digit | `"32"` | Jawa Barat |
+| Kabupaten/Kota | 4 digit | `"3204"` | Kab. Bandung |
+| Kecamatan | 6 digit | `"320407"` | Nagreg |
+
+Range kode provinsi yang valid: **11** (Aceh) sampai **97** (Papua Barat Daya).
+
+> Package ini hanya memvalidasi **range** kode provinsi (11-97), tidak mengecek apakah kode spesifik benar-benar ada. Untuk lookup nama wilayah, gunakan [`kode-wilayah-id`](https://www.npmjs.com/package/kode-wilayah-id).
+
+## Contributing
+
+Kontribusi sangat diterima!
+
+```bash
+git clone https://github.com/sumitroajiprabowo/nik-id.git
+cd nik-id
+npm install
+npm run lint          # Lint check (Biome)
+npm run format:check  # Format check
+npm run typecheck     # TypeScript check
+npm run test:coverage # Test dengan coverage (harus 100%)
+npm run build         # Build ESM + CJS
+```
+
+## Changelog
+
+Lihat [CHANGELOG.md](CHANGELOG.md) untuk riwayat perubahan.
+
+## Lisensi
+
+[MIT](LICENSE) (c) [Sumitro Aji Prabowo](https://github.com/sumitroajiprabowo)

package/dist/generate.cjs

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/generate.ts
+var generate_exports = {};
+__export(generate_exports, {
+  generateNIK: () => generateNIK
+});
+module.exports = __toCommonJS(generate_exports);
+var MIN_PROVINCE_CODE = 11;
+var MAX_PROVINCE_CODE = 97;
+var MIN_BIRTH_YEAR = 1950;
+var MAX_BIRTH_YEAR = 2005;
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+function padZero(num, length) {
+  return String(num).padStart(length, "0");
+}
+function getDaysInMonth(year, month) {
+  return new Date(year, month, 0).getDate();
+}
+function randomBirthDate() {
+  const year = randomInt(MIN_BIRTH_YEAR, MAX_BIRTH_YEAR);
+  const month = randomInt(1, 12);
+  const maxDay = getDaysInMonth(year, month);
+  const day = randomInt(1, maxDay);
+  return new Date(year, month - 1, day);
+}
+function generateNIK(options = {}) {
+  const { gender, birthDate } = options;
+  let provinceCode;
+  if (options.provinceCode !== void 0) {
+    const pc = Number.parseInt(options.provinceCode, 10);
+    if (Number.isNaN(pc) || pc < MIN_PROVINCE_CODE || pc > MAX_PROVINCE_CODE) {
+      throw new Error("Kode provinsi tidak valid (harus 11-97)");
+    }
+    provinceCode = padZero(pc, 2);
+  } else {
+    provinceCode = padZero(randomInt(MIN_PROVINCE_CODE, MAX_PROVINCE_CODE), 2);
+  }
+  let regencyCode;
+  if (options.regencyCode !== void 0) {
+    if (!options.regencyCode.startsWith(provinceCode)) {
+      throw new Error(
+        `Kode kabupaten/kota "${options.regencyCode}" tidak sesuai dengan kode provinsi "${provinceCode}"`
+      );
+    }
+    regencyCode = options.regencyCode;
+  } else {
+    regencyCode = provinceCode + padZero(randomInt(1, 99), 2);
+  }
+  let districtCode;
+  if (options.districtCode !== void 0) {
+    if (!options.districtCode.startsWith(regencyCode)) {
+      throw new Error(
+        `Kode kecamatan "${options.districtCode}" tidak sesuai dengan kode kabupaten/kota "${regencyCode}"`
+      );
+    }
+    districtCode = options.districtCode;
+  } else {
+    districtCode = regencyCode + padZero(randomInt(1, 99), 2);
+  }
+  const birth = birthDate ?? randomBirthDate();
+  const day = birth.getDate();
+  const month = birth.getMonth() + 1;
+  const year = birth.getFullYear();
+  const selectedGender = gender ?? (Math.random() < 0.5 ? "M" : "F");
+  const encodedDay = selectedGender === "F" ? day + 40 : day;
+  const ddStr = padZero(encodedDay, 2);
+  const mmStr = padZero(month, 2);
+  const yyStr = padZero(year % 100, 2);
+  const seq = padZero(randomInt(1, 9999), 4);
+  return districtCode + ddStr + mmStr + yyStr + seq;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateNIK
+});

package/dist/generate.d.cts

@@ -0,0 +1,83 @@
+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 };