/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 *   US Census FIPS state codes → two-letter abbreviation + full display name.
 *
 *   Covers all 50 states + DC + the five primary territories (PR, GU, VI, MP, AS).
 *
 *   The data is public-domain US Census reference (FIPS PUB 5-2, withdrawn but still the canonical
 *   numeric ID used by every TIGER product). It is reproduced here so the TIGER adapter can resolve
 *   `statefp` columns (e.g. `"50"`) into a `region` component (e.g. `"VT"`) without an extra DB
 *   join.
 */

/**
 * Per-state record: two-letter postal abbreviation + full canonical display name.
 */
export interface USStateInfo {
	abbreviation: string
	name: string
}

/**
 * FIPS state-or-territory code → `{ abbreviation, name }`. Includes all 50 states, DC, and the five primary territories
 * (PR, GU, VI, MP, AS). Codes are two-digit zero-padded strings to match TIGER column `statefp`.
 */
export const US_FIPS_STATE: Readonly<Record<string, USStateInfo>> = Object.freeze({
	"01": { abbreviation: "AL", name: "Alabama" },
	"02": { abbreviation: "AK", name: "Alaska" },
	"04": { abbreviation: "AZ", name: "Arizona" },
	"05": { abbreviation: "AR", name: "Arkansas" },
	"06": { abbreviation: "CA", name: "California" },
	"08": { abbreviation: "CO", name: "Colorado" },
	"09": { abbreviation: "CT", name: "Connecticut" },
	"10": { abbreviation: "DE", name: "Delaware" },
	"11": { abbreviation: "DC", name: "District of Columbia" },
	"12": { abbreviation: "FL", name: "Florida" },
	"13": { abbreviation: "GA", name: "Georgia" },
	"15": { abbreviation: "HI", name: "Hawaii" },
	"16": { abbreviation: "ID", name: "Idaho" },
	"17": { abbreviation: "IL", name: "Illinois" },
	"18": { abbreviation: "IN", name: "Indiana" },
	"19": { abbreviation: "IA", name: "Iowa" },
	"20": { abbreviation: "KS", name: "Kansas" },
	"21": { abbreviation: "KY", name: "Kentucky" },
	"22": { abbreviation: "LA", name: "Louisiana" },
	"23": { abbreviation: "ME", name: "Maine" },
	"24": { abbreviation: "MD", name: "Maryland" },
	"25": { abbreviation: "MA", name: "Massachusetts" },
	"26": { abbreviation: "MI", name: "Michigan" },
	"27": { abbreviation: "MN", name: "Minnesota" },
	"28": { abbreviation: "MS", name: "Mississippi" },
	"29": { abbreviation: "MO", name: "Missouri" },
	"30": { abbreviation: "MT", name: "Montana" },
	"31": { abbreviation: "NE", name: "Nebraska" },
	"32": { abbreviation: "NV", name: "Nevada" },
	"33": { abbreviation: "NH", name: "New Hampshire" },
	"34": { abbreviation: "NJ", name: "New Jersey" },
	"35": { abbreviation: "NM", name: "New Mexico" },
	"36": { abbreviation: "NY", name: "New York" },
	"37": { abbreviation: "NC", name: "North Carolina" },
	"38": { abbreviation: "ND", name: "North Dakota" },
	"39": { abbreviation: "OH", name: "Ohio" },
	"40": { abbreviation: "OK", name: "Oklahoma" },
	"41": { abbreviation: "OR", name: "Oregon" },
	"42": { abbreviation: "PA", name: "Pennsylvania" },
	"44": { abbreviation: "RI", name: "Rhode Island" },
	"45": { abbreviation: "SC", name: "South Carolina" },
	"46": { abbreviation: "SD", name: "South Dakota" },
	"47": { abbreviation: "TN", name: "Tennessee" },
	"48": { abbreviation: "TX", name: "Texas" },
	"49": { abbreviation: "UT", name: "Utah" },
	"50": { abbreviation: "VT", name: "Vermont" },
	"51": { abbreviation: "VA", name: "Virginia" },
	"53": { abbreviation: "WA", name: "Washington" },
	"54": { abbreviation: "WV", name: "West Virginia" },
	"55": { abbreviation: "WI", name: "Wisconsin" },
	"56": { abbreviation: "WY", name: "Wyoming" },
	// Territories
	"60": { abbreviation: "AS", name: "American Samoa" },
	"66": { abbreviation: "GU", name: "Guam" },
	"69": { abbreviation: "MP", name: "Northern Mariana Islands" },
	"72": { abbreviation: "PR", name: "Puerto Rico" },
	"78": { abbreviation: "VI", name: "Virgin Islands" },
})

/**
 * Lookup helper. Returns null when the FIPS code isn't recognized.
 */
export function lookupFipsState(statefp: string | null | undefined): USStateInfo | null {
	if (!statefp) return null

	return US_FIPS_STATE[statefp] ?? null
}

/**
 * Inverted view: two-letter postal abbreviation → `USStateInfo`. Built once at module load. Used by adapters whose
 * source data ships the abbreviation rather than the FIPS code (FCC BDC, most federal CSVs).
 */
export const US_STATE_BY_ABBREVIATION: Readonly<Record<string, USStateInfo>> = Object.freeze(
	Object.fromEntries(Object.values(US_FIPS_STATE).map((info) => [info.abbreviation, info]))
)

/**
 * Lookup helper for adapters carrying 2-char USPS abbreviations (`"CA"`, `"VT"`). Case-folded; null for any value
 * outside the 50 states + DC + the five primary territories.
 */
export function lookupStateAbbreviation(abbreviation: string | null | undefined): USStateInfo | null {
	if (!abbreviation) return null

	return US_STATE_BY_ABBREVIATION[abbreviation.toUpperCase()] ?? null
}