codice-fiscale-ts/build/index.d.ts

A TypeScript library for calculating, validating, and decoding Italian Fiscal Codes (Codice Fiscale)

export declare interface BasePerson {
    firstName: string;
    lastName: string;
    birthDate: Date;
    gender: 'M' | 'F';
}

export declare type BilingualMunicipality = [
...ItalianMunicipality,
italianName: string,
foreignName: string
];

/**
 * Calculate the check character (last character) of the fiscal code
 * @param code - The first 15 characters of the fiscal code
 * @returns The check character
 * @example
 * calculateCheckCharacter("RSSMRA90A15H501"); // Returns a check character like "X"
 */
export declare function calculateCheckCharacter(code: string): string;

/**
 * Calculate the day and gender code according to fiscal code rules
 * @param date - The date to extract the day from
 * @param gender - The gender ('M' for male, 'F' for female)
 * @returns Two-digit code representing day and gender (for females, 40 is added to the day)
 * @example
 * calculateDayGenderCode(new Date(1990, 0, 15), 'M'); // Returns "15"
 * calculateDayGenderCode(new Date(1990, 0, 15), 'F'); // Returns "55"
 */
export declare function calculateDayGenderCode(date: Date, gender: 'M' | 'F'): string;

/**
 * Calculate the three letters code for a first name according to fiscal code rules
 * @param firstName - The first name to encode
 * @returns Three-letter code representing the first name
 * @example
 * calculateFirstNameCode("Mario"); // Returns "MRA"
 * calculateFirstNameCode("Luca"); // Returns "LCU"
 */
export declare function calculateFirstNameCode(firstName: string): string;

/**
 * Calculate the complete fiscal code for a person
 * @param person - Object containing person's data
 * @returns The complete 16-character fiscal code
 * @example
 * await calculateFiscalCode(\{
 *   firstName: "Mario",
 *   lastName: "Rossi",
 *   gender: "M",
 *   birthDate: new Date(1990, 0, 15),
 *   birthPlace: "ROMA"
 * \}); // Returns something like "RSSMRA90A15H501X"
 * @throws If the person data is invalid
 */
export declare function calculateFiscalCode(person: Person): Promise<string>;

/**
 * Calculate the three letters code for a last name according to fiscal code rules
 * @param lastName - The last name to encode
 * @returns Three-letter code representing the last name
 * @example
 * calculateLastNameCode("Rossi"); // Returns "RSS"
 * calculateLastNameCode("Bo"); // Returns "BOX"
 */
export declare function calculateLastNameCode(lastName: string): string;

/**
 * Calculate the letter code for the month according to fiscal code rules
 * @param date - The date to extract the month from
 * @returns Single letter representing the month
 * @example
 * calculateMonthCode(new Date(1990, 0, 1)); // Returns "A" (for January)
 */
export declare function calculateMonthCode(date: Date): string;

/**
 * Calculate the two-digit year code from a date
 * @param date - The date to extract the year from
 * @returns Two-digit year code (last two digits of the year)
 * @example
 * calculateYearCode(new Date(1990, 0, 1)); // Returns "90"
 */
export declare function calculateYearCode(date: Date): string;

export declare type Country = [cadastralCode: string, alpha2: string];

/**
 * Decode the birth day from the fiscal code's day component
 * @param dayCode - Two-digit day code from the fiscal code
 * @returns Day of month (1-31)
 * @example
 * decodeDay(15); // Returns 15
 * decodeDay(55); // Returns 15 (for females)
 */
export declare function decodeDay(dayCode: number): number;

/**
 * Decode a fiscal code to extract available information
 * @param fiscalCode - The fiscal code to decode
 * @returns Object containing decoded information (birth date, gender, place)
 * @example
 * await decodeFiscalCode("RSSMRA90A15H501X");
 * // Returns \{
 * //   birthDate: new Date(1990, 0, 15),
 * //   gender: "M",
 * //   birthPlace: "ROMA",
 * //   birthProvince: "RM"
 * // \}
 * @throws If the fiscal code is invalid
 */
export declare function decodeFiscalCode(fiscalCode: string): Promise<FiscalCodeData>;

/**
 * Decode the birth month from the fiscal code's month component
 * @param monthCode - One letter month code from the fiscal code
 * @returns Month number (1-12)
 * @example
 * decodeMonth("A"); // Returns 1 (January)
 */
export declare function decodeMonth(monthCode: string): number;

/**
 * Decode the birth year from the fiscal code's year component
 * @param yearCode - Two-digit year code from the fiscal code
 * @returns Full year (4 digits)
 * @example
 * decodeYear("90"); // Returns 1990 (or could be 2090 depending on current year)
 */
export declare function decodeYear(yearCode: string): number;

/**
 * Helper function to extract consonants from a string
 * @param str - The string to extract consonants from
 * @returns A string containing only the consonants
 * @example
 * extractConsonants("Hello"); // Returns "HLL"
 */
export declare function extractConsonants(str: string): string;

/**
 * Helper function to extract vowels from a string
 * @param str - The string to extract vowels from
 * @returns A string containing only the vowels
 * @example
 * extractVowels("Hello"); // Returns "EO"
 */
export declare function extractVowels(str: string): string;

export declare type FiscalCodeData = {
    birthDate?: Date;
    gender?: 'M' | 'F';
    firstName?: string;
    lastName?: string;
    birthPlace?: string;
    birthProvince?: string;
    foreignCountry?: string;
};

export declare interface ForeignPerson extends BasePerson {
    foreignCountry: string;
    birthPlace?: never;
}

/**
 * Get the country code from ISO Alpha2 country code
 * @param countryCode - The ISO Alpha2 country code (e.g., "US", "FR")
 * @returns The cadastral code for the country (Z followed by three digits)
 * @example
 * await getCountryCode("US"); // Returns "Z404"
 * @throws If the country code is invalid
 */
export declare function getCountryCode(countryCode: string): Promise<string>;

/**
 * Get all supported foreign countries (ISO Alpha2). Italy is not included.
 * @returns Array of countries with cadastral code and ISO Alpha2 code.
 * @example
 * ```ts
 * const countries = await getForeignCountries();
 * console.log(countries); // [['Z001', 'FR'], ['Z002', 'DE']]
 * ```
 */
export declare function getForeignCountries(): Promise<Country[]>;

/**
 * Get cadastral code from place name or cadastral code
 * @param place - The name of the municipality or its cadastral code
 * @returns The cadastral code for the municipality
 * @example
 * await getMunicipalCodeFromPlace("ROMA"); // Returns "H501"
 * await getMunicipalCodeFromPlace("H501"); // Returns "H501"
 * @throws If the place is not found
 */
export declare function getMunicipalCodeFromPlace(place: string): Promise<string>;

/**
 * Get all Italian municipalities.
 * @returns Array of municipalities with cadastral code, name, province
 * If the municipality is bilingual, the cadastral code will be followed by
 * the italian name and the foreign name.
 * @example
 * ```ts
 * const municipalities = await getMunicipalities();
 * console.log(municipalities); // [['001', 'ROMA', 'RM'], ['002', 'BOLZANO', 'BZ', 'BOLZANO', 'BOZEN']]
 * ```
 */
export declare function getMunicipalities(): Promise<Municipality[]>;

/**
 * Gets municipality information by code
 * @param code - The cadastral code to lookup
 * @returns Municipality data
 * @example
 * await getMunicipalityByCode("H501"); // Returns ["H501", "ROMA", "RM"]
 * @throws If the municipality code is invalid
 */
export declare function getMunicipalityByCode(code: string): Promise<Municipality>;

/**
 * Type guard to check if a person is a foreign person
 */
export declare function isForeignPerson(person: Person): person is ForeignPerson;

/**
 * Type guard to check if a person is an Italian person
 */
export declare function isItalianPerson(person: Person): person is ItalianPerson;

/**
 * Validates if a string is a valid fiscal code
 * @param fiscalCode - The fiscal code to validate
 * @returns True if the fiscal code is valid, false otherwise
 * @example
 * isValidFiscalCode("RSSMRA90A15H501X"); // Returns true if valid
 * isValidFiscalCode("INVALID"); // Returns false
 */
export declare function isValidFiscalCode(fiscalCode: string): boolean;

export declare type ItalianMunicipality = [
cadastralCode: string,
name: string,
province: string
];

export declare interface ItalianPerson extends BasePerson {
    birthPlace: string;
    foreignCountry?: 'IT' | undefined;
}

export declare type Municipality = ItalianMunicipality | BilingualMunicipality;

/**
 * Normalize a string by removing spaces, accents and special characters
 * @param str - The string to normalize
 * @returns Normalized string in uppercase without spaces or accents
 * @example
 * normalizeString("D'Août-Martin"); // Returns "DAOUTMARTIN"
 */
export declare function normalizeString(str: string): string;

export declare type Person = ItalianPerson | ForeignPerson;

/**
 * Validates that a person object has all required fields and follows the correct format
 * @throws Error if the person object is invalid
 */
export declare function validatePerson(person: Person): void;

export { }