@mailwoman/codex 4.0.0

package/out/us/street-suffix.js

@@ -0,0 +1,313 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C — Postal Service Standard Suffix Abbreviations.
+ *
+ *   For each canonical suffix the value lists every recognized variant in USPS-published order; the
+ *   first variant is the preferred USPS abbreviation (e.g. `AVENUE → ["AVE", "AV", "AVEN", "AVENU",
+ *   "AVN", "AVNUE"]` — `AVE` is what the post office prints).
+ *
+ *   This module is the single home for the USPS suffix table. It carries both the synthesis-layer
+ *   helpers (`US_STREET_SUFFIX_PREFERRED_ABBR`, `matchCase`, `matchTrailingSuffix` — used by
+ *   `@mailwoman/corpus`) and the richer branded-type lookup (`StreetSuffix`, `lookupStreetSuffix`,
+ *   `isStreetSuffix`) salvaged from the original isp-nexus `postal/suffix.ts`. The data is verbatim
+ *   USPS Pub-28; the two APIs share one underlying record.
+ *
+ *   Salvaged 2026-05-17 (data) / 2026-06-03 (types) from
+ *   `isp-nexus/universe@6eeb7bd99643a6d62a8b8abbd50968a1e492b90b` `mailwoman/postal/suffix.ts`
+ *   (originally copyright Sister Software; both projects are AGPL-3.0).
+ * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Street Suffix Abbreviations}
+ */
+/**
+ * Canonical USPS street suffix → list of recognized variants. The first variant in each list is the
+ * preferred USPS abbreviation. Keys + values are uppercase per the publication.
+ */
+export const US_STREET_SUFFIX_VARIANTS = {
+    ALLEY: ["ALY", "ALLEE", "ALLY"],
+    ANEX: ["ANX", "ANNEX", "ANNX"],
+    ARCADE: ["ARC"],
+    AVENUE: ["AVE", "AV", "AVEN", "AVENU", "AVN", "AVNUE"],
+    BAYOU: ["BYU", "BAYOO"],
+    BEACH: ["BCH"],
+    BEND: ["BND"],
+    BLUFF: ["BLF", "BLUF"],
+    BLUFFS: ["BLFS"],
+    BOTTOM: ["BTM", "BOT", "BOTTM"],
+    BOULEVARD: ["BLVD", "BOUL", "BOULV"],
+    BRANCH: ["BR", "BRNCH"],
+    BRIDGE: ["BRG", "BRDGE"],
+    BROOK: ["BRK"],
+    BROOKS: ["BRKS"],
+    BURG: ["BG"],
+    BURGS: ["BGS"],
+    BYPASS: ["BYP", "BYPA", "BYPAS", "BYPS"],
+    CAMP: ["CP", "CMP"],
+    CANYON: ["CYN", "CANYN", "CNYN"],
+    CAPE: ["CPE"],
+    CAUSEWAY: ["CSWY", "CAUSWA"],
+    CENTER: ["CTR", "CEN", "CENT", "CENTR", "CENTRE", "CNTER", "CNTR"],
+    CENTERS: ["CTRS"],
+    CIRCLE: ["CIR", "CIRC", "CIRCL", "CRCL", "CRCLE"],
+    CIRCLES: ["CIRS"],
+    CLIFF: ["CLF"],
+    CLIFFS: ["CLFS"],
+    CLUB: ["CLB"],
+    COMMON: ["CMN"],
+    COMMONS: ["CMNS"],
+    CORNER: ["COR"],
+    CORNERS: ["CORS"],
+    COURSE: ["CRSE"],
+    COURT: ["CT"],
+    COURTS: ["CTS"],
+    COVE: ["CV"],
+    COVES: ["CVS"],
+    CREEK: ["CRK"],
+    CRESCENT: ["CRES", "CRSENT", "CRSNT"],
+    CREST: ["CRST"],
+    CROSSING: ["XING", "CRSSNG"],
+    CROSSROAD: ["XRD"],
+    CROSSROADS: ["XRDS"],
+    CURVE: ["CURV"],
+    DALE: ["DL"],
+    DAM: ["DM"],
+    DIVIDE: ["DV", "DIV", "DVD"],
+    DRIVE: ["DR", "DRIV", "DRV"],
+    DRIVES: ["DRS"],
+    ESTATE: ["EST"],
+    ESTATES: ["ESTS"],
+    EXPRESSWAY: ["EXPY", "EXP", "EXPR", "EXPRESS", "EXPW"],
+    EXTENSION: ["EXT", "EXTN", "EXTNSN"],
+    EXTENSIONS: ["EXTS"],
+    FALL: ["FALL"],
+    FALLS: ["FLS"],
+    FERRY: ["FRY", "FRRY"],
+    FIELD: ["FLD"],
+    FIELDS: ["FLDS"],
+    FLAT: ["FLT"],
+    FLATS: ["FLTS"],
+    FORD: ["FRD"],
+    FORDS: ["FRDS"],
+    FOREST: ["FRST", "FORESTS"],
+    FORGE: ["FRG", "FORG"],
+    FORGES: ["FRGS"],
+    FORK: ["FRK"],
+    FORKS: ["FRKS"],
+    FORT: ["FT", "FRT"],
+    FREEWAY: ["FWY", "FREEWY", "FRWAY", "FRWY"],
+    GARDEN: ["GDN", "GARDN", "GRDEN", "GRDN"],
+    GARDENS: ["GDNS", "GRDNS"],
+    GATEWAY: ["GTWY", "GATEWY", "GATWAY", "GTWAY"],
+    GLEN: ["GLN"],
+    GLENS: ["GLNS"],
+    GREEN: ["GRN"],
+    GREENS: ["GRNS"],
+    GROVE: ["GRV", "GROV"],
+    GROVES: ["GRVS"],
+    HARBOR: ["HBR", "HARB", "HARBR", "HRBOR"],
+    HARBORS: ["HBRS"],
+    HAVEN: ["HVN"],
+    HEIGHTS: ["HTS", "HT"],
+    HIGHWAY: ["HWY", "HIGHWY", "HIWAY", "HIWY", "HWAY"],
+    HILL: ["HL"],
+    HILLS: ["HLS"],
+    HOLLOW: ["HOLW", "HLLW", "HOLLOWS", "HOLWS"],
+    INLET: ["INLT"],
+    ISLAND: ["IS", "ISLND"],
+    ISLANDS: ["ISS", "ISLNDS"],
+    ISLE: ["ISLE", "ISLES"],
+    JUNCTION: ["JCT", "JCTION", "JCTN", "JUNCTN", "JUNCTON"],
+    JUNCTIONS: ["JCTS", "JCTNS"],
+    KEY: ["KY"],
+    KEYS: ["KYS"],
+    KNOLL: ["KNL", "KNOL"],
+    KNOLLS: ["KNLS"],
+    LAKE: ["LK"],
+    LAKES: ["LKS"],
+    LAND: ["LAND"],
+    LANDING: ["LNDG", "LNDNG"],
+    LANE: ["LN"],
+    LIGHT: ["LGT"],
+    LIGHTS: ["LGTS"],
+    LOAF: ["LF"],
+    LOCK: ["LCK"],
+    LOCKS: ["LCKS"],
+    LODGE: ["LDG", "LDGE", "LODG"],
+    LOOP: ["LOOP", "LOOPS"],
+    MALL: ["MALL"],
+    MANOR: ["MNR"],
+    MANORS: ["MNRS"],
+    MEADOW: ["MDW"],
+    MEADOWS: ["MDWS", "MDW", "MEDOWS"],
+    MEWS: ["MEWS"],
+    MILL: ["ML"],
+    MILLS: ["MLS"],
+    MISSION: ["MSN", "MISSN", "MSSN"],
+    MOTORWAY: ["MTWY"],
+    MOUNT: ["MT", "MNT"],
+    MOUNTAIN: ["MTN", "MNTAIN", "MNTN", "MOUNTIN", "MTIN"],
+    MOUNTAINS: ["MTNS", "MNTNS"],
+    NECK: ["NCK"],
+    ORCHARD: ["ORCH", "ORCHRD"],
+    OVAL: ["OVAL", "OVL"],
+    OVERPASS: ["OPAS"],
+    PARK: ["PARK", "PRK", "PARKS"],
+    PARKWAY: ["PKWY", "PARKWY", "PKWAY", "PKY"],
+    PARKWAYS: ["PKWY", "PKWYS"],
+    PASS: ["PASS"],
+    PASSAGE: ["PSGE"],
+    PATH: ["PATH", "PATHS"],
+    PIKE: ["PIKE", "PIKES"],
+    PINE: ["PNE"],
+    PINES: ["PNES"],
+    PLACE: ["PL"],
+    PLAIN: ["PLN"],
+    PLAINS: ["PLNS"],
+    PLAZA: ["PLZ", "PLZA"],
+    POINT: ["PT"],
+    POINTS: ["PTS"],
+    PORT: ["PRT"],
+    PORTS: ["PRTS"],
+    PRAIRIE: ["PR", "PRR"],
+    RADIAL: ["RADL", "RAD", "RADIEL"],
+    RAMP: ["RAMP"],
+    RANCH: ["RNCH", "RANCHES", "RNCHS"],
+    RAPID: ["RPD"],
+    RAPIDS: ["RPDS"],
+    REST: ["RST"],
+    RIDGE: ["RDG", "RDGE"],
+    RIDGES: ["RDGS"],
+    RIVER: ["RIV", "RVR", "RIVR"],
+    ROAD: ["RD"],
+    ROADS: ["RDS"],
+    ROUTE: ["RTE"],
+    ROW: ["ROW"],
+    RUE: ["RUE"],
+    RUN: ["RUN"],
+    SHOAL: ["SHL"],
+    SHOALS: ["SHLS"],
+    SHORE: ["SHR", "SHOAR"],
+    SHORES: ["SHRS", "SHOARS"],
+    SKYWAY: ["SKWY"],
+    SPRING: ["SPG", "SPNG", "SPRNG"],
+    SPRINGS: ["SPGS", "SPNGS", "SPRNGS"],
+    SPUR: ["SPUR"],
+    SPURS: ["SPUR"],
+    SQUARE: ["SQ", "SQR", "SQRE", "SQU"],
+    SQUARES: ["SQS", "SQRS"],
+    STATION: ["STA", "STATN", "STN"],
+    STRAVENUE: ["STRA", "STRAV", "STRAVEN", "STRAVN", "STRVN", "STRVNUE"],
+    STREAM: ["STRM", "STREME"],
+    STREET: ["ST", "STRT", "STR"],
+    STREETS: ["STS"],
+    SUMMIT: ["SMT", "SUMIT", "SUMITT"],
+    TERRACE: ["TER", "TERR"],
+    THROUGHWAY: ["TRWY"],
+    TRACE: ["TRCE", "TRACES"],
+    TRACK: ["TRAK", "TRACKS", "TRK", "TRKS"],
+    TRAFFICWAY: ["TRFY"],
+    TRAIL: ["TRL", "TRAILS", "TRLS"],
+    TRAILER: ["TRLR", "TRLRS"],
+    TUNNEL: ["TUNL", "TUNEL", "TUNLS", "TUNNELS", "TUNNL"],
+    TURNPIKE: ["TPKE", "TRNPK", "TURNPK"],
+    UNDERPASS: ["UPAS"],
+    UNION: ["UN"],
+    UNIONS: ["UNS"],
+    VALLEY: ["VLY", "VALLY", "VLLY"],
+    VALLEYS: ["VLYS"],
+    VIADUCT: ["VIA", "VDCT", "VIADCT"],
+    VIEW: ["VW"],
+    VIEWS: ["VWS"],
+    VILLAGE: ["VLG", "VILL", "VILLAG", "VILLG", "VILLIAGE"],
+    VILLAGES: ["VLGS"],
+    VILLE: ["VL"],
+    VISTA: ["VIS", "VIST", "VST", "VSTA"],
+    WALK: ["WALK"],
+    WALKS: ["WALK"],
+    WALL: ["WALL"],
+    WAY: ["WAY", "WY"],
+    WAYS: ["WAYS"],
+    WELL: ["WL"],
+    WELLS: ["WLS"],
+};
+/**
+ * Inverse lookup: every variant abbreviation OR full canonical word → its canonical key. Built once
+ * at module load, lowercase-keyed for case-insensitive matching (`street` → `"STREET"`, `st` →
+ * `"STREET"`, `strt` → `"STREET"`, …).
+ */
+export const US_STREET_SUFFIX_LOOKUP = (() => {
+    const out = new Map();
+    for (const canonical of Object.keys(US_STREET_SUFFIX_VARIANTS)) {
+        out.set(canonical.toLowerCase(), canonical);
+        for (const variant of US_STREET_SUFFIX_VARIANTS[canonical]) {
+            // Don't overwrite — first canonical that claims a variant wins (matches USPS Pub-28's
+            // ordering). E.g. "WALK" and "WALKS" both list "WALK" as a variant; "WALK" wins because it
+            // sorts first in `Object.keys`.
+            if (!out.has(variant.toLowerCase()))
+                out.set(variant.toLowerCase(), canonical);
+        }
+    }
+    return out;
+})();
+/** Preferred USPS abbreviation per canonical (`AVENUE → "AVE"`, `STREET → "ST"`). */
+export const US_STREET_SUFFIX_PREFERRED_ABBR = Object.fromEntries(Object.keys(US_STREET_SUFFIX_VARIANTS).map((k) => [k, US_STREET_SUFFIX_VARIANTS[k][0]]));
+/**
+ * Apply `target`'s letters in the same case-pattern as `reference`. Three patterns covered:
+ *
+ * - All-uppercase reference (`"AVE"`) → uppercase target (`"AVENUE"`).
+ * - All-lowercase reference (`"ave"`) → lowercase target (`"avenue"`).
+ * - Anything else (`"Ave"`, `"aVe"`) → title-case target (`"Avenue"`).
+ */
+export function matchCase(target, reference) {
+    if (!reference)
+        return target;
+    if (reference === reference.toUpperCase())
+        return target.toUpperCase();
+    if (reference === reference.toLowerCase())
+        return target.toLowerCase();
+    return target.charAt(0).toUpperCase() + target.slice(1).toLowerCase();
+}
+/**
+ * If the last whitespace-separated word of `street` is a known USPS suffix variant, return the
+ * canonical key and the matched word. Returns null if the trailing word isn't a known suffix.
+ */
+export function matchTrailingSuffix(street) {
+    const trimmed = street.trim();
+    if (!trimmed)
+        return null;
+    const parts = trimmed.split(/\s+/);
+    const last = parts[parts.length - 1];
+    const canonical = US_STREET_SUFFIX_LOOKUP.get(last.toLowerCase());
+    if (!canonical)
+        return null;
+    return { canonical, matched: last };
+}
+// ── Branded-type lookup (salvaged from isp-nexus postal/suffix.ts) ───────────────────────────────
+// The record above is the data; the types below give callers a precise StreetSuffix / abbreviation
+// vocabulary and a type-safe lookup, without a second copy of the table.
+/**
+ * The USPS suffix record, under its original isp-nexus name. Aliases
+ * {@link US_STREET_SUFFIX_VARIANTS}.
+ */
+export const StreetSuffixAbbreviationRecord = US_STREET_SUFFIX_VARIANTS;
+export function lookupStreetSuffix(input) {
+    if (!input || typeof input !== "string")
+        return null;
+    const suffix = US_STREET_SUFFIX_LOOKUP.get(input.trim().toLowerCase());
+    if (!suffix)
+        return null;
+    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")? */
+export function isStreetSuffix(input) {
+    return typeof input === "string" && Object.hasOwn(US_STREET_SUFFIX_VARIANTS, input);
+}
+/**
+ * True when a token is any USPS street suffix or abbreviation (case-insensitive) — `"St"`,
+ * `"BLVD"`, `"trail"`.
+ */
+export function isStreetSuffixToken(input) {
+    return typeof input === "string" && US_STREET_SUFFIX_LOOKUP.has(input.trim().toLowerCase());
+}
+//# sourceMappingURL=street-suffix.js.map

package/out/us/street-suffix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"street-suffix.js","sourceRoot":"","sources":["../../us/street-suffix.ts"],"names":[],"mappings":"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"}

package/out/us/zipcode.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US ZIP (Zone Improvement Plan) codes: branded string types, the shape patterns, the first-digit →
+ *   state geographic prior, and a state-plus-ZIP plucker.
+ *
+ *   Salvaged 2026-06-03 from `isp-nexus/universe@6eeb7bd99643a6d62a8b8abbd50968a1e492b90b`
+ *   `mailwoman/postal/zipcode.ts` (originally copyright Sister Software; both projects are
+ *   AGPL-3.0). The only adaptation: the state abbreviation type comes from this package's own
+ *   {@link state.js} rather than `@isp.nexus/tiger`, so the codex stays dependency-free.
+ */
+import type { Tagged } from "type-fest";
+import { type UsStateAbbreviation } from "./state.js";
+/**
+ * USPS-recognized ZIP code digits.
+ *
+ * @internal
+ */
+export type ZipCodeDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * A ZIP (Zone Improvement Plan) Code is a five-digit code assigned by the USPS to a section of a
+ * street, a collection of streets, an establishment, structure, or group of post office boxes, for
+ * the delivery of mail.
+ *
+ * - The first 3 digits of the ZIP code represent a specific central mail processing facility, which
+ *   can be used to identify the locality and region of the address, i.e. the city and state.
+ * - The last 2 digits of the ZIP code represent a specific post office or delivery area.
+ *
+ * ```txt
+ *        90210
+ *       / |⎿__(Post Office)
+ *      /   \
+ *  (State)  \
+ *            \
+ *           (City)
+ * ```
+ *
+ * Note that ZIP codes are not truly areas, but rather a group of deliverable addresses, which can
+ * and do change over time.
+ *
+ * @category Delivery
+ * @category Postal
+ * @type string
+ * @see {@linkcode ZipCodePlusFour} for the extended ZIP code format.
+ * @title ZIP Code
+ * @pattern ^\d{5}$
+ */
+export type ZipCode = Tagged<string, "ZipCode">;
+/**
+ * The extended ZIP code format includes the five-digit ZIP code followed by a hyphen and four
+ * additional digits. This extended format is used to provide more precise location information.
+ *
+ * - The first 3 digits of the ZIP code represent a specific central mail processing facility,
+ * - The last 2 digits of the ZIP code represent a specific post office or delivery area.
+ * - The four additional digits represent a specific delivery route within the ZIP code area.
+ *
+ * ```txt
+ *                  90210-1234
+ *                  \_/\ /\__/
+ *                  /   |    \
+ *  (State, City)_ /    |     \_ (Delivery Route)
+ *                      |
+ *                (Post Office)
+ * ```
+ *
+ * Note that ZIP codes are not truly areas, but rather a group of deliverable addresses, which can
+ * and do change over time.
+ *
+ * @category Delivery
+ * @category Postal
+ * @type string
+ * @see {@linkcode ZipCode} for the standard ZIP code format.
+ * @title ZIP Code+4
+ * @pattern ^\d{5}-\d{4}$
+ */
+export type ZipCodePlusFour = Tagged<string, "ZipCodePlusFour">;
+/**
+ * Type utility to extract the state abbreviation from a ZIP code.
+ *
+ * @internal
+ */
+export type ExtractStateFromZipCode<Zip extends ZipCode | ZipCodePlusFour> = Zip extends `${infer StateCode}${infer _Rest}` ? StateCode : never;
+/**
+ * Record of US state abbreviations to their corresponding ZIP code prefix (the leading digit). A
+ * cheap geographic prior: a 5-digit code's first digit narrows it to a band of states, which the
+ * parser can weigh against the surrounding city/state tokens.
+ *
+ * @see {@linkcode ZipCodePrefixAbbreviationMap} for the reverse mapping.
+ * @internal
+ */
+export declare const StateAbbreviationZipCodePrefixRecord: {
+    readonly AL: 3;
+    readonly AK: 9;
+    readonly AZ: 8;
+    readonly AR: 7;
+    readonly CA: 9;
+    readonly CO: 8;
+    readonly CT: 0;
+    readonly DE: 1;
+    readonly DC: 2;
+    readonly FL: 3;
+    readonly GA: 3;
+    readonly HI: 9;
+    readonly ID: 8;
+    readonly IL: 6;
+    readonly IN: 4;
+    readonly IA: 5;
+    readonly KS: 6;
+    readonly KY: 4;
+    readonly LA: 7;
+    readonly ME: 0;
+    readonly MD: 2;
+    readonly MA: 0;
+    readonly MI: 4;
+    readonly MN: 5;
+    readonly MS: 3;
+    readonly MO: 6;
+    readonly MT: 5;
+    readonly NE: 6;
+    readonly NV: 8;
+    readonly NH: 0;
+    readonly NJ: 0;
+    readonly NM: 8;
+    readonly NY: 1;
+    readonly NC: 2;
+    readonly ND: 5;
+    readonly OH: 4;
+    readonly OK: 7;
+    readonly OR: 9;
+    readonly PA: 1;
+    readonly RI: 0;
+    readonly SC: 2;
+    readonly SD: 5;
+    readonly TN: 3;
+    readonly TX: 7;
+    readonly UT: 8;
+    readonly VT: 0;
+    readonly VA: 2;
+    readonly WA: 9;
+    readonly WV: 2;
+    readonly WI: 5;
+    readonly WY: 8;
+    readonly PR: 0;
+    readonly GU: 9;
+    readonly VI: 0;
+    readonly MP: 9;
+    readonly AS: 9;
+};
+/**
+ * Map of ZIP code prefixes to their corresponding US state abbreviations.
+ */
+declare const ZipCodePrefixAbbreviationMap: Map<ZipCodeDigit, ("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")[]>;
+export { ZipCodePrefixAbbreviationMap };
+/**
+ * Regex patterns for ZIP codes.
+ */
+export declare const ZipCodePatterns: {
+    /**
+     * 5-digit, or 9-digit ZIP code or ZIP+4 code.
+     */
+    readonly Standard: RegExp;
+    /**
+     * Two-letter state abbreviation followed by a 5-digit ZIP code or ZIP+4 code.
+     */
+    readonly StateAbbreviationWithZipCode: RegExp;
+};
+/**
+ * Type-predicate to determine if a value is a valid ZIP code.
+ */
+export declare function isZipCode(input: unknown): input is ZipCode | ZipCodePlusFour;
+export interface PluckedStateZIPCodeResult {
+    stateAbbreviation: UsStateAbbreviation | null;
+    zipCode: ZipCode | ZipCodePlusFour;
+}
+/**
+ * Given an address string like `"NY"`, `"CA 94016"`, attempts to match the state abbreviation and
+ * postal code, if applicable.
+ *
+ * @see {@linkcode isUsStateAbbreviation} to validate the state abbreviation.
+ */
+export declare function pluckStateZIPCode(input: unknown): PluckedStateZIPCodeResult | null;
+//# sourceMappingURL=zipcode.d.ts.map

package/out/us/zipcode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zipcode.d.ts","sourceRoot":"","sources":["../../us/zipcode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;AAE/D;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,CAAC,GAAG,SAAS,OAAO,GAAG,eAAe,IACxE,GAAG,SAAS,GAAG,MAAM,SAAS,GAAG,MAAM,KAAK,EAAE,GAAG,SAAS,GAAG,KAAK,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDa,CAAA;AAE9D;;GAEG;AACH,QAAA,MAAM,4BAA4B,8ZAAiD,CAAA;AAUnF,OAAO,EAAE,4BAA4B,EAAE,CAAA;AAEvC;;GAEG;AACH,eAAO,MAAM,eAAe;IAC3B;;OAEG;;IAGH;;OAEG;;CAEM,CAAA;AAEV;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,GAAG,eAAe,CAE5E;AAED,MAAM,WAAW,yBAAyB;IACzC,iBAAiB,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAC7C,OAAO,EAAE,OAAO,GAAG,eAAe,CAAA;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAalF"}

package/out/us/zipcode.js

@@ -0,0 +1,127 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US ZIP (Zone Improvement Plan) codes: branded string types, the shape patterns, the first-digit →
+ *   state geographic prior, and a state-plus-ZIP plucker.
+ *
+ *   Salvaged 2026-06-03 from `isp-nexus/universe@6eeb7bd99643a6d62a8b8abbd50968a1e492b90b`
+ *   `mailwoman/postal/zipcode.ts` (originally copyright Sister Software; both projects are
+ *   AGPL-3.0). The only adaptation: the state abbreviation type comes from this package's own
+ *   {@link state.js} rather than `@isp.nexus/tiger`, so the codex stays dependency-free.
+ */
+import { isUsStateAbbreviation } from "./state.js";
+/**
+ * Record of US state abbreviations to their corresponding ZIP code prefix (the leading digit). A
+ * cheap geographic prior: a 5-digit code's first digit narrows it to a band of states, which the
+ * parser can weigh against the surrounding city/state tokens.
+ *
+ * @see {@linkcode ZipCodePrefixAbbreviationMap} for the reverse mapping.
+ * @internal
+ */
+export const StateAbbreviationZipCodePrefixRecord = {
+    AL: 3,
+    AK: 9,
+    AZ: 8,
+    AR: 7,
+    CA: 9,
+    CO: 8,
+    CT: 0,
+    DE: 1,
+    DC: 2,
+    FL: 3,
+    GA: 3,
+    HI: 9,
+    ID: 8,
+    IL: 6,
+    IN: 4,
+    IA: 5,
+    KS: 6,
+    KY: 4,
+    LA: 7,
+    ME: 0,
+    MD: 2,
+    MA: 0,
+    MI: 4,
+    MN: 5,
+    MS: 3,
+    MO: 6,
+    MT: 5,
+    NE: 6,
+    NV: 8,
+    NH: 0,
+    NJ: 0,
+    NM: 8,
+    NY: 1,
+    NC: 2,
+    ND: 5,
+    OH: 4,
+    OK: 7,
+    OR: 9,
+    PA: 1,
+    RI: 0,
+    SC: 2,
+    SD: 5,
+    TN: 3,
+    TX: 7,
+    UT: 8,
+    VT: 0,
+    VA: 2,
+    WA: 9,
+    WV: 2,
+    WI: 5,
+    WY: 8,
+    PR: 0,
+    GU: 9,
+    VI: 0,
+    MP: 9,
+    AS: 9,
+};
+/**
+ * Map of ZIP code prefixes to their corresponding US state abbreviations.
+ */
+const ZipCodePrefixAbbreviationMap = new Map();
+for (const [state, prefix] of Object.entries(StateAbbreviationZipCodePrefixRecord)) {
+    const states = ZipCodePrefixAbbreviationMap.get(prefix) ?? [];
+    ZipCodePrefixAbbreviationMap.set(prefix, [...states, state]);
+}
+export { ZipCodePrefixAbbreviationMap };
+/**
+ * Regex patterns for ZIP codes.
+ */
+export const ZipCodePatterns = {
+    /**
+     * 5-digit, or 9-digit ZIP code or ZIP+4 code.
+     */
+    Standard: /^\d{5}(?:[-\s]\d{4})?$/,
+    /**
+     * Two-letter state abbreviation followed by a 5-digit ZIP code or ZIP+4 code.
+     */
+    StateAbbreviationWithZipCode: /^(?:([A-Za-z]{2})[ ,]*)?([0-9]{5}(?:[-\s][0-9]{4})?)$/,
+};
+/**
+ * Type-predicate to determine if a value is a valid ZIP code.
+ */
+export function isZipCode(input) {
+    return typeof input === "string" && ZipCodePatterns.Standard.test(input);
+}
+/**
+ * Given an address string like `"NY"`, `"CA 94016"`, attempts to match the state abbreviation and
+ * postal code, if applicable.
+ *
+ * @see {@linkcode isUsStateAbbreviation} to validate the state abbreviation.
+ */
+export function pluckStateZIPCode(input) {
+    if (!input || typeof input !== "string")
+        return null;
+    const [, stateAbbreviation, zipCode = null] = input.match(ZipCodePatterns.StateAbbreviationWithZipCode) || [];
+    if (!zipCode)
+        return null;
+    const normalizedState = stateAbbreviation?.toUpperCase();
+    return {
+        stateAbbreviation: isUsStateAbbreviation(normalizedState) ? normalizedState : null,
+        zipCode: zipCode,
+    };
+}
+//# sourceMappingURL=zipcode.js.map

package/out/us/zipcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zipcode.js","sourceRoot":"","sources":["../../us/zipcode.ts"],"names":[],"mappings":"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"}