@mailwoman/codex 8.1.0 → 8.3.0

package/us/military-address.ts

@@ -33,16 +33,22 @@
  * @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). */
+/**
+ * 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. */
+	/**
+	 * 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). */
+	/**
+	 * Diplomatic Post Office — US embassies and missions (added 2011).
+	 */
 	{ code: "DPO", name: "Diplomatic Post Office", armedForces: false },
 ] as const
 
@@ -96,20 +102,32 @@ export const US_MILITARY_UNIT_DESIGNATORS = [
 
 export type USMilitaryUnitDesignatorCode = (typeof US_MILITARY_UNIT_DESIGNATORS)[number]["code"]
 
-/** Result of a military address line parse (the unit line: PSC/CMR/UNIT). */
+/**
+ * Result of a military address line parse (the unit line: PSC/CMR/UNIT).
+ */
 export interface USMilitaryUnitMatch {
-	/** The designator as it appeared ("PSC", "CMR", "Unit"). */
+	/**
+	 * The designator as it appeared ("PSC", "CMR", "Unit").
+	 */
 	matched: string
-	/** The canonical designator code ("PSC", "CMR", "UNIT"). */
+	/**
+	 * The canonical designator code ("PSC", "CMR", "UNIT").
+	 */
 	code: USMilitaryUnitDesignatorCode
-	/** The installation identifier ("1520", "453"). */
+	/**
+	 * The installation identifier ("1520", "453").
+	 */
 	id: string
-	/** The box number when present ("4620", "1234A"). */
+	/**
+	 * 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.
+/**
+ * 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
 
 /**
@@ -137,7 +155,9 @@ export function matchMilitaryUnitLine(input: unknown): USMilitaryUnitMatch | nul
 	return { matched: m[1]!, code, id, ...(box ? { box } : {}) }
 }
 
-/** Type-predicate: does the input look like a USPS military unit line (PSC/CMR/UNIT)? */
+/**
+ * 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
@@ -146,13 +166,21 @@ export function isMilitaryUnitLine(input: unknown): boolean {
 	}
 }
 
-/** Result of a military city-line parse (APO/FPO/DPO + region code + ZIP). */
+/**
+ * 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"). */
+	/**
+	 * The post-office code as it appeared ("APO", "FPO", "DPO").
+	 */
 	matched: string
-	/** The canonical post-office code. */
+	/**
+	 * The canonical post-office code.
+	 */
 	code: USMilitaryPostOfficeCode
-	/** The Armed Forces region code ("AA", "AE", "AP"). */
+	/**
+	 * 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
@@ -161,14 +189,13 @@ export interface USMilitaryCityMatch {
 	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).
+/**
+ * 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
 
 /**
@@ -193,7 +220,9 @@ export function matchMilitaryCityLine(input: unknown): USMilitaryCityMatch | nul
 	}
 }
 
-/** Type-predicate: does the input look like a USPS military city line (APO/FPO/DPO + region + ZIP)? */
+/**
+ * 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

@@ -30,8 +30,10 @@ export const US_PO_BOX_DESIGNATORS = [
 
 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).
+/**
+ * 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
 
@@ -44,11 +46,17 @@ 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. */
+/**
+ * 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". */
+	/**
+	 * The designator phrase as it appeared, e.g. "P.O. Box", "Post Office Box".
+	 */
 	matched: string
-	/** The box identifier, e.g. "123", "12-A". */
+	/**
+	 * The box identifier, e.g. "123", "12-A".
+	 */
 	id: string
 }
 

package/us/state.ts

@@ -75,7 +75,9 @@ export const US_STATE_ABBREVIATIONS = [
 	"AS",
 ] as const satisfies readonly string[]
 
-/** A USPS two-letter state-or-territory abbreviation. */
+/**
+ * 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)
@@ -152,5 +154,7 @@ export const US_STATE_BY_ABBREVIATION = {
 	AS: "American Samoa",
 } as const satisfies Record<USStateAbbreviation, string>
 
-/** The full state/territory names, derived from {@link US_STATE_BY_ABBREVIATION}. */
+/**
+ * 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)

package/us/street-directional.ts

@@ -29,7 +29,9 @@ export const DirectionalAbbreviation = {
 
 export type DirectionalAbbreviation = (typeof DirectionalAbbreviation)[keyof typeof DirectionalAbbreviation]
 
-/** The 8 directional names accepted by the USPS (intercardinals spaced, per the publication). */
+/**
+ * The 8 directional names accepted by the USPS (intercardinals spaced, per the publication).
+ */
 export const DirectionalNames = [
 	"NORTH",
 	"EAST",
@@ -43,6 +45,9 @@ export const DirectionalNames = [
 
 export type DirectionalName = (typeof DirectionalNames)[number]
 
+/**
+ * Surface forms a US directional can take (`N`, `N.`, `North`), for both parsing and formatting.
+ */
 export const DirectionalNameVariations = [
 	...DirectionalNames,
 	// Without spaces (the common US street form: "Northeast Main St")…
@@ -143,7 +148,7 @@ export function lookupDirectionalAbbreviation(input: unknown): DirectionalAbbrev
 
 	return (
 		DirectionalToAbbreviationMap.get(input) ||
-		DirectionalToAbbreviationMap.get(input.trim().toUpperCase().replace(/\s+/g, " ")) ||
+		DirectionalToAbbreviationMap.get(input.trim().toUpperCase().replaceAll(/\s+/g, " ")) ||
 		null
 	)
 }
@@ -152,9 +157,13 @@ export function lookupDirectionalAbbreviation(input: unknown): DirectionalAbbrev
  * Result of a directional lookup: the canonical full name + its preferred abbreviation.
  */
 export interface DirectionalMatch {
-	/** The matched directional name, e.g. "NORTH", "NORTH EAST". */
+	/**
+	 * The matched directional name, e.g. "NORTH", "NORTH EAST".
+	 */
 	directional: DirectionalName
-	/** The corresponding USPS abbreviation, e.g. "N", "NE". */
+	/**
+	 * The corresponding USPS abbreviation, e.g. "N", "NE".
+	 */
 	abbreviation: DirectionalAbbreviation
 }
 
@@ -207,7 +216,7 @@ export function renderDirectional(
 	form: "abbr" | "full",
 	reference: string
 ): string {
-	const target = form === "abbr" ? match.abbreviation : match.canonical.replace(/\s+/g, "")
+	const target = form === "abbr" ? match.abbreviation : match.canonical.replaceAll(/\s+/g, "")
 
 	return matchCase(target, reference)
 }

package/us/street-suffix.ts

@@ -228,7 +228,9 @@ export const US_STREET_SUFFIX_VARIANTS = {
 	WELLS: ["WLS"],
 } as const satisfies Record<string, readonly string[]>
 
-/** Canonical USPS suffix (full word, uppercase per the publication). */
+/**
+ * Canonical USPS suffix (full word, uppercase per the publication).
+ */
 export type USStreetSuffix = keyof typeof US_STREET_SUFFIX_VARIANTS
 
 /**
@@ -254,7 +256,9 @@ export const US_STREET_SUFFIX_LOOKUP: ReadonlyMap<string, USStreetSuffix> = (()
 	return out
 })()
 
-/** Preferred USPS abbreviation per canonical (`AVENUE → "AVE"`, `STREET → "ST"`). */
+/**
+ * Preferred USPS abbreviation per canonical (`AVENUE → "AVE"`, `STREET → "ST"`).
+ */
 export const US_STREET_SUFFIX_PREFERRED_ABBR: Readonly<Record<USStreetSuffix, string>> = Object.fromEntries(
 	(Object.keys(US_STREET_SUFFIX_VARIANTS) as USStreetSuffix[]).map((k) => [k, US_STREET_SUFFIX_VARIANTS[k][0]])
 ) as Readonly<Record<USStreetSuffix, string>>
@@ -285,7 +289,7 @@ export function matchTrailingSuffix(street: string): { canonical: USStreetSuffix
 
 	if (!trimmed) return null
 	const parts = trimmed.split(/\s+/)
-	const last = parts[parts.length - 1]!
+	const last = parts.at(-1)!
 	const canonical = US_STREET_SUFFIX_LOOKUP.get(last.toLowerCase())
 
 	if (!canonical) return null
@@ -297,6 +301,7 @@ export function matchTrailingSuffix(street: string): { canonical: USStreetSuffix
  * The USPS suffix record, under its original isp-nexus name. Aliases {@link US_STREET_SUFFIX_VARIANTS}.
  */
 export const StreetSuffixAbbreviationRecord = US_STREET_SUFFIX_VARIANTS
+
 export type StreetSuffixAbbreviationRecord = typeof US_STREET_SUFFIX_VARIANTS
 
 /**
@@ -304,17 +309,27 @@ export type StreetSuffixAbbreviationRecord = typeof US_STREET_SUFFIX_VARIANTS
  */
 export type StreetSuffix = USStreetSuffix
 
-/** A standardized USPS street suffix abbreviation (the preferred form), i.e. "ST", "AVE", "BLVD". */
+/**
+ * A standardized USPS street suffix abbreviation (the preferred form), i.e. "ST", "AVE", "BLVD".
+ */
 export type USPSStandardSuffixAbbreviation = StreetSuffixAbbreviationRecord[StreetSuffix][0]
 
-/** Any USPS-recognized suffix variant or abbreviation. */
+/**
+ * Any USPS-recognized suffix variant or abbreviation.
+ */
 export type StreetSuffixAbbreviation = StreetSuffixAbbreviationRecord[StreetSuffix][number]
 
-/** Result of a successful USPS street suffix lookup. */
+/**
+ * Result of a successful USPS street suffix lookup.
+ */
 export interface StreetSuffixMatch<S extends StreetSuffix = StreetSuffix> {
-	/** The matched canonical USPS street suffix, i.e. "STREET", "AVENUE". */
+	/**
+	 * The matched canonical USPS street suffix, i.e. "STREET", "AVENUE".
+	 */
 	suffix: S
-	/** The preferred USPS street suffix abbreviation, i.e. "ST", "AVE". */
+	/**
+	 * The preferred USPS street suffix abbreviation, i.e. "ST", "AVE".
+	 */
 	abbreviation: StreetSuffixAbbreviationRecord[S][0]
 }
 
@@ -323,6 +338,7 @@ export interface StreetSuffixMatch<S extends StreetSuffix = StreetSuffix> {
  */
 export function lookupStreetSuffix<S extends StreetSuffix>(suffix: S): StreetSuffixMatch<S>
 export function lookupStreetSuffix(input: string | null | undefined): StreetSuffixMatch | null
+
 export function lookupStreetSuffix(input: string | null | undefined): StreetSuffixMatch | null {
 	if (!input || typeof input !== "string") return null
 	const suffix = US_STREET_SUFFIX_LOOKUP.get(input.trim().toLowerCase())
@@ -332,7 +348,9 @@ export function lookupStreetSuffix(input: string | null | undefined): StreetSuff
 	return { suffix, abbreviation: US_STREET_SUFFIX_VARIANTS[suffix][0] }
 }
 
-/** Type-predicate: is the input a canonical USPS street suffix (uppercase full word, e.g. "STREET")? */
+/**
+ * Type-predicate: is the input a canonical USPS street suffix (uppercase full word, e.g. "STREET")?
+ */
 export function isStreetSuffix(input: unknown): input is StreetSuffix {
 	return typeof input === "string" && Object.hasOwn(US_STREET_SUFFIX_VARIANTS, input)
 }

package/us/unit-designator.ts

@@ -62,7 +62,9 @@ export const US_UNIT_DESIGNATOR_VARIANTS = {
 	UPPER: ["UPPR"],
 } as const satisfies Record<string, readonly string[]>
 
-/** Canonical USPS secondary unit designator (full word, uppercase per the publication). */
+/**
+ * Canonical USPS secondary unit designator (full word, uppercase per the publication).
+ */
 export type USUnitDesignator = keyof typeof US_UNIT_DESIGNATOR_VARIANTS
 
 /**
@@ -86,7 +88,9 @@ export const US_UNIT_DESIGNATOR_LOOKUP: ReadonlyMap<string, USUnitDesignator> =
 	return out
 })()
 
-/** Approved USPS abbreviation per canonical (`APARTMENT → "APT"`, `SUITE → "STE"`). */
+/**
+ * Approved USPS abbreviation per canonical (`APARTMENT → "APT"`, `SUITE → "STE"`).
+ */
 export const US_UNIT_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<USUnitDesignator, string>> = Object.fromEntries(
 	(Object.keys(US_UNIT_DESIGNATOR_VARIANTS) as USUnitDesignator[]).map((k) => [k, US_UNIT_DESIGNATOR_VARIANTS[k][0]])
 ) as Readonly<Record<USUnitDesignator, string>>
@@ -141,11 +145,17 @@ export function matchLeadingDesignator(unit: string): { canonical: USUnitDesigna
 	return { canonical, matched: first }
 }
 
-/** Result of {@link matchLeadingDesignatorWithRange}: the leading designator plus its optional secondary range. */
+/**
+ * Result of {@link matchLeadingDesignatorWithRange}: the leading designator plus its optional secondary range.
+ */
 export interface UnitDesignatorRangeMatch {
-	/** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+	/**
+	 * The matched canonical designator, i.e. "APARTMENT", "SUITE".
+	 */
 	canonical: USUnitDesignator
-	/** The designator's own matched surface form, i.e. "Apt". */
+	/**
+	 * The designator's own matched surface form, i.e. "Apt".
+	 */
 	matched: string
 	/**
 	 * The secondary range/identifier token immediately following the designator, i.e. "4B" in "Apt 4B". Undefined when
@@ -183,11 +193,17 @@ export function matchLeadingDesignatorWithRange(unit: string): UnitDesignatorRan
 	}
 }
 
-/** Result of a successful USPS secondary-unit designator lookup. */
+/**
+ * Result of a successful USPS secondary-unit designator lookup.
+ */
 export interface UnitDesignatorMatch<D extends USUnitDesignator = USUnitDesignator> {
-	/** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+	/**
+	 * The matched canonical designator, i.e. "APARTMENT", "SUITE".
+	 */
 	designator: D
-	/** The approved USPS abbreviation, i.e. "APT", "STE". */
+	/**
+	 * The approved USPS abbreviation, i.e. "APT", "STE".
+	 */
 	abbreviation: (typeof US_UNIT_DESIGNATOR_VARIANTS)[D][0]
 }
 
@@ -197,6 +213,7 @@ export interface UnitDesignatorMatch<D extends USUnitDesignator = USUnitDesignat
  */
 export function lookupUnitDesignator<D extends USUnitDesignator>(designator: D): UnitDesignatorMatch<D>
 export function lookupUnitDesignator(input: string | null | undefined): UnitDesignatorMatch | null
+
 export function lookupUnitDesignator(input: string | null | undefined): UnitDesignatorMatch | null {
 	if (!input || typeof input !== "string") return null
 	const designator = US_UNIT_DESIGNATOR_LOOKUP.get(input.trim().toLowerCase())