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

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

import { PassportComponents, PassportErrorCode, ValidationOptions, ValidationResult } from '../types/passport';
/**
 * Custom error class for passport validation failures
 * @class
 * @extends Error
 * @description
 * Specialized error class that includes both an error code and message.
 * Useful for catching and handling specific validation errors.
 *
 * @example
 * ```typescript
 * try {
 *   validatePassport('invalid');
 * } catch (error) {
 *   if (error instanceof PassportValidationError) {
 *     console.log(error.code); // Access the error code
 *   }
 * }
 * ```
 */
export declare class PassportValidationError extends Error {
    code: PassportErrorCode;
    constructor(code: PassportErrorCode, message: string);
}
/**
 * Normalizes a passport number by removing spaces and converting to uppercase
 * @param {string} passport - Raw passport number to normalize
 * @throws {PassportValidationError} If input is not a string or exceeds max length
 * @returns {string} Normalized passport number
 *
 * @example
 * ```typescript
 * const normalized = normalizePassport('ab 123 456'); // Returns 'AB123456'
 * ```
 */
export declare function normalizePassport(passport: string): string;
/**
 * Checks if a given string is a valid Moroccan passport number
 * @param passport - The passport number to validate
 * @param options - Validation options
 * @returns boolean indicating validity
 */
export declare function isValidPassport(passport: string, options?: ValidationOptions): boolean;
/**
 * Comprehensive passport validation with detailed feedback
 * @param {string} passport - The passport number to validate
 * @param {ValidationOptions} [options=DEFAULT_OPTIONS] - Validation options
 * @returns {ValidationResult} Detailed validation result
 *
 * @example
 * ```typescript
 * const result = validatePassport('AB123456');
 * if (!result.isValid) {
 *   console.log(result.errors); // Array of validation errors
 * }
 * ```
 *
 * @security
 * - Implements input length restrictions to prevent DOS attacks
 * - Sanitizes input through normalization
 * - Provides detailed error feedback without exposing system details
 *
 * @performance
 * - O(n) time complexity where n is input length
 * - Early returns for invalid inputs
 * - Optimized regex patterns
 */
export declare function validatePassport(passport: string, options?: ValidationOptions): ValidationResult;
/**
 * Formats a passport number to the standard format
 * @param passport - The passport number to format
 * @param separator - Optional separator between prefix and number
 * @returns Formatted passport number or null if invalid
 */
export declare function formatPassport(passport: string, separator?: string): string | null;
/**
 * Generates a random valid Moroccan passport number
 * @param options - Generation options
 * @returns A valid passport number
 */
export declare function generateRandomPassport(options?: {
    prefix?: string;
    avoiding?: Set<string>;
}): string;
/**
 * Extracts and validates components of a passport number
 * @param passport - The passport number to analyze
 * @returns PassportComponents object or null if invalid
 */
export declare function extractPassportComponents(passport: string): PassportComponents | null;
/**
 * Checks if two passport numbers are equivalent (accounting for formatting)
 * @param passport1 - First passport number
 * @param passport2 - Second passport number
 * @returns boolean indicating if passports are equivalent
 */
export declare function arePassportsEquivalent(passport1: string, passport2: string): boolean;