@sri-lanka/nic

Parse, validate, and build Sri Lankan National Identity Card numbers.

Zero dependencies · TypeScript · Works everywhere

Documentation

Full documentation is available at the docs site.

Install

# npm
npm install @sri-lanka/nic

# pnpm
pnpm add @sri-lanka/nic

# yarn
yarn add @sri-lanka/nic

Validate a NIC

import { NIC } from "@sri-lanka/nic";

// Check without throwing
NIC.valid("901404567V"); // true
NIC.valid("invalid"); // false

Parse a NIC

import { NIC } from "@sri-lanka/nic";

const result = NIC.parse("200001501234"); // throws if invalid

console.log(result.birthday); // { year: 2000, month: 1, day: 15 }
console.log(result.gender); // "MALE"
console.log(result.age); // 25
console.log(result.type); // "NEW"
console.log(result.value); // "200001501234"
console.log(result.parts); // { year: "2000", days: "015", serial: "123", checkdigit: "4", letter: null }
console.log(result.config); // { minimumAge: 16, maximumAge: 126, minimumBirthYear: 1900, maximumBirthYear: 2010 }

Safe Parse

import { NIC } from "@sri-lanka/nic";

// Safe parse — returns a result object, never throws
const result = NIC.safeParse("901404567V");
if (result.success) {
  console.log(result.data.gender); // "MALE"
} else {
  console.log(result.error.message);
}

Build a NIC

import { NIC, Gender } from "@sri-lanka/nic";

const nic = NIC.builder
  .new()
  .birthday({ year: 1995, month: 6, day: 15 })
  .gender(Gender.MALE)
  .build();

console.log(nic); // "199516600000" (example)

Build from Age

import { NIC, Gender } from "@sri-lanka/nic";

const nic = NIC.builder.new().age(25).gender(Gender.FEMALE).build();

console.log(nic); // A valid new-format NIC for a 25-year-old female

Convert Between Formats

const parsed = NIC.parse("901404567V");

// Old → New
const newFormat = parsed.convert();
console.log(newFormat); // "199014004567"

// New → Old
const back = NIC.parse(newFormat);
console.log(back.convert({ letter: "V" })); // "901404567V"

Configuration

NIC.parse("901404567V", {
  minimumAge: 18,
  maximumAge: 100,
  minimumBirthYear: 1950,
  maximumBirthYear: 2005,

  // Custom validation
  check(nic, NICError) {
    if (nic.gender === "FEMALE") {
      throw new NICError("Only male NICs allowed");
    }
  },
});

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT © Vinod Liyanage