@sri-lanka/nic 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vinod Liyanage
+
+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,343 @@
+<p align="start">
+  <img src="https://raw.githubusercontent.com/vinodliyanage/sri-lanka-nic/main/public/sri-lanka-nic-logo.jpg" alt="Sri Lanka NIC Logo" width="200" />
+</p>
+
+# @sri-lanka/nic
+
+[![NPM Version](https://img.shields.io/npm/v/%40sri-lanka%2Fnic)](https://www.npmjs.com/package/@sri-lanka/nic)
+[![npm bundle size](https://img.shields.io/bundlejs/size/%40sri-lanka%2Fnic)](https://bundlejs.com/?q=%40sri-lanka%2Fnic)
+[![NPM License](https://img.shields.io/npm/l/%40sri-lanka%2Fnic)](./LICENSE)
+
+A lightweight, zero-dependency TypeScript library to **parse**, **validate**, **convert**, and **generate** Sri Lankan National Identity Card (NIC) numbers.
+
+Supports both the old format (`9 digits + V/X`) and the new format (`12 digits`), with accurate validation logic that goes beyond simple regex matching.
+
+**[Live Demo & API Explorer](https://nic.vinodliyanage.me)** · **[NPM Package](https://www.npmjs.com/package/@sri-lanka/nic)**
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Validation](#validation)
+- [Parsing](#parsing)
+- [Format Conversion](#format-conversion)
+- [Random NIC Generation](#random-nic-generation)
+- [Sanitization](#sanitization)
+- [Error Handling](#error-handling)
+- [Integration with Zod](#integration-with-zod)
+- [Error Codes](#error-codes)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Module Support](#module-support)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **Zero dependencies** — lightweight and self-contained, nothing extra to install
+- **Accurate validation** — goes beyond regex to validate birth year, day-of-year, leap years, and minimum age
+- **Full parsing** — extract birthday, gender, age, serial number, voter status, and more from any valid NIC
+- **Format conversion** — convert between old (9-digit + letter) and new (12-digit) NIC formats
+- **Random generation** — generate structurally valid NIC numbers, useful for testing and mock data
+- **Tiny footprint** — under 6 kB minified with tree-shaking support
+- **Universal module support** — ships ESM, CJS, and TypeScript declarations out of the box
+
+---
+
+## Installation
+
+```bash
+pnpm add @sri-lanka/nic
+```
+
+```bash
+npm install @sri-lanka/nic
+```
+
+```bash
+yarn add @sri-lanka/nic
+```
+
+---
+
+## Quick Start
+
+```ts
+import { NIC } from "@sri-lanka/nic";
+
+const nic = NIC.parse("200012301234");
+
+console.log(nic.type); // "new"
+console.log(nic.gender); // "male"
+console.log(nic.birthday); // { year: 2000, month: 5, day: 15 }
+console.log(nic.age); // 25
+```
+
+That's it — one import, one call, and you have everything about the NIC.
+
+---
+
+## Validation
+
+Most NIC validation libraries do a simple regex check to see if the string _looks_ like a NIC. This library goes much further and validates the **actual data encoded in the number**.
+
+Here's what the validation checks:
+
+1. **Structure** — the string must match either the old format (9 digits followed by `V` or `X`) or the new format (exactly 12 digits). Anything else is immediately rejected.
+
+2. **Birth year range** — the birth year extracted from the NIC must fall between 1901 and a reasonable upper limit. For the new format, the upper limit is dynamically calculated as `current year - 15`, ensuring the NIC holder meets the minimum age.
+
+3. **Day-of-year bounds** — Sri Lankan NICs encode the birthday as a day-of-year value (1–365 for males, 501–865 for females). The library validates that this value falls within the correct range, accounting for whether the birth year is a leap year (allowing day 366 / 866).
+
+4. **Leap year correctness** — day 366 (or 866 for females) is only valid if the birth year is actually a leap year. The library checks this against the real birth year, not a static assumption.
+
+5. **Minimum age requirement** — in Sri Lanka, the legal age to obtain a NIC is **15 years** ([source](https://drp.gov.lk/en/normal.php)). The library doesn't just check the year — it checks down to the **exact day**. If someone was born on day 300 of the maximum allowed year, but today is only day 200, it correctly rejects the NIC because the person hasn't turned 15 yet.
+
+### Using Validation
+
+There are two ways to validate:
+
+#### Quick boolean check
+
+```ts
+NIC.valid("853400937V"); // true
+NIC.valid("000000000V"); // false
+```
+
+#### Detailed result with error information
+
+```ts
+const result = NIC.validate("853400937V");
+
+if (result.valid) {
+  console.log("NIC is valid");
+} else {
+  console.log(result.error.code); // e.g. "INVALID_NIC_STRUCTURE"
+  console.log(result.error.message); // Human-readable error description
+}
+```
+
+`NIC.validate()` never throws. It returns a result object so you can safely check validity and inspect the specific error if the NIC is invalid.
+
+---
+
+## Parsing
+
+`NIC.parse()` reads a NIC string and returns a rich `NIC` object with all the extracted information. If the NIC is invalid, it throws a `NIC.Error`.
+
+```ts
+const nic = NIC.parse("853400937V");
+```
+
+Once parsed, you have access to all the details:
+
+```ts
+nic.value; // "853400937V" — the sanitized NIC string
+nic.type; // "old" — format type ("old" or "new")
+nic.gender; // "male" — gender encoded in the NIC
+nic.birthday; // { year: 1985, month: 12, day: 6 } — full date of birth
+nic.age; // 40 — current age in years
+nic.year; // 1985 — birth year
+nic.days; // 340 — day-of-year value from the NIC
+nic.serial; // "093" — serial number portion
+nic.checkdigit; // "7" — check digit
+nic.letter; // "V" — trailing letter (null for new format NICs)
+nic.voter; // true — voter registration status (null for new format NICs)
+```
+
+You can also get a summary object or the plain string:
+
+```ts
+nic.toJSON();
+// { type: "old", gender: "male", birthday: { year: 1985, month: 12, day: 6 }, age: 40 }
+
+nic.toString(); // "853400937V"
+```
+
+---
+
+## Format Conversion
+
+Sri Lanka has used two NIC formats over the years. This library lets you convert between them:
+
+- **Old format**: 2-digit year + 3-digit day + 4-digit serial + letter (e.g. `853400937V`)
+- **New format**: 4-digit year + 3-digit day + 4-digit serial + check digit (e.g. `198534009370`)
+
+```ts
+// Old → New
+const nic = NIC.parse("853400937V");
+nic.convert(); // "198534009370"
+
+// New → Old
+const nic2 = NIC.parse("198534009370");
+nic2.convert(); // "853400937V"
+```
+
+> **Note:** New → Old conversion only works for birth years in the 1900s, since the old format only has 2 digits for the year.
+
+---
+
+## Random NIC Generation
+
+Generate a valid, random NIC number. Useful for unit tests, seeding databases, or creating mock data.
+
+```ts
+const randomNIC = NIC.random();
+console.log(randomNIC); // e.g. "941520456V" or "199815204560"
+```
+
+The generated NIC will always pass validation — it uses real date logic to ensure the birth year, day-of-year, and all other fields are structurally correct.
+
+---
+
+## Sanitization
+
+Clean up user input before processing. `NIC.sanitize()` trims whitespace and normalizes the letter casing.
+
+```ts
+NIC.sanitize("  853400937v  "); // "853400937V"
+NIC.sanitize(" 200012301234 "); // "200012301234"
+```
+
+Throws `NIC.Error` if the input is completely invalid (not recognizable as a NIC at all).
+
+---
+
+## Error Handling
+
+When `NIC.parse()` encounters an invalid NIC, it throws a `NIC.Error` with a specific error code:
+
+```ts
+try {
+  NIC.parse("invalid-nic");
+} catch (error) {
+  if (error instanceof NIC.Error) {
+    console.log(error.code); // "INVALID_NIC_STRUCTURE"
+    console.log(error.message); // "Invalid NIC structure in the given NIC number..."
+  }
+}
+```
+
+If you prefer not to use try/catch, use `NIC.validate()` or `NIC.valid()` instead — they never throw.
+
+---
+
+## Integration with Zod
+
+You can easily use this library as a custom Zod validator for form validation or API input:
+
+```ts
+import { z } from "zod";
+import { NIC } from "@sri-lanka/nic";
+
+const schema = z.object({
+  nic: z.string().refine((v) => NIC.valid(v), {
+    message: "Invalid Sri Lankan NIC",
+  }),
+});
+
+// Usage
+schema.parse({ nic: "853400937V" }); // ✅ passes
+schema.parse({ nic: "0000000000" }); // ❌ throws ZodError
+```
+
+---
+
+## Error Codes
+
+Every error thrown by the library includes a specific `code` property:
+
+| Code                                                 | Description                                                                                  |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `INVALID_NIC_STRUCTURE`                              | The input doesn't match either the old format (9 digits + V/X) or the new format (12 digits) |
+| `INVALID_BIRTH_YEAR`                                 | The birth year extracted from the NIC is outside the valid range (before 1901 or too recent) |
+| `INVALID_DAY_OF_YEAR`                                | The day-of-year value is outside valid bounds for the given birth year                       |
+| `MINIMUM_AGE_REQUIREMENT_NOT_MET`                    | The person would be under 15 years old, which is below the legal minimum age for a NIC       |
+| `ONLY_19XX_YEAR_NICS_CAN_BE_CONVERTED_TO_OLD_FORMAT` | Attempted to convert a NIC with a birth year of 2000 or later to the old format              |
+
+---
+
+## Configuration
+
+The library exposes its validation constants through `NIC.Config`, which you can override to suit your needs:
+
+```ts
+// Read the current values
+NIC.Config.MINIMUM_LEGAL_AGE_TO_HAVE_NIC; // 15
+NIC.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC; // 1901
+
+// Override them
+NIC.Config.MINIMUM_LEGAL_AGE_TO_HAVE_NIC = 16;
+NIC.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC = 1950;
+```
+
+These values are used internally during validation, generation, and error messages. Changing them affects all subsequent calls to `NIC.parse()`, `NIC.validate()`, `NIC.valid()`, and `NIC.random()`.
+
+---
+
+## API Reference
+
+### Static Methods
+
+| Method              | Returns                                        | Throws      | Description                           |
+| ------------------- | ---------------------------------------------- | ----------- | ------------------------------------- |
+| `NIC.parse(nic)`    | `NIC` instance                                 | `NIC.Error` | Parse a NIC string into a rich object |
+| `NIC.validate(nic)` | `{ valid: true }` or `{ valid: false, error }` | —           | Validate without throwing             |
+| `NIC.valid(nic)`    | `boolean`                                      | —           | Quick validity check                  |
+| `NIC.random()`      | `string`                                       | —           | Generate a random valid NIC           |
+| `NIC.sanitize(nic)` | `string`                                       | `NIC.Error` | Clean up and normalize a NIC string   |
+
+### Instance Properties
+
+| Property      | Type                   | Description                                                     |
+| ------------- | ---------------------- | --------------------------------------------------------------- |
+| `.value`      | `string`               | The sanitized NIC string                                        |
+| `.type`       | `"old" \| "new"`       | NIC format type                                                 |
+| `.gender`     | `"male" \| "female"`   | Gender encoded in the NIC                                       |
+| `.birthday`   | `{ year, month, day }` | Full date of birth                                              |
+| `.age`        | `number`               | Current age in years                                            |
+| `.year`       | `number`               | Birth year                                                      |
+| `.days`       | `number`               | Day-of-year value from the NIC                                  |
+| `.serial`     | `string`               | Serial number portion                                           |
+| `.checkdigit` | `string`               | Check digit character                                           |
+| `.letter`     | `string \| null`       | Trailing letter — `"V"` or `"X"` for old format, `null` for new |
+| `.voter`      | `boolean \| null`      | Voter registration status — old format only, `null` for new     |
+
+### Instance Methods
+
+| Method        | Returns  | Description                                               |
+| ------------- | -------- | --------------------------------------------------------- |
+| `.convert()`  | `string` | Convert between old and new NIC formats                   |
+| `.toJSON()`   | `object` | Get a summary object with type, gender, birthday, and age |
+| `.toString()` | `string` | Get the NIC as a plain string                             |
+
+---
+
+## Module Support
+
+The library ships with both ESM and CommonJS builds, plus TypeScript declarations:
+
+```ts
+// ESM
+import { NIC } from "@sri-lanka/nic";
+
+// CommonJS
+const { NIC } = require("@sri-lanka/nic");
+```
+
+Tree-shaking is fully supported.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class e{static MINIMUM_LEGAL_AGE_TO_HAVE_NIC=15;static OLDEST_BIRTH_YEAR_FOR_VALID_NIC=1901}const t={INVALID_NIC_STRUCTURE:()=>"Invalid NIC structure in the given NIC number. Old format requires 9 digits followed by 'V' or 'X'. New format requires 12 digits.",INVALID_BIRTH_YEAR:()=>`Invalid birth year in the given NIC number. Old format requires a year between ${e.OLDEST_BIRTH_YEAR_FOR_VALID_NIC} and 1999 (inclusive). New format requires a year between ${e.OLDEST_BIRTH_YEAR_FOR_VALID_NIC} and the current year minus the minimum legal age (${e.MINIMUM_LEGAL_AGE_TO_HAVE_NIC}) to have an NIC (inclusive).`,INVALID_DAY_OF_YEAR:()=>"Invalid day of the year in the given NIC number. Must be between 001 and 365 or 366 (inclusive) for males, or 501 and 865 or 866 (inclusive) for females.",MINIMUM_AGE_REQUIREMENT_NOT_MET:()=>`Minimum age requirement not met in the given NIC number. The legal age to obtain an NIC in Sri Lanka is ${e.MINIMUM_LEGAL_AGE_TO_HAVE_NIC} years.`,ONLY_19XX_YEAR_NICS_CAN_BE_CONVERTED_TO_OLD_FORMAT:()=>"Only 19xx year NICs can be converted to OLD format"};class r extends Error{code;constructor(e){super(t[e]()),Object.setPrototypeOf(this,r.prototype),this.name="NICError",this.code=e}}const i=(e,t)=>Math.floor(Math.random()*(t-e+1))+e;var s=(e=>(e.OLD="old",e.NEW="new",e))(s||{}),n=(e=>(e.MALE="male",e.FEMALE="female",e))(n||{});const a={now(){const e=new Date,t=new Intl.DateTimeFormat("en-CA",{timeZone:"Asia/Colombo",year:"numeric",month:"numeric",day:"numeric",hourCycle:"h23"}).formatToParts(e),r=e=>Number(t.find(t=>t.type===e)?.value);return{year:r("year"),month:r("month"),day:r("day")}},dayInCurrentYear(){const e=this.now(),t=new Date(e.year,0,1),r=new Date(e.year,e.month-1,e.day);return Math.round((r.getTime()-t.getTime())/864e5)+1},isLeap:e=>e%4==0&&e%100!=0||e%400==0};class o{value;static Error=r;static Config=e;nic;_days;_year;_type;_gender;static STRUCTURE_OLD=/^[0-9]{9}[vVxX]$/;static STRUCTURE_NEW=/^[0-9]{12}$/;constructor(e,t,r,i,s){this.nic=e,this._type=t,this._gender=r,this._days=i,this._year=s,this.value=e}static sanitize(e){const t=o.validator(e);if(!t.success)throw t.error;return t.data.nic}static valid(e){return o.validate(e).valid}static validate(e){const t=o.validator(e);return t.success?{valid:!0}:{valid:!1,error:t.error}}static parse(e){const t=o.validator(e);if(!t.success)throw t.error;const{nic:r,type:i,gender:s,days:n,year:a}=t.data;return new o(r,i,s,n,a)}static random(){let e;const t=Math.random()<.5?s.OLD:s.NEW,r=Math.random()<.5?n.MALE:n.FEMALE,_=a.now().year-o.Config.MINIMUM_LEGAL_AGE_TO_HAVE_NIC;e=t===s.OLD?i(o.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC,1999):i(o.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC,_);let c=a.isLeap(e)?366:365;e===_&&(c=a.dayInCurrentYear());let E=i(1,c);r===n.FEMALE&&(E+=500);const u=String(e),h=String(E).padStart(3,"0"),I=String(i(1,999)).padStart(3,"0"),d=String(i(1,9));return t===s.OLD?`${u.slice(2)}${h}${I}${d}V`:`${u}${h}0${I}${d}`}convert(){if(this._type===s.OLD)return`${this.year}${this.days}0${this.serial}${this.checkdigit}`;if(this.nic.startsWith("19")){const e=this.year.slice(2),t=this.serial.slice(1);return`${e}${this.days}${t}${this.checkdigit}V`}throw new o.Error("ONLY_19XX_YEAR_NICS_CAN_BE_CONVERTED_TO_OLD_FORMAT")}get year(){return String(this._year)}get days(){return String(this._days).padStart(3,"0")}get serial(){return this._type===s.OLD?this.nic.substring(5,8):this.nic.substring(7,11)}get checkdigit(){return this._type===s.OLD?this.nic.substring(8,9):this.nic.substring(11,12)}get letter(){return this._type===s.OLD?this.nic.substring(9,10):null}get type(){return this._type}get gender(){return this._gender}get voter(){return this._type===s.NEW?null:"V"===this.letter}get birthday(){let e=[31,59,90,120,151,181,212,243,273,304,334,365];a.isLeap(this._year)&&(e=e.map((e,t)=>t>0?e+1:e));const t=this._days;let r=0,i=1,s=0;for(let n=0;n<e.length;n++){const a=e[n];if(!(t>a)){s=t-r;break}i++,r=a}return{year:this._year,month:i,day:s}}get age(){const e=a.now(),t=e.year,r=e.month,i=e.day,s=this.birthday;let n=t-s.year;const o=r-s.month,_=i-s.day;return(o<0||0===o&&_<0)&&n--,n}toString(){return this.nic}toJSON(){return{nic:this.nic,year:this.year,days:this.days,serial:this.serial,checkdigit:this.checkdigit,letter:this.letter,type:this.type,gender:this.gender,voter:this.voter,birthday:this.birthday,age:this.age}}static validator(e){if(e=e.trim().toUpperCase(),!o.STRUCTURE_OLD.test(e)&&!o.STRUCTURE_NEW.test(e))return{success:!1,error:new o.Error("INVALID_NIC_STRUCTURE")};const t=10===e.length,r=a.now().year-o.Config.MINIMUM_LEGAL_AGE_TO_HAVE_NIC;let i,_,c;if(t){if(i=1900+Number(e.substring(0,2)),i<o.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC)return{success:!1,error:new o.Error("INVALID_BIRTH_YEAR")}}else{const t=Number(e.substring(0,4));if(t<o.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC)return{success:!1,error:new o.Error("INVALID_BIRTH_YEAR")};if(t>r)return{success:!1,error:new o.Error("MINIMUM_AGE_REQUIREMENT_NOT_MET")};i=t}_=Number(t?e.substring(2,5):e.substring(4,7)),_>500?(_-=500,c=n.FEMALE):c=n.MALE;const E=a.isLeap(i)?366:365;if(_<1||_>E)return{success:!1,error:new o.Error("INVALID_DAY_OF_YEAR")};if(i===r&&_>a.dayInCurrentYear())return{success:!1,error:new o.Error("MINIMUM_AGE_REQUIREMENT_NOT_MET")};return{success:!0,data:{nic:e,type:t?s.OLD:s.NEW,gender:c,days:_,year:i}}}}exports.Gender=n,exports.NIC=o,exports.NICConfig=e,exports.NICError=r,exports.NICType=s;

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+export declare type Birthday = {
+    year: number;
+    month: number;
+    day: number;
+};
+
+declare type ErrorCodes = keyof typeof errors;
+
+declare const errors: {
+    INVALID_NIC_STRUCTURE: () => string;
+    INVALID_BIRTH_YEAR: () => string;
+    INVALID_DAY_OF_YEAR: () => string;
+    MINIMUM_AGE_REQUIREMENT_NOT_MET: () => string;
+    ONLY_19XX_YEAR_NICS_CAN_BE_CONVERTED_TO_OLD_FORMAT: () => string;
+};
+
+export declare enum Gender {
+    MALE = "male",
+    FEMALE = "female"
+}
+
+export declare class NIC {
+    /**
+     * The NIC number as a string.
+     */
+    readonly value: string;
+    static readonly Error: typeof NICError;
+    static readonly Config: typeof NICConfig;
+    private readonly nic;
+    private readonly _days;
+    private readonly _year;
+    private readonly _type;
+    private readonly _gender;
+    private static readonly STRUCTURE_OLD;
+    private static readonly STRUCTURE_NEW;
+    private constructor();
+    /**
+     * Cleans up the given NIC number by removing extra spaces and formatting it properly.
+     * Throws an error if the NIC is completely invalid.
+     *
+     * @param nic - The NIC number string.
+     * @returns The cleaned up NIC string.
+     */
+    static sanitize(nic: string): string;
+    /**
+     * Quickly checks if a given NIC number string is valid.
+     *
+     * @param nic - The NIC number string.
+     * @returns `true` if it's a valid NIC, otherwise `false`.
+     */
+    static valid(nic: string): boolean;
+    /**
+     * Detailed check to see if a NIC number is valid.
+     * Instead of throwing an error, it returns an object explaining what went wrong if it's invalid.
+     *
+     * @param nic - The NIC number string.
+     * @returns An object with `valid: true` or `valid: false` along with the specific error.
+     */
+    static validate(nic: string): {
+        valid: boolean;
+        error?: undefined;
+    } | {
+        valid: boolean;
+        error: NICError;
+    };
+    /**
+     * Reads a NIC string and extracts all the useful details from it like the birth year and gender.
+     * Throws an error if the NIC is invalid.
+     *
+     * @param nic - The NIC number string.
+     * @returns A completely populated `NIC` object.
+     */
+    static parse(nic: string): NIC;
+    /**
+     * Generates a completely valid, random NIC number.
+     * Great for testing and mocking data!
+     *
+     * @returns A random NIC string.
+     */
+    static random(): string;
+    /**
+     * Switches the NIC number between the old and new formats.
+     * Old format -> New format.
+     * New format -> Old format (Only works for birth years starting with 19xx).
+     *
+     * @returns The converted NIC number string.
+     */
+    convert(): string;
+    /**
+     * Full birth year (e.g. "1991" or "2001").
+     */
+    get year(): string;
+    /**
+     * The number of days passed in the birth year.
+     */
+    get days(): string;
+    /**
+     * The unique serial number assigned on the birth day.
+     */
+    get serial(): string;
+    /**
+     * The single check digit character of the NIC.
+     */
+    get checkdigit(): string;
+    /**
+     * The trailing letter of the old format NIC (usually "V" or "X").
+     * Returns null if it's a new format NIC.
+     */
+    get letter(): string | null;
+    /**
+     * Identifies whether the format is OLD or NEW.
+     */
+    get type(): NICType;
+    /**
+     * The gender (Male or Female) extracted from the NIC.
+     */
+    get gender(): Gender;
+    /**
+     * Identifies if the person is a registered voter.
+     * Only applicable for old format NICs (letter "V"), returns null for new ones.
+     */
+    get voter(): boolean | null;
+    /**
+     * The full date of birth separated into year, month, and day.
+     */
+    get birthday(): Birthday;
+    /**
+     * Calculates the person's current age in years.
+     */
+    get age(): number;
+    /**
+     * The plain NIC number string.
+     */
+    toString(): string;
+    /**
+     * Creates a neat summary object containing all the details of the NIC.
+     */
+    toJSON(): {
+        nic: string;
+        year: string;
+        days: string;
+        serial: string;
+        checkdigit: string;
+        letter: string | null;
+        type: NICType;
+        gender: Gender;
+        voter: boolean | null;
+        birthday: Birthday;
+        age: number;
+    };
+    private static validator;
+}
+
+export declare class NICConfig {
+    /**
+     * The minimum legal age to hold a NIC in Sri Lanka is 15 years.
+     * This value is used to validate the birth year.
+     * "Every person who is a citizen of Sri Lanka and who has attained or attains the age of 15 years shall apply for a National Identity card."
+     * @see https://drp.gov.lk/en/normal.php
+     */
+    static MINIMUM_LEGAL_AGE_TO_HAVE_NIC: number;
+    /**
+     * The oldest birth year considered valid. NICs with birth years before this are invalid.
+     */
+    static OLDEST_BIRTH_YEAR_FOR_VALID_NIC: number;
+}
+
+export declare class NICError extends Error {
+    readonly code: ErrorCodes;
+    constructor(code: ErrorCodes);
+}
+
+export declare enum NICType {
+    OLD = "old",
+    NEW = "new"
+}
+
+export declare type ValidatorResult = {
+    success: true;
+    data: {
+        nic: string;
+        type: NICType;
+        gender: Gender;
+        days: number;
+        year: number;
+    };
+} | {
+    success: false;
+    error: NICError;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1 @@
+class t{static MINIMUM_LEGAL_AGE_TO_HAVE_NIC=15;static OLDEST_BIRTH_YEAR_FOR_VALID_NIC=1901}const e={INVALID_NIC_STRUCTURE:()=>"Invalid NIC structure in the given NIC number. Old format requires 9 digits followed by 'V' or 'X'. New format requires 12 digits.",INVALID_BIRTH_YEAR:()=>`Invalid birth year in the given NIC number. Old format requires a year between ${t.OLDEST_BIRTH_YEAR_FOR_VALID_NIC} and 1999 (inclusive). New format requires a year between ${t.OLDEST_BIRTH_YEAR_FOR_VALID_NIC} and the current year minus the minimum legal age (${t.MINIMUM_LEGAL_AGE_TO_HAVE_NIC}) to have an NIC (inclusive).`,INVALID_DAY_OF_YEAR:()=>"Invalid day of the year in the given NIC number. Must be between 001 and 365 or 366 (inclusive) for males, or 501 and 865 or 866 (inclusive) for females.",MINIMUM_AGE_REQUIREMENT_NOT_MET:()=>`Minimum age requirement not met in the given NIC number. The legal age to obtain an NIC in Sri Lanka is ${t.MINIMUM_LEGAL_AGE_TO_HAVE_NIC} years.`,ONLY_19XX_YEAR_NICS_CAN_BE_CONVERTED_TO_OLD_FORMAT:()=>"Only 19xx year NICs can be converted to OLD format"};class r extends Error{code;constructor(t){super(e[t]()),Object.setPrototypeOf(this,r.prototype),this.name="NICError",this.code=t}}const i=(t,e)=>Math.floor(Math.random()*(e-t+1))+t;var s=/* @__PURE__ */(t=>(t.OLD="old",t.NEW="new",t))(s||{}),n=/* @__PURE__ */(t=>(t.MALE="male",t.FEMALE="female",t))(n||{});const a={now(){const t=/* @__PURE__ */new Date,e=new Intl.DateTimeFormat("en-CA",{timeZone:"Asia/Colombo",year:"numeric",month:"numeric",day:"numeric",hourCycle:"h23"}).formatToParts(t),r=t=>Number(e.find(e=>e.type===t)?.value);return{year:r("year"),month:r("month"),day:r("day")}},dayInCurrentYear(){const t=this.now(),e=new Date(t.year,0,1),r=new Date(t.year,t.month-1,t.day);return Math.round((r.getTime()-e.getTime())/864e5)+1},isLeap:t=>t%4==0&&t%100!=0||t%400==0};class _{value;static Error=r;static Config=t;nic;_days;_year;_type;_gender;static STRUCTURE_OLD=/^[0-9]{9}[vVxX]$/;static STRUCTURE_NEW=/^[0-9]{12}$/;constructor(t,e,r,i,s){this.nic=t,this._type=e,this._gender=r,this._days=i,this._year=s,this.value=t}static sanitize(t){const e=_.validator(t);if(!e.success)throw e.error;return e.data.nic}static valid(t){return _.validate(t).valid}static validate(t){const e=_.validator(t);return e.success?{valid:!0}:{valid:!1,error:e.error}}static parse(t){const e=_.validator(t);if(!e.success)throw e.error;const{nic:r,type:i,gender:s,days:n,year:a}=e.data;return new _(r,i,s,n,a)}static random(){let t;const e=Math.random()<.5?s.OLD:s.NEW,r=Math.random()<.5?n.MALE:n.FEMALE,o=a.now().year-_.Config.MINIMUM_LEGAL_AGE_TO_HAVE_NIC;t=e===s.OLD?i(_.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC,1999):i(_.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC,o);let c=a.isLeap(t)?366:365;t===o&&(c=a.dayInCurrentYear());let E=i(1,c);r===n.FEMALE&&(E+=500);const h=String(t),u=String(E).padStart(3,"0"),I=String(i(1,999)).padStart(3,"0"),d=String(i(1,9));return e===s.OLD?`${h.slice(2)}${u}${I}${d}V`:`${h}${u}0${I}${d}`}convert(){if(this._type===s.OLD)return`${this.year}${this.days}0${this.serial}${this.checkdigit}`;if(this.nic.startsWith("19")){const t=this.year.slice(2),e=this.serial.slice(1);return`${t}${this.days}${e}${this.checkdigit}V`}throw new _.Error("ONLY_19XX_YEAR_NICS_CAN_BE_CONVERTED_TO_OLD_FORMAT")}get year(){return String(this._year)}get days(){return String(this._days).padStart(3,"0")}get serial(){return this._type===s.OLD?this.nic.substring(5,8):this.nic.substring(7,11)}get checkdigit(){return this._type===s.OLD?this.nic.substring(8,9):this.nic.substring(11,12)}get letter(){return this._type===s.OLD?this.nic.substring(9,10):null}get type(){return this._type}get gender(){return this._gender}get voter(){return this._type===s.NEW?null:"V"===this.letter}get birthday(){let t=[31,59,90,120,151,181,212,243,273,304,334,365];a.isLeap(this._year)&&(t=t.map((t,e)=>e>0?t+1:t));const e=this._days;let r=0,i=1,s=0;for(let n=0;n<t.length;n++){const a=t[n];if(!(e>a)){s=e-r;break}i++,r=a}return{year:this._year,month:i,day:s}}get age(){const t=a.now(),e=t.year,r=t.month,i=t.day,s=this.birthday;let n=e-s.year;const _=r-s.month,o=i-s.day;return(_<0||0===_&&o<0)&&n--,n}toString(){return this.nic}toJSON(){return{nic:this.nic,year:this.year,days:this.days,serial:this.serial,checkdigit:this.checkdigit,letter:this.letter,type:this.type,gender:this.gender,voter:this.voter,birthday:this.birthday,age:this.age}}static validator(t){if(t=t.trim().toUpperCase(),!_.STRUCTURE_OLD.test(t)&&!_.STRUCTURE_NEW.test(t))return{success:!1,error:new _.Error("INVALID_NIC_STRUCTURE")};const e=10===t.length,r=a.now().year-_.Config.MINIMUM_LEGAL_AGE_TO_HAVE_NIC;let i,o,c;if(e){if(i=1900+Number(t.substring(0,2)),i<_.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC)return{success:!1,error:new _.Error("INVALID_BIRTH_YEAR")}}else{const e=Number(t.substring(0,4));if(e<_.Config.OLDEST_BIRTH_YEAR_FOR_VALID_NIC)return{success:!1,error:new _.Error("INVALID_BIRTH_YEAR")};if(e>r)return{success:!1,error:new _.Error("MINIMUM_AGE_REQUIREMENT_NOT_MET")};i=e}o=Number(e?t.substring(2,5):t.substring(4,7)),o>500?(o-=500,c=n.FEMALE):c=n.MALE;const E=a.isLeap(i)?366:365;if(o<1||o>E)return{success:!1,error:new _.Error("INVALID_DAY_OF_YEAR")};if(i===r&&o>a.dayInCurrentYear())return{success:!1,error:new _.Error("MINIMUM_AGE_REQUIREMENT_NOT_MET")};return{success:!0,data:{nic:t,type:e?s.OLD:s.NEW,gender:c,days:o,year:i}}}}export{n as Gender,_ as NIC,t as NICConfig,r as NICError,s as NICType};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@sri-lanka/nic",
+  "version": "1.0.0",
+  "description": "A lightweight library for parsing, validating, and generating Sri Lankan National Identity Card (NIC) numbers.",
+  "author": "Vinod Liyanage <vinodliyanage.me>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "sri-lanka",
+    "nic",
+    "national-identity-card",
+    "validator",
+    "parser",
+    "generator",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vinodliyanage/sri-lanka-nic"
+  },
+  "homepage": "https://nic.vinodliyanage.me",
+  "bugs": {
+    "url": "https://github.com/vinodliyanage/sri-lanka-nic/issues"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.4",
+    "@vitest/coverage-v8": "4.0.18",
+    "autoprefixer": "^10.4.24",
+    "lucide-react": "^0.564.0",
+    "postcss": "^8.5.6",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwindcss": "^4.1.18",
+    "terser": "^5.46.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build --config vite.lib.config.ts",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}