Configuration

You can pass an options object to NIC.parse(), NIC.validate(), or NIC.valid() to override default validation constraints and add custom rules.

Options

The options parameter accepts NICOptions, which combines two interfaces:

// Validation boundary overrides
interface NICConfig {
  minimumAge?: number;
  maximumAge?: number;
  minimumBirthYear?: number;
  maximumBirthYear?: number;
}
 
// Custom validation hooks and format restrictions
interface NICValidatorConfig {
  onlyNew?: boolean;
  onlyOld?: boolean;
  check?: (nic: NICInstance, NICError: typeof NICError) => void;
}
 
// Combined type used by parse(), validate(), and valid()
type NICOptions = NICConfig & NICValidatorConfig;

Age Constraints

Override the default age limits:

import { NIC } from "@sri-lanka/nic";
 
// Only accept NICs from people aged 18–65
NIC.parse("901404567V", {
  minimumAge: 18,
  maximumAge: 65,
});

Defaults:

Option	Default
`minimumAge`	`15` (legal age to hold a NIC)
`maximumAge`	Current year minus 1900

Birth Year Constraints

Restrict the accepted birth year range:

NIC.parse("901404567V", {
  minimumBirthYear: 1950,
  maximumBirthYear: 2005,
});

Defaults:

Option	New NIC	Old NIC
`minimumBirthYear`	`1900`	`1900`
`maximumBirthYear`	Current year minus 15	`1999`

Type Restrictions

Restrict validation to only accept a specific NIC format:

import { NIC } from "@sri-lanka/nic";
 
// Only accept new-format (12-digit) NICs
NIC.parse("200001501234", { onlyNew: true }); // ✅ passes
NIC.parse("901404567V", { onlyNew: true }); // ❌ throws NICError
 
// Only accept old-format (9-digit + letter) NICs
NIC.parse("901404567V", { onlyOld: true }); // ✅ passes
NIC.parse("200001501234", { onlyOld: true }); // ❌ throws NICError

This works with NIC.validate() and NIC.valid() too:

NIC.valid("901404567V", { onlyNew: true }); // false
NIC.valid("901404567V", { onlyOld: true }); // true

Custom Validation

Add your own rules with the check function. It runs after all built-in checks pass:

NIC.parse("200001501234", {
  check(nic, NICError) {
    // Only accept female NICs
    if (nic.gender !== "FEMALE") {
      throw new NICError("Only female NICs are accepted");
    }
 
    // Only accept people born after 1990
    if (nic.birthday.year < 1990) {
      throw new NICError("Birth year must be 1990 or later");
    }
  },
});

The check function receives:

nic — The parsed NIC object (same shape as what .parse() returns)
NICError — The error class to throw (so you get consistent error types)

Note: The check function only runs if all built-in validations pass first. If the NIC structure is invalid, your function won't be called.

Default Config

The NIC.defaultConfig getter returns the built-in validation boundaries for both NIC formats. This is useful for inspecting or logging the defaults:

import { NIC } from "@sri-lanka/nic";
 
console.log(NIC.defaultConfig.new);
// {
//   minimumAge: 15,
//   maximumAge: 126,        (current year - 1900)
//   minimumBirthYear: 1900,
//   maximumBirthYear: 2011, (current year - 15)
// }
 
console.log(NIC.defaultConfig.old);
// {
//   minimumAge: 15,
//   maximumAge: 126,        (current year - 1900)
//   minimumBirthYear: 1900,
//   maximumBirthYear: 1999, (fixed, old format is always 19XX)
// }

Note: maximumAge and maximumBirthYear (for new NICs) are computed from the current date, so they change each year.

PreviousValidation NextBuilder