declare enum EGender {
    Male = "male",
    Female = "female",
    Unisex = "unisex"
}
declare enum ERegion {
    North = "north",
    Central = "central",
    South = "south"
}
declare enum EEra {
    Traditional = "traditional",
    Modern = "modern"
}
declare enum EMeaningCategory {
    Strength = "strength",
    Virtue = "virtue",
    Nature = "nature",
    Precious = "precious",
    Beauty = "beauty",
    Celestial = "celestial",
    Season = "season",
    Intellect = "intellect",
    Prosperity = "prosperity"
}
type TWeightedEntry = {
    value: string;
    weight: number;
};
type TGivenNameEntry = {
    value: string;
    meaning?: string;
    sinoVietnamese?: string;
    category?: EMeaningCategory;
};
declare enum ENameFormat {
    Full = "full",
    Abbreviated = "abbreviated",
    Reversed = "reversed",
    Slug = "slug"
}
type TNameStyle = 'japanese' | 'korean' | 'western' | 'hybrid';
declare enum EFormality {
    WrittenFormal = "written-formal",
    SpokenFormal = "spoken-formal",
    Professional = "professional",
    Casual = "casual",
    Intimate = "intimate"
}
declare enum EHonorificCategory {
    Royal = "royal",
    Mandarin = "mandarin",
    Scholar = "scholar",
    Family = "family",
    AgeBased = "age-based",
    Professional = "professional",
    Religious = "religious",
    GenZ = "genz",
    Regional = "regional"
}
declare enum EReligion {
    Buddhism = "buddhism",
    Catholicism = "catholicism",
    CaoDai = "cao-dai",
    HoaHao = "hoa-hao",
    Folk = "folk"
}
declare enum EFeudalRank {
    Emperor = "emperor",
    Consort = "consort",
    Prince = "prince",
    Princess = "princess",
    Nobility = "nobility",
    Mandarin = "mandarin",
    Scholar = "scholar"
}
interface IPronounPair {
    self: string;
    addressee: string;
}
interface IAddressOptions {
    familyRelation?: string;
    role?: string;
    speakerAge?: number;
    addresseeAge?: number;
    gender?: EGender;
    formality?: EFormality;
    region?: ERegion;
    era?: EEra;
    religion?: EReligion;
    seed?: number;
}
interface IAddressResult {
    honorific: string;
    addressTerm: string;
    fullAddress: string;
    pronounPair: IPronounPair;
    category: EHonorificCategory;
    formality: EFormality;
    region: ERegion;
}
interface ITitleEntry {
    title: string;
    sinoVietnamese?: string;
    era: EEra | 'all';
    gender?: EGender | 'any';
    description?: string;
}
interface IKinshipTerm {
    term: string;
    relation: string;
    generation: number;
    side?: 'paternal' | 'maternal';
    gender: EGender | 'any';
    regionVariants?: Partial<Record<ERegion, string>>;
}
type TGenerateOptions = {
    gender?: EGender;
    region?: ERegion;
    era?: EEra;
    compoundName?: boolean;
    meaningCategory?: EMeaningCategory;
    withMiddleName?: boolean;
    seed?: number;
    format?: ENameFormat | ENameFormat[];
    style?: TNameStyle;
    secure?: boolean;
};
interface IRomanizedName {
    surname: string;
    middleName: string;
    givenName: string;
    fullName: string;
}
interface INameParts {
    surname: string;
    middleName: string;
    givenName: string;
    fullName: string;
    romanized: IRomanizedName;
}
interface IParsedName {
    surname: string;
    middleName: string;
    givenName: string;
    fullName: string;
}
interface IValidationResult {
    valid: boolean;
    reasons: string[];
}
interface IGenderResult {
    gender: EGender | "unknown";
    confidence: "high" | "medium" | "low";
    signals: {
        middleName?: {
            gender: EGender | "unknown";
            value: string;
        };
        givenName?: {
            gender: EGender | "unknown";
            value: string;
        };
    };
}
interface INameResult extends INameParts {
    gender: EGender;
    region: ERegion;
    era: EEra;
    formatted: Partial<Record<ENameFormat, string>>;
}

/**
 * Generate a random Vietnamese name with full cultural metadata.
 *
 * @param options - Generation options including gender, region, era, seed, style, format, and more
 * @returns A complete name result with surname, middle name, given name, romanized forms, formatted variants, and metadata
 * @example
 * ```typescript
 * const name = generate({ gender: EGender.Female, region: ERegion.South, seed: 42 });
 * // { surname: 'Nguyễn', middleName: 'Thị', givenName: 'Mai', fullName: 'Nguyễn Thị Mai', ... }
 * ```
 */
declare function generate(options?: TGenerateOptions): INameResult;
/**
 * Generate a random Vietnamese full name as a single string.
 *
 * @param options - Generation options including gender, region, era, seed, style, and more
 * @returns The full Vietnamese name string (e.g. "Nguyễn Văn An")
 * @example
 * ```typescript
 * const name = generateFullName({ gender: EGender.Male, region: ERegion.North });
 * // 'Trần Văn Hùng'
 * ```
 */
declare function generateFullName(options?: TGenerateOptions): string;
/**
 * Generate multiple unique Vietnamese names at once.
 *
 * @param count - Number of unique names to generate (must be greater than 0)
 * @param options - Generation options including gender, region, era, seed, and more
 * @returns An array of unique name results with full metadata
 * @throws {Error} If count is less than or equal to 0, or if unique name space is exhausted
 * @example
 * ```typescript
 * const names = generateMany(3, { gender: EGender.Female, era: EEra.Modern });
 * // [{ fullName: 'Lê Thị Hà' }, { fullName: 'Phạm Thị Linh' }, { fullName: 'Võ Thị Ngọc' }]
 * ```
 */
declare function generateMany(count: number, options?: TGenerateOptions): INameResult[];
/**
 * Generate multiple unique Vietnamese full names as plain strings.
 *
 * @param count - Number of unique names to generate (must be greater than 0)
 * @param options - Generation options including gender, region, era, seed, and more
 * @returns An array of unique full name strings
 * @throws {Error} If count is less than or equal to 0, or if unique name space is exhausted
 * @example
 * ```typescript
 * const names = generateManyFullNames(3, { region: ERegion.Central, seed: 100 });
 * // ['Nguyễn Văn Bình', 'Trần Thị Lan', 'Lê Hoàng Nam']
 * ```
 */
declare function generateManyFullNames(count: number, options?: TGenerateOptions): string[];

/**
 * Convert Vietnamese text with diacritics to plain ASCII (romanized form).
 * Removes all tone marks and accent characters while preserving the base letters.
 * Handles the special Vietnamese characters Đ/đ.
 *
 * @param input - Vietnamese string with diacritics (e.g. "Nguyễn Văn Ân")
 * @returns {string} ASCII string with all diacritics and tone marks removed
 * @example
 * ```typescript
 * romanize('Nguyễn Văn Ân');
 * // 'Nguyen Van An'
 *
 * romanize('Đặng Thị Hồng');
 * // 'Dang Thi Hong'
 * ```
 */
declare function romanize(input: string): string;

/**
 * Format a Vietnamese name into the specified display format.
 *
 * Supports full name, abbreviated (initials + given name), reversed (Western order),
 * and URL-safe slug formats.
 *
 * @param parts - The name parts including surname, middle name, given name, and romanized forms
 * @param format - The desired output format (Full, Abbreviated, Reversed, or Slug)
 * @returns The formatted name string
 * @example
 * ```typescript
 * const parts = { surname: 'Nguyễn', middleName: 'Thị', givenName: 'Mai', fullName: 'Nguyễn Thị Mai', romanized: { surname: 'Nguyen', middleName: 'Thi', givenName: 'Mai', fullName: 'Nguyen Thi Mai' } };
 * formatName(parts, ENameFormat.Abbreviated); // 'N.T. Mai'
 * formatName(parts, ENameFormat.Slug);        // 'nguyen-thi-mai'
 * ```
 */
declare function formatName(parts: INameParts, format: ENameFormat): string;

/**
 * Parse a Vietnamese full name into structured parts (surname, middle name, given name).
 * Handles compound surnames (e.g. "Tôn Thất", "Tôn Nữ") and romanized input.
 *
 * @param input - Full Vietnamese name string to parse
 * @returns {IParsedName} Parsed name with surname, middleName, givenName, and fullName fields
 * @example
 * ```typescript
 * parseName('Nguyễn Văn An');
 * // { surname: 'Nguyễn', middleName: 'Văn', givenName: 'An', fullName: 'Nguyễn Văn An' }
 *
 * parseName('Tôn Thất Minh Đức');
 * // { surname: 'Tôn Thất', middleName: 'Minh', givenName: 'Đức', fullName: 'Tôn Thất Minh Đức' }
 * ```
 */
declare function parseName(input: string): IParsedName;

/**
 * Validate whether a string is a well-formed Vietnamese name.
 * Checks for non-empty input, Vietnamese alphabet characters, proper capitalization,
 * known surname, and reasonable part count (2-6 parts).
 *
 * @param input - Full Vietnamese name string to validate
 * @returns {IValidationResult} Object with `valid` boolean and `reasons` array describing any failures
 * @example
 * ```typescript
 * validateName('Nguyễn Thị Mai');
 * // { valid: true, reasons: [] }
 *
 * validateName('xyz An');
 * // { valid: false, reasons: ['Unknown surname: xyz'] }
 * ```
 */
declare function validateName(input: string): IValidationResult;

/**
 * Detect the likely gender of a Vietnamese name by analyzing middle name and given name signals.
 * Middle names carry the strongest signal (e.g. "Thị" is exclusively female, "Văn" is exclusively male).
 *
 * @param input - A Vietnamese full name string (e.g. "Nguyễn Thị Mai")
 * @returns {IGenderResult} Object with gender ('male' | 'female' | 'unisex' | 'unknown'),
 *   confidence ('high' | 'medium' | 'low'), and per-component signals
 * @example
 * ```typescript
 * detectGender('Nguyễn Thị Mai');
 * // { gender: 'female', confidence: 'high', signals: { middleName: { gender: 'female', value: 'Thị' }, ... } }
 *
 * detectGender('Trần Văn Minh');
 * // { gender: 'male', confidence: 'high', signals: { middleName: { gender: 'male', value: 'Văn' }, ... } }
 * ```
 */
declare function detectGender(input: string): IGenderResult;

interface IEmailResult {
    email: string;
    name: INameResult;
}
type TEmailOptions = TGenerateOptions & {
    domain?: string;
};
/**
 * Generate a realistic email address from a randomly generated Vietnamese name.
 * Supports custom domain and all standard generation options (gender, region, era, seed).
 *
 * @param options - Optional generation options including custom domain and name generation params
 * @returns Object containing the generated email and the full name result
 * @example
 * ```typescript
 * generateEmail({ domain: 'company.vn', seed: 42 });
 * // { email: 'minh.nguyen@company.vn', name: { fullName: 'Nguyen Van Minh', ... } }
 * generateEmail();
 * // { email: 'lan.tran@gmail.com', name: { fullName: 'Tran Thi Lan', ... } }
 * ```
 */
declare function generateEmail(options?: TEmailOptions): IEmailResult;

interface IUsernameResult {
    username: string;
    name: INameResult;
}
/**
 * Generate a username from a randomly generated Vietnamese name using common
 * username patterns (dot-separated, underscore, initial+surname, etc.).
 *
 * @param options - Optional generation options (gender, region, era, seed)
 * @returns Object containing the generated username and the full name result
 * @example
 * ```typescript
 * generateUsername({ seed: 42 });
 * // { username: 'minh_nguyen', name: { fullName: 'Nguyen Van Minh', ... } }
 * generateUsername();
 * // { username: 'lan.tran', name: { fullName: 'Tran Thi Lan', ... } }
 * ```
 */
declare function generateUsername(options?: TGenerateOptions): IUsernameResult;

interface ISurnameInfo {
    surname: string;
    found: boolean;
    frequency: Record<string, number>;
    rank: Record<string, number>;
    isCompound: boolean;
    regionalVariants?: {
        north?: string;
        south?: string;
    };
}
/**
 * Look up detailed information about a Vietnamese surname, including regional
 * frequency weights, rank, compound status, and North/South variants.
 *
 * @param surname - Vietnamese surname to look up (e.g. "Nguyen", "Hoang", "Vo")
 * @returns Surname info with frequency, rank, compound flag, and regional variants
 * @example
 * ```typescript
 * getSurnameInfo('Nguyen');
 * // { surname: 'Nguyen', found: true, frequency: { north: 38, south: 40 }, rank: { north: 1, south: 1 }, ... }
 * getSurnameInfo('Hoang');
 * // { ..., regionalVariants: { south: 'Huynh' } }
 * ```
 */
declare function getSurnameInfo(surname: string): ISurnameInfo;

/**
 * Convert a Vietnamese surname to its regional variant (e.g. Hoang <-> Huynh, Vu <-> Vo).
 * Returns the original surname if no variant exists for the target region.
 * Supports both diacritical and romanized (ASCII) input.
 *
 * @param surname - Vietnamese surname to convert (e.g. "Hoang", "Vu")
 * @param targetRegion - Target region to get the variant for
 * @returns The regional variant of the surname, or the original if no variant exists
 * @example
 * ```typescript
 * getRegionalVariant('Hoang', ERegion.South); // 'Huynh'
 * getRegionalVariant('Vu', ERegion.South);    // 'Vo'
 * getRegionalVariant('Tran', ERegion.North);  // 'Tran' (no variant)
 * ```
 */
declare function getRegionalVariant(surname: string, targetRegion: ERegion): string;

type TGenderOption = 'male' | 'female';
/**
 * A faker.js-compatible adapter for generating Vietnamese person and internet data.
 * Provides `person` (firstName, lastName, middleName, fullName, sex, prefix) and
 * `internet` (email, username) namespaces with the same API shape as faker.js.
 *
 * @example
 * ```typescript
 * fakerVi.person.fullName({ gender: 'female' }); // 'Tran Thi Lan'
 * fakerVi.person.firstName('male');               // 'Minh'
 * fakerVi.internet.email();                       // 'lan.tran@gmail.com'
 * fakerVi.internet.username();                    // 'minh_nguyen'
 * ```
 */
declare const fakerVi: {
    person: {
        firstName(gender?: TGenderOption): string;
        lastName(): string;
        middleName(gender?: TGenderOption): string;
        fullName(options?: {
            gender?: TGenderOption;
        }): string;
        sex(): TGenderOption;
        prefix(gender?: TGenderOption): string;
    };
    internet: {
        email(options?: {
            firstName?: string;
            lastName?: string;
        }): string;
        username(options?: {
            firstName?: string;
            lastName?: string;
        }): string;
    };
};

interface ISimilarityResult {
    score: number;
    exactMatch: boolean;
    romanizedMatch: boolean;
    details: {
        surnameMatch: boolean;
        givenNameMatch: boolean;
        middleNameMatch: boolean;
    };
}
/**
 * Compare two Vietnamese names and compute a similarity score (0.0 to 1.0).
 * Handles word order permutations, romanized/diacritical mismatches, regional
 * surname variants (e.g. Vo/Vu), and missing middle names.
 *
 * @param name1 - First Vietnamese full name
 * @param name2 - Second Vietnamese full name to compare against
 * @returns Similarity result with score, match flags, and per-part match details
 * @example
 * ```typescript
 * nameSimilarity('Nguyen Van Minh', 'Nguyen Van Minh');
 * // { score: 1, exactMatch: true, romanizedMatch: true, details: { ... } }
 * nameSimilarity('Vo Thi Lan', 'Vu Thi Lan');
 * // { score: 0.94, exactMatch: false, romanizedMatch: false, details: { surnameMatch: true, ... } }
 * ```
 */
declare function nameSimilarity(name1: string, name2: string): ISimilarityResult;

interface INameMeaning {
    name: string;
    found: boolean;
    category?: string;
    genders: string[];
    regions: string[];
    eras: string[];
    isCompound: boolean;
}
/**
 * Look up cultural metadata for a Vietnamese given name, including which genders,
 * regions, and eras it appears in, and whether it is a compound name.
 *
 * @param name - Vietnamese given name to look up (e.g. "Minh", "Thanh Huong")
 * @returns Name meaning result with gender/region/era usage and compound status
 * @example
 * ```typescript
 * getMeaning('Minh');
 * // { name: 'Minh', found: true, genders: ['male','female'], regions: ['north','south'], ... }
 * getMeaning('xyz');
 * // { name: 'xyz', found: false, genders: [], regions: [], eras: [], isCompound: false }
 * ```
 */
declare function getMeaning(name: string): INameMeaning;

interface IStatisticsResult {
    totalSurnames: number;
    totalGivenNames: number;
    totalCompoundNames: number;
    totalMiddleNames: number;
}
interface IRankedName {
    name: string;
    weight?: number;
    count?: number;
}
/**
 * Get a high-level overview of the built-in Vietnamese name dataset, returning
 * counts of unique surnames, given names, compound names, and middle names.
 *
 * @returns Statistics object with totals for each name category
 * @example
 * ```typescript
 * getStatistics();
 * // { totalSurnames: 150, totalGivenNames: 800, totalCompoundNames: 120, totalMiddleNames: 30 }
 * ```
 */
declare function getStatistics(): IStatisticsResult;
/**
 * Get the top N most common Vietnamese surnames ranked by frequency weight.
 * When a region is specified, uses that region's weights; otherwise averages across all regions.
 *
 * @param options - Optional filters: region ('north'|'central'|'south') and limit (default 10)
 * @returns Array of ranked surname entries sorted by weight descending
 * @example
 * ```typescript
 * getTopSurnames({ limit: 3 });
 * // [{ name: 'Nguyen', weight: 38.4 }, { name: 'Tran', weight: 11.2 }, ...]
 * getTopSurnames({ region: 'south', limit: 2 });
 * // [{ name: 'Nguyen', weight: 40.1 }, { name: 'Tran', weight: 10.8 }]
 * ```
 */
declare function getTopSurnames(options?: {
    region?: string;
    limit?: number;
}): IRankedName[];
/**
 * Count given names in the dataset, optionally filtered by gender, region, and/or era.
 * Returns the total count across all matching combinations.
 *
 * @param options - Optional filters: gender ('male'|'female'), region ('north'|'central'|'south'), era
 * @returns Number of given name entries matching the filters
 * @example
 * ```typescript
 * getGivenNameCount({ gender: 'female', region: 'north' });
 * // 245
 * getGivenNameCount();
 * // 1800 (total across all combinations)
 * ```
 */
declare function getGivenNameCount(options?: {
    gender?: string;
    region?: string;
    era?: string;
}): number;
/**
 * Get a sorted list of unique given names from the dataset, optionally filtered
 * by gender and limited to a maximum number of results.
 *
 * @param options - Optional filters: gender ('male'|'female') and result limit
 * @returns Alphabetically sorted array of unique Vietnamese given names
 * @example
 * ```typescript
 * getUniqueGivenNames({ gender: 'female', limit: 3 });
 * // ['An', 'Anh', 'Bach']
 * getUniqueGivenNames({ limit: 5 });
 * // ['An', 'Anh', 'Bach', 'Bao', 'Binh']
 * ```
 */
declare function getUniqueGivenNames(options?: {
    gender?: string;
    limit?: number;
}): string[];

/**
 * Regular expression that matches strings containing only Unicode letters and whitespace.
 * Used to validate that a Vietnamese name contains no digits, punctuation, or special characters.
 *
 * @example
 * ```typescript
 * VIETNAMESE_NAME_REGEX.test('Nguyễn Văn An'); // true
 * VIETNAMESE_NAME_REGEX.test('Nguyen123');      // false
 * ```
 */
declare const VIETNAMESE_NAME_REGEX: RegExp;
/**
 * Normalize a Vietnamese string to NFC (canonical composition) form.
 * Ensures consistent Unicode representation for comparison and storage.
 *
 * @param input - Vietnamese string to normalize
 * @returns {string} NFC-normalized string
 * @example
 * ```typescript
 * normalize('Nguyễn'); // 'Nguyễn' (NFC form)
 * ```
 */
declare function normalize(input: string): string;
/**
 * Check whether a query string appears within a text, ignoring Vietnamese diacritics and tone marks.
 * Both strings are romanized and lowercased before comparison.
 *
 * @param text - The text to search within
 * @param query - The substring to search for
 * @returns {boolean} True if the romanized query is found within the romanized text
 * @example
 * ```typescript
 * accentInsensitiveMatch('Nguyễn Văn An', 'nguyen'); // true
 * accentInsensitiveMatch('Trần Thị Mai', 'thi');     // true
 * ```
 */
declare function accentInsensitiveMatch(text: string, query: string): boolean;
/**
 * Check whether two strings are equal when ignoring Vietnamese diacritics and tone marks.
 * Both strings are romanized and lowercased before comparison.
 *
 * @param a - First string to compare
 * @param b - Second string to compare
 * @returns {boolean} True if both strings are identical after romanization and lowercasing
 * @example
 * ```typescript
 * accentInsensitiveEqual('Nguyễn', 'Nguyen'); // true
 * accentInsensitiveEqual('Đặng', 'Dang');     // true
 * ```
 */
declare function accentInsensitiveEqual(a: string, b: string): boolean;

type TFormality = 'formal' | 'casual' | 'professional';
interface ISalutationOptions {
    gender?: 'male' | 'female';
    formality?: TFormality;
}
interface ISalutationResult {
    salutation: string;
    honorific: string;
    addressName: string;
    fullSalutation: string;
}
/**
 * Generate a Vietnamese salutation/honorific for a person based on their name,
 * gender, and formality level. Automatically detects gender from the name if not provided.
 *
 * @deprecated Use addressCalculate() for the full honorific system with age-based pronouns, professional titles, and regional variants.
 * @param fullName - Vietnamese full name (e.g. "Nguyen Van Minh")
 * @param options - Optional settings: gender ('male'|'female') and formality ('formal'|'casual'|'professional')
 * @returns Salutation result with honorific, address name, and full salutation string
 * @example
 * ```typescript
 * salutation('Nguyen Van Minh', { formality: 'formal' });
 * // { salutation: 'Ong Minh', honorific: 'Ong', addressName: 'Minh', fullSalutation: 'Kinh gui Ong Minh' }
 * salutation('Tran Thi Lan', { formality: 'casual' });
 * // { salutation: 'Chi Lan', honorific: 'Chi', addressName: 'Lan', fullSalutation: 'Chi Lan' }
 * ```
 */
declare function salutation(fullName: string, options?: ISalutationOptions): ISalutationResult;

/**
 * Calculate the appropriate Vietnamese address term, honorific, and pronoun pair for a person.
 *
 * Uses a priority-based decision tree: professional role first, then age-based lookup,
 * then gender/formality fallback.
 *
 * @param fullName - The full Vietnamese name to address (e.g. "Nguyễn Văn An")
 * @param options - Address options including role, speaker/addressee ages, gender, formality, and region
 * @returns An address result with honorific, address term, full address phrase, pronoun pair, and metadata
 * @example
 * ```typescript
 * const result = addressCalculate('Nguyễn Văn An', { speakerAge: 25, addresseeAge: 50, formality: EFormality.SpokenFormal });
 * // { honorific: 'Chú', addressTerm: 'Chú An', fullAddress: 'Thưa Chú An', pronounPair: { self: 'cháu', addressee: 'chú' }, ... }
 * ```
 */
declare function addressCalculate(fullName: string, options?: IAddressOptions): IAddressResult;
/**
 * Get the Vietnamese pronoun pair (self/addressee) based on relative ages.
 *
 * Determines the culturally appropriate first-person and second-person pronouns
 * for a conversation between two people of known ages.
 *
 * @param speakerAge - Age of the person speaking
 * @param addresseeAge - Age of the person being addressed
 * @param options - Optional gender and region for more accurate pronoun selection
 * @returns A pronoun pair with self (first-person) and addressee (second-person) terms
 * @example
 * ```typescript
 * const pair = pronounPairGet(25, 55, { gender: EGender.Male, region: ERegion.North });
 * // { self: 'cháu', addressee: 'chú' }
 * ```
 */
declare function pronounPairGet(speakerAge: number, addresseeAge: number, options?: {
    gender?: EGender;
    region?: ERegion;
}): IPronounPair;

type TSortField = 'givenName' | 'surname' | 'fullName';
interface ISortOptions {
    field?: TSortField;
    order?: 'asc' | 'desc';
}
/**
 * Create a comparator function for sorting Vietnamese names with proper locale
 * awareness. By default sorts by given name (Vietnamese convention), with
 * configurable field and order.
 *
 * @param options - Optional sort settings: field ('givenName'|'surname'|'fullName') and order ('asc'|'desc')
 * @returns A comparator function compatible with Array.prototype.sort()
 * @example
 * ```typescript
 * const cmp = vietnameseNameComparator({ field: 'givenName', order: 'asc' });
 * ['Nguyen Van Binh', 'Tran Thi An'].sort(cmp);
 * // ['Tran Thi An', 'Nguyen Van Binh']
 * ```
 */
declare function vietnameseNameComparator(options?: ISortOptions): (a: string, b: string) => number;
/**
 * Sort an array of Vietnamese names with proper locale awareness.
 * Returns a new sorted array without mutating the original.
 *
 * @param names - Array of Vietnamese full names to sort
 * @param options - Optional sort settings: field ('givenName'|'surname'|'fullName') and order ('asc'|'desc')
 * @returns New array of names sorted according to the specified options
 * @example
 * ```typescript
 * sortVietnamese(['Nguyen Van Binh', 'Tran Thi An', 'Le Van Cuong']);
 * // ['Tran Thi An', 'Nguyen Van Binh', 'Le Van Cuong'] (sorted by given name)
 * sortVietnamese(['Nguyen Van Binh', 'Tran Thi An'], { field: 'surname' });
 * // ['Le Van Cuong', 'Nguyen Van Binh', 'Tran Thi An']
 * ```
 */
declare function sortVietnamese(names: string[], options?: ISortOptions): string[];

/**
 * Vietnamese Five Elements (Ngu Hanh) used in traditional naming and fortune.
 *
 * @example
 * ```typescript
 * EElement.Kim  // 'kim' - Metal
 * EElement.Thuy // 'thuy' - Water
 * ```
 */
declare enum EElement {
    Kim = "kim",
    Moc = "moc",
    Thuy = "thuy",
    Hoa = "hoa",
    Tho = "tho"
}
interface IElementInfo {
    element: EElement;
    hanViet: string;
    meaning: string;
    generating: EElement;
    destroying: EElement;
}
/**
 * Retrieve detailed information about a Five Element (Ngu Hanh), including its
 * Han Viet character, meaning, and generating/destroying cycle relationships.
 *
 * @param element - The element to look up
 * @returns Element info with Han Viet character, meaning, and cycle relationships
 * @example
 * ```typescript
 * getElementInfo(EElement.Kim);
 * // { element: 'kim', hanViet: '金', meaning: 'Metal', generating: 'thuy', destroying: 'moc' }
 * ```
 */
declare function getElementInfo(element: EElement): IElementInfo;
/**
 * Determine the Five Element (Ngu Hanh) associated with a Vietnamese given name.
 *
 * @param name - Vietnamese given name to look up (e.g. "Minh", "Lan")
 * @returns The associated element, or null if the name is not in the element map
 * @example
 * ```typescript
 * getNameElement('Minh'); // 'hoa' (Fire)
 * getNameElement('Lan');  // 'moc' (Wood)
 * ```
 */
declare function getNameElement(name: string): EElement | null;
/**
 * Get a list of Vietnamese given names associated with a specific Five Element.
 * Optionally filter by gender and limit the number of results.
 *
 * @param element - The Five Element to filter names by
 * @param options - Optional filters: gender ('male'|'female') and result limit
 * @returns Array of Vietnamese given names belonging to the specified element
 * @example
 * ```typescript
 * getNamesByElement(EElement.Moc);
 * // ['Lam', 'Phong', 'Xuan', 'Mai', 'Lan', ...]
 * getNamesByElement(EElement.Kim, { limit: 3 });
 * // ['Kim', 'Ngan', 'Bao']
 * ```
 */
declare function getNamesByElement(element: EElement, options?: {
    gender?: string;
    limit?: number;
}): string[];
/**
 * Determine the Five Element (Ngu Hanh) for a birth year based on the last digit
 * of the year in the Vietnamese/Chinese zodiac system.
 *
 * @param year - Birth year (e.g. 1990, 2000)
 * @returns The Five Element corresponding to the birth year
 * @example
 * ```typescript
 * getBirthYearElement(1990); // 'kim' (Metal) - last digit 0
 * getBirthYearElement(1995); // 'moc' (Wood) - last digit 5
 * ```
 */
declare function getBirthYearElement(year: number): EElement;

type THanVietEntry = {
    name: string;
    character: string;
    pinyin?: string;
    meaning: string;
    alternates?: {
        character: string;
        meaning: string;
    }[];
};

/**
 * Look up Han Viet (Sino-Vietnamese) character origin and meaning for a Vietnamese name.
 * Supports both diacritical and romanized (ASCII) input.
 *
 * @param name - Vietnamese given name to look up (e.g. "Minh", "Thanh")
 * @returns Han Viet entry with Chinese character and meaning, or null if not found
 * @example
 * ```typescript
 * getHanViet('Minh');
 * // { character: '明', meaning: 'bright, intelligent', ... }
 * getHanViet('xyz'); // null
 * ```
 */
declare function getHanViet(name: string): THanVietEntry | null;

type TNicknameCategory = 'animal' | 'descriptor' | 'ordinal' | 'food' | 'endearment';
interface INicknameOptions {
    category?: TNicknameCategory;
    seed?: number;
}
interface INicknameResult {
    nickname: string;
    category: TNicknameCategory;
    meaning: string;
    culturalNote: string;
}
/**
 * Generate a traditional Vietnamese protective nickname (ten xau de nuoi).
 * These deliberately unflattering names are given to ward off evil spirits,
 * a longstanding Vietnamese cultural practice.
 *
 * @param options - Optional generation settings: category and seed for deterministic output
 * @returns Nickname result with the name, category, meaning, and cultural context
 * @example
 * ```typescript
 * generateNickname({ category: 'animal' });
 * // { nickname: 'Coc', category: 'animal', meaning: 'toad', culturalNote: '...' }
 * generateNickname({ seed: 42 });
 * // deterministic output based on seed
 * ```
 */
declare function generateNickname(options?: INicknameOptions): INicknameResult;

type TPetNameCategory = 'byColor' | 'byFood' | 'byNature' | 'byLuck' | 'byHumor' | 'byPopCulture' | 'endearment';
interface IPetNameOptions {
    category?: TPetNameCategory;
    petType?: 'dog' | 'cat';
    furColor?: string;
    seed?: number;
}
interface IPetNameResult {
    name: string;
    meaning: string;
    category: TPetNameCategory;
    petType?: string;
    furColor?: string;
}
/**
 * Generate a single Vietnamese pet name, optionally filtered by category, pet type, or fur color.
 *
 * @param options - Optional filters: category, petType ('dog'|'cat'), furColor, and seed
 * @returns A pet name result with name, meaning, category, and optional pet metadata
 * @throws {Error} If no pet names match the given filter combination
 * @example
 * ```typescript
 * generatePetName({ petType: 'cat', category: 'byColor' });
 * // { name: 'Meo Muop', meaning: 'tabby cat', category: 'byColor', petType: 'cat' }
 * generatePetName({ seed: 123 });
 * // deterministic output based on seed
 * ```
 */
declare function generatePetName(options?: IPetNameOptions): IPetNameResult;
/**
 * Generate multiple unique Vietnamese pet names. Names are deduplicated until
 * the pool is exhausted, then names may repeat.
 *
 * @param count - Number of pet names to generate
 * @param options - Optional filters: category, petType ('dog'|'cat'), furColor, and seed
 * @returns Array of pet name results
 * @throws {Error} If no pet names match the given filter combination
 * @example
 * ```typescript
 * generateManyPetNames(3, { petType: 'dog' });
 * // [{ name: 'Lu', meaning: 'fluffy', ... }, { name: 'Bong', ... }, ...]
 * ```
 */
declare function generateManyPetNames(count: number, options?: IPetNameOptions): IPetNameResult[];

type TGenZNicknameStyle = 'social-handle' | 'jp-suffix' | 'kr-suffix' | 'cute' | 'meme' | 'english-viet';

interface IGenZNicknameOptions {
    name?: string;
    style?: TGenZNicknameStyle;
    gender?: 'male' | 'female' | 'unisex';
    seed?: number;
    secure?: boolean;
}
interface IGenZNicknameResult {
    nickname: string;
    style: TGenZNicknameStyle;
    origin: string;
    culturalNote: string;
}
/**
 * Generate a Gen Z-style Vietnamese nickname using modern social media and
 * cross-cultural naming patterns (JP/KR suffixes, meme styles, English-Viet blends).
 *
 * @param options - Optional settings: input name, style, gender, seed, and secure flag
 * @returns Nickname result with the generated name, style, cultural origin, and note
 * @example
 * ```typescript
 * generateGenZNickname({ name: 'Nguyen Thi Lan', style: 'jp-suffix' });
 * // { nickname: 'Lan-chan', style: 'jp-suffix', origin: 'japanese-honorific', culturalNote: '...' }
 * generateGenZNickname({ style: 'social-handle', seed: 42 });
 * // deterministic social media handle
 * ```
 */
declare function generateGenZNickname(options?: IGenZNicknameOptions): IGenZNicknameResult;

declare const VietnameseNameGenerator: {
    readonly generate: typeof generate;
    readonly generateFullName: typeof generateFullName;
    readonly generateMany: typeof generateMany;
    readonly generateManyFullNames: typeof generateManyFullNames;
    readonly generateEmail: typeof generateEmail;
    readonly generateUsername: typeof generateUsername;
    readonly generateNickname: typeof generateNickname;
    readonly generatePetName: typeof generatePetName;
    readonly generateManyPetNames: typeof generateManyPetNames;
    readonly generateGenZNickname: typeof generateGenZNickname;
    readonly parseName: typeof parseName;
    readonly validateName: typeof validateName;
    readonly detectGender: typeof detectGender;
    readonly addressCalculate: typeof addressCalculate;
    readonly pronounPairGet: typeof pronounPairGet;
    readonly romanize: typeof romanize;
    readonly formatName: typeof formatName;
    readonly salutation: typeof salutation;
    readonly normalize: typeof normalize;
    readonly accentInsensitiveMatch: typeof accentInsensitiveMatch;
    readonly accentInsensitiveEqual: typeof accentInsensitiveEqual;
    readonly sortVietnamese: typeof sortVietnamese;
    readonly vietnameseNameComparator: typeof vietnameseNameComparator;
    readonly VIETNAMESE_NAME_REGEX: RegExp;
    readonly getHanViet: typeof getHanViet;
    readonly getElementInfo: typeof getElementInfo;
    readonly getNameElement: typeof getNameElement;
    readonly getNamesByElement: typeof getNamesByElement;
    readonly getBirthYearElement: typeof getBirthYearElement;
    readonly getMeaning: typeof getMeaning;
    readonly getSurnameInfo: typeof getSurnameInfo;
    readonly getRegionalVariant: typeof getRegionalVariant;
    readonly nameSimilarity: typeof nameSimilarity;
    readonly getStatistics: typeof getStatistics;
    readonly getTopSurnames: typeof getTopSurnames;
    readonly getGivenNameCount: typeof getGivenNameCount;
    readonly getUniqueGivenNames: typeof getUniqueGivenNames;
    readonly fakerVi: {
        person: {
            firstName(gender?: "male" | "female"): string;
            lastName(): string;
            middleName(gender?: "male" | "female"): string;
            fullName(options?: {
                gender?: "male" | "female";
            }): string;
            sex(): "male" | "female";
            prefix(gender?: "male" | "female"): string;
        };
        internet: {
            email(options?: {
                firstName?: string;
                lastName?: string;
            }): string;
            username(options?: {
                firstName?: string;
                lastName?: string;
            }): string;
        };
    };
    readonly EGender: typeof EGender;
    readonly ERegion: typeof ERegion;
    readonly EEra: typeof EEra;
    readonly EMeaningCategory: typeof EMeaningCategory;
    readonly ENameFormat: typeof ENameFormat;
    readonly EElement: typeof EElement;
    readonly EFormality: typeof EFormality;
    readonly EHonorificCategory: typeof EHonorificCategory;
    readonly EReligion: typeof EReligion;
    readonly EFeudalRank: typeof EFeudalRank;
};

export { EElement, EEra, EFeudalRank, EFormality, EGender, EHonorificCategory, EMeaningCategory, ENameFormat, ERegion, EReligion, type IAddressOptions, type IAddressResult, type IEmailResult, type IGenZNicknameOptions, type IGenZNicknameResult, type IGenderResult, type IKinshipTerm, type INameMeaning, type INameParts, type INameResult, type INicknameResult, type IParsedName, type IPetNameOptions, type IPetNameResult, type IPronounPair, type IRankedName, type IRomanizedName, type ISimilarityResult, type IStatisticsResult, type ISurnameInfo, type ITitleEntry, type IUsernameResult, type IValidationResult, type TEmailOptions, type TGenZNicknameStyle, type TGenerateOptions, type TGivenNameEntry, type THanVietEntry, type TNameStyle, type TNicknameCategory, type TPetNameCategory, type TWeightedEntry, VIETNAMESE_NAME_REGEX, accentInsensitiveEqual, accentInsensitiveMatch, addressCalculate, VietnameseNameGenerator as default, detectGender, fakerVi, formatName, generate, generateEmail, generateFullName, generateGenZNickname, generateMany, generateManyFullNames, generateManyPetNames, generateNickname, generatePetName, generateUsername, getBirthYearElement, getElementInfo, getGivenNameCount, getHanViet, getMeaning, getNameElement, getNamesByElement, getRegionalVariant, getStatistics, getSurnameInfo, getTopSurnames, getUniqueGivenNames, nameSimilarity, normalize, parseName, pronounPairGet, romanize, salutation, sortVietnamese, validateName, vietnameseNameComparator };