@mailwoman/codex 7.1.0 → 7.2.1

package/fr/cedex.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   CEDEX — Courrier d'Entreprise à Distribution EXceptionnelle (La Poste business routing, NF Z
+ *   10-011 §3.4). A CEDEX line replaces the ordinary delivery line for high-volume business
+ *   recipients: `75008 PARIS CEDEX 08` — the word CEDEX after the distribution office name,
+ *   optionally followed by a 1–2 digit office number. The component is the `CEDEX [NN]` phrase
+ *   itself (the schema's `cedex` tag); the preceding postcode/locality keep their own tags.
+ *
+ *   This slice closes the gap PR #516 documented: the shard builder sourced the shape from SCHEMA.mdx
+ *   prose because codex had no cedex home. Now it does — the builder and any future consumer import
+ *   from here (the provenance-first discipline: one provenanced source).
+ */
+
+/** Matches a CEDEX phrase: the keyword plus an optional 1–2 digit office number. */
+export const CEDEX_PATTERN = /\bCEDEX(?:\s+(\d{1,2}))?\b/i
+
+/** A matched CEDEX phrase with its char range and optional office number. */
+export interface CedexMatch {
+	/** The full matched phrase as it appears ("CEDEX 08", "Cedex"). */
+	matched: string
+	start: number
+	end: number
+	/** The office number when present ("08"), undefined for bare CEDEX. */
+	office?: string
+}
+
+/**
+ * Find the CEDEX phrase in a line, if any. Returns the LAST match — a CEDEX line places the phrase terminally (NF Z
+ * 10-011), and any earlier occurrence in pathological input is more likely a venue name fragment.
+ */
+export function matchCedex(text: string): CedexMatch | null {
+	let match: CedexMatch | null = null
+	const re = new RegExp(CEDEX_PATTERN.source, "gi")
+
+	for (const m of text.matchAll(re)) {
+		match = {
+			matched: m[0],
+			start: m.index,
+			end: m.index + m[0].length,
+			...(m[1] ? { office: m[1] } : {}),
+		}
+	}
+
+	return match
+}
+
+/** True when the string is exactly a CEDEX phrase (the component-value validator). */
+export function isCedex(input: unknown): boolean {
+	if (typeof input !== "string") return false
+	const m = input.trim().match(CEDEX_PATTERN)
+
+	return m !== null && m[0].length === input.trim().length
+}

package/fr/code-postal.ts

@@ -0,0 +1,105 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   French postal codes (code postal): the branded type, the shape, normalization, and the
+ *   first-two-digits → département mapping — the cleanest postcode→admin prior of the three
+ *   systems.
+ *
+ *   The informative contrast across `us/zipcode.ts`, `de/postleitzahl.ts`, and here:
+ *
+ *   - A US ZIP's first digit maps to a loose BAND of states.
+ *   - A German PLZ's first digit maps to a Leitzone that CROSSES Bundesland borders.
+ *   - A French code postal's first TWO digits ARE the département number directly (`75008` → 75, Paris;
+ *       `13001` → 13, Bouches-du-Rhône). So the French prefix pins the actual admin unit, and the
+ *       région follows from the département. It is the tightest of the three.
+ *
+ *   The exceptions are the interesting part: Corsica shares prefix `20` across two départements (`2A`
+ *   Corse-du-Sud / `2B` Haute-Corse, resolved by the rest of the code), and the overseas DOM use a
+ *   THREE-digit prefix (`971`–`976`). `departementOfCodePostal` handles both. Two further
+ *   real-world caveats it does NOT try to model: a handful of communes sit under a neighbouring
+ *   département's code (e.g. some `05`/`04` border villages), and a CEDEX code can carry a
+ *   large-volume-mail prefix that differs from the geographic one — both rare enough to leave to
+ *   the gazetteer.
+ */
+
+import type { Tagged } from "type-fest"
+
+import { departementInfo, type DepartementCode, type DepartementInfo } from "./departement.ts"
+import { FR_REGIONS, type FrenchRegionInfo } from "./region.ts"
+
+/**
+ * A French postal code: five digits (`75008`). Same shape as a US ZIP or a German PLZ — the shape alone does not
+ * disambiguate the country.
+ *
+ * @category Postal
+ * @type string
+ * @title Code postal
+ * @pattern ^\d{5}$
+ */
+export type CodePostal = Tagged<string, "CodePostal">
+
+/** The code-postal shape: exactly five digits. */
+export const CODE_POSTAL_PATTERN = /^\d{5}$/
+
+/**
+ * Normalize a code-postal surface form to the bare five digits: strip an `F-` country courtesy prefix and surrounding
+ * whitespace (`F-75008` → `75008`). Returns null if the result is not five digits.
+ */
+export function normalizeCodePostal(raw: unknown): CodePostal | null {
+	if (typeof raw !== "string") return null
+	const s = raw.trim().toUpperCase().replace(/^F-/, "")
+
+	return CODE_POSTAL_PATTERN.test(s) ? (s as CodePostal) : null
+}
+
+/** Type-predicate for a (normalized) French postal code. */
+export function isCodePostal(input: unknown): input is CodePostal {
+	return typeof input === "string" && CODE_POSTAL_PATTERN.test(input)
+}
+
+/**
+ * The département code a postal code belongs to. The clean rule plus its two exceptions:
+ *
+ * - `20xxx` → Corsica. The split is by the rest of the code: roughly `20000`–`20199` → `2A` (Ajaccio side), `20200`+ →
+ *   `2B` (Bastia side). Approximate at the boundary, exact for the bulk.
+ * - `970`–`976`xx → an overseas DOM, keyed by the three-digit prefix (`971`–`974`, `976`).
+ * - Otherwise the first two digits are the département number.
+ *
+ * Returns null for a prefix with no département (e.g. `975`/`977`/`98x` collectivities, or a malformed code).
+ */
+export function departementOfCodePostal(codePostal: unknown): DepartementCode | null {
+	const cp = normalizeCodePostal(codePostal)
+
+	if (!cp) return null
+
+	if (cp.startsWith("20")) {
+		// Corsica: prefix 20 covers both départements; the numeric value splits them.
+		return Number(cp) < 20200 ? "2A" : "2B"
+	}
+
+	if (cp.startsWith("97") || cp.startsWith("98")) {
+		// Overseas: three-digit prefix. Only the five DOM are départements.
+		const dom = cp.slice(0, 3)
+
+		return departementInfo(dom) ? (dom as DepartementCode) : null
+	}
+	const dd = cp.slice(0, 2)
+
+	return departementInfo(dd) ? (dd as DepartementCode) : null
+}
+
+/** The full département record a postal code resolves to (name + région), or null. */
+export function departementForCodePostal(codePostal: unknown): DepartementInfo | null {
+	return departementInfo(departementOfCodePostal(codePostal))
+}
+
+/**
+ * The région a postal code resolves to, via its département; null if the code maps to no département.
+ */
+export function regionForCodePostal(codePostal: unknown): FrenchRegionInfo | null {
+	const dep = departementForCodePostal(codePostal)
+
+	return dep ? FR_REGIONS[dep.region] : null
+}

package/fr/departement.ts

@@ -0,0 +1,142 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The 101 French départements (96 metropolitan including Corsica's 2A/2B, plus the 5 overseas DOM),
+ *   each mapped to its région.
+ *
+ *   The département is the key admin unit for French postal geography: a code postal's first two
+ *   digits ARE the département number (see `code-postal.ts`), and the région is derived from the
+ *   département. This table is therefore the hinge between `code-postal.ts` and `region.ts`.
+ */
+
+import type { FrenchRegionCode } from "./region.ts"
+
+/** Per-département record: code (2-digit, or `2A`/`2B`, or 3-digit DOM) + name + its région. */
+export interface DepartementInfo {
+	/** Département code: `01`–`95` (metropolitan), `2A`/`2B` (Corsica), or `971`–`976` (overseas). */
+	code: string
+	/** French name (e.g. `Bouches-du-Rhône`). */
+	name: string
+	/** The ISO 3166-2:FR code of the région this département belongs to. */
+	region: FrenchRegionCode
+}
+
+/** Département code → info. 96 metropolitan (incl. 2A/2B) + 5 overseas = 101. */
+export const FR_DEPARTEMENTS = {
+	"01": { code: "01", name: "Ain", region: "ARA" },
+	"02": { code: "02", name: "Aisne", region: "HDF" },
+	"03": { code: "03", name: "Allier", region: "ARA" },
+	"04": { code: "04", name: "Alpes-de-Haute-Provence", region: "PAC" },
+	"05": { code: "05", name: "Hautes-Alpes", region: "PAC" },
+	"06": { code: "06", name: "Alpes-Maritimes", region: "PAC" },
+	"07": { code: "07", name: "Ardèche", region: "ARA" },
+	"08": { code: "08", name: "Ardennes", region: "GES" },
+	"09": { code: "09", name: "Ariège", region: "OCC" },
+	"10": { code: "10", name: "Aube", region: "GES" },
+	"11": { code: "11", name: "Aude", region: "OCC" },
+	"12": { code: "12", name: "Aveyron", region: "OCC" },
+	"13": { code: "13", name: "Bouches-du-Rhône", region: "PAC" },
+	"14": { code: "14", name: "Calvados", region: "NOR" },
+	"15": { code: "15", name: "Cantal", region: "ARA" },
+	"16": { code: "16", name: "Charente", region: "NAQ" },
+	"17": { code: "17", name: "Charente-Maritime", region: "NAQ" },
+	"18": { code: "18", name: "Cher", region: "CVL" },
+	"19": { code: "19", name: "Corrèze", region: "NAQ" },
+	"2A": { code: "2A", name: "Corse-du-Sud", region: "COR" },
+	"2B": { code: "2B", name: "Haute-Corse", region: "COR" },
+	"21": { code: "21", name: "Côte-d'Or", region: "BFC" },
+	"22": { code: "22", name: "Côtes-d'Armor", region: "BRE" },
+	"23": { code: "23", name: "Creuse", region: "NAQ" },
+	"24": { code: "24", name: "Dordogne", region: "NAQ" },
+	"25": { code: "25", name: "Doubs", region: "BFC" },
+	"26": { code: "26", name: "Drôme", region: "ARA" },
+	"27": { code: "27", name: "Eure", region: "NOR" },
+	"28": { code: "28", name: "Eure-et-Loir", region: "CVL" },
+	"29": { code: "29", name: "Finistère", region: "BRE" },
+	"30": { code: "30", name: "Gard", region: "OCC" },
+	"31": { code: "31", name: "Haute-Garonne", region: "OCC" },
+	"32": { code: "32", name: "Gers", region: "OCC" },
+	"33": { code: "33", name: "Gironde", region: "NAQ" },
+	"34": { code: "34", name: "Hérault", region: "OCC" },
+	"35": { code: "35", name: "Ille-et-Vilaine", region: "BRE" },
+	"36": { code: "36", name: "Indre", region: "CVL" },
+	"37": { code: "37", name: "Indre-et-Loire", region: "CVL" },
+	"38": { code: "38", name: "Isère", region: "ARA" },
+	"39": { code: "39", name: "Jura", region: "BFC" },
+	"40": { code: "40", name: "Landes", region: "NAQ" },
+	"41": { code: "41", name: "Loir-et-Cher", region: "CVL" },
+	"42": { code: "42", name: "Loire", region: "ARA" },
+	"43": { code: "43", name: "Haute-Loire", region: "ARA" },
+	"44": { code: "44", name: "Loire-Atlantique", region: "PDL" },
+	"45": { code: "45", name: "Loiret", region: "CVL" },
+	"46": { code: "46", name: "Lot", region: "OCC" },
+	"47": { code: "47", name: "Lot-et-Garonne", region: "NAQ" },
+	"48": { code: "48", name: "Lozère", region: "OCC" },
+	"49": { code: "49", name: "Maine-et-Loire", region: "PDL" },
+	"50": { code: "50", name: "Manche", region: "NOR" },
+	"51": { code: "51", name: "Marne", region: "GES" },
+	"52": { code: "52", name: "Haute-Marne", region: "GES" },
+	"53": { code: "53", name: "Mayenne", region: "PDL" },
+	"54": { code: "54", name: "Meurthe-et-Moselle", region: "GES" },
+	"55": { code: "55", name: "Meuse", region: "GES" },
+	"56": { code: "56", name: "Morbihan", region: "BRE" },
+	"57": { code: "57", name: "Moselle", region: "GES" },
+	"58": { code: "58", name: "Nièvre", region: "BFC" },
+	"59": { code: "59", name: "Nord", region: "HDF" },
+	"60": { code: "60", name: "Oise", region: "HDF" },
+	"61": { code: "61", name: "Orne", region: "NOR" },
+	"62": { code: "62", name: "Pas-de-Calais", region: "HDF" },
+	"63": { code: "63", name: "Puy-de-Dôme", region: "ARA" },
+	"64": { code: "64", name: "Pyrénées-Atlantiques", region: "NAQ" },
+	"65": { code: "65", name: "Hautes-Pyrénées", region: "OCC" },
+	"66": { code: "66", name: "Pyrénées-Orientales", region: "OCC" },
+	"67": { code: "67", name: "Bas-Rhin", region: "GES" },
+	"68": { code: "68", name: "Haut-Rhin", region: "GES" },
+	"69": { code: "69", name: "Rhône", region: "ARA" },
+	"70": { code: "70", name: "Haute-Saône", region: "BFC" },
+	"71": { code: "71", name: "Saône-et-Loire", region: "BFC" },
+	"72": { code: "72", name: "Sarthe", region: "PDL" },
+	"73": { code: "73", name: "Savoie", region: "ARA" },
+	"74": { code: "74", name: "Haute-Savoie", region: "ARA" },
+	"75": { code: "75", name: "Paris", region: "IDF" },
+	"76": { code: "76", name: "Seine-Maritime", region: "NOR" },
+	"77": { code: "77", name: "Seine-et-Marne", region: "IDF" },
+	"78": { code: "78", name: "Yvelines", region: "IDF" },
+	"79": { code: "79", name: "Deux-Sèvres", region: "NAQ" },
+	"80": { code: "80", name: "Somme", region: "HDF" },
+	"81": { code: "81", name: "Tarn", region: "OCC" },
+	"82": { code: "82", name: "Tarn-et-Garonne", region: "OCC" },
+	"83": { code: "83", name: "Var", region: "PAC" },
+	"84": { code: "84", name: "Vaucluse", region: "PAC" },
+	"85": { code: "85", name: "Vendée", region: "PDL" },
+	"86": { code: "86", name: "Vienne", region: "NAQ" },
+	"87": { code: "87", name: "Haute-Vienne", region: "NAQ" },
+	"88": { code: "88", name: "Vosges", region: "GES" },
+	"89": { code: "89", name: "Yonne", region: "BFC" },
+	"90": { code: "90", name: "Territoire de Belfort", region: "BFC" },
+	"91": { code: "91", name: "Essonne", region: "IDF" },
+	"92": { code: "92", name: "Hauts-de-Seine", region: "IDF" },
+	"93": { code: "93", name: "Seine-Saint-Denis", region: "IDF" },
+	"94": { code: "94", name: "Val-de-Marne", region: "IDF" },
+	"95": { code: "95", name: "Val-d'Oise", region: "IDF" },
+	"971": { code: "971", name: "Guadeloupe", region: "GUA" },
+	"972": { code: "972", name: "Martinique", region: "MTQ" },
+	"973": { code: "973", name: "Guyane", region: "GUF" },
+	"974": { code: "974", name: "La Réunion", region: "LRE" },
+	"976": { code: "976", name: "Mayotte", region: "MAY" },
+} as const satisfies Record<string, DepartementInfo>
+
+/** A French département code (`01`–`95`, `2A`/`2B`, or `971`–`976`). */
+export type DepartementCode = keyof typeof FR_DEPARTEMENTS
+
+/**
+ * Look up a département by code (case-insensitive for the Corsica `2A`/`2B` letters); null if unknown.
+ */
+export function departementInfo(code: string | null | undefined): DepartementInfo | null {
+	if (!code || typeof code !== "string") return null
+	const key = code.trim().toUpperCase()
+
+	return (FR_DEPARTEMENTS as Record<string, DepartementInfo>)[key] ?? null
+}

package/fr/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The French address system (La Poste / ISO 3166-2:FR): street types (voie), postal codes (code
+ *   postal), and the admin hierarchy of départements and régions.
+ */
+
+export * from "./cedex.ts"
+export * from "./code-postal.ts"
+export * from "./departement.ts"
+export * from "./region.ts"
+export * from "./voie.ts"

package/fr/region.ts

@@ -0,0 +1,93 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The 18 French régions (13 metropolitan + 5 overseas), keyed by their ISO 3166-2:FR code.
+ *
+ *   The contrast with `de/bundesland.ts` and `us/state.ts`: France's regions were redrawn in the 2016
+ *   reform that merged 22 metropolitan régions into 13 (Aquitaine + Limousin + Poitou-Charentes →
+ *   Nouvelle-Aquitaine, etc.). So a French region is a large, recent amalgamation, and — like a
+ *   German Bundesland — it is almost never written on an address line, which reads `code-postal
+ *   commune`. The region is inferred from the département, which is inferred from the postcode (see
+ *   `code-postal.ts`).
+ */
+
+/** Per-region record: ISO 3166-2:FR code (sans `FR-` prefix) + French name. */
+export interface FrenchRegionInfo {
+	/** ISO 3166-2:FR region code without the `FR-` prefix (e.g. `IDF` for `FR-IDF`). */
+	code: string
+	/** French name (e.g. `Île-de-France`). */
+	name: string
+}
+
+/** ISO 3166-2:FR region code → info, for all 18 régions (13 metropolitan + 5 overseas). */
+export const FR_REGIONS = {
+	ARA: { code: "ARA", name: "Auvergne-Rhône-Alpes" },
+	BFC: { code: "BFC", name: "Bourgogne-Franche-Comté" },
+	BRE: { code: "BRE", name: "Bretagne" },
+	CVL: { code: "CVL", name: "Centre-Val de Loire" },
+	COR: { code: "COR", name: "Corse" },
+	GES: { code: "GES", name: "Grand Est" },
+	HDF: { code: "HDF", name: "Hauts-de-France" },
+	IDF: { code: "IDF", name: "Île-de-France" },
+	NOR: { code: "NOR", name: "Normandie" },
+	NAQ: { code: "NAQ", name: "Nouvelle-Aquitaine" },
+	OCC: { code: "OCC", name: "Occitanie" },
+	PDL: { code: "PDL", name: "Pays de la Loire" },
+	PAC: { code: "PAC", name: "Provence-Alpes-Côte d'Azur" },
+	GUA: { code: "GUA", name: "Guadeloupe" },
+	MTQ: { code: "MTQ", name: "Martinique" },
+	GUF: { code: "GUF", name: "Guyane" },
+	LRE: { code: "LRE", name: "La Réunion" },
+	MAY: { code: "MAY", name: "Mayotte" },
+} as const satisfies Record<string, FrenchRegionInfo>
+
+/** An ISO 3166-2:FR region code (`ARA`, `IDF`, `PAC`, …). */
+export type FrenchRegionCode = keyof typeof FR_REGIONS
+
+const REGION_CODE_SET: ReadonlySet<string> = new Set(Object.keys(FR_REGIONS))
+
+/** Type-predicate for an ISO 3166-2:FR region code. Case-insensitive. */
+export function isFrenchRegionCode(input: unknown): input is FrenchRegionCode {
+	return typeof input === "string" && REGION_CODE_SET.has(input.toUpperCase())
+}
+
+/** Strip diacritics + lowercase so `Île-de-France`, `ile-de-france`, `Ile de France` all key alike. */
+function foldName(s: string): string {
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+}
+
+/**
+ * Folded region name / code → ISO 3166-2:FR code. Built diacritic-insensitive so the resolver's surface form
+ * (`Île-de-France`, or an unaccented `Ile-de-France`) maps regardless of accents. Mirrors `de/bundesland.ts`'s
+ * `lookupGermanState`, the same role: fold a region surface form to one code so a resolver eval can compare
+ * like-for-like without a US-USPS-shaped matcher.
+ */
+export const FR_REGION_NAME_TO_CODE: ReadonlyMap<string, FrenchRegionCode> = (() => {
+	const out = new Map<string, FrenchRegionCode>()
+
+	for (const code of Object.keys(FR_REGIONS) as FrenchRegionCode[]) {
+		out.set(foldName(FR_REGIONS[code].name), code)
+		out.set(code.toLowerCase(), code)
+	}
+
+	return out
+})()
+
+/**
+ * Resolve a French region surface form (ISO code or name, accents optional) to its ISO code; null if unknown.
+ */
+export function lookupFrenchRegion(input: string | null | undefined): FrenchRegionCode | null {
+	if (!input || typeof input !== "string") return null
+	const upper = input.trim().toUpperCase()
+
+	if (REGION_CODE_SET.has(upper)) return upper as FrenchRegionCode
+
+	return FR_REGION_NAME_TO_CODE.get(foldName(input)) ?? null
+}

package/fr/voie.ts

@@ -0,0 +1,98 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   French street types (types de voie).
+ *
+ *   The third point on the morphology spectrum the codex now spans:
+ *
+ *   - US — the type is a TRAILING word with a standardized abbreviation (`Main Street` → `ST`).
+ *   - German — the type is a fused TRAILING suffix (`Hauptstraße`).
+ *   - French — the type is a LEADING standalone word (`Rue de la Paix`, `Avenue des Champs-Élysées`).
+ *       It carries common abbreviations (`bd`, `av`, `pl`) but no single national standard like
+ *       USPS Pub-28.
+ *
+ *   So French detection is "is this token a known voie word", position-first — which is why
+ *   {@link isFrenchStreetWord} matches a whole token rather than a suffix.
+ */
+
+/**
+ * Canonical French voie type → common written abbreviations. The leading word of a French street name. The first entry
+ * of each list is the most common abbreviation where one exists.
+ */
+export const FR_VOIE_TYPES = {
+	rue: ["r"],
+	avenue: ["av", "ave"],
+	boulevard: ["bd", "boul"],
+	place: ["pl"],
+	impasse: ["imp"],
+	allée: ["all"],
+	allées: [],
+	chemin: ["ch", "che"],
+	quai: [],
+	cours: ["crs"],
+	passage: ["pass", "psg"],
+	square: ["sq"],
+	route: ["rte"],
+	sentier: ["sen"],
+	villa: [],
+	cité: [],
+	esplanade: ["espl"],
+	faubourg: ["fbg", "fg"],
+	mail: [],
+	promenade: ["prom"],
+	"rond-point": ["rpt"],
+	voie: [],
+	chaussée: ["chée"],
+	ruelle: [],
+	venelle: [],
+	traverse: ["trav"],
+	montée: ["mtée"],
+	clos: [],
+	hameau: ["ham"],
+	résidence: ["rés"],
+	lotissement: ["lot"],
+} as const satisfies Record<string, readonly string[]>
+
+/** A canonical French voie type (e.g. `rue`, `avenue`, `boulevard`). */
+export type FrenchVoieType = keyof typeof FR_VOIE_TYPES
+
+/**
+ * Set of every French voie token — each canonical type plus each abbreviation — folded to lowercase/diacritic-free for
+ * matching. `Allée`/`allee`/`all` all resolve here.
+ */
+const VOIE_TOKEN_SET: ReadonlySet<string> = (() => {
+	const fold = (s: string): string =>
+		s
+			.toLowerCase()
+			.normalize("NFD")
+			.replace(/[\u0300-\u036f]/g, "")
+	const out = new Set<string>()
+
+	for (const canonical of Object.keys(FR_VOIE_TYPES) as FrenchVoieType[]) {
+		out.add(fold(canonical))
+
+		for (const abbr of FR_VOIE_TYPES[canonical]) {
+			out.add(fold(abbr))
+		}
+	}
+
+	return out
+})()
+
+/**
+ * True when a token is a French voie type word or abbreviation (case- and accent-insensitive) — `Rue`, `BD`, `Allée`,
+ * `impasse`. Matches the WHOLE token (French types lead the street name, they are not fused suffixes), so a city or
+ * surname is not caught the way a suffix test might.
+ */
+export function isFrenchStreetWord(token: unknown): boolean {
+	if (typeof token !== "string") return false
+	const t = token
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.replace(/[^a-z-]/g, "")
+
+	return t.length > 0 && VOIE_TOKEN_SET.has(t)
+}

package/gb/country.ts

@@ -0,0 +1,74 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The four constituent countries of the United Kingdom, keyed by their ISO 3166-2:GB code: England
+ *   (`ENG`), Scotland (`SCT`), Wales (`WLS`), Northern Ireland (`NIR`).
+ *
+ *   The UK's top-level admin tier is itself the first oddity of this system. France has régions,
+ *   Germany has Bundesländer, the US has states — a single flat layer. The UK has _countries_
+ *   inside a country, and an address almost never names which one: a line reads `street, town,
+ *   postcode`, and the constituent country is inferred — usually, but not always cleanly, from the
+ *   postcode area (see `postcode-area.ts`). So this file is the coarse admin label, and the
+ *   postcode is the thing that actually carries the geography.
+ */
+
+/** Per-country record: ISO 3166-2:GB code (sans `GB-` prefix) + English name. */
+export interface UkCountryInfo {
+	/** ISO 3166-2:GB country code without the `GB-` prefix (e.g. `ENG` for `GB-ENG`). */
+	code: string
+	/** English name (e.g. `Scotland`). */
+	name: string
+}
+
+/** ISO 3166-2:GB country code → info, for all four constituent countries. */
+export const GB_COUNTRIES = {
+	ENG: { code: "ENG", name: "England" },
+	SCT: { code: "SCT", name: "Scotland" },
+	WLS: { code: "WLS", name: "Wales" },
+	NIR: { code: "NIR", name: "Northern Ireland" },
+} as const satisfies Record<string, UkCountryInfo>
+
+/** An ISO 3166-2:GB constituent-country code (`ENG`, `SCT`, `WLS`, `NIR`). */
+export type UkCountryCode = keyof typeof GB_COUNTRIES
+
+const COUNTRY_CODE_SET: ReadonlySet<string> = new Set(Object.keys(GB_COUNTRIES))
+
+/** Type-predicate for an ISO 3166-2:GB country code. Case-insensitive. */
+export function isUkCountryCode(input: unknown): input is UkCountryCode {
+	return typeof input === "string" && COUNTRY_CODE_SET.has(input.toUpperCase())
+}
+
+/** Lowercase + collapse non-alphanumerics so `Northern Ireland`, `northern-ireland` key alike. */
+function foldName(s: string): string {
+	return s
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+}
+
+/** Folded country name / code → ISO 3166-2:GB code, so a surface form maps regardless of casing. */
+const COUNTRY_NAME_TO_CODE: ReadonlyMap<string, UkCountryCode> = (() => {
+	const out = new Map<string, UkCountryCode>()
+
+	for (const code of Object.keys(GB_COUNTRIES) as UkCountryCode[]) {
+		out.set(foldName(GB_COUNTRIES[code].name), code)
+		out.set(code.toLowerCase(), code)
+	}
+
+	return out
+})()
+
+/**
+ * Resolve a UK constituent-country surface form (ISO code or English name) to its ISO code; null if unknown. Accepts
+ * `ENG`, `England`, `Northern Ireland`, `scotland`, etc.
+ */
+export function lookupUkCountry(input: string | null | undefined): UkCountryCode | null {
+	if (!input || typeof input !== "string") return null
+	const upper = input.trim().toUpperCase()
+
+	if (COUNTRY_CODE_SET.has(upper)) return upper as UkCountryCode
+
+	return COUNTRY_NAME_TO_CODE.get(foldName(input)) ?? null
+}

package/gb/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The United Kingdom address system (Royal Mail / ISO 3166-2:GB): the variable-length alphanumeric
+ *   postcode and its Royal-Mail postcode areas, the four constituent countries, and British street
+ *   vocabulary.
+ */
+
+export * from "./country.ts"
+export * from "./postcode-area.ts"
+export * from "./postcode.ts"
+export * from "./street-type.ts"