malaysia-dev-kit

Malaysian developer utilities — MyKad, SSM, Address parsing and validation.

Utiliti pembangun Malaysia — penghurai dan pengesah MyKad, SSM, dan Alamat.

---

Why this exists

Every Malaysian software company building for government or enterprise clients ends up solving the same problems from scratch — parsing IC numbers, validating SSM registrations, normalising messy address strings. There has been no shared, well-maintained open source library for Malaysian-specific data formats.

malaysia-dev-kit fixes that. It is a small, excellent, zero-dependency TypeScript library that handles the most common Malaysian data parsing and validation tasks so you never have to write this code again.

Built and maintained by Obsidia Systems Sdn Bhd.

---

Features

Module	What it does
MyKad	Parse IC numbers — date of birth, gender, birth state, IC type (MyKad/MyPR), with or without dashes
SSM	Parse company registration numbers — old and new formats, entity type detection, normalisation
Address	Parse and normalise Malaysian addresses — abbreviation expansion, postcode lookup, state validation

Design principles:

• Zero runtime dependencies — installs clean, no supply chain risk
• Always returns a result — parse functions never throw for bad input; check isValid and errors
• Strongly typed — rich result objects, never just true/false
• Meaningful errors — every error tells you exactly what is wrong and why
• 100% test coverage — on every module

---

Installation

npm install @obsidia-my/malaysia-dev-kit
# or
yarn add @obsidia-my/malaysia-dev-kit
# or
pnpm add @obsidia-my/malaysia-dev-kit

Requirements: Node.js 18+ (also browser-compatible where possible)

---

Table of Contents

• MyKad — IC Number
• SSM — Company Registration
• Address
• Error Handling
• TypeScript Types
• Contributing
• Licence

---

MyKad — IC Number

Malaysian IC numbers follow the format YYMMDD-PB-XXXG. This module parses any variant — with dashes, without dashes, with extra whitespace — and returns fully structured data.

import { parseMyKad, isValidMyKad, getMyKadDateOfBirth } from '@obsidia-my/malaysia-dev-kit';

// Full parse
const ic = parseMyKad('900101-14-1234');

ic.isValid                      // true
ic.type                         // 'MYKAD'
ic.gender                       // 'MALE'
ic.dateOfBirth.formatted        // '01/01/1990'
ic.dateOfBirth.iso              // '1990-01-01'
ic.dateOfBirth.year             // 1990
ic.birthPlace.code              // '14'
ic.birthPlace.description       // 'Wilayah Persekutuan Kuala Lumpur'
ic.birthPlace.isMalaysia        // true
ic.normalised                   // '900101141234'
ic.formatted                    // '900101-14-1234'

// Input flexibility — all of these work
parseMyKad('900101141234')      // no dashes
parseMyKad('900101 14 1234')    // spaces
parseMyKad('  900101-14-1234 ') // leading/trailing whitespace

// Permanent resident (born abroad)
const pr = parseMyKad('850615-61-5678');
pr.type                         // 'MYPR'
pr.birthPlace.description       // 'Indonesia'
pr.birthPlace.isAbroad          // true

// Quick check
isValidMyKad('900101-14-1234')  // true
isValidMyKad('ABCDEFGHIJKL')    // false

// Just the date
getMyKadDateOfBirth('900101141234')  // Date(1990, 0, 1)

IC types

Type	Condition
MYKAD	Malaysian citizen, born in Malaysia
MYPR	Permanent resident (foreign birth code)
MYTENTERA	Armed forces
MYKID	Malaysian citizen below 12
UNKNOWN	Unrecognised birth place code

Functions

Function	Returns
parseMyKad(input)	MyKadParseResult
isValidMyKad(input)	boolean
getMyKadDateOfBirth(input)	Date | null
getMyKadGender(input)	'MALE' | 'FEMALE' | null
getMyKadBirthPlace(input)	MyKadParseResult['birthPlace']

Full MyKad documentation →

---

SSM — Company Registration

Handles both old format (123456-W) and new format (202001234567). Normalises messy input — lowercase suffixes, missing dashes, spaces.

import { parseSSM, isValidSSM, normaliseSSM } from '@obsidia-my/malaysia-dev-kit';

// New format (2017 onwards) — 12 digits, first 4 are the year
const co = parseSSM('202001234567');

co.isValid                      // true
co.format                       // 'NEW'
co.registrationYear             // 2020
co.entityType                   // 'SDN_BHD'
co.entityTypeDescription        // 'Sendirian Berhad'

// Old format — number + suffix letter
const co2 = parseSSM('123456-W');

co2.isValid                     // true
co2.format                      // 'OLD'
co2.entityType                  // 'SDN_BHD'
co2.suffix                      // 'W'

// Input normalisation — all of these resolve to '123456-W'
normaliseSSM('123456w')         // '123456-W'
normaliseSSM('123456W')         // '123456-W'
normaliseSSM('123456 w')        // '123456-W'

Old format suffixes

Suffix	Entity
-W	Sendirian Berhad (Sdn Bhd)
-X	Berhad (Bhd)
-H	LLP (Syarikat Perkongsian Liabiliti Terhad)
-K	Koperasi
-SA	Persatuan / Society
-D, -M, -T, -V, -A	Enterprise / Sole Proprietor

Functions

Function	Returns
parseSSM(input)	SSMParseResult
isValidSSM(input)	boolean
normaliseSSM(input)	string
getSSMEntityType(input)	SSMEntityType | null
getSSMFormat(input)	'OLD' | 'NEW' | 'UNKNOWN'

Full SSM documentation →

---

Address

Parses freeform Malaysian address strings into structured fields. Includes a complete static postcode dataset for all 16 states and federal territories.

import { parseAddress, normaliseAddress, validatePostcode } from '@obsidia-my/malaysia-dev-kit';

// Parse a messy real-world address string
const addr = parseAddress('No. 5, Jln Ampang, Tmn Ampang, 55000 KL, Selangor');

addr.isValid                    // false — postcode/state mismatch detected
addr.unit                       // 'No. 5'
addr.street                     // 'Jalan Ampang'   ← Jln expanded
addr.area                       // 'Taman Ampang'   ← Tmn expanded
addr.postcode                   // '55000'
addr.city                       // 'Kuala Lumpur'   ← from postcode dataset
addr.state                      // 'Wilayah Persekutuan Kuala Lumpur'
addr.stateCode                  // 'WP KL'
addr.postcodeValid              // true
addr.postcodeStateMatch         // false  ← 55000 is WP KL, not Selangor
addr.errors[0].code             // 'POSTCODE_STATE_MISMATCH'
addr.warnings[0].code           // 'ABBREVIATION_EXPANDED'

// Normalise only — quick clean-up
normaliseAddress('No. 5, Jln Ampang, Tmn Ampang, 55000 KL, Selangor')
// → 'No. 5, Jalan Ampang, Taman Ampang, 55000 Kuala Lumpur, Wilayah Persekutuan Kuala Lumpur'

// Postcode lookup
validatePostcode('50000')
// → { postcode: '50000', city: 'Kuala Lumpur', state: 'Wilayah Persekutuan Kuala Lumpur', stateCode: 'WP KL' }

validatePostcode('88000')
// → { postcode: '88000', city: 'Kota Kinabalu', state: 'Sabah', stateCode: 'SBH' }

// Postcode/state validation
postcodeMatchesState('50000', 'Wilayah Persekutuan Kuala Lumpur')  // true
postcodeMatchesState('50000', 'KL')                                // true  ← normalised
postcodeMatchesState('50000', 'Selangor')                          // false

Abbreviation expansion

Input	Expanded
Jln	Jalan
Tmn	Taman
Kg / Kpg	Kampung
Bdr	Bandar
Bkt	Bukit
Pst	Pusat
KL (standalone)	Kuala Lumpur
PJ	Petaling Jaya
JB	Johor Bahru
KK	Kota Kinabalu

Functions

Function	Returns
parseAddress(input)	AddressParseResult
normaliseAddress(input)	string
validatePostcode(postcode)	PostcodeEntry | null
getStateFromPostcode(postcode)	string | null
postcodeMatchesState(postcode, state)	boolean
formatAddress(parts)	string

Full Address documentation →

---

Error Handling

Parse functions never throw for invalid input — they always return a result object. Check isValid and errors.

const result = parseMyKad('not-an-ic');

result.isValid   // false
result.errors
// [
//   { code: 'INVALID_LENGTH', field: 'LENGTH', message: 'IC number must be 12 digits...' },
//   { code: 'INVALID_CHARACTERS', field: 'FORMAT', message: 'IC number must contain only numeric digits.' }
// ]

Functions do throw a MalaysiaDevKitError if you pass a non-string (programmer error):

import { MalaysiaDevKitError } from '@obsidia-my/malaysia-dev-kit';

try {
  parseMyKad(null);
} catch (e) {
  if (e instanceof MalaysiaDevKitError) {
    console.log(e.code);    // 'INVALID_INPUT_TYPE'
    console.log(e.module);  // 'MYKAD'
  }
}

---

TypeScript Types

All types are exported and fully documented.

import type {
  // MyKad
  MyKadParseResult,
  MyKadType,
  MyKadError,
  MyKadErrorCode,
  Gender,

  // SSM
  SSMParseResult,
  SSMFormat,
  SSMEntityType,
  SSMError,
  SSMErrorCode,

  // Address
  AddressParseResult,
  PostcodeEntry,
  AddressError,
  AddressWarning,
  AddressErrorCode,
  AddressWarningCode,
} from '@obsidia-my/malaysia-dev-kit';

---

Roadmap

Planned additions for future releases:

• Phone number — Malaysian mobile and landline parsing (+601X, 03-XXXX)
• Bank account — format validation for Maybank, CIMB, Public Bank, etc.
• Vehicle plate — Malaysian plate number parsing (state prefix, year)
• KWSP/EPF number — member number validation
• Business prefix lookup — Sdn Bhd, Bhd, LLP name suffix normalisation

PRs welcome. See CONTRIBUTING.md.

---

Contributing

See CONTRIBUTING.md for full guidelines.

Quick rules:

• Zero runtime dependencies — always
• 100% test coverage required for all new code
• Strict TypeScript — no any, no non-null assertions

---

Licence

MIT © 2026 Obsidia Systems Sdn Bhd