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

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

import { CINFormatOptions, CINFormatResult } from '../types/cin';
/**
 * Error class for CIN (Citizen Identification Number) formatting errors.
 * Used to throw specific formatting-related errors during CIN processing.
 *
 * @extends Error
 */
export declare class CINFormattingError extends Error {
    constructor(message: string);
}
/**
 * A comprehensive formatter for Citizen Identification Numbers (CIN) with extensive configuration options.
 * Provides various formatting capabilities including:
 * - Case formatting (upper/lower)
 * - Digit grouping with custom separators
 * - Region and issuing office inclusion
 * - Custom templates
 * - Masking for sensitive information
 *
 * @example
 * ```typescript
 * const formatter = new CINFormatter({
 *   addSpaces: true,
 *   letterCase: 'upper',
 *   includeRegion: true
 * });
 * const result = formatter.format('ABC123456');
 * ```
 */
export declare class CINFormatter {
    private options;
    private static readonly DEFAULT_OPTIONS;
    /**
     * Creates a new instance of CINFormatter with specified options.
     *
     * @param {CINFormatOptions} options - Configuration options for CIN formatting
     * @throws {CINFormattingError} When provided options are invalid
     */
    constructor(options?: CINFormatOptions);
    /**
     * Validate formatting options
     */
    private validateOptions;
    /**
     * Validate template string format
     */
    private isValidTemplate;
    /**
     * Formats a CIN string according to the specified options.
     *
     * @param {unknown} cin - The CIN to format (can be string, number, or other types)
     * @returns {CINFormatResult} Formatted result containing the formatted CIN and metadata
     *
     * @throws {CINFormattingError} When formatting fails due to invalid input or options
     *
     * @example
     * ```typescript
     * const result = formatter.format('ABC123456');
     * console.log(result.formatted); // Formatted CIN
     * console.log(result.metadata); // Additional formatting metadata
     * ```
     */
    format(cin: unknown): CINFormatResult;
    /**
     * Apply formatting according to options
     */
    private applyFormatting;
    /**
     * Format letter case according to options
     */
    private formatLetterCase;
    /**
     * Format sequence according to digit grouping options
     */
    private formatSequence;
    /**
     * Apply template formatting
     */
    private applyTemplate;
    /**
     * Apply masking to sensitive digits
     */
    private applyMasking;
    /**
     * Find indexes of digits in formatted string
     */
    private findDigitIndexes;
    /**
     * Calculate number of masked digits
     */
    private calculateMaskedDigits;
    /**
     * Get detailed validation information
     */
    private getValidationDetails;
}
/**
 * Utility function to format a CIN with various display options.
 * Provides a simplified interface to the CINFormatter class.
 *
 * @param {unknown} cin - The CIN to format
 * @param {CINFormatOptions} options - Formatting options
 * @returns {CINFormatResult} Formatted result containing the formatted CIN and metadata
 *
 * @example
 * ```typescript
 * const result = formatCIN('ABC123456', { addSpaces: true });
 * console.log(result.formatted);
 * ```
 */
export declare function formatCIN(cin: unknown, options?: CINFormatOptions): CINFormatResult;
/**
 * Generates all possible standard format variations of a CIN.
 * Useful for displaying different formatting options or for comparison purposes.
 *
 * @param {unknown} cin - The CIN to format
 * @returns {Record<string, string> | null} Object containing different format variations,
 *                                         or null if the input CIN is invalid
 *
 * @example
 * ```typescript
 * const formats = getAllCINFormats('ABC123456');
 * if (formats) {
 *   console.log(formats.standard);    // Basic format
 *   console.log(formats.withSpaces);  // Format with spaces
 *   console.log(formats.masked);      // Masked format
 * }
 * ```
 */
export declare function getAllCINFormats(cin: unknown): Record<string, string> | null;