@mailwoman/codex 7.2.0 → 7.3.0

package/us/floor-designator.ts

@@ -0,0 +1,119 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C2 — Floor-class Secondary Unit Designators.
+ *
+ *   The sibling of {@link ./unit-designator.ts}: where the unit table covers the full secondary-unit
+ *   vocabulary (APT, STE, RM, …), this module extracts the floor-class subset — designators that
+ *   name a FLOOR or LEVEL of the building rather than a specific addressable unit on that floor.
+ *   USPS Pub 28 Appendix C2 identifies these designators as requiring a secondary number: "FL" (the
+ *   approved abbreviation for FLOOR). The publication gives `FLOOR` as the canonical designator
+ *   with approved abbreviation `FL` and variant `FLR`; `BASEMENT` (`BSMT`), `PENTHOUSE` (`PH`), and
+ *   `LOBBY` (`LBBY`) are the standalone-or-numbered floor-adjacent types also listed in Appendix
+ *   C2.
+ *
+ *   Appendix C2 explicitly marks FLOOR, BASEMENT as requiring a secondary number (alongside APT,
+ *   BLDG, etc.) while PENTHOUSE and LOBBY may stand alone. PH and LBBY are kept here (not just in
+ *   {@link ./unit-designator.ts}) because the span proposer treats them as level-class hints —
+ *   "LOBBY" and "PH" name a specific floor-analog, not a numbered unit, and the prior map routes
+ *   `LEVEL_PHRASE` → `unit` (the schema carries no separate `level` tag).
+ *
+ *   This table drives the `levelDesignators` set in the span-proposer lexicon. The full
+ *   secondary-unit designators (APT, STE, RM, …) remain in {@link ./unit-designator.ts}.
+ *
+ *   Data is verbatim USPS Pub 28 Appendix C2.
+ * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Publication 28 — Appendix C2: Secondary Unit Designators}
+ */
+
+/**
+ * One USPS Pub 28 C2 floor-class designator row.
+ *
+ * `requiresNumber` mirrors the Appendix C2 classification: FLOOR and BASEMENT must be followed by a secondary number;
+ * PENTHOUSE and LOBBY may stand alone.
+ */
+export interface USFloorDesignator {
+	/** Full canonical designator (uppercase per the publication). */
+	name: string
+	/** Approved USPS abbreviation (what the post office prints on standardized mail). */
+	abbreviation: string
+	/** Additional recognized surface variants from Appendix C2. */
+	variants: readonly string[]
+	/**
+	 * True when Appendix C2 marks this designator as "Requires a Secondary Number" (FLOOR, BASEMENT). False for
+	 * standalone types (PENTHOUSE, LOBBY) that name a specific floor-analog without an identifier.
+	 */
+	requiresNumber: boolean
+}
+
+/**
+ * USPS Pub 28 C2 floor-class secondary unit designators. Verbatim from the publication; see the module header for the
+ * per-row provenance. Ordered with the most-common numbered form first.
+ */
+export const US_FLOOR_DESIGNATORS = [
+	{ name: "FLOOR", abbreviation: "FL", variants: ["FLR"], requiresNumber: true },
+	{ name: "BASEMENT", abbreviation: "BSMT", variants: [], requiresNumber: true },
+	{ name: "PENTHOUSE", abbreviation: "PH", variants: [], requiresNumber: false },
+	{ name: "LOBBY", abbreviation: "LBBY", variants: [], requiresNumber: false },
+] as const satisfies readonly USFloorDesignator[]
+
+/** A canonical USPS floor-class designator name. */
+export type USFloorDesignatorName = (typeof US_FLOOR_DESIGNATORS)[number]["name"]
+
+/**
+ * Inverse lookup: every surface form (canonical name, approved abbreviation, or Appendix C2 variant) → its canonical
+ * designator name. Lowercase-keyed for case-insensitive matching: `"fl"` → `"FLOOR"`, `"bsmt"` → `"BASEMENT"`, `"ph"` →
+ * `"PENTHOUSE"`.
+ */
+export const US_FLOOR_DESIGNATOR_LOOKUP: ReadonlyMap<string, USFloorDesignatorName> = (() => {
+	const out = new Map<string, USFloorDesignatorName>()
+
+	for (const row of US_FLOOR_DESIGNATORS) {
+		out.set(row.name.toLowerCase(), row.name)
+		out.set(row.abbreviation.toLowerCase(), row.name)
+
+		for (const v of row.variants) {
+			if (!out.has(v.toLowerCase())) {
+				out.set(v.toLowerCase(), row.name)
+			}
+		}
+	}
+
+	return out
+})()
+
+/**
+ * All lowercase surface tokens for the floor-class designators — the set the span proposer populates `levelDesignators`
+ * with when wiring the US codex slice. Includes canonical names, approved abbreviations, and Appendix C2 variants.
+ */
+export const US_FLOOR_DESIGNATOR_TOKENS: ReadonlySet<string> = new Set(US_FLOOR_DESIGNATOR_LOOKUP.keys())
+
+/** Approved USPS abbreviation per canonical floor designator name. */
+export const US_FLOOR_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<USFloorDesignatorName, string>> = Object.fromEntries(
+	US_FLOOR_DESIGNATORS.map((r) => [r.name, r.abbreviation])
+) as Readonly<Record<USFloorDesignatorName, string>>
+
+/**
+ * Look up a USPS floor-class designator (by canonical name, abbreviation, or any Appendix C2 variant) and return the
+ * canonical name + approved abbreviation. Returns null if the token isn't a recognized floor-class designator.
+ */
+export function lookupFloorDesignator(input: string | null | undefined): {
+	designator: USFloorDesignatorName
+	abbreviation: string
+} | null {
+	if (!input || typeof input !== "string") return null
+	const designator = US_FLOOR_DESIGNATOR_LOOKUP.get(input.trim().toLowerCase())
+
+	if (!designator) return null
+
+	return { designator, abbreviation: US_FLOOR_DESIGNATOR_PREFERRED_ABBR[designator] }
+}
+
+/**
+ * True when a token is a recognized USPS floor-class secondary unit designator (case-insensitive) — `"Floor"`, `"FL"`,
+ * `"flr"`, `"bsmt"`, `"ph"`, `"lbby"`.
+ */
+export function isFloorDesignatorToken(input: unknown): boolean {
+	return typeof input === "string" && US_FLOOR_DESIGNATOR_LOOKUP.has(input.trim().toLowerCase())
+}

package/us/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The United States address system (USPS): street suffixes, secondary unit designators, floor-class
+ *   designators (USPS Pub 28 C2 floor/level subset), military/diplomatic post office designators
+ *   (USPS Pub 28 Chapter 7: APO/FPO/DPO + PSC/CMR/UNIT), ZIP codes, and the state abbreviations
+ *   they hang off of.
+ */
+
+export * from "./floor-designator.ts"
+export * from "./military-address.ts"
+export * from "./po-box.ts"
+export * from "./state.ts"
+export * from "./street-directional.ts"
+export * from "./street-suffix.ts"
+export * from "./unit-designator.ts"
+export * from "./zipcode.ts"

package/us/military-address.ts

@@ -0,0 +1,199 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28 — Military / Diplomatic Post Office designators.
+ *
+ *   Military and diplomatic overseas addresses use a distinct addressing scheme: instead of a city
+ *   name, a standardized location-class code (APO, FPO, DPO) appears on the city line, followed by
+ *   the armed-forces "state" code (AA, AE, AP) and a 09xxx ZIP code. The unit/PSC/CMR line
+ *   appearing above the city line identifies the specific installation unit, postal service center,
+ *   or community mail room.
+ *
+ *   Sourcing (accessed 2026-06-12):
+ *
+ *   - **USPS Publication 28, Chapter 7** ("Armed Forces and Diplomatic Post Offices") defines the three
+ *       armed-forces location codes and three state-code regions, and states: "Use APO with AA
+ *       (Americas), AE (Europe/Middle East/Africa/Canada), or AP (Pacific)"; "FPO (Fleet Post
+ *       Office) for Navy ships and shore installations"; "DPO (Diplomatic Post Office) for US
+ *       embassies and missions." Full URL: https://pe.usps.com/text/pub28/28c7_001.htm
+ *   - **USPS Publication 28, Appendix B** gives the complete list of accepted unit-line formats: `UNIT
+ *       <id>`, `PSC <id> BOX <box>`, `CMR <id> BOX <box>`, and `UNIT <id> BOX <box>`. The same
+ *       appendix notes the two-digit unit ranges for PSC/CMR/UNIT assignment by theater. Full URL:
+ *       https://pe.usps.com/text/pub28/28apb_001.htm
+ *   - The **Armed Forces "state" codes** (AA, AE, AP) are defined in the same USPS appendix and are
+ *       also the official USPS abbreviations for the three Armed Forces addressing regions. See:
+ *       https://pe.usps.com/text/pub28/28apb_002.htm
+ *   - "DPO" for Diplomatic Post Offices was added as a distinct code in 2011 (USPS Customer/ Industry
+ *       Notice 61). It does NOT replace APO in diplomatic mail — both exist, with DPO used
+ *       specifically for State Department overseas posts and APO/FPO retained for DoD.
+ *
+ * @see {@link https://pe.usps.com/text/pub28/28c7_001.htm USPS Pub 28 Chapter 7 — Military Addresses}
+ * @see {@link https://pe.usps.com/text/pub28/28apb_001.htm USPS Pub 28 Appendix B — Armed Forces Addresses}
+ */
+
+/** USPS military / diplomatic post-office location codes (the "city" substitute on the city line). */
+export const US_MILITARY_POST_OFFICE_CODES = [
+	/**
+	 * Army Post Office — domestic USPS gateway for Army and Air Force overseas mail; also used for some diplomatic
+	 * addresses (DPO is preferred for State Dept posts since 2011).
+	 */
+	{ code: "APO", name: "Army Post Office", armedForces: true },
+	/** Fleet Post Office — Navy ships and shore installations. */
+	{ code: "FPO", name: "Fleet Post Office", armedForces: true },
+	/** Diplomatic Post Office — US embassies and missions (added 2011). */
+	{ code: "DPO", name: "Diplomatic Post Office", armedForces: false },
+] as const
+
+export type USMilitaryPostOfficeCode = (typeof US_MILITARY_POST_OFFICE_CODES)[number]["code"]
+
+/**
+ * USPS Armed Forces "state" codes used in place of state names on military/diplomatic addresses. These appear where a
+ * US state abbreviation (NY, CA, …) would appear in a civilian address.
+ */
+export const US_ARMED_FORCES_REGIONS = [
+	{ code: "AA", name: "Armed Forces Americas", description: "Americas (excluding Canada)" },
+	{ code: "AE", name: "Armed Forces Europe", description: "Europe, Middle East, Africa, and Canada" },
+	{ code: "AP", name: "Armed Forces Pacific", description: "Pacific" },
+] as const
+
+export type USArmedForcesRegionCode = (typeof US_ARMED_FORCES_REGIONS)[number]["code"]
+
+/**
+ * USPS Pub 28 Appendix B unit-line designators for military/diplomatic overseas addresses. Each designator introduces
+ * an installation identifier and optionally a box number.
+ *
+ * Format rules per Appendix B:
+ *
+ * - `PSC <id> BOX <box>` — Postal Service Center
+ * - `CMR <id> BOX <box>` — Community Mail Room
+ * - `UNIT <id> BOX <box>` — numbered unit (battalion/company); UNIT may stand alone with just an id and no BOX when the
+ *   unit has direct mail delivery
+ *
+ * BOX is required for PSC and CMR; UNIT may omit BOX.
+ */
+export const US_MILITARY_UNIT_DESIGNATORS = [
+	{
+		code: "PSC",
+		name: "Postal Service Center",
+		requiresBox: true,
+		description: "Installation-level postal service center; format: PSC <id> BOX <box>",
+	},
+	{
+		code: "CMR",
+		name: "Community Mail Room",
+		requiresBox: true,
+		description: "Sub-installation mail room; format: CMR <id> BOX <box>",
+	},
+	{
+		code: "UNIT",
+		name: "Unit",
+		requiresBox: false,
+		description: "Numbered military unit (battalion/company); format: UNIT <id> [BOX <box>]",
+	},
+] as const
+
+export type USMilitaryUnitDesignatorCode = (typeof US_MILITARY_UNIT_DESIGNATORS)[number]["code"]
+
+/** Result of a military address line parse (the unit line: PSC/CMR/UNIT). */
+export interface USMilitaryUnitMatch {
+	/** The designator as it appeared ("PSC", "CMR", "Unit"). */
+	matched: string
+	/** The canonical designator code ("PSC", "CMR", "UNIT"). */
+	code: USMilitaryUnitDesignatorCode
+	/** The installation identifier ("1520", "453"). */
+	id: string
+	/** The box number when present ("4620", "1234A"). */
+	box?: string
+}
+
+// Unit-line regex: PSC/CMR/UNIT <id> [BOX <box>]
+// Identifiers are numeric; box numbers are alphanumeric. UNIT may stand without BOX.
+const UNIT_LINE_RE = /^\s*(psc|cmr|unit)\s+(\d+)(?:\s+box\s+([\dA-Za-z]+))?\s*$/i
+
+/**
+ * If `input` is a USPS military unit-line ("PSC 1520 BOX 4620", "CMR 453 BOX 100", "UNIT 7 BOX 234A", "UNIT 7"), return
+ * the canonical designator, installation id, and optional box. Null otherwise. Throws on a PSC or CMR line without a
+ * BOX component (per Appendix B, BOX is required for PSC/CMR; a bare "PSC 1520" is malformed).
+ */
+export function matchMilitaryUnitLine(input: unknown): USMilitaryUnitMatch | null {
+	if (typeof input !== "string") return null
+	const m = UNIT_LINE_RE.exec(input)
+
+	if (!m) return null
+	const code = m[1]!.toUpperCase() as USMilitaryUnitDesignatorCode
+	const id = m[2]!
+	const box = m[3]
+
+	const row = US_MILITARY_UNIT_DESIGNATORS.find((r) => r.code === code)!
+
+	if (row.requiresBox && !box) {
+		throw new Error(
+			`[codex/us/military-address] ${code} line requires a BOX component per USPS Pub 28 Appendix B; got bare "${input.trim()}"`
+		)
+	}
+
+	return { matched: m[1]!, code, id, ...(box ? { box } : {}) }
+}
+
+/** Type-predicate: does the input look like a USPS military unit line (PSC/CMR/UNIT)? */
+export function isMilitaryUnitLine(input: unknown): boolean {
+	try {
+		return matchMilitaryUnitLine(input) !== null
+	} catch {
+		return false // PSC/CMR without BOX is structurally malformed (not a false negative)
+	}
+}
+
+/** Result of a military city-line parse (APO/FPO/DPO + region code + ZIP). */
+export interface USMilitaryCityMatch {
+	/** The post-office code as it appeared ("APO", "FPO", "DPO"). */
+	matched: string
+	/** The canonical post-office code. */
+	code: USMilitaryPostOfficeCode
+	/** The Armed Forces region code ("AA", "AE", "AP"). */
+	region: USArmedForcesRegionCode
+	/**
+	 * The 5-digit or 9-digit ZIP code. Typical ranges per Pub 28: 09xxx (AE), 34xxx (AA), 96xxx (AP) — range validation
+	 * per region is caller responsibility.
+	 */
+	zip: string
+}
+
+// City-line regex: APO/FPO/DPO <region> <zip>
+// USPS military ZIP assignment per Pub 28 and the Armed Forces zip code list:
+//   - AA (Americas): 340xx range
+//   - AE (Europe/ME/Africa/Canada): 09xxx range
+//   - AP (Pacific): 962xx-966xx range
+// The regex accepts any 5-digit or 9-digit ZIP code in combination with a valid region code —
+// validating the specific numeric range for each region is left to the caller (region+ZIP
+// co-validation is operational policy, not structural syntax).
+const CITY_LINE_RE = /^\s*(apo|fpo|dpo)\s+(aa|ae|ap)\s+(\d{5}(?:-\d{4})?)\s*$/i
+
+/**
+ * If `input` is a USPS military city line ("APO AE 09165", "FPO AP 96602-1254", "DPO AE 09498", "APO AA 34022", "APO AP
+ * 96525"), return the canonical code, region, and ZIP. Null otherwise.
+ *
+ * ZIP ranges per Pub 28: AE (Europe/ME/Africa/Canada) → 09xxx; AP (Pacific) → 96xxx; AA (Americas) → 34xxx. Range
+ * validation per region is left to the caller; the matcher accepts any 5. or 9-digit ZIP paired with a valid region
+ * code.
+ */
+export function matchMilitaryCityLine(input: unknown): USMilitaryCityMatch | null {
+	if (typeof input !== "string") return null
+	const m = CITY_LINE_RE.exec(input)
+
+	if (!m) return null
+
+	return {
+		matched: m[1]!.toUpperCase(),
+		code: m[1]!.toUpperCase() as USMilitaryPostOfficeCode,
+		region: m[2]!.toUpperCase() as USArmedForcesRegionCode,
+		zip: m[3]!,
+	}
+}
+
+/** Type-predicate: does the input look like a USPS military city line (APO/FPO/DPO + region + ZIP)? */
+export function isMilitaryCityLine(input: unknown): boolean {
+	return matchMilitaryCityLine(input) !== null
+}

package/us/po-box.ts

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS PO Box recognition + normalization to the surface forms that actually occur
+ *   (case-insensitive, punctuated "P.O. Box", spelled-out "Post Office Box", bare "Box"). A PO box
+ *   isn't a closed vocabulary like street suffixes — it's a designator phrase + a box id — so the
+ *   API is a detector ({@link isPOBox}), a normalizer ({@link normalizePOBox}), and an extractor
+ *   ({@link matchPOBox}) the corpus po_box synth/parsing can reuse instead of re-deriving the
+ *   regex.
+ * @see {@link https://pe.usps.com/text/pub28/28c2_012.htm USPS Pub 28 §29 (PO Box / Caller service)}
+ */
+
+/**
+ * USPS designator phrases that introduce a post-office-box identifier, longest-first so the matcher prefers the most
+ * specific phrase ("Post Office Box" before "Box"). Each is matched case-insensitively with flexible internal
+ * punctuation/spacing.
+ */
+export const US_PO_BOX_DESIGNATORS = [
+	"POST OFFICE BOX",
+	"PO BOX",
+	"P O BOX",
+	"FIRM CALLER",
+	"CALLER",
+	"DRAWER",
+	"LOCKBOX",
+	"BOX",
+] as const satisfies readonly string[]
+
+export type USPoBoxDesignator = (typeof US_PO_BOX_DESIGNATORS)[number]
+
+// Matches a leading PO-box designator + its identifier. Allows "P.O. Box", "PO BOX", "Post Office
+// Box", "Box 12-A", etc. The id is alphanumeric with optional dashes (USPS caller/firm ids exist).
+const PO_BOX_RE =
+	/^\s*(?:(p\.?\s*o\.?\s*box)|(post\s+office\s+box)|(firm\s+caller)|(caller)|(drawer)|(lockbox)|(box))\s*#?\s*([\dA-Za-z][\dA-Za-z-]*)\s*$/i
+
+/**
+ * Type-predicate: does the input look like a standalone PO Box address? Case-insensitive and tolerant of "P.O. Box",
+ * "Post Office Box", "Box 12", "PMB"-style ids. (Widens the original isp-nexus `/^PO BOX [\d-]+$/`, which only matched
+ * all-caps "PO BOX 123".)
+ */
+export function isPOBox(input: unknown): boolean {
+	return typeof input === "string" && PO_BOX_RE.test(input)
+}
+
+/** Result of a PO-box parse: the matched designator phrase and the box identifier. */
+export interface PoBoxMatch {
+	/** The designator phrase as it appeared, e.g. "P.O. Box", "Post Office Box". */
+	matched: string
+	/** The box identifier, e.g. "123", "12-A". */
+	id: string
+}
+
+/**
+ * If `input` is a PO-box phrase ("PO Box 123", "P.O. Box 12-A", "Post Office Box 7"), return the designator phrase and
+ * the id. Null otherwise. Useful for the corpus po_box shard (split the designator from the number) and for
+ * resolver/parsing reuse.
+ */
+export function matchPOBox(input: unknown): PoBoxMatch | null {
+	if (typeof input !== "string") return null
+	const m = PO_BOX_RE.exec(input)
+
+	if (!m) return null
+	const matched = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? m[6] ?? m[7] ?? "").trim()
+	const id = m[8]!
+
+	return { matched, id }
+}
+
+/**
+ * Normalize any recognized PO-box phrase to the canonical USPS "PO BOX <id>" form. Returns the input unchanged if it
+ * isn't a PO box. (Widens the original isp-nexus normalizer, which only collapsed the "P.O. BOX" spelling and left the
+ * id/casing alone.)
+ */
+export function normalizePOBox(input: string): string {
+	const m = matchPOBox(input)
+
+	if (!m) return input
+
+	return `PO BOX ${m.id.toUpperCase()}`
+}

package/us/state.ts

@@ -0,0 +1,156 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US two-letter postal abbreviations for the 50 states, DC, and the five primary territories.
+ *
+ *   This is the minimal state primitive `zipcode.ts` needs (a closed abbreviation set + predicate)
+ *   without pulling in `@mailwoman/tiger`'s FIPS enums and their `shapefile-parser` dependency —
+ *   the point of the codex being a zero-runtime-dep package the browser-pure parser can consume.
+ *   The full FIPS-keyed table still lives in `@mailwoman/tiger` (`tiger/state.ts`) and in the
+ *   corpus TIGER adapter; folding those onto this set is a deliberate follow-up, not a v1 concern.
+ */
+
+/**
+ * USPS two-letter abbreviations: the 50 states, the District of Columbia, and the five primary territories (Puerto
+ * Rico, Guam, US Virgin Islands, Northern Mariana Islands, American Samoa).
+ */
+export const US_STATE_ABBREVIATIONS = [
+	"AL",
+	"AK",
+	"AZ",
+	"AR",
+	"CA",
+	"CO",
+	"CT",
+	"DE",
+	"DC",
+	"FL",
+	"GA",
+	"HI",
+	"ID",
+	"IL",
+	"IN",
+	"IA",
+	"KS",
+	"KY",
+	"LA",
+	"ME",
+	"MD",
+	"MA",
+	"MI",
+	"MN",
+	"MS",
+	"MO",
+	"MT",
+	"NE",
+	"NV",
+	"NH",
+	"NJ",
+	"NM",
+	"NY",
+	"NC",
+	"ND",
+	"OH",
+	"OK",
+	"OR",
+	"PA",
+	"RI",
+	"SC",
+	"SD",
+	"TN",
+	"TX",
+	"UT",
+	"VT",
+	"VA",
+	"WA",
+	"WV",
+	"WI",
+	"WY",
+	"PR",
+	"GU",
+	"VI",
+	"MP",
+	"AS",
+] as const satisfies readonly string[]
+
+/** A USPS two-letter state-or-territory abbreviation. */
+export type USStateAbbreviation = (typeof US_STATE_ABBREVIATIONS)[number]
+
+const STATE_ABBREVIATION_SET: ReadonlySet<string> = new Set(US_STATE_ABBREVIATIONS)
+
+/**
+ * Type-predicate for a USPS state-or-territory abbreviation. Case-insensitive (`"ca"` and `"CA"` both pass), since the
+ * abbreviation arrives from raw address text.
+ */
+export function isUSStateAbbreviation(input: unknown): input is USStateAbbreviation {
+	return typeof input === "string" && STATE_ABBREVIATION_SET.has(input.toUpperCase())
+}
+
+/**
+ * Full names for the 50 states, DC, and the five primary territories, keyed by USPS abbreviation. The names half of the
+ * closed region vocabulary — where the country/state homographs live ("Georgia", "Washington"), which the
+ * gazetteer-anchor lexicon needs to flag candidate-tag collisions. Source: USPS Publication 28, Appendix B.
+ */
+export const US_STATE_BY_ABBREVIATION = {
+	AL: "Alabama",
+	AK: "Alaska",
+	AZ: "Arizona",
+	AR: "Arkansas",
+	CA: "California",
+	CO: "Colorado",
+	CT: "Connecticut",
+	DE: "Delaware",
+	DC: "District of Columbia",
+	FL: "Florida",
+	GA: "Georgia",
+	HI: "Hawaii",
+	ID: "Idaho",
+	IL: "Illinois",
+	IN: "Indiana",
+	IA: "Iowa",
+	KS: "Kansas",
+	KY: "Kentucky",
+	LA: "Louisiana",
+	ME: "Maine",
+	MD: "Maryland",
+	MA: "Massachusetts",
+	MI: "Michigan",
+	MN: "Minnesota",
+	MS: "Mississippi",
+	MO: "Missouri",
+	MT: "Montana",
+	NE: "Nebraska",
+	NV: "Nevada",
+	NH: "New Hampshire",
+	NJ: "New Jersey",
+	NM: "New Mexico",
+	NY: "New York",
+	NC: "North Carolina",
+	ND: "North Dakota",
+	OH: "Ohio",
+	OK: "Oklahoma",
+	OR: "Oregon",
+	PA: "Pennsylvania",
+	RI: "Rhode Island",
+	SC: "South Carolina",
+	SD: "South Dakota",
+	TN: "Tennessee",
+	TX: "Texas",
+	UT: "Utah",
+	VT: "Vermont",
+	VA: "Virginia",
+	WA: "Washington",
+	WV: "West Virginia",
+	WI: "Wisconsin",
+	WY: "Wyoming",
+	PR: "Puerto Rico",
+	GU: "Guam",
+	VI: "US Virgin Islands",
+	MP: "Northern Mariana Islands",
+	AS: "American Samoa",
+} as const satisfies Record<USStateAbbreviation, string>
+
+/** The full state/territory names, derived from {@link US_STATE_BY_ABBREVIATION}. */
+export const US_STATE_NAMES: readonly string[] = Object.values(US_STATE_BY_ABBREVIATION)