/**
 * TypeScript interfaces for @countrystatecity/postalcodes
 */
/**
 * A single postal-code entry.
 *
 * `city_id` from the upstream source is omitted entirely — it is null on
 * 100% of upstream records and carries no usable information. Use
 * `locality_name` for place matching instead.
 */
interface IPostalCode {
    id: number;
    code: string;
    country_code: string;
    state_code: string | null;
    locality_name: string | null;
    type: string;
    latitude: string | null;
    longitude: string | null;
}
/**
 * One manifest entry per country that has postal-code data.
 * Not all countries do — see getSupportedCountryCodes().
 */
interface IPostalCodeManifestEntry {
    country_code: string;
    count: number;
    state_codes: string[];
    has_unassigned: boolean;
}

/**
 * Dynamic data loaders for @countrystatecity/postalcodes
 * Uses dynamic import() to enable code-splitting and lazy loading
 * Falls back to fs.readFileSync for CommonJS environments
 */

/**
 * Clear all in-memory data caches (manifest and state files).
 * Mainly useful in tests; data only changes between package versions.
 */
declare function clearCache(): void;
/**
 * Get the manifest of all countries that have postal code data.
 * Not all 250 countries have postal codes — currently ~125 do.
 * Cached in memory after the first load.
 * @bundle ~21KB - Loads manifest.json
 */
declare function getManifest(): Promise<IPostalCodeManifestEntry[]>;
/**
 * Get all postal codes for a specific country + state.
 * @param countryCode - ISO2 country code (e.g., 'US', 'AD')
 * @param stateCode - State code as used by the upstream database
 * @returns Promise with array of postal codes, or empty array if not found
 * @bundle Varies by state — largest known file (Portugal's biggest state) is ~3.2MB
 */
declare function getPostalCodesOfState(countryCode: string, stateCode: string): Promise<IPostalCode[]>;
/**
 * Get postal codes that have no state subdivision in the upstream data
 * (small territories/city-states, or a country's non-state-linked subset).
 * @param countryCode - ISO2 country code
 * @returns Promise with array of postal codes, or empty array if none
 */
declare function getUnassignedPostalCodesOfCountry(countryCode: string): Promise<IPostalCode[]>;
/**
 * Get ALL postal codes for an entire country: every state file plus the
 * unassigned bucket, concatenated.
 * WARNING: can be large — Portugal alone is ~197K records.
 * @param countryCode - ISO2 country code
 * @returns Promise with array of all postal codes in the country
 */
declare function getAllPostalCodesOfCountry(countryCode: string): Promise<IPostalCode[]>;

/**
 * Helper utilities for @countrystatecity/postalcodes
 */

/**
 * Check whether a postal code exists in the dataset for a country.
 *
 * This is an EXISTENCE check, not a format/regex check — the upstream
 * database doesn't expose postal code format patterns through any versioned
 * release asset, only through a mutable, unversioned branch file that this
 * package deliberately avoids depending on. An existence check also catches
 * typos in otherwise-plausible codes that a format regex would miss.
 *
 * @param countryCode - ISO2 country code
 * @param code - The postal code to check
 * @param stateCode - Optional state code to narrow the search (faster)
 */
declare function validatePostalCode(countryCode: string, code: string, stateCode?: string): Promise<boolean>;
/**
 * Look up all records matching an exact postal code.
 * Never assumes uniqueness — the same code can legitimately appear more
 * than once within a country (different localities sharing a code).
 *
 * @param countryCode - ISO2 country code
 * @param code - The postal code to look up
 * @param stateCode - Optional state code to narrow the search (faster)
 */
declare function lookupPostalCode(countryCode: string, code: string, stateCode?: string): Promise<IPostalCode[]>;
/**
 * Search postal codes within a country + state by locality name (case-insensitive substring match).
 * There is no city_id linkage in the upstream data, so locality name is the only usable place field.
 */
declare function searchPostalCodesByLocality(countryCode: string, stateCode: string, searchTerm: string): Promise<IPostalCode[]>;
/**
 * Search postal codes across an entire country by locality name (case-insensitive substring match).
 */
declare function searchPostalCodesByLocalityInCountry(countryCode: string, searchTerm: string): Promise<IPostalCode[]>;
/**
 * Get the list of country codes that have postal code data.
 * Not all countries do — currently ~125 of 250.
 */
declare function getSupportedCountryCodes(): Promise<string[]>;
/**
 * Check whether a country has any postal code data.
 */
declare function isCountrySupported(countryCode: string): Promise<boolean>;

export { type IPostalCode, type IPostalCodeManifestEntry, clearCache, getManifest as default, getAllPostalCodesOfCountry, getManifest, getPostalCodesOfState, getSupportedCountryCodes, getUnassignedPostalCodesOfCountry, isCountrySupported, lookupPostalCode, searchPostalCodesByLocality, searchPostalCodesByLocalityInCountry, validatePostalCode };