@mailwoman/formatter 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 +74 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# @mailwoman/formatter
|
|
2
|
+
|
|
3
|
+
**The inverse of the parser** — render Mailwoman address components into an
|
|
4
|
+
idiomatic, locale-aware address string, plus produce a canonical, normalized
|
|
5
|
+
match key for record linkage.
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import { formatAddress, canonicalKey } from "@mailwoman/formatter"
|
|
9
|
+
|
|
10
|
+
const components = {
|
|
11
|
+
house_number: "1600",
|
|
12
|
+
street: "Amphitheatre Parkway",
|
|
13
|
+
locality: "Mountain View",
|
|
14
|
+
region: "CA",
|
|
15
|
+
postcode: "94043",
|
|
16
|
+
country: "US",
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
// Display format
|
|
20
|
+
formatAddress(components, { locale: "en-US" })
|
|
21
|
+
// → "1600 Amphitheatre Parkway, Mountain View, CA 94043"
|
|
22
|
+
|
|
23
|
+
// Canonical match key (for blocking / dedup)
|
|
24
|
+
canonicalKey(components)
|
|
25
|
+
// → "1600 amphitheatre pkwy mountain view ca 94043"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## API
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
// Address formatting — components → idiomatic display string
|
|
32
|
+
formatAddress(
|
|
33
|
+
components: ClassificationMap,
|
|
34
|
+
opts?: { locale?: LocaleTag; country?: string }
|
|
35
|
+
): string
|
|
36
|
+
|
|
37
|
+
// Shortcut that takes a Classification directly
|
|
38
|
+
formatFromClassificationMap(
|
|
39
|
+
classification: ClassificationMap,
|
|
40
|
+
opts?: FormatOpts
|
|
41
|
+
): string
|
|
42
|
+
|
|
43
|
+
// Canonical match key — normalized, deterministic string for record linkage
|
|
44
|
+
canonicalKey(components: ClassificationMap): string
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## What it does
|
|
48
|
+
|
|
49
|
+
| Function | Purpose |
|
|
50
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| **`formatAddress`** | Render parsed components into a locale-appropriate address string using `@fragaria/address-formatter` templates. |
|
|
52
|
+
| **`canonicalKey`** | Produce a lowercase, abbreviation-expanded, punctuation-stripped key that two records for the same place will match on, even if their original strings differ (`"123 Main St"` and `"123 MAIN STREET"` → same key). |
|
|
53
|
+
|
|
54
|
+
## Design
|
|
55
|
+
|
|
56
|
+
- **Locale-aware formatting.** Uses `@fragaria/address-formatter`'s per-country
|
|
57
|
+
templates, so `region postcode` renders `"CA 94043"` for US but `"75008 Paris"`
|
|
58
|
+
for FR.
|
|
59
|
+
- **Match key is deterministic.** No machine learning, no scoring — the
|
|
60
|
+
canonical key is a pure function of the address components. It's the
|
|
61
|
+
exact-match complement to the fuzzy matcher's probabilistic scoring.
|
|
62
|
+
- **Consolidated API.** Formerly scattered across `@mailwoman/core` and the
|
|
63
|
+
corpus synthesis layer; now one package, one API.
|
|
64
|
+
|
|
65
|
+
## Related
|
|
66
|
+
|
|
67
|
+
- [`@mailwoman/match`](../match) — the fuzzy matcher (uses canonical key for blocking)
|
|
68
|
+
- [`@mailwoman/record`](../record) — record normalizers that call into formatter
|
|
69
|
+
- [`@mailwoman/address-id`](../address-id) — stable primary key (complementary to canonical key)
|
|
70
|
+
- [`@mailwoman/core`](../core) — `ClassificationMap`, `ComponentTag` types
|
|
71
|
+
|
|
72
|
+
## License
|
|
73
|
+
|
|
74
|
+
[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mailwoman/formatter",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.11.0",
|
|
4
4
|
"description": "The inverse of the parser: render Mailwoman `ComponentTag` components into an idiomatic, locale-aware address string — plus a canonical, normalized match key for record linkage. Consolidates the former core/formatter stub and corpus synthesis formatter behind one API.",
|
|
5
5
|
"license": "AGPL-3.0-only",
|
|
6
6
|
"repository": {
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
},
|
|
18
18
|
"dependencies": {
|
|
19
19
|
"@fragaria/address-formatter": "^6.7.1",
|
|
20
|
-
"@mailwoman/core": "4.
|
|
20
|
+
"@mailwoman/core": "4.11.0"
|
|
21
21
|
},
|
|
22
22
|
"devDependencies": {
|
|
23
23
|
"@types/node": "^25.9.2"
|