Welcome to the comprehensive Node.js and TypeScript library for processing Egyptian National IDs.

Built with scalability, extreme edge-case handling, and Developer Experience (DX) in mind, egypt-natid is a reliable processing layer for modern Web and Backend applications whether you are building a Fintech KYC system, an E-commerce platform, a Healthcare app, or a vast HR database.

✨ Why Choose This Core?

• ⚡ Extreme Performance: Highly optimized algorithms capable of processing and validating 100,000+ IDs in milliseconds.
• 🛡️ Strict Structural Validation: Goes far beyond regex. It performs deep mathematical validations including string length constraints, positive integer verification, absolute date-of-birth existence, rigorous century logics, and finalizes with the sophisticated Modulo 11 Checksum Algorithm. This ensures the ID is structurally valid according to the publicly known Egyptian National ID format and mathematical rules.
• 🎛️ Advanced Recursive Filtering: Instantly sift through thousands of users! Search, map, and filter massive Arrays or Objects by age, exact birth dates, governorates, regions, or gender using our blazing fast case-insensitive filter engine.
• 🚀 100% Type-Safe (TypeScript): Built from the ground up in strict TypeScript to provide beautiful exact autocomplete, extensive types (Governorate, NationalIdAnalysis), and absolute peace of mind.
• 🛠️ All-in-One Toolkit: Stop relying on 10 different snippets! Enjoy built-in Parsers, Generators (for your E2E tests), Bulk Statistical Analyzers, flexible Data Extractors, and even a global CLI Interface!
• 🎨 Drop-in Form Schemas: Ship faster! We expose ready-to-use Regex patterns and structured error maps that seamlessly plug directly into zod, yup, or React Hook Form.

🆚 Why Not Just Use Regex?

If you rely solely on Regular Expressions to validate Egyptian National IDs, you are leaving your database vulnerable to fake, yet structurally plausible numbers.

Regex CANNOT: ❌ Verify the Modulo 11 Checksum (The mathematical secret that proves the ID digits are coherent). ❌ Validate that the Date of Birth actually exists (e.g., preventing February 30th). ❌ Accurately calculate the user's Age or extract demographic data. ❌ Perform Bulk Filtering or Statistical Aggregation.

egypt-natid is not a simple regex utility; it is a full Data-Processing Framework built specifically for the Egyptian National ID.

📦 Installation

Install via your favorite package manager:

npm install egypt-natid
# or
yarn add egypt-natid
# or
pnpm add egypt-natid

📖 Table of Contents

1. Basic Usage
2. Data Processing (Core)
3. Helper Utilities
4. Generating Dummy IDs
5. Form Validation (Regex)
6. CLI Capabilities

1. Basic Usage (Parsing & Validating)

🧐 Validating an ID

Need to know if an ID is structurally valid and passes mathematical rules?

import { validate } from "egypt-natid";

const isValid = validate("30201011234557");
console.log(isValid); // false (Invalid check digit!)

const isValid2 = validate("29912010112341");
console.log(isValid2); // true

� Sanitizing IDs

If your users input IDs containing spaces, dashes, or Arabic numerals (٠-٩), you can effortlessly clean the string before processing.

import { sanitize } from "egypt-natid";

const dirtyId = " 301050-501755٩٧ ";
const cleanId = sanitize(dirtyId);

console.log(cleanId); // "30105050175597"

�🧠 Parsing an ID

Extract all demographic information hidden inside the National ID securely.

import { parse } from "egypt-natid";

const data = parse("30105050175597"); 
/* 
Returns:
{
  nationalId: "30105050175597",
  birthDate: 2001-05-05T00:00:00.000Z, // Date Object
  birthYear: 2001,
  birthMonth: 5,
  birthDay: 5,
  age: 24, // Dynamically calculated based on the current year
  gender: "Male",
  governorate: { code: 1, name: "Cairo", nameAr: "القاهرة", region: "Cairo" },
  region: "Cairo",
  insideEgypt: true,
  isAdult: true // >= 18
}
*/

2. Data Processing (Core)

If your database returns an array of thousands of IDs, the processing module allows you to filter, map, and analyze them blazingly fast.

🔍 Filtering

The filter function is incredibly flexible and case-insensitive. You can pass raw arrays of strings, or arrays of Objects!

import { filter } from "egypt-natid";

const staffIds = ["30105050175597", "29912010112341", "invalid_id_here"];

// Get only Males
const males = filter(staffIds, { gender: "male" }); // Case-insensitive!

// Get adults (18+) from Alexandria
const alexAdults = filter(staffIds, { 
    region: "alexandria", 
    ageFrom: 18 
});

🎛️ Available Filter Properties

You can mix and match any of these properties inside your filter object!

| Property | Type | Description | |-----------|---------|-------------| | isAdult | boolean | Find people above or equal to 18 years old. | | gender | "Male" \| "Female" | Filter by gender (Case-insensitive 🪄). | | region | string | Filter by a single region (e.g. "Cairo", "Delta"). | | regions | string[] | Filter by multiple regions ["Cairo", "Canal"]. | | governorateCode | number | Filter by a specific Governorate code (e.g., 1 for Cairo). | | governorates | number[] | Filter by an array of codes [1, 2, 88]. | | birthYear | number | People born in a specific year (1999). | | birthYearFrom | number | People born starting from a year (2000). | | birthYearTo | number | People born up to a year (2010). | | birthDateFrom | Date | People born after an exact JavaScript Date object. | | birthDateTo | Date | People born before an exact JavaScript Date object. | | ageFrom | number | Minimum age required. | | ageTo | number | Maximum age limit. | | insideEgypt | boolean | Whether they were born inside Egypt or abroad (code 88). |

Filtering Arrays of Objects? No problem. Just specify the key holding the ID!

const database = [
  { id: 1, fullname: "Ahmed", nid: "30105050175597" },
  { id: 2, fullname: "Mona", nid: "29912010112341" }
];

const menOfCairo = filter(database, { 
    key: "nid", // The property containing the ID
    gender: "male",
    region: "cairo" 
});

console.log(menOfCairo); // Returns the full Objects! [{ id: 1, fullname: "Ahmed", nid: "..." }]

🗺️ Mapping with Analysis

Sometimes you want to attach the extracted data directly to your Original Dataset! Use mapWithAnalysis. It safely ignores items with invalid IDs instead of crashing!

import { mapWithAnalysis } from "egypt-natid";

const enrichedData = mapWithAnalysis(database, "nid");
/* 
Returns a combined Object array:
[{
    id: 1, 
    fullname: "Ahmed", 
    nid: "30105050175597",
    analysis: { age: 24, gender: "Male", governorate: {...} } // The newly attached parse!
}]
*/

📊 Bulk Statistics

Get instant demographics from an array of IDs. It safely skips invalid IDs without crashing.

import { stats } from "egypt-natid";

const report = stats(staffIds);
/*
Returns:
{
  total: 2,
  adults: 2,
  males: 1,
  females: 1,
  averageAge: 24.5,
  governoratesDistribution: { "Cairo": 1, "Alexandria": 1 },
  insideEgypt: 2,
  outsideEgypt: 0
}
*/

3. Helper Utilities

Sometimes you just want a simple boolean answer without dealing with whole payload objects.

import { 
    isMale, 
    isFemale, 
    isAdult, 
    isInsideEgypt, 
    isFromGovernorate, 
    isFromRegion 
} from "egypt-natid";

const id = "30105050175597";

isMale(id); // true
isAdult(id); // true
isInsideEgypt(id); // true
isFromRegion(id, "Cairo"); // true

4. Generating Dummy IDs (For Testing)

If you are unit testing your application, you can programmatically generate 100% mathematically valid National IDs!

⚠️ Disclaimer: Generated IDs are for testing purposes only and do not correspond to real individuals.

import { generateId } from "egypt-natid";

const randomId = generateId(); // Totally random valid ID

const specificId = generateId({ 
    gender: "Female", 
    birthYear: 1999, 
    governorateCode: 2 // Alexandria
});

console.log(specificId); // 299XXXX02XXXXX (Valid modulo 11 Checksum)

⚖️ Legal Notice

This library validates and parses Egyptian National IDs based solely on publicly known structural rules and mathematical algorithms. It does NOT verify identities against any governmental authority or official database. The authors are not affiliated with any Egyptian government entity.

5. Form Validation (Regex)

Building a React, Vue, or Angular Frontend? We expose the strict validation tools.

import { NationalIdRegex, NationalIdSchemaMap } from "egypt-natid";

// 1. Raw Regex Usage
const isValid = NationalIdRegex.test("30105050175597");

// 2. Drop it in Zod!
import { z } from "zod";
const schema = z.string().regex(NationalIdSchemaMap.pattern, { 
    message: NationalIdSchemaMap.errorMessage 
});

6. CLI Capabilities

Did you know this package comes with a CLI tool?

If you install this toolkit globally (npm install -g egyptian-national-id), or run it via npx, you can use it right in your terminal!

# Validate an ID
npx egyid validate 30105050175597

# Analyze an ID directly in your terminal
npx egyid analyze 30105050175597

# Generate a mock ID for testing
npx egyid generate --female --year 1995 --gov 1

# Filter through multiple IDs in your console
npx egyid filter 30105050175597 29912010112341 --gender male --region cairo

# Get instant analytics on a dataset of IDs
npx egyid stats 30105050175597 29912010112341

👨‍💻 Author

Mahmoud Ebeid

• 💼 LinkedIn
• 🐙 GitHub

Designed with ❤️ to make Egyptian Software Engineering much easier.