🇩🇿 DZ NIN Checker - Algerian National Identification Number Validator

📦 Available on npm: dz-nin-checker

Language: English | Français

The most comprehensive and accurate validator for Algerian National Identification Numbers (NIN)!

Built with the modified Luhn algorithm, this package offers ultra-robust validation, an interactive interface, and powerful features for your Algerian identity validation needs.

Features

Interactive Interface

• Interactive menu with 6 options
• Real-time validation with immediate feedback
• Detailed analysis with complete NIN breakdown
• Debug mode showing each step of the Luhn calculation
• Batch validation to process hundreds of NINs
• NIN generator for testing and development

Robust Validation

• Complete validation of Algerian NINs (18 digits)
• Modified Luhn algorithm for maximum accuracy
• Smart extraction (nationality, sex, year, municipality, etc.)
• Advanced error handling with explicit messages
• Automatic cleaning of spaces and unwanted characters

Developer-Friendly

• Full TypeScript support with strict types
• Optimized performance (0 external dependencies)
• Comprehensive tests (Mocha + Jest + Interactive tests)
• Exhaustive documentation with practical examples
• Simple and intuitive API for easy integration

Algerian NIN Format

The Algerian NIN consists of 18 digits structured as follows:

1 0 004 4567 89012 34 56
│ │  │   │     │   │  │
│ │  │   │     │   │  └── Control key (2 digits)
│ │  │   │     │   └───── Registration number (2 digits)  
│ │  │   │     └───────── Birth certificate number (5 digits)
│ │  │   └─────────────── Municipality/country code of birth (4 digits)
│ │  └─────────────────── Birth registration year (3 digits) *
│ └────────────────────── Sex (0=Male, 1=Female)
└──────────────────────── Nationality (1=Algerian, 2=Dual nationality)

* Note: This is the birth registration year, not necessarily the actual birth year.
  For presumed births, these two dates may differ.

Birth Registration Year Interpretation:

• First digit = 0: Add 2000 (e.g., 004 → 2004, 023 → 2023)
• First digit = 9: Add 1000 (e.g., 983 → 1983, 995 → 1995)
• Important: This is the registration year, not necessarily the actual birth year (presumed birth cases)

Nationality:

• Code 1: "Algerian nationality" (for both male and female)
• Code 2: "Dual nationality"

Concrete Examples

| NIN | Description | Nationality | Sex | Registration Year | |-----|-------------|-------------|------|-------------------| | 1000400000000000XX | Algerian male registered in 2004 | Algerian nationality | Male | 2004 | | 1199500000000000XX | Algerian female registered in 1995 | Algerian nationality | Female | 1995 | | 2098300000000000XX | Dual nationality registered in 1983 | Dual nationality | Male | 1983 |

Try It Now - Interactive Interface

Discover the power of DZ NIN Checker in seconds!

# Clone and test immediately
git clone https://github.com/itshakim213/dz-nin-checker.git
cd dz-nin-checker
npm install
npm run test:interactive

Perfect for:

• Developers: Test your integrations in real-time
• Businesses: Validate employee databases
• Students: Understand the Luhn algorithm
• Curious minds: Explore the structure of Algerian NINs

Installation

npm install dz-nin-checker

yarn add dz-nin-checker

pnpm add dz-nin-checker

Usage

Import

// ES6+ Modules
import { validateNIN, generateValidNIN, debugNIN } from 'dz-nin-checker';

// CommonJS
const { validateNIN, generateValidNIN, debugNIN } = require('dz-nin-checker');

Simple Validation

import { validateNIN } from 'dz-nin-checker';

const result = validateNIN('your-nin-here');

console.log(result.isValid); // true/false
console.log(result.nationality); // 'Algerian nationality' | 'Dual nationality' | 'Unknown'
console.log(result.sex); // 'Male' | 'Female' | 'Unknown'
console.log(result.year); // Birth registration year

Validation with Formatted Message

import { validateNINWithMessage } from 'dz-nin-checker';

const result = validateNINWithMessage('your-nin-here');
console.log(result.message); 
// "✅ Valid NIN - Algerian nationality Male born in 2004"
// or "❌ Invalid control key. Expected: 47, Provided: 02"

Batch Validation

import { validateMultipleNINs } from 'dz-nin-checker';

const nins = ['nin1', 'nin2', 'nin3'];
const results = validateMultipleNINs(nins);

results.forEach((result, index) => {
  console.log(`NIN ${index + 1}: ${result.isValid ? '✅' : '❌'}`);
  console.log(result.message);
});

Generate Valid NIN

import { generateValidNIN } from 'dz-nin-checker';

// Generate a valid NIN from the first 16 digits
const validNIN = generateValidNIN('1000400000000000');
console.log(validNIN); // "1000400000000000XX" (XX = calculated key)
// Male, Algerian nationality, registered in 2004

Debug Mode

import { debugNIN } from 'dz-nin-checker';

const debug = debugNIN('your-nin-here');

console.log(debug.components); // Details of each component
console.log(debug.validation); // Validation information
console.log(debug.calculation.steps); // Key calculation steps

API Reference

validateNIN(nin: string): NINDetails

Validates a NIN and returns complete details.

Parameters:

• nin (string): The NIN to validate (18 digits, spaces allowed)

Returns:

interface NINDetails {
  raw: string;                    // Cleaned NIN
  nationality: string;            // "Algerian nationality" | "Dual nationality" | "Unknown"
  sex: string;                    // "Male" | "Female" | "Unknown"
  year: string;                   // Birth registration year (e.g., "2004", "1983")
                                  // Note: not necessarily the actual birth year (presumed cases)
  communeOrCountry: string;       // Municipality/country code
  birthAct: string;               // Birth certificate number
  registerNumber: string;         // Registration number
  controlKey: string;             // Provided control key
  calculatedKey: string;          // Calculated control key
  isValid: boolean;               // NIN validity
  error?: string;                 // Error message if invalid
}

validateNINWithMessage(nin: string): ValidationResult

Validates a NIN and returns a formatted message.

validateMultipleNINs(nins: string[]): ValidationResult[]

Validates multiple NINs in a single operation.

generateValidNIN(base16Digits: string): string

Generates a valid NIN from the first 16 digits.

debugNIN(nin: string)

Detailed analysis of a NIN with debugging information.

Tests & Demonstration

Interactive Interface (Recommended)

The most immersive experience to discover DZ NIN Checker

npm run test:interactive

Interface features:

• Single validation: Test a NIN with complete analysis
• Multiple validation: Process multiple NINs at once
• Debug mode: See each step of the Luhn calculation in detail
• Generator: Create valid NINs from a base
• Demonstration: Predefined tests with various examples
• Quit: Clean exit from the application

Why try the interactive interface?

• Intuitive interface: No need to code to test
• Visual feedback: Colored and formatted results
• Learning: Understand the Luhn algorithm step by step
• Speed: Test hundreds of NINs in seconds
• Creativity: Generate NINs for your tests

Automated Tests

# Complete unit tests (Mocha)
npm test

# Tests with Jest
npm run test:jest

# Batch tests (Mocha)
npm run test:batch

# Code coverage
npm run test:coverage

Test coverage:

• 23 unit tests covering all use cases
• Integration tests with 50+ randomly generated NINs
• Robustness tests (invalid NINs, incorrect formats)
• Performance tests and Luhn algorithm validation

Algorithm

The validator uses the Luhn algorithm:

1. Right-to-left processing of the first 16 digits
2. Alternation: multiplication by 2 for every second digit
3. Reduction: if result > 9, subtract 9
4. Sum of all processed digits
5. Modulo 10 of the sum
6. Key = 10 - remainder (or 0 if remainder = 0)

Development

Setup

git clone https://github.com/itshakim213/dz-nin-checker.git
cd dz-nin-checker
npm install

Available Scripts

• npm run build - Compile TypeScript
• npm run test - Run unit tests
• npm run test:watch - Tests in watch mode
• npm run lint - ESLint check
• npm run clean - Clean dist folder

Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Thanks to the Algerian developer community
• Inspired by international identifier validation standards

Ready to Get Started?

3 steps to discover DZ NIN Checker:

1. Installation: npm install dz-nin-checker
2. Interactive test: npm run test:interactive
3. Integration: Use the API in your project!

Why choose DZ NIN Checker?

• Maximum accuracy with the Luhn algorithm
• Interactive interface to test without coding
• Optimized performance (0 dependencies)
• Complete documentation with practical examples
• Exhaustive tests (23+ unit tests)
• Native TypeScript for perfect integration

Support

• Issues: GitHub Issues
• Email: [email protected]
• LinkedIn: Sid Ali Ikhlef
• Discussions: GitHub Discussions

Keywords

Algeria NIN validator, Algerian National Identification Number, NIN validation, Luhn algorithm, Algeria identity verification, Algerian ID checker, birth registration year, CNIBE validator, DZ NIN, Algerian national ID, identity validation Algeria, NIN verifier, Algerian citizenship verification, dual nationality Algeria, TypeScript NIN validator

🇩🇿 DZ NIN Checker - The reference validator for Algerian NINs

Developed with ❤️ for the Algerian developer community