us-states-list/dist/index.d.cts

[DEPRECATED] A clean, typed, and comprehensive list of all U.S. states and territories with full metadata.

/**
 * A valid 2-letter U.S. state or territory abbreviation (e.g., 'CA', 'NY', 'PR').
 */
type USStateAbbreviation = string;
/**
 * The type of U.S. entry (state, district, territory, commonwealth, insular area).
 */
type USEntryType = 'state' | 'district' | 'territory' | 'commonwealth' | 'insular area';
/**
 * U.S. Census Bureau region or custom region for territories.
 */
type USRegion = 'Northeast' | 'Midwest' | 'South' | 'West' | string;
/**
 * Metadata for a U.S. state, district, or territory.
 */
interface USStateEntry {
    /** Full name (e.g., 'California', 'Puerto Rico', 'District of Columbia') */
    name: string;
    /** 2-letter postal abbreviation */
    abbreviation: USStateAbbreviation;
    /** Entry type (e.g., 'state', 'district', 'territory', etc.) */
    entryType: USEntryType;
    /** Capital city, or null if not applicable */
    capital: string | null;
    /** Region (e.g., 'West', 'South', 'Territories') */
    region: USRegion;
    /** State FIPS code (optional) */
    fipsCode?: string;
    /** Land area in square miles (optional) */
    landAreaSqMi?: number;
}

/**
 * Immutable array of all U.S. states, DC, and major territories with metadata.
 * Data sources: USPS, U.S. Census Bureau, official territorial governments.
 */
declare const usEntries: Readonly<USStateEntry[]>;
/**
 * Immutable map of USStateEntry objects keyed by 2-letter abbreviation.
 */
declare const usEntryMapByAbbreviation: Readonly<Record<USStateAbbreviation, USStateEntry>>;

/**
 * Get a USStateEntry by 2-letter abbreviation (case-insensitive).
 * @param abbreviation - 2-letter code
 * @returns USStateEntry or undefined
 */
declare function getEntryByAbbreviation(abbreviation: string): USStateEntry | undefined;
/**
 * Get all USStateEntry objects for a given region (case-insensitive).
 * @param region - Region name
 * @returns Array of USStateEntry
 */
declare function getEntriesByRegion(region: USRegion | string): USStateEntry[];
/**
 * Get all entries that are DC or territories (entryType !== 'state').
 * @returns Array of USStateEntry
 */
declare function getTerritories(): USStateEntry[];
/**
 * Check if a 2-letter abbreviation is valid (case-insensitive).
 * @param abbreviation - 2-letter code
 * @returns true if valid
 */
declare function isValidAbbreviation(abbreviation: string): boolean;
/**
 * Get the capital city for a given abbreviation (case-insensitive).
 * @param abbreviation - 2-letter code
 * @returns Capital city string, null if no capital, or undefined if not found
 */
declare function getCapitalByAbbreviation(abbreviation: string): string | null | undefined;
/**
 * Get the 2-letter abbreviation for a given state/territory name (case-insensitive, trims input).
 * @param name - Full name
 * @returns Abbreviation or undefined
 */
declare function getAbbreviationByName(name: string): USStateAbbreviation | undefined;

export { USEntryType, USRegion, USStateAbbreviation, USStateEntry, getAbbreviationByName, getCapitalByAbbreviation, getEntriesByRegion, getEntryByAbbreviation, getTerritories, isValidAbbreviation, usEntries, usEntryMapByAbbreviation };