zellige.js/lib/validators/cin.d.ts

A Moroccan utility library for working with CIN, phone numbers, currency, addresses, dates, and more.

import { CINRegionPrefix } from '../constants/regions';
import { CINValidationResult } from '../types/cin';
/**
 * Sanitizes a CIN (Carte d'Identité Nationale) input string by removing whitespace and special characters
 *
 * @param input - Raw CIN input that needs to be sanitized
 * @returns Sanitized uppercase string or null if input is invalid
 *
 * @example
 * ```typescript
 * sanitizeCIN('A 123456'); // Returns 'A123456'
 * sanitizeCIN('BE-789.012'); // Returns 'BE789012'
 * sanitizeCIN(null); // Returns null
 * ```
 */
export declare function sanitizeCIN(input: unknown): string | null;
/**
 * Performs comprehensive validation of a Moroccan CIN (Carte d'Identité Nationale)
 *
 * @param cin - The CIN string to validate
 * @returns Validation result containing status, errors, and metadata if valid
 *
 * @example
 * ```typescript
 * validateCIN('A123456');
 * // Returns {
 * //   isValid: true,
 * //   errors: [],
 * //   metadata: {
 * //     region: 'Rabat',
 * //     sequence: '123456',
 * //     issuingOffice: 'A'
 * //   }
 * // }
 *
 * validateCIN('XX999999');
 * // Returns {
 * //   isValid: false,
 * //   errors: [{
 * //     code: CINErrorCode.INVALID_REGION,
 * //     message: 'Invalid region prefix: XX'
 * //   }]
 * // }
 * ```
 */
export declare function validateCIN(cin: unknown): CINValidationResult;
/**
 * Quick check to determine if a string is a valid Moroccan CIN
 *
 * @param cin - The CIN string to check
 * @returns True if the CIN is valid, false otherwise
 *
 * @example
 * ```typescript
 * isValidCIN('A123456'); // Returns true
 * isValidCIN('XX999999'); // Returns false
 * isValidCIN('12345'); // Returns false
 * ```
 */
export declare function isValidCIN(cin: unknown): boolean;
/**
 * Retrieves the region name associated with a CIN prefix
 *
 * @param prefix - The CIN prefix (1-3 letters) to look up
 * @returns The full region name or null if the prefix is invalid
 *
 * @example
 * ```typescript
 * getCINRegion('A'); // Returns 'Rabat'
 * getCINRegion('BK'); // Returns 'Casablanca'
 * getCINRegion('XX'); // Returns null
 * ```
 */
export declare function getCINRegion(prefix: string): string | null;
/**
 * Generates a random valid CIN for testing purposes
 *
 * @param prefix - Optional specific region prefix to use
 * @returns A valid CIN string
 *
 * @example
 * ```typescript
 * generateTestCIN(); // Returns random CIN like 'A123456'
 * generateTestCIN('BK'); // Returns random CIN starting with 'BK'
 * ```
 */
export declare function generateTestCIN(prefix?: CINRegionPrefix): string;