@mailwoman/address-id 4.9.0

package/out/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/address-id` — turn a canonicalized + geocoded address into a STABLE, parseable
+ *   primary key: `<state>.<H3-cell>.<hash>`. The deterministic, exact-match complement to the fuzzy
+ *   matcher (`@mailwoman/match`): where the matcher decides whether two messy records are probably
+ *   the same entity, the address-id is a content-addressed key you can GROUP BY / JOIN ON without
+ *   running the matcher at all — for the common "same canonical address" case.
+ *
+ *   The three parts (see {@link createPostalAddressID}):
+ *
+ *   - **state** — a coarse region prefix (`tx`, `ca`, …), from a supplied state or plucked from the
+ *       address's ZIP ({@link @mailwoman/codex}); `xx` when unknown. Makes the key region-sortable.
+ *   - **H3 cell** — a jitter-stable locality token from the resolved coordinate (`h3-js`'s
+ *       `latLngToCell` at {@link ADDRESS_H3_RESOLUTION}). Coarse on purpose: two geocodes of the
+ *       same place a few metres apart land in the same cell.
+ *   - **hash** — a content hash of the address canonicalized by {@link @mailwoman/normalize} (so `123
+ *       Main St` and `123 MAIN STREET` hash identically). This is the identity; the cell + state
+ *       localize and partition it.
+ *
+ *   Lineage: the isp-nexus `createPostalAddressID` / `parsePostalAddressID`. `@mailwoman/normalize`
+ *   is the descendant of that era's `sanitize`, re-scoped to parser-input prep — this layer is the
+ *   keying purpose, kept separate by design. (Self-contained on `h3-js`, not `@mailwoman/spatial`,
+ *   which isn't published.)
+ */
+/** A geographic coordinate (the geocoder/resolver shape). */
+export interface LatLng {
+    latitude: number;
+    longitude: number;
+}
+/**
+ * H3 resolution for the locality cell — coarse on purpose (~edge 174 m). The same place geocoded a
+ * few metres apart (situs vs interpolation, geocode jitter) lands in the same cell, so the key is
+ * stable; the address hash carries the precise identity. Self-contained here (not via
+ * `@mailwoman/spatial`, which isn't a published package) so this stays cleanly publishable.
+ */
+export declare const ADDRESS_H3_RESOLUTION = 9;
+/**
+ * A stable address primary key, `<state>.<H3-cell>.<hash>`. Branded so it can't be confused with an
+ * arbitrary string.
+ */
+export type PostalAddressID = string & {
+    readonly __postalAddressID: unique symbol;
+};
+/** Inputs for {@link createPostalAddressID}. */
+export interface CreatePostalAddressIDInput {
+    /** The resolved coordinate (the geocoder's output) — drives the locality cell. */
+    coordinate: LatLng;
+    /** The address string to content-hash. Canonicalized via {@link normalize} before hashing. */
+    address: string;
+    /** 2-letter region/state for the prefix. When omitted, plucked from the address's ZIP; else `xx`. */
+    state?: string;
+    /** H3 resolution for the cell. Default {@link ADDRESS_H3_RESOLUTION} (jitter-stable). */
+    resolution?: number;
+}
+/** The parsed parts of a {@link PostalAddressID}. */
+export interface ParsedPostalAddressID {
+    state: string;
+    cell: string;
+    hash: string;
+}
+/**
+ * Build a stable {@link PostalAddressID} from a geocoded, canonicalizable address. Deterministic:
+ * the same (coordinate-cell, canonical address, state) always yields the same key. Two records that
+ * resolve to the same place and share a canonical address get the SAME id — a join/dedup key that
+ * needs no matcher. (Distinct canonical address strings → distinct keys; semantic equivalence that
+ * isn't string-identical is the fuzzy matcher's job, not this one's.)
+ */
+export declare function createPostalAddressID(input: CreatePostalAddressIDInput): PostalAddressID;
+/** Parse a {@link PostalAddressID} into its parts, or null if it isn't one. */
+export declare function parsePostalAddressID(id: string): ParsedPostalAddressID | null;
+/** Type guard: is `value` a well-formed {@link PostalAddressID}? */
+export declare function isPostalAddressID(value: string): value is PostalAddressID;
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,6DAA6D;AAC7D,MAAM,WAAW,MAAM;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,MAAM,CAAA;CAAE,CAAA;AAWpF,gDAAgD;AAChD,MAAM,WAAW,0BAA0B;IAC1C,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAA;IACf,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACZ;AAwBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,eAAe,CASxF;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAI7E;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE"}

package/out/index.js

@@ -0,0 +1,91 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/address-id` — turn a canonicalized + geocoded address into a STABLE, parseable
+ *   primary key: `<state>.<H3-cell>.<hash>`. The deterministic, exact-match complement to the fuzzy
+ *   matcher (`@mailwoman/match`): where the matcher decides whether two messy records are probably
+ *   the same entity, the address-id is a content-addressed key you can GROUP BY / JOIN ON without
+ *   running the matcher at all — for the common "same canonical address" case.
+ *
+ *   The three parts (see {@link createPostalAddressID}):
+ *
+ *   - **state** — a coarse region prefix (`tx`, `ca`, …), from a supplied state or plucked from the
+ *       address's ZIP ({@link @mailwoman/codex}); `xx` when unknown. Makes the key region-sortable.
+ *   - **H3 cell** — a jitter-stable locality token from the resolved coordinate (`h3-js`'s
+ *       `latLngToCell` at {@link ADDRESS_H3_RESOLUTION}). Coarse on purpose: two geocodes of the
+ *       same place a few metres apart land in the same cell.
+ *   - **hash** — a content hash of the address canonicalized by {@link @mailwoman/normalize} (so `123
+ *       Main St` and `123 MAIN STREET` hash identically). This is the identity; the cell + state
+ *       localize and partition it.
+ *
+ *   Lineage: the isp-nexus `createPostalAddressID` / `parsePostalAddressID`. `@mailwoman/normalize`
+ *   is the descendant of that era's `sanitize`, re-scoped to parser-input prep — this layer is the
+ *   keying purpose, kept separate by design. (Self-contained on `h3-js`, not `@mailwoman/spatial`,
+ *   which isn't published.)
+ */
+import { us } from "@mailwoman/codex";
+import { normalize } from "@mailwoman/normalize";
+import { latLngToCell } from "h3-js";
+import { createHash } from "node:crypto";
+/**
+ * H3 resolution for the locality cell — coarse on purpose (~edge 174 m). The same place geocoded a
+ * few metres apart (situs vs interpolation, geocode jitter) lands in the same cell, so the key is
+ * stable; the address hash carries the precise identity. Self-contained here (not via
+ * `@mailwoman/spatial`, which isn't a published package) so this stays cleanly publishable.
+ */
+export const ADDRESS_H3_RESOLUTION = 9;
+/** `<2-letter-state>.<hex-cell>.<hex-hash>` — lowercase, dot-delimited. */
+const POSTAL_ADDRESS_ID_PATTERN = /^([a-z]{2})\.([0-9a-f]{1,15})\.([0-9a-f]{8,})$/;
+/**
+ * Hex chars of the address content hash kept in the key (64 bits — collision-safe at billions of
+ * keys).
+ */
+const HASH_LENGTH = 16;
+/**
+ * Canonicalize an address for content-hashing: {@link normalize} (NFC + whitespace + punctuation +
+ * abbreviation expansion) then uppercase, so casing/abbreviation/spacing variants key identically.
+ */
+function canonicalizeForHash(address) {
+    return normalize(address).normalized.toUpperCase().trim();
+}
+/**
+ * Best-effort 2-letter US state from a full address: scan for `ST ZIP` occurrences (codex's
+ * `pluckStateZIPCode` anchors to a bare snippet, so it can't read a full address) and take the LAST
+ * valid one — addresses end with the state + ZIP. Returns the uppercase abbreviation or null.
+ */
+function deriveState(address) {
+    const candidates = [...address.matchAll(/\b([A-Za-z]{2})[ ,]+\d{5}(?:-\d{4})?\b/g)];
+    for (let i = candidates.length - 1; i >= 0; i--) {
+        const abbreviation = candidates[i][1].toUpperCase();
+        if (us.isUsStateAbbreviation(abbreviation))
+            return abbreviation;
+    }
+    return null;
+}
+/**
+ * Build a stable {@link PostalAddressID} from a geocoded, canonicalizable address. Deterministic:
+ * the same (coordinate-cell, canonical address, state) always yields the same key. Two records that
+ * resolve to the same place and share a canonical address get the SAME id — a join/dedup key that
+ * needs no matcher. (Distinct canonical address strings → distinct keys; semantic equivalence that
+ * isn't string-identical is the fuzzy matcher's job, not this one's.)
+ */
+export function createPostalAddressID(input) {
+    const cell = latLngToCell(input.coordinate.latitude, input.coordinate.longitude, input.resolution ?? ADDRESS_H3_RESOLUTION);
+    const hash = createHash("sha256").update(canonicalizeForHash(input.address)).digest("hex").slice(0, HASH_LENGTH);
+    const state = (input.state ?? deriveState(input.address) ?? "xx").toLowerCase();
+    return `${state}.${cell}.${hash}`;
+}
+/** Parse a {@link PostalAddressID} into its parts, or null if it isn't one. */
+export function parsePostalAddressID(id) {
+    const match = POSTAL_ADDRESS_ID_PATTERN.exec(id);
+    if (!match)
+        return null;
+    return { state: match[1], cell: match[2], hash: match[3] };
+}
+/** Type guard: is `value` a well-formed {@link PostalAddressID}? */
+export function isPostalAddressID(value) {
+    return POSTAL_ADDRESS_ID_PATTERN.test(value);
+}
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAQxC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAQtC,2EAA2E;AAC3E,MAAM,yBAAyB,GAAG,gDAAgD,CAAA;AAElF;;;GAGG;AACH,MAAM,WAAW,GAAG,EAAE,CAAA;AAqBtB;;;GAGG;AACH,SAAS,mBAAmB,CAAC,OAAe;IAC3C,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;AAC1D,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,OAAe;IACnC,MAAM,UAAU,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,yCAAyC,CAAC,CAAC,CAAA;IACnF,KAAK,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,YAAY,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAA;QACrD,IAAI,EAAE,CAAC,qBAAqB,CAAC,YAAY,CAAC;YAAE,OAAO,YAAY,CAAA;IAChE,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiC;IACtE,MAAM,IAAI,GAAG,YAAY,CACxB,KAAK,CAAC,UAAU,CAAC,QAAQ,EACzB,KAAK,CAAC,UAAU,CAAC,SAAS,EAC1B,KAAK,CAAC,UAAU,IAAI,qBAAqB,CACzC,CAAA;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAA;IAChH,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,EAAE,CAAA;IAC/E,OAAO,GAAG,KAAK,IAAI,IAAI,IAAI,IAAI,EAAqB,CAAA;AACrD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC9C,MAAM,KAAK,GAAG,yBAAyB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAA;AAC9D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC9C,OAAO,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAC7C,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@mailwoman/address-id",
+	"version": "4.9.0",
+	"description": "Turn a canonicalized + geocoded address into a stable, parseable primary key (`<state>.<H3-cell>.<hash>`) for deterministic record joins / dedup — the exact-match complement to the fuzzy matcher.",
+	"license": "AGPL-3.0-only",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/sister-software/mailwoman.git",
+		"directory": "address-id"
+	},
+	"type": "module",
+	"exports": {
+		"./package.json": "./package.json",
+		".": "./out/index.js"
+	},
+	"dependencies": {
+		"@mailwoman/codex": "workspace:*",
+		"@mailwoman/normalize": "workspace:*",
+		"h3-js": "^4.4.0"
+	},
+	"devDependencies": {
+		"@types/node": "^25.9.2"
+	},
+	"files": [
+		"out/**/*.js",
+		"out/**/*.js.map",
+		"out/**/*.d.ts",
+		"out/**/*.d.ts.map"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}