Parsing

Use NIC.parse() to extract all the information encoded in a NIC string.

Basic Usage

import { NIC } from "@sri-lanka/nic";
 
const result = NIC.parse("901404567V");
 
console.log(result.value); // "901404567V"
console.log(result.type); // "OLD"
console.log(result.gender); // "MALE"
console.log(result.birthday); // { year: 1990, month: 5, day: 19 }
console.log(result.age); // calculated from current date

How Birthday Dates Are Encoded

The Sri Lankan government uses a fixed 366-day calendar when encoding birthdays inside NIC numbers. This is an official convention — not a bug — and it affects every NIC ever issued.

February always has 29 days, no matter what year you were born in. Even if your birth year was not a leap year, the NIC system still assigns day 60 to February 29th and day 61 to March 1st.

Day number	Date
1	January 1st
31	January 31st
60	February 29th — in every year
61	March 1st — in every year
275	October 1st
366	December 31st

This library follows the official government convention exactly, so the birthdays it returns always match what was recorded by the Department of Registration of Persons.

Auto-Sanitization

Input is automatically trimmed and converted to uppercase:

NIC.parse("  901404567v  ");
// Same as NIC.parse("901404567V")

You can also sanitize manually:

NIC.sanitize("  901404567v  "); // "901404567V"

Safe Parsing

If you'd rather not deal with try/catch, use NIC.safeParse(). It returns a result object instead of throwing:

const result = NIC.safeParse("901404567V");
 
if (result.success) {
  console.log(result.data.gender); // "MALE"
  console.log(result.data.birthday); // { year: 1990, month: 5, day: 19 }
} else {
  console.log(result.error.message); // error details
}

This is especially useful in form handlers, API routes, or anywhere you want to handle success and failure in a single code path without exceptions:

// In an API route
const result = NIC.safeParse(req.body.nic);
 
if (!result.success) {
  return res.status(400).json({ error: result.error.message });
}
 
return res.json({ gender: result.data.gender, age: result.data.age });

Tip: safeParse accepts the same options as parse, including custom check callbacks, onlyNew/onlyOld, and boundary overrides.

Format Detection

The library auto-detects the NIC format:

New format: 12 digits (e.g., 200001501234)
Old format: 9 digits + V or X (e.g., 901404567V)

You can check the format without parsing:

NIC.getType("200001501234"); // "NEW"
NIC.getType("901404567V"); // "OLD"
NIC.getType("invalid"); // throws NICError

Raw Parts

Access the raw string slices from the NIC:

const { parts } = NIC.parse("200001501234");
 
parts.year; // "2000"
parts.days; // "015"
parts.serial; // "0123"
parts.checkdigit; // "4"
parts.letter; // null (new format has no letter)

For old format NICs:

const { parts } = NIC.parse("901404567V");
 
parts.year; // "1990" (prepended "19")
parts.days; // "140"
parts.serial; // "456"
parts.checkdigit; // "7"
parts.letter; // "V"

Resolved Config

After parsing, you can inspect the validation boundaries that were applied:

const nic = NIC.parse("200001501234");
 
console.log(nic.config);
// {
//   minimumAge: 15,
//   maximumAge: 126,
//   minimumBirthYear: 1900,
//   maximumBirthYear: 2011,
// }

When you pass custom overrides, the resolved config reflects the merge:

const nic = NIC.parse("200001501234", { minimumAge: 18 });
 
console.log(nic.config.minimumAge); // 18 (your override)
console.log(nic.config.maximumAge); // 126 (default)

This is useful for debugging why a NIC passed or failed validation, or for logging the exact rules that were applied.

Format Conversion

Convert between old and new formats:

// Old → New
const old = NIC.parse("901404567V");
old.convert(); // "199014004567"
 
// New → Old
const nic = NIC.parse("199014004567");
nic.convert(); // "901404567V" (default letter: V)
nic.convert({ letter: "X" }); // "901404567X"

Note: Not all new NICs can be converted to old format. The year must be 19XX and the serial must be 3 digits or fewer.

String & JSON Representation

You can easily convert a parsed NIC object into a string or JSON.

const nic = NIC.parse("200001501234");
 
// String representation (Implicitly calls toString)
console.log(`User NIC is ${nic}`); 
// "User NIC is 200001501234"
 
// JSON representation (Implicitly calls toJSON)
console.log(JSON.stringify(nic, null, 2));
// {
//   "value": "200001501234",
//   "type": "NEW",
//   "parts": {
//     "year": "2000",
//     "days": "015",
//     "serial": "123",
//     "checkdigit": "4",
//     "letter": null
//   },
//   "birthday": {
//     "year": 2000,
//     "month": 1,
//     "day": 15
//   },
//   "age": 26,
//   "gender": "MALE",
//   "config": {
//     "minimumAge": 15,
//     "maximumAge": 126,
//     "minimumBirthYear": 1900,
//     "maximumBirthYear": 2011
//   }
// }

PreviousGetting Started NextValidation