@mailwoman/codex 7.2.0 → 7.2.1

package/ca/postal-code.ts

@@ -0,0 +1,121 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Canadian postal codes: the branded type, the shape, normalization, and the FSA-letter →
+ *   province/territory prior — the only ALPHANUMERIC postcode of the systems the codex models.
+ *
+ *   The informative contrast across `us/zipcode.ts`, `de/postleitzahl.ts`, `fr/code-postal.ts`, and
+ *   here:
+ *
+ *   - A US ZIP is numeric; its first digit maps to a loose BAND of states.
+ *   - A German PLZ is numeric; its first digit maps to a Leitzone that CROSSES Bundesland borders.
+ *   - A French code postal is numeric; its first TWO digits ARE the département.
+ *   - A Canadian postal code is `A1A 1A1` — Letter Digit Letter, then Digit Letter Digit — and its
+ *       first LETTER pins the province or territory directly (`M` → Ontario, `H` → Quebec, `V` →
+ *       British Columbia). So like the French prefix it is a clean admin prior, but it does the job
+ *       with a single ALPHA character rather than digits.
+ *
+ *   The clean rule has two wrinkles worth knowing. `X` is SHARED by the Northwest Territories and
+ *   Nunavut (no single letter splits them), so `provinceOfPostalCode` returns an array there. And
+ *   the large provinces span SEVERAL letters: Ontario alone owns `K L M N P`, Quebec owns `G H J`.
+ *   The first three characters form the FSA (Forward Sortation Area); the last three are the LDU
+ *   (Local Delivery Unit). A FSA whose SECOND character (the first digit) is `0` is a RURAL area —
+ *   the bridge to the wider, lower-density delivery zones.
+ */
+
+import type { Tagged } from "type-fest"
+
+import type { CanadianProvinceCode } from "./province.ts"
+
+/**
+ * A Canadian postal code: `A1A 1A1`. Six alphanumeric characters in a strict Letter-Digit-Letter-Digit-Letter-Digit
+ * pattern, conventionally written with a single space after the third. Unlike the other systems' bare five digits, the
+ * shape alone already says "Canada".
+ *
+ * @category Postal
+ * @type string
+ * @title Postal Code
+ * @pattern ^[ABCEGHJ-NPRSTVXY]\d[ABCEGHJ-NPRSTV-Z] ?\d[ABCEGHJ-NPRSTV-Z]\d$
+ */
+export type PostalCode = Tagged<string, "CaPostalCode">
+
+/**
+ * The Canadian postal-code shape. The valid FIRST letters exclude `D F I O Q U W Z` (never used to open a postcode);
+ * the interior letters additionally exclude `D F I O Q U` (the visually ambiguous ones). The space between FSA and LDU
+ * is optional in the raw form.
+ */
+export const CA_POSTAL_CODE_PATTERN = /^[ABCEGHJ-NPRSTVXY]\d[ABCEGHJ-NPRSTV-Z] ?\d[ABCEGHJ-NPRSTV-Z]\d$/i
+
+/**
+ * Normalize a postal-code surface form to canonical `A1A 1A1`: uppercase and ensure exactly one space between the FSA
+ * (first three chars) and the LDU (last three) — `K1A0B1` → `K1A 0B1`, `k1a 0b1` → `K1A 0B1`. Returns null if the input
+ * is not a valid Canadian postal code.
+ */
+export function normalizeCaPostalCode(raw: unknown): PostalCode | null {
+	if (typeof raw !== "string") return null
+	const compact = raw.trim().toUpperCase().replace(/\s+/g, "")
+
+	if (compact.length !== 6) return null
+	const spaced = `${compact.slice(0, 3)} ${compact.slice(3)}`
+
+	return CA_POSTAL_CODE_PATTERN.test(spaced) ? (spaced as PostalCode) : null
+}
+
+/** Type-predicate for a Canadian postal code (accepts the spaced or unspaced surface form). */
+export function isCaPostalCode(input: unknown): input is PostalCode {
+	return typeof input === "string" && CA_POSTAL_CODE_PATTERN.test(input)
+}
+
+/**
+ * FSA first letter → province/territory. Clean (one province per letter) except `X`, shared by the Northwest
+ * Territories and Nunavut, and the large provinces that span several letters: Ontario owns `K L M N P` and Quebec owns
+ * `G H J`. Letters `D F I O Q U W Z` never open a Canadian postcode and so do not appear here.
+ */
+export const FSA_LETTER_TO_PROVINCE: Record<string, CanadianProvinceCode | CanadianProvinceCode[]> = {
+	A: "NL",
+	B: "NS",
+	C: "PE",
+	E: "NB",
+	G: "QC",
+	H: "QC",
+	J: "QC",
+	K: "ON",
+	L: "ON",
+	M: "ON",
+	N: "ON",
+	P: "ON",
+	R: "MB",
+	S: "SK",
+	T: "AB",
+	V: "BC",
+	X: ["NT", "NU"],
+	Y: "YT",
+}
+
+/**
+ * The province/territory a postal code belongs to, via its FSA first letter. Returns the single code for the clean
+ * letters, the `["NT", "NU"]` pair for the shared `X`, and null if the input is not a valid Canadian postal code (or
+ * its first letter has no province, which the pattern already forbids).
+ */
+export function provinceOfPostalCode(postalCode: unknown): CanadianProvinceCode | CanadianProvinceCode[] | null {
+	const normalized = normalizeCaPostalCode(postalCode)
+
+	if (!normalized) return null
+
+	return FSA_LETTER_TO_PROVINCE[normalized[0]!] ?? null
+}
+
+/**
+ * True when a postal code is RURAL: its SECOND character (the FSA's first digit) is `0`. Canada Post uses a `0` in that
+ * position to mark the lower-density delivery zones (rural routes, small communities) — the contrast with the urban
+ * `1`–`9` FSAs. Returns false for a non-code.
+ */
+export function isRuralPostalCode(pc: unknown): boolean {
+	const normalized = normalizeCaPostalCode(pc)
+
+	if (!normalized) return false
+
+	return normalized[1] === "0"
+}

package/ca/province.ts

@@ -0,0 +1,99 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The 13 Canadian provinces and territories (10 provinces + 3 territories), keyed by their ISO
+ *   3166-2:CA code.
+ *
+ *   The informative contrast with `de/bundesland.ts` and `us/state.ts`: a Canadian subdivision is
+ *   officially BILINGUAL, so each unit carries two equally-canonical names — an English one and a
+ *   French one — and the gap between them is wide (`Nova Scotia` / `Nouvelle-Écosse`, `British
+ *   Columbia` / `Colombie-Britannique`). That mirrors the German English-exonym pattern (`Bavaria`
+ *   / `Bayern`), except here the French name is not a foreign exonym but a co-official form a real
+ *   address can be written in. And like a US two-letter state code, the ISO code (`ON`, `QC`, `BC`)
+ *   is the abbreviation people actually write on the address line — so unlike German or French
+ *   regions, the Canadian code IS a surface form, not just a resolver key.
+ */
+
+/** Per-province record: ISO 3166-2:CA code, English name, and the co-official French name. */
+export interface CanadianProvinceInfo {
+	/** ISO 3166-2:CA subdivision code without the `CA-` prefix (e.g. `ON` for `CA-ON`). */
+	code: string
+	/** English name (e.g. `Quebec`). */
+	name: string
+	/** Co-official French name (e.g. `Québec`). */
+	french: string
+}
+
+/**
+ * ISO 3166-2:CA code → province/territory info, for all 13 subdivisions (10 provinces + 3 territories). Codes are the
+ * official subdivision codes minus the `CA-` prefix.
+ */
+export const CA_PROVINCES = {
+	AB: { code: "AB", name: "Alberta", french: "Alberta" },
+	BC: { code: "BC", name: "British Columbia", french: "Colombie-Britannique" },
+	MB: { code: "MB", name: "Manitoba", french: "Manitoba" },
+	NB: { code: "NB", name: "New Brunswick", french: "Nouveau-Brunswick" },
+	NL: { code: "NL", name: "Newfoundland and Labrador", french: "Terre-Neuve-et-Labrador" },
+	NS: { code: "NS", name: "Nova Scotia", french: "Nouvelle-Écosse" },
+	NT: { code: "NT", name: "Northwest Territories", french: "Territoires du Nord-Ouest" },
+	NU: { code: "NU", name: "Nunavut", french: "Nunavut" },
+	ON: { code: "ON", name: "Ontario", french: "Ontario" },
+	PE: { code: "PE", name: "Prince Edward Island", french: "Île-du-Prince-Édouard" },
+	QC: { code: "QC", name: "Quebec", french: "Québec" },
+	SK: { code: "SK", name: "Saskatchewan", french: "Saskatchewan" },
+	YT: { code: "YT", name: "Yukon", french: "Yukon" },
+} as const satisfies Record<string, CanadianProvinceInfo>
+
+/** An ISO 3166-2:CA province/territory code (`AB`, `ON`, `QC`, …). */
+export type CanadianProvinceCode = keyof typeof CA_PROVINCES
+
+const PROVINCE_CODE_SET: ReadonlySet<string> = new Set(Object.keys(CA_PROVINCES))
+
+/** Type-predicate for an ISO 3166-2:CA province/territory code. Case-insensitive. */
+export function isCanadianProvinceCode(input: unknown): input is CanadianProvinceCode {
+	return typeof input === "string" && PROVINCE_CODE_SET.has(input.toUpperCase())
+}
+
+/** Strip diacritics + lowercase so `Québec`, `Quebec`, and `quebec` all key alike. */
+function foldName(s: string): string {
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+}
+
+/**
+ * Folded province name (English or French) / code → ISO 3166-2:CA code. Built diacritic-insensitive so both co-official
+ * names map regardless of accents: `Québec`, `Quebec`, and an unaccented `Nouvelle-Ecosse` all resolve. The two-name
+ * design is the Canadian wrinkle — unlike the German lookup's English exonym, the French form here is a name a real
+ * address may legitimately use.
+ */
+export const CA_PROVINCE_NAME_TO_CODE: ReadonlyMap<string, CanadianProvinceCode> = (() => {
+	const out = new Map<string, CanadianProvinceCode>()
+
+	for (const code of Object.keys(CA_PROVINCES) as CanadianProvinceCode[]) {
+		const info = CA_PROVINCES[code]
+		out.set(foldName(info.name), code)
+		out.set(foldName(info.french), code)
+		out.set(code.toLowerCase(), code)
+	}
+
+	return out
+})()
+
+/**
+ * Resolve a Canadian province/territory surface form (ISO code, English name, or French name, accents optional) to its
+ * ISO code; null if unknown.
+ */
+export function lookupCanadianProvince(input: string | null | undefined): CanadianProvinceCode | null {
+	if (!input || typeof input !== "string") return null
+	const upper = input.trim().toUpperCase()
+
+	if (PROVINCE_CODE_SET.has(upper)) return upper as CanadianProvinceCode
+
+	return CA_PROVINCE_NAME_TO_CODE.get(foldName(input)) ?? null
+}

package/ca/street-type.ts

@@ -0,0 +1,167 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Canadian street types and directionals — BILINGUAL, because Canada Post recognizes both English
+ *   and French forms on the same national network.
+ *
+ *   The informative contrast with `us/street-suffix.ts`, `de/street-type.ts`, and `fr/voie.ts`:
+ *
+ *   - US — a trailing word with a USPS-standardized abbreviation (`Main Street` → `ST`).
+ *   - German — a fused TRAILING suffix (`Hauptstraße`).
+ *   - French — a LEADING standalone word (`Rue de la Paix`).
+ *   - Canadian — BOTH at once. An English street puts the type LAST (`Maple Avenue`, `Sunset
+ *       Crescent`); a French street puts it FIRST (`Rue Sainte-Catherine`, `Boulevard
+ *       René-Lévesque`). So {@link isCanadianStreetWord} matches a whole token against EITHER
+ *       vocabulary and stays position-agnostic — it cannot assume a side the way the
+ *       single-language files do.
+ *
+ *   The directionals carry the same bilingual twist, and one trap inside it: French `Ouest`
+ *   abbreviates to `O`, not `W`. A naive English-only matcher reading `Rue Sherbrooke O` would miss
+ *   the quadrant entirely. {@link CA_DIRECTIONALS} spells out the French abbreviations so `O` =
+ *   Ouest = West is recognized.
+ */
+
+/**
+ * English Canadian street-type words (Canada Post's recognized set, lowercase). Appear as the TRAILING token of an
+ * English street name (`Maple Avenue`, `Sunset Crescent`).
+ */
+export const CA_STREET_TYPES_EN: ReadonlySet<string> = new Set([
+	"street",
+	"avenue",
+	"boulevard",
+	"drive",
+	"road",
+	"crescent",
+	"court",
+	"place",
+	"lane",
+	"way",
+	"trail",
+	"terrace",
+	"close",
+	"circle",
+	"square",
+	"heights",
+	"grove",
+	"gardens",
+	"hill",
+	"park",
+	"row",
+	"walk",
+	"green",
+	"bay",
+	"cove",
+	"gate",
+	"point",
+	"ridge",
+	"view",
+])
+
+/**
+ * French Canadian street-type words (Canada Post's recognized set, lowercase, accent-bearing). Appear as the LEADING
+ * token of a French street name (`Rue Sainte-Catherine`, `Chemin du Roy`). Folded for matching in
+ * {@link isCanadianStreetWord}, so `Côte`/`cote` and `Allée`/`allee` key alike.
+ */
+export const CA_STREET_TYPES_FR: ReadonlySet<string> = new Set([
+	"rue",
+	"avenue",
+	"boulevard",
+	"chemin",
+	"côte",
+	"place",
+	"impasse",
+	"allée",
+	"croissant",
+	"montée",
+	"rang",
+	"ruelle",
+	"voie",
+	"passage",
+	"carré",
+	"terrasse",
+	"promenade",
+	"sentier",
+])
+
+/** Strip diacritics + lowercase so `Côte`/`cote`, `Allée`/`allee`, `Crescent`/`crescent` key alike. */
+function foldToken(s: string): string {
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.replace(/[^a-z]/g, "")
+}
+
+/** The English + French street-type vocabularies, both folded, for one position-agnostic lookup. */
+const STREET_WORD_SET: ReadonlySet<string> = (() => {
+	const out = new Set<string>()
+
+	for (const w of CA_STREET_TYPES_EN) {
+		out.add(foldToken(w))
+	}
+
+	for (const w of CA_STREET_TYPES_FR) {
+		out.add(foldToken(w))
+	}
+
+	return out
+})()
+
+/**
+ * True when a token is a Canadian street-type word in EITHER language (case- and accent-insensitive) — `Street`,
+ * `Crescent`, `Rue`, `Chemin`, `Côte`. Position-agnostic, because an English type trails the name and a French type
+ * leads it; the matcher cannot lean on a side.
+ */
+export function isCanadianStreetWord(token: unknown): boolean {
+	if (typeof token !== "string") return false
+	const t = foldToken(token)
+
+	return t.length > 0 && STREET_WORD_SET.has(t)
+}
+
+/**
+ * Bilingual directional words → canonical compass letter. Covers the bare letters (`N S E W`), the full English words
+ * (`North`/`South`/`East`/`West`), and the full French words (`Nord`/`Sud`/`Est`/`Ouest`). The bilingual twist is `O`:
+ * French `Ouest` abbreviates to `O`, NOT `W`, so an English-only matcher silently drops the quadrant on a French
+ * address line. Keys are folded (lowercase, accent-free); values are the English compass letter.
+ */
+export const CA_DIRECTIONALS: Record<string, "N" | "S" | "E" | "W"> = {
+	n: "N",
+	north: "N",
+	nord: "N",
+	s: "S",
+	south: "S",
+	sud: "S",
+	e: "E",
+	east: "E",
+	est: "E",
+	w: "W",
+	west: "W",
+	ouest: "W",
+	o: "W", // French Ouest abbreviates to O, not W — the bilingual trap.
+}
+
+/**
+ * True when a token is a Canadian directional in either language (case- and accent-insensitive) — `N`, `NW`, `Nord`,
+ * `Ouest`, `O`. Compound English quadrants (`NW`, `SE`) are accepted by decomposing into their single-letter halves;
+ * the lone French `O` resolves to West.
+ */
+export function isCanadianDirectional(token: unknown): boolean {
+	if (typeof token !== "string") return false
+	const t = foldToken(token)
+
+	if (t.length === 0) return false
+
+	if (t in CA_DIRECTIONALS) return true
+
+	// Compound English quadrants like NW / SE / NE / SW: each half must be a single-letter directional.
+	if (t.length === 2) {
+		const isLetter = (h: string): boolean => h === "n" || h === "s" || h === "e" || h === "w"
+
+		return isLetter(t[0]!) && isLetter(t[1]!)
+	}
+
+	return false
+}