@mailwoman/codex 4.10.0 → 4.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -0
- package/out/address-system-conventions.d.ts.map +1 -1
- package/out/address-system-conventions.js +20 -8
- package/out/address-system-conventions.js.map +1 -1
- package/out/us/zipcode.d.ts +0 -1
- package/out/us/zipcode.d.ts.map +1 -1
- package/out/us/zipcode.js.map +1 -1
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# @mailwoman/codex
|
|
2
|
+
|
|
3
|
+
**Per-address-system postal reference data and branded types.**
|
|
4
|
+
|
|
5
|
+
Every country's postal authority (USPS, La Poste, Deutsche Post, …) has its own
|
|
6
|
+
conventions for what a postcode, a street suffix, or a unit designator looks like.
|
|
7
|
+
`@mailwoman/codex` is the shared, dependency-free home for that reference knowledge,
|
|
8
|
+
kept apart from the locale-agnostic tokenizer/solver in `@mailwoman/core` and from
|
|
9
|
+
the training pipeline in `@mailwoman/corpus`.
|
|
10
|
+
|
|
11
|
+
The parser, the resolver, and the synthesis layer all reach for the same tables
|
|
12
|
+
instead of each carrying their own copy.
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { us, fr, gb, de } from "@mailwoman/codex"
|
|
16
|
+
|
|
17
|
+
// USPS street suffix lookup
|
|
18
|
+
us.lookupStreetSuffix("PKWY") // → { primary: "Parkway", standard: "Parkway", ... }
|
|
19
|
+
us.lookupStreetSuffix("PKY") // → { primary: "Parkway", standard: "Parkway", ... }
|
|
20
|
+
|
|
21
|
+
// French postcode pattern
|
|
22
|
+
fr.postcodePattern // → /^\d{5}$/
|
|
23
|
+
|
|
24
|
+
// US ZIP code branded type
|
|
25
|
+
import { us } from "@mailwoman/codex"
|
|
26
|
+
const zip: us.ZipCode = "94043" // branded, not just string
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Supported address systems
|
|
30
|
+
|
|
31
|
+
Each system is exposed as a namespace and as a subpath import:
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { us } from "@mailwoman/codex"
|
|
35
|
+
import { lookupStreetSuffix } from "@mailwoman/codex/us"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
| System | Scope |
|
|
39
|
+
| -------- | ------------------------------------------------------------------------------------ |
|
|
40
|
+
| **`us`** | USPS street suffixes, directional abbreviations, ZIP code types, state abbreviations |
|
|
41
|
+
| **`fr`** | La Poste postcode format, CEDEX conventions, département codes |
|
|
42
|
+
| **`gb`** | Royal Mail postcode format, post town conventions |
|
|
43
|
+
| **`de`** | Deutsche Post postcode format, Bundesland abbreviations |
|
|
44
|
+
| **`ca`** | Canada Post postcode format, province abbreviations |
|
|
45
|
+
| **`au`** | Australia Post postcode format, state abbreviations |
|
|
46
|
+
|
|
47
|
+
## Cross-system utilities
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { candidateSystemsForPostcode } from "@mailwoman/codex"
|
|
51
|
+
|
|
52
|
+
// Which systems could "94043" belong to?
|
|
53
|
+
candidateSystemsForPostcode("94043") // → ["us"]
|
|
54
|
+
candidateSystemsForPostcode("75008") // → ["fr"]
|
|
55
|
+
candidateSystemsForPostcode("10115") // → ["de"]
|
|
56
|
+
|
|
57
|
+
// Address system conventions (forbidden tags, expected shapes, etc.)
|
|
58
|
+
import { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem } from "@mailwoman/codex"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Design
|
|
62
|
+
|
|
63
|
+
- **Zero runtime dependencies.** Pure TypeScript data tables — no database, no I/O,
|
|
64
|
+
no network. Suitable for bundling into browser and edge environments.
|
|
65
|
+
- **Branded types.** ZIP codes, postcodes, and abbreviations carry nominal types
|
|
66
|
+
so the type system catches locale mismatches at compile time.
|
|
67
|
+
- **Single source of truth.** The resolver, the decoder's convention masks, the
|
|
68
|
+
corpus synthesis layer, and the matcher all import from `@mailwoman/codex`.
|
|
69
|
+
|
|
70
|
+
## Related
|
|
71
|
+
|
|
72
|
+
- [`@mailwoman/core`](../core) — `ComponentTag` schema, pipeline infrastructure
|
|
73
|
+
- [`@mailwoman/classifiers`](../classifiers) — rule-based classifiers that consume codex data
|
|
74
|
+
- [`@mailwoman/address-id`](../address-id) — uses codex for stable address primary keys
|
|
75
|
+
- [Address system conventions](https://mailwoman.sister.software/articles/plan/reference/SCHEMA/)
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"address-system-conventions.d.ts","sourceRoot":"","sources":["../address-system-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,eAAO,MAAM,0BAA0B,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,wBAAwB,CAAC,
|
|
1
|
+
{"version":3,"file":"address-system-conventions.d.ts","sourceRoot":"","sources":["../address-system-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,eAAO,MAAM,0BAA0B,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,wBAAwB,CAAC,CA0B5F,CAAA;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,wBAAwB,GAAG,IAAI,CAG3G"}
|
|
@@ -20,16 +20,28 @@
|
|
|
20
20
|
import { CODE_POSTAL_PATTERN } from "./fr/code-postal.js";
|
|
21
21
|
export const ADDRESS_SYSTEM_CONVENTIONS = {
|
|
22
22
|
/**
|
|
23
|
-
* France (La Poste / AFNOR NF Z 10-011): street
|
|
24
|
-
* ("Rue de Rivoli", "Avenue des Champs-Élysées"
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
23
|
+
* France (La Poste / AFNOR NF Z 10-011): the street TYPE is a LEADING particle of the street name
|
|
24
|
+
* ("Rue de Rivoli", "Avenue des Champs-Élysées", "Cours Lafayette") and is labeled
|
|
25
|
+
* `street_prefix` — French addresses DO carry a street_prefix, just never a trailing USPS-style
|
|
26
|
+
* street_suffix (the libpostal French dictionaries have no trailing street-suffix class; Pub-28's
|
|
27
|
+
* suffix decomposition has no French counterpart).
|
|
28
|
+
*
|
|
29
|
+
* Provenance / why this is NOT a blanket prefix+suffix forbid (#719, 2026-06-18): an earlier
|
|
30
|
+
* model mis-tagged the leading "Rue" as a US-style `street_suffix` (RUE is genuinely a Pub-28
|
|
31
|
+
* suffix variant) — the 2026-06-10 v1.1.0 gate — so #511 forbade BOTH affix tags to stop that
|
|
32
|
+
* leakage. That forbid was correct for THAT model but became a live production bug for the
|
|
33
|
+
* current one: the shipped model (v1.5.0) emits the FR `street_prefix` correctly, but the
|
|
34
|
+
* conventions mask was a hard −1e9 on every B-/I-street_prefix emission, so the detected-FR parse
|
|
35
|
+
* could never KEEP a prefix — it destroyed `street_prefix` wholesale (measured on
|
|
36
|
+
* data/eval/external/ fr-street-prefix-real.jsonl at conventions=auto: F1 0.0 with the forbid on
|
|
37
|
+
* → 80.0 with it off; the larger real-FR eval reported the same collapse, ~96 → ~0.6). We keep
|
|
38
|
+
* ONLY `street_suffix` forbidden: the current model with the forbid OFF shows zero FR
|
|
39
|
+
* street_suffix leakage (fp=0 on that same slice) and FR genuinely has no trailing street suffix,
|
|
40
|
+
* so the constraint costs nothing while still guarding against any future suffix mis-tag.
|
|
41
|
+
* Postcode: exactly five digits (NF Z 10-011; see fr/code-postal).
|
|
30
42
|
*/
|
|
31
43
|
fr: {
|
|
32
|
-
forbiddenTags: ["
|
|
44
|
+
forbiddenTags: ["street_suffix"],
|
|
33
45
|
postcodePattern: CODE_POSTAL_PATTERN,
|
|
34
46
|
},
|
|
35
47
|
};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"address-system-conventions.js","sourceRoot":"","sources":["../address-system-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAiBzD,MAAM,CAAC,MAAM,0BAA0B,GAA0D;IAChG
|
|
1
|
+
{"version":3,"file":"address-system-conventions.js","sourceRoot":"","sources":["../address-system-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAiBzD,MAAM,CAAC,MAAM,0BAA0B,GAA0D;IAChG;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,EAAE,EAAE;QACH,aAAa,EAAE,CAAC,eAAe,CAAC;QAChC,eAAe,EAAE,mBAAmB;KACpC;CACD,CAAA;AAED,iGAAiG;AACjG,MAAM,UAAU,oBAAoB,CAAC,MAAqC;IACzE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IACxB,OAAO,0BAA0B,CAAC,MAAM,CAAC,IAAI,IAAI,CAAA;AAClD,CAAC"}
|
package/out/us/zipcode.d.ts
CHANGED
package/out/us/zipcode.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"zipcode.d.ts","sourceRoot":"","sources":["../../us/zipcode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;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
|
|
1
|
+
{"version":3,"file":"zipcode.d.ts","sourceRoot":"","sources":["../../us/zipcode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"zipcode.js","sourceRoot":"","sources":["../../us/zipcode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,qBAAqB,EAA4B,MAAM,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"zipcode.js","sourceRoot":"","sources":["../../us/zipcode.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mailwoman/codex",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.11.0",
|
|
4
4
|
"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.",
|
|
5
5
|
"license": "AGPL-3.0-only",
|
|
6
6
|
"repository": {
|