🇿🇦 @mzantsi/id-verifier

A lightweight, dependency-free South African ID number validator and parser with a fluent API.

Built for correctness, clarity, and real-world usage.

✨ Features

• ✅ Validates South African ID numbers
• 🔍 Parses birth date, gender, and citizenship
• 🧮 Calculates age correctly
• 🧱 Fluent (builder-style) API
• ⚡ Zero dependencies
• 📦 ESM + CJS support
• 🧾 Strict TypeScript types

📦 Installation

pnpm add @mzantsi/id-verifier
# or
npm install @mzantsi/id-verifier
# or
yarn add @mzantsi/id-verifier

🚀 Quick Start

import { id } from "@mzantsi/id-verifier";

const person = id("8001015009087");

if (person.isValid()) {
  console.log(person.parse());
  console.log("Age:", person.age());
}

🧠 What is a South African ID?

A South African ID number is a 13-digit string:

YYMMDD SSSS C A Z

| Part | Meaning | | -------- | ------------------------------------------------- | | YYMMDD | Date of birth | | SSSS | Gender (0000–4999 female, 5000–9999 male) | | C | Citizenship (0 = citizen, 1 = permanent resident) | | A | Usually 8 or 9 | | Z | Luhn checksum |

This library validates all of the above, including the checksum.

🧱 Fluent API (recommended)

Validate

id("8001015009087").isValid(); // true | false

Parse

const parsed = id("8001015009087").parse();

if (parsed) {
  console.log(parsed.birthDate);
  console.log(parsed.gender);
  console.log(parsed.citizenship);
}

Age calculation

const age = id("8001015009087").age(); // number | null

Age is calculated correctly based on the current date (birthday-aware).

Strict mode

Throw immediately if invalid:

id("123").assertValid().parse();

Useful in trusted or internal flows.

🔧 Functional API (alternative)

If you prefer plain functions:

import { verifyId, parseId } from "@mzantsi/id-verifier";

verifyId("8001015009087"); // boolean

parseId("8001015009087");
/*
{
  isValid: true,
  birthDate: Date,
  gender: "male",
  citizenship: "citizen"
}
*/

📄 Example script

See examples/example.ts:

import { id } from "../src";

const person = id("8001015009087");

console.log("Valid:", person.isValid());
console.log("Parsed:", person.parse());
console.log("Age:", person.age());

Run it with:

pnpm add -D tsx
pnpm tsx examples/example.ts

🛡️ Edge cases handled

• ❌ Invalid dates (e.g. 991332)
• 📆 Leap years (Feb 29 handled correctly)
• 🧮 Proper Luhn checksum validation
• 🕰️ Correct century resolution (1900 vs 2000)
• 🪪 Citizenship digit validation

📐 Design philosophy

• No external validation libraries
• One source of truth for validation
• Explicit over implicit
• Safe defaults, strict when requested

This library is intentionally small and boring — because identity validation should be.

🧪 Testing

Tests are not bundled yet. The logic is deterministic and designed to be easily testable.

(Contributions welcome.)

📜 License

MIT © Gradiate OSS

🤝 Contributing

Issues and PRs are welcome. If you’re extending this, please keep the API small and predictable.