@cakfan/valid-id

Validate and parse Indonesian identity numbers — NIK, NPWP, and NIB — in JavaScript and TypeScript.

Zero dependencies. Works in Node.js, Bun, Deno, and the browser.

Features

• NIK validation — format, region codes (Kemendagri 2025), birth date, gender extraction
• NPWP validation — auto-detects old (15-digit), new 16-digit, and NIK-based formats with Luhn checksum
• NIB validation — 13-digit format check for Nomor Induk Berusaha
• CLI support — run via npx @cakfan/valid-id
• TypeScript — full type definitions included
• Zero dependencies — no network calls, all validation is local
• Input normalization — accepts dots, dashes, and spaces

Table of Contents

• Install
• Quick Start
• Usage
  • Library
  • CLI
• API Reference
• Region Data
• Use Cases
• Limitations
• License

Install

npm install @cakfan/valid-id

Also available with bun, yarn, or pnpm:

bun add @cakfan/valid-id
yarn add @cakfan/valid-id
pnpm add @cakfan/valid-id

Quick Start

import { validateNik, validateNpwp, validateNib } from "@cakfan/valid-id";

validateNik("3171061501900001");    // { valid: true, data: { region, birthDate, ... } }
validateNpwp("01.300.066.6-091.000"); // { valid: true, format: "old_15", ... }
validateNib("1234567890123");        // { valid: true }

Usage

Library

import { validateNik, validateNpwp, validateNib } from "@cakfan/valid-id";

// Validate NIK (Nomor Induk Kependudukan)
const nik = validateNik("3171 0615 0190 0001"); // spaces are auto-stripped
if (nik.valid) {
  console.log(nik.data.region.provinceName); // "DKI JAKARTA"
  console.log(nik.data.region.regencyName);  // "KOTA ADM. JAKARTA PUSAT"
  console.log(nik.data.region.districtName); // "MENTENG"
  console.log(nik.data.birthDate.year);      // 1990
  console.log(nik.data.birthDate.month);     // 1
  console.log(nik.data.birthDate.day);       // 15
  console.log(nik.data.birthDate.gender);    // "male"
}

// Validate NPWP (Nomor Pokok Wajib Pajak)
const npwp = validateNpwp("01.300.066.6-091.000"); // dots and dashes are auto-stripped
if (npwp.valid) {
  console.log(npwp.format);              // "old_15"
  console.log(npwp.data.taxpayerType);   // "Instansi Pemerintah"
  console.log(npwp.data.kppCode);        // "091"
  console.log(npwp.data.branchCode);     // "000"
}

// Validate NIB (Nomor Induk Berusaha)
const nib = validateNib("1234567890123");
if (nib.valid) {
  console.log("NIB format is valid");
}

CLI

npx @cakfan/valid-id nik 3171061501900001
npx @cakfan/valid-id npwp 01.300.066.6-091.000
npx @cakfan/valid-id nib 1234567890123

Example output:

✓ NIK valid
  Provinsi    : DKI JAKARTA (31)
  Kab/Kota    : KOTA ADM. JAKARTA PUSAT (3171)
  Kecamatan   : MENTENG (317106)
  Tgl Lahir   : 15-01-1990
  Gender      : Laki-laki

API Reference

validateNik(nik: string): NikValidationResult

Validates a 16-digit NIK (Nomor Induk Kependudukan). Checks format, region codes against the Kemendagri database, and birth date validity. Extracts parsed data including gender (via the +40 rule for females).

| Field | Type | Description | |-------|------|-------------| | valid | boolean | Whether the NIK is valid | | reason | string? | Explanation if invalid | | data.region | NikRegionInfo | Province, regency, district (code + name) | | data.birthDate | BirthDateInfo | Day, month, year, gender, Date object | | data.sequenceNumber | number | Last 4 digits |

validateNpwp(npwp: string): NpwpValidationResult

Validates an NPWP (Nomor Pokok Wajib Pajak). Auto-detects format:

| Format | Digits | Description | |--------|--------|-------------| | old_15 | 15 | Traditional NPWP with Luhn checksum | | new_16 | 16 | New format (starts with 0) with Luhn checksum | | new_nik | 16 | NIK-based NPWP (validated as NIK) |

| Field | Type | Description | |-------|------|-------------| | valid | boolean | Whether the NPWP is valid | | format | NpwpFormat | Detected format | | reason | string? | Explanation if invalid | | data.taxpayerType | string? | Taxpayer category | | data.kppCode | string? | Tax office code | | data.branchCode | string? | Branch code ("000" = head office) |

validateNib(nib: string): NibValidationResult

Validates a 13-digit NIB (Nomor Induk Berusaha). Format check only.

| Field | Type | Description | |-------|------|-------------| | valid | boolean | Whether the NIB format is valid | | reason | string? | Explanation if invalid |

extractBirthDateFromNik(digits: string): BirthDateInfo | null

Lower-level function to extract birth date from the 6-digit date portion of a NIK (digits 7-12). Handles the +40 rule for females.

Region Data

NIK validation includes a static database of Indonesian region codes (Kemendagri 2025):

• 34 provinces
• 488 regencies/cities
• 6,635 districts

Source: Kepmendagri No. 300.2.2-2138 Tahun 2025.

Note: 4 newly formed Papua provinces (BPS codes 92, 95, 96, 97) do not yet have official Kemendagri codes and are excluded from validation.

Use Cases

• KYC forms — validate user identity numbers during registration
• Backend validation — verify NIK/NPWP format before database insertion
• Fintech onboarding — check taxpayer identification numbers
• E-commerce — validate buyer/seller identity for compliance
• Government apps — validate citizen identification numbers
• Tax filing — verify NPWP format before submission

Limitations

• Format validation only — does not verify against official government databases (Dukcapil, DJP, OSS)
• No network calls — all validation is local, using static data bundled in the package
• NIB has no checksum — only 13-digit format is validated; authenticity cannot be verified locally
• Region codes may become outdated — new regencies/districts (pemekaran wilayah) require a package update

License

MIT