@mailwoman/codex 7.2.1 → 7.4.0

package/country/index.ts

@@ -12,3 +12,4 @@ export * from "./names.ts"
 export * from "./official-languages.ts"
 export * from "./reference-data.ts"
 export * from "./reference.ts"
+export * from "./subdivision.ts"

package/country/subdivision.ts

@@ -0,0 +1,93 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   ISO 3166-2 subdivision → country reference, the cross-country complement to `country.ts`'s
+ *   ISO 3166-1 `matchCountry`. A subdivision token ("QC", "Ontario", "Illinois") names a first-level
+ *   admin unit whose COUNTRY is the piece the resolver needs when a region qualifier is the only
+ *   signal that the locale-inferred default country is wrong ("Montreal QC" under a US locale).
+ *
+ *   Scope is deliberately minimal: the two subdivision systems whose two-letter codes people write
+ *   ON THE ADDRESS LINE and whose homonymous localities collide across the border — US states
+ *   (`us/state.ts`) and Canadian provinces (`ca/province.ts`). Both directions are covered: the ISO
+ *   code (`QC` → Quebec) and the full name (`Quebec` / `Québec` → the `QC` record), so a resolver
+ *   can expand the abbreviation the gazetteer FTS index lacks ("QC" is not an alt-name of Québec)
+ *   into the full name it does carry. This is a soft prior, not a routing decision — the gazetteer
+ *   still does the geographic confirmation (per the registry-backed-soft-prior doctrine).
+ *
+ *   The US and Canadian code sets are disjoint (no two-letter code, and no full name, collides
+ *   between the two), so the combined lookup below is unambiguous. `CA` resolves to California the
+ *   US state (Canada's provinces carry no `CA` subdivision code), never to Canada the country —
+ *   country recognition stays with `matchCountry`.
+ *
+ *   Source: the underlying `US_STATE_BY_ABBREVIATION` (USPS Publication 28, Appendix B) and
+ *   `CA_PROVINCES` (ISO 3166-2:CA) tables. No new provenance is introduced here — this module only
+ *   re-keys those two existing tables into one subdivision→country view.
+ */
+
+import { CA_PROVINCES } from "../ca/province.ts"
+import { US_STATE_BY_ABBREVIATION } from "../us/state.ts"
+
+/** A resolved subdivision: its ISO 3166-2 code (sans country prefix), canonical English name, and ISO 3166-1 country. */
+export interface SubdivisionMatch {
+	/** ISO 3166-2 subdivision code without the country prefix (e.g. `QC` for `CA-QC`, `IL` for `US-IL`). */
+	code: string
+	/** Canonical English name (e.g. `Quebec`, `Illinois`). */
+	name: string
+	/** ISO 3166-1 alpha-2 country the subdivision belongs to (`CA`, `US`). */
+	country: string
+}
+
+/** Strip diacritics + lowercase so `Québec`, `Quebec`, and `quebec` all key alike (mirrors `ca/province.ts`). */
+function foldName(s: string): string {
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+}
+
+/**
+ * Folded surface form (ISO code, English name, or — for CA — co-official French name) → subdivision. Built once. US
+ * states are inserted first and never overwritten, so on the (currently empty) event of a future code/name collision
+ * the US entry wins deterministically; today the two sets are disjoint.
+ */
+const SUBDIVISION_LOOKUP: ReadonlyMap<string, SubdivisionMatch> = (() => {
+	const out = new Map<string, SubdivisionMatch>()
+	const put = (key: string, match: SubdivisionMatch): void => {
+		const folded = foldName(key)
+
+		if (folded.length > 0 && !out.has(folded)) {
+			out.set(folded, match)
+		}
+	}
+
+	for (const [code, name] of Object.entries(US_STATE_BY_ABBREVIATION)) {
+		const match: SubdivisionMatch = { code, name, country: "US" }
+		put(code, match)
+		put(name, match)
+	}
+
+	for (const info of Object.values(CA_PROVINCES)) {
+		const match: SubdivisionMatch = { code: info.code, name: info.name, country: "CA" }
+		put(info.code, match)
+		put(info.name, match)
+		put(info.french, match)
+	}
+
+	return out
+})()
+
+/**
+ * Resolve a first-level subdivision surface form (ISO 3166-2 code, English name, or co-official French name for CA;
+ * accents optional) to its `{ code, name, country }`. Case- and diacritic-insensitive. Returns null for anything that
+ * isn't a US state or Canadian province/territory — including bare country tokens (use {@link matchCountry} for
+ * those).
+ */
+export function matchSubdivision(token: string | null | undefined): SubdivisionMatch | null {
+	if (!token || typeof token !== "string") return null
+
+	return SUBDIVISION_LOOKUP.get(foldName(token)) ?? null
+}

package/out/country/index.d.ts

@@ -11,4 +11,5 @@ export * from "./names.ts";
 export * from "./official-languages.ts";
 export * from "./reference-data.ts";
 export * from "./reference.ts";
+export * from "./subdivision.ts";
 //# sourceMappingURL=index.d.ts.map

package/out/country/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA"}

package/out/country/index.js

@@ -11,4 +11,5 @@ export * from "./names.js";
 export * from "./official-languages.js";
 export * from "./reference-data.js";
 export * from "./reference.js";
+export * from "./subdivision.js";
 //# sourceMappingURL=index.js.map

package/out/country/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../country/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA"}

package/out/country/subdivision.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   ISO 3166-2 subdivision → country reference, the cross-country complement to `country.ts`'s
+ *   ISO 3166-1 `matchCountry`. A subdivision token ("QC", "Ontario", "Illinois") names a first-level
+ *   admin unit whose COUNTRY is the piece the resolver needs when a region qualifier is the only
+ *   signal that the locale-inferred default country is wrong ("Montreal QC" under a US locale).
+ *
+ *   Scope is deliberately minimal: the two subdivision systems whose two-letter codes people write
+ *   ON THE ADDRESS LINE and whose homonymous localities collide across the border — US states
+ *   (`us/state.ts`) and Canadian provinces (`ca/province.ts`). Both directions are covered: the ISO
+ *   code (`QC` → Quebec) and the full name (`Quebec` / `Québec` → the `QC` record), so a resolver
+ *   can expand the abbreviation the gazetteer FTS index lacks ("QC" is not an alt-name of Québec)
+ *   into the full name it does carry. This is a soft prior, not a routing decision — the gazetteer
+ *   still does the geographic confirmation (per the registry-backed-soft-prior doctrine).
+ *
+ *   The US and Canadian code sets are disjoint (no two-letter code, and no full name, collides
+ *   between the two), so the combined lookup below is unambiguous. `CA` resolves to California the
+ *   US state (Canada's provinces carry no `CA` subdivision code), never to Canada the country —
+ *   country recognition stays with `matchCountry`.
+ *
+ *   Source: the underlying `US_STATE_BY_ABBREVIATION` (USPS Publication 28, Appendix B) and
+ *   `CA_PROVINCES` (ISO 3166-2:CA) tables. No new provenance is introduced here — this module only
+ *   re-keys those two existing tables into one subdivision→country view.
+ */
+/** A resolved subdivision: its ISO 3166-2 code (sans country prefix), canonical English name, and ISO 3166-1 country. */
+export interface SubdivisionMatch {
+    /** ISO 3166-2 subdivision code without the country prefix (e.g. `QC` for `CA-QC`, `IL` for `US-IL`). */
+    code: string;
+    /** Canonical English name (e.g. `Quebec`, `Illinois`). */
+    name: string;
+    /** ISO 3166-1 alpha-2 country the subdivision belongs to (`CA`, `US`). */
+    country: string;
+}
+/**
+ * Resolve a first-level subdivision surface form (ISO 3166-2 code, English name, or co-official French name for CA;
+ * accents optional) to its `{ code, name, country }`. Case- and diacritic-insensitive. Returns null for anything that
+ * isn't a US state or Canadian province/territory — including bare country tokens (use {@link matchCountry} for
+ * those).
+ */
+export declare function matchSubdivision(token: string | null | undefined): SubdivisionMatch | null;
+//# sourceMappingURL=subdivision.d.ts.map

package/out/country/subdivision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subdivision.d.ts","sourceRoot":"","sources":["../../country/subdivision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,yHAAyH;AACzH,MAAM,WAAW,gBAAgB;IAChC,wGAAwG;IACxG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAA;CACf;AA2CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAI1F"}

package/out/country/subdivision.js

@@ -0,0 +1,76 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   ISO 3166-2 subdivision → country reference, the cross-country complement to `country.ts`'s
+ *   ISO 3166-1 `matchCountry`. A subdivision token ("QC", "Ontario", "Illinois") names a first-level
+ *   admin unit whose COUNTRY is the piece the resolver needs when a region qualifier is the only
+ *   signal that the locale-inferred default country is wrong ("Montreal QC" under a US locale).
+ *
+ *   Scope is deliberately minimal: the two subdivision systems whose two-letter codes people write
+ *   ON THE ADDRESS LINE and whose homonymous localities collide across the border — US states
+ *   (`us/state.ts`) and Canadian provinces (`ca/province.ts`). Both directions are covered: the ISO
+ *   code (`QC` → Quebec) and the full name (`Quebec` / `Québec` → the `QC` record), so a resolver
+ *   can expand the abbreviation the gazetteer FTS index lacks ("QC" is not an alt-name of Québec)
+ *   into the full name it does carry. This is a soft prior, not a routing decision — the gazetteer
+ *   still does the geographic confirmation (per the registry-backed-soft-prior doctrine).
+ *
+ *   The US and Canadian code sets are disjoint (no two-letter code, and no full name, collides
+ *   between the two), so the combined lookup below is unambiguous. `CA` resolves to California the
+ *   US state (Canada's provinces carry no `CA` subdivision code), never to Canada the country —
+ *   country recognition stays with `matchCountry`.
+ *
+ *   Source: the underlying `US_STATE_BY_ABBREVIATION` (USPS Publication 28, Appendix B) and
+ *   `CA_PROVINCES` (ISO 3166-2:CA) tables. No new provenance is introduced here — this module only
+ *   re-keys those two existing tables into one subdivision→country view.
+ */
+import { CA_PROVINCES } from "../ca/province.js";
+import { US_STATE_BY_ABBREVIATION } from "../us/state.js";
+/** Strip diacritics + lowercase so `Québec`, `Quebec`, and `quebec` all key alike (mirrors `ca/province.ts`). */
+function foldName(s) {
+    return s
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+/**
+ * Folded surface form (ISO code, English name, or — for CA — co-official French name) → subdivision. Built once. US
+ * states are inserted first and never overwritten, so on the (currently empty) event of a future code/name collision
+ * the US entry wins deterministically; today the two sets are disjoint.
+ */
+const SUBDIVISION_LOOKUP = (() => {
+    const out = new Map();
+    const put = (key, match) => {
+        const folded = foldName(key);
+        if (folded.length > 0 && !out.has(folded)) {
+            out.set(folded, match);
+        }
+    };
+    for (const [code, name] of Object.entries(US_STATE_BY_ABBREVIATION)) {
+        const match = { code, name, country: "US" };
+        put(code, match);
+        put(name, match);
+    }
+    for (const info of Object.values(CA_PROVINCES)) {
+        const match = { code: info.code, name: info.name, country: "CA" };
+        put(info.code, match);
+        put(info.name, match);
+        put(info.french, match);
+    }
+    return out;
+})();
+/**
+ * Resolve a first-level subdivision surface form (ISO 3166-2 code, English name, or co-official French name for CA;
+ * accents optional) to its `{ code, name, country }`. Case- and diacritic-insensitive. Returns null for anything that
+ * isn't a US state or Canadian province/territory — including bare country tokens (use {@link matchCountry} for
+ * those).
+ */
+export function matchSubdivision(token) {
+    if (!token || typeof token !== "string")
+        return null;
+    return SUBDIVISION_LOOKUP.get(foldName(token)) ?? null;
+}
+//# sourceMappingURL=subdivision.js.map

package/out/country/subdivision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subdivision.js","sourceRoot":"","sources":["../../country/subdivision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAYzD,iHAAiH;AACjH,SAAS,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC;SACN,WAAW,EAAE;SACb,SAAS,CAAC,KAAK,CAAC;SAChB,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,IAAI,EAAE,CAAA;AACT,CAAC;AAED;;;;GAIG;AACH,MAAM,kBAAkB,GAA0C,CAAC,GAAG,EAAE;IACvE,MAAM,GAAG,GAAG,IAAI,GAAG,EAA4B,CAAA;IAC/C,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,KAAuB,EAAQ,EAAE;QAC1D,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;QAE5B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QACvB,CAAC;IACF,CAAC,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,CAAC;QACrE,MAAM,KAAK,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QAC7D,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAChB,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IACjB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAChD,MAAM,KAAK,GAAqB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;QACnF,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACrB,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACrB,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC,CAAC,EAAE,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgC;IAChE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAEpD,OAAO,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAA;AACvD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/codex",
-  "version": "7.2.1",
+  "version": "7.4.0",
   "description": "Per-address-system postal reference data + branded types (USPS street suffixes, US ZIP codes). Pure, zero-runtime-dep — the shared canonical home for postal-system primitives the parser, resolver, and synthesis layers all reach for.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -124,6 +124,6 @@
     "type-fest": "^5.8.0"
   },
   "devDependencies": {
-    "@mailwoman/annotations": "7.2.1"
+    "@mailwoman/annotations": "7.4.0"
   }
 }