MalaysiaIC

The MyKad library provides tools to validate, parse, generate, and format Malaysian Identity Card (MyKad) numbers.

Installation

Using npm:

npm install mykad

Using yarn:

yarn install mykad

Using pnpm:

pnpm install mykad

Using bun:

bun install mykad

Importing

import { isValid, parse, format, unformat, generateRandom } from 'malaysiaic';

Browser

<script src="browser/mykad.min.js"></script>

Features

Validation

MyKad numbers can be checked for validity. It ensures correct 12-digits, valid date of birth, and place of birth code.

if (isValid('560224108354')) {
  console.log('Valid MyKad number');
}

if (isValid('560224-10-8354')) {
  console.log('Also valid...');
}

// Not valid. Invalid date of birth and place of birth code.
isValid('561372-70-7953');

Formatting

MyKad numbers can be formatted to either have dash or without. Note that this simply formats without validation (date/place of birth code). You can use isValid() if you need to check for validity.

Format

try {
  const formatted = format('111013018934');
  console.log(formatted); // 111013-01-8934
} catch (error) {
  throw error; // Input error
}

Unformat

try {
  const unformatted = unformat('111013-01-8934');
  console.log(unformatted); // 111013018934
} catch (error) {
  throw error; // Input error
}

Generate

You can generate random MyKad numbers. All generate numbers are valid MyKad numbers.

const randomIcNum = generateRandom();
console.log(randomIcNum);

Parsing

MyKad numbers contain information about the holder's date of birth, place of birth, and gender. Date of birth assumes the age is under 100 years old. For example, the birth year '12' is 2012 instead of 1912.

try {
  const data = parse('890724-01-2498');
  console.log(data);
} catch (error) {
  throw error;
}

Parsed data is as the following:

{
    birthDate: new Date(1989, 6, 24),
    birthPlace: { region: 'SOUTHEAST_ASIA', country: 'MY', state: 'JHR' },
    gender: 'female'
}

Birthplace

State information is available for those born in Malaysia. For others, it either contains the specific country information or only an approximation of the region. However, some countries are uncategorized.

States

[
  'JHR',
  'KDH',
  'KTN',
  'MLK',
  'NSN',
  'PHG',
  'PNG',
  'PRK',
  'PLS',
  'SBH',
  'SWK',
  'SGR',
  'TRG',
  'KUL',
  'LBN',
  'PJY',
  'UNKNOWN_STATE',
];

Countries

Refer to ISO 3166-1 for country codes. Country codes can also contain these following status.

['FOREIGN_UNKNOWN', 'STATELESS', 'UNSPECIFIED'];

Region

Some codes for place of birth only contain information of the approximate region or some only an approximate country. The list of regions are the following:

[
  'SOUTHEAST_ASIA',
  'BRITISH_ISLES',
  'SOVIET_REPUBLIC',
  'EAST_ASIA',
  'SOUTH_ASIA',
  'AFRICA',
  'SOUTH_AMERICA',
  'CENTRAL_AMERICA',
  'OCEANIA',
  'MIDDLE_EAST',
  'EUROPE',
  'MIDDLE_AMERICA',
  'MISCELLANEOUS',
];

Known regions data contains the list of the countries as documented in the official registry. For example:

{
    region: 'NORTH_AMERICA',
    country: 'CA|GL|AN|PM|US',
    state: null
}

Gender

Gender information is provided in the form of the following values:

['male', 'female'];

Error handling

You can omit try/catch error handling when the inputted IC numbers are certain to be valid, such as after calling isValid(icNum) to verify the input.

if (isValid(icNum)) {
  format(icNum);
  unformat(icNum);
  parse(icNum);
}