@mailwoman/match 4.8.1

package/out/blocking.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Blocking — candidate generation. Comparing every pair is O(n²) (a million records is a trillion
+ *   comparisons), so we only score pairs that share a cheap key. This is where the geocode-first
+ *   bet pays off: two records resolving to the same place land in the same spatial cell regardless
+ *   of how their address strings are spelled, so geography is the primary block.
+ *
+ *   A {@link BlockingKey} maps a record to zero or more string keys; records sharing any key become
+ *   candidates. Keys compose as a _union_ (the standard multi-pass approach — high recall from
+ *   cheap rules): block on the spatial cell OR the canonical key OR the postcode, and a pair that
+ *   any rule catches is scored. {@link conjunction} builds the AND-style key Geo-ER uses (`name-cell
+ *   AND geo-cell`) when a single rule is too loose.
+ *
+ *   Recall is the priority — a pair the blocker never proposes can never match, the most dangerous
+ *   silent failure in record linkage. So the spatial grid is generous and neighbour-expanded by
+ *   default, and any block too large to scan is _reported_, never quietly dropped.
+ */
+/** Maps a record to zero or more block keys. Two records sharing any key become a candidate pair. */
+export type BlockingKey<R> = (record: R) => string[];
+/** A geographic coordinate (WGS84 decimal degrees). */
+export interface LatLon {
+    latitude: number;
+    longitude: number;
+}
+/**
+ * A spatial-cell block key: a configurable lat/lon grid. `precisionDegrees` sets the cell size
+ * (default 0.05° ≈ 5.5 km of latitude — deliberately generous, per the literature, so same-place
+ * records reliably co-block). With `neighbors` (default `true`) a record also keys its 8 adjacent
+ * cells, so a pair straddling a cell boundary still meets.
+ *
+ * Note: an equal-_degree_ grid (longitude cells shrink toward the poles) and neighbour expansion
+ * inflates block sizes ~9×; an equal-area H3/geohash index with a single-cell + neighbour-query is
+ * the refinement. Behaviour — proximity co-blocking — is the same.
+ */
+export declare function geoCellKey<R>(extract: (record: R) => LatLon | null | undefined, opts?: {
+    precisionDegrees?: number;
+    neighbors?: boolean;
+}): BlockingKey<R>;
+/**
+ * An exact-value block key (the canonical address key, a postcode, an email domain…), normalized
+ * and optionally truncated to a leading `prefix` of characters (a cheaper, higher-recall rule). A
+ * missing or empty value produces no key.
+ */
+export declare function exactKey<R>(extract: (record: R) => string | null | undefined, opts?: {
+    prefix?: number;
+    normalize?: (value: string) => string;
+}): BlockingKey<R>;
+/**
+ * A conjunctive block key — the cross-product of its sub-keys, joined (Geo-ER's "name AND
+ * distance"). A record is keyed by every combination of one sub-key from each input, so two records
+ * co-block only when they agree on _all_ inputs. Tighter blocks, lower recall — use when a single
+ * rule is too loose.
+ */
+export declare function conjunction<R>(...keys: BlockingKey<R>[]): BlockingKey<R>;
+/** The outcome of a blocking pass. */
+export interface BlockResult<R> {
+    /** Deduplicated candidate pairs (no self-pairs; a pair caught by multiple keys appears once). */
+    pairs: Array<[R, R]>;
+    /** Blocks that exceeded `maxBlockSize` and were skipped — surfaced so coverage limits are visible. */
+    droppedBlocks: Array<{
+        key: string;
+        size: number;
+    }>;
+}
+/**
+ * Generate candidate pairs from `records` via one or more blocking keys (their union). Builds an
+ * inverted index (key → records) and emits the unique within-block pairs. A block larger than
+ * `maxBlockSize` is skipped and reported in `droppedBlocks` rather than blowing up into a quadratic
+ * scan — an explicit, visible coverage limit, not a silent drop.
+ */
+export declare function block<R>(records: readonly R[], blockingKeys: BlockingKey<R> | BlockingKey<R>[], opts?: {
+    maxBlockSize?: number;
+}): BlockResult<R>;
+//# sourceMappingURL=blocking.d.ts.map

package/out/blocking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocking.d.ts","sourceRoot":"","sources":["../blocking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qGAAqG;AACrG,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,EAAE,CAAA;AAEpD,uDAAuD;AACvD,MAAM,WAAW,MAAM;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,EACjD,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,WAAW,CAAC,CAAC,CAAC,CAoBhB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACzB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,EACjD,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAAO,GACnE,WAAW,CAAC,CAAC,CAAC,CAUhB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAUxE;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,iGAAiG;IACjG,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACpB,sGAAsG;IACtG,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,CAAC,EACtB,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,EAAE,EAC/C,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,WAAW,CAAC,CAAC,CAAC,CA0ChB"}

package/out/blocking.js

@@ -0,0 +1,136 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Blocking — candidate generation. Comparing every pair is O(n²) (a million records is a trillion
+ *   comparisons), so we only score pairs that share a cheap key. This is where the geocode-first
+ *   bet pays off: two records resolving to the same place land in the same spatial cell regardless
+ *   of how their address strings are spelled, so geography is the primary block.
+ *
+ *   A {@link BlockingKey} maps a record to zero or more string keys; records sharing any key become
+ *   candidates. Keys compose as a _union_ (the standard multi-pass approach — high recall from
+ *   cheap rules): block on the spatial cell OR the canonical key OR the postcode, and a pair that
+ *   any rule catches is scored. {@link conjunction} builds the AND-style key Geo-ER uses (`name-cell
+ *   AND geo-cell`) when a single rule is too loose.
+ *
+ *   Recall is the priority — a pair the blocker never proposes can never match, the most dangerous
+ *   silent failure in record linkage. So the spatial grid is generous and neighbour-expanded by
+ *   default, and any block too large to scan is _reported_, never quietly dropped.
+ */
+/**
+ * A spatial-cell block key: a configurable lat/lon grid. `precisionDegrees` sets the cell size
+ * (default 0.05° ≈ 5.5 km of latitude — deliberately generous, per the literature, so same-place
+ * records reliably co-block). With `neighbors` (default `true`) a record also keys its 8 adjacent
+ * cells, so a pair straddling a cell boundary still meets.
+ *
+ * Note: an equal-_degree_ grid (longitude cells shrink toward the poles) and neighbour expansion
+ * inflates block sizes ~9×; an equal-area H3/geohash index with a single-cell + neighbour-query is
+ * the refinement. Behaviour — proximity co-blocking — is the same.
+ */
+export function geoCellKey(extract, opts = {}) {
+    const step = opts.precisionDegrees ?? 0.05;
+    const expand = opts.neighbors ?? true;
+    return (record) => {
+        const coordinate = extract(record);
+        if (!coordinate || !Number.isFinite(coordinate.latitude) || !Number.isFinite(coordinate.longitude))
+            return [];
+        const latCell = Math.floor(coordinate.latitude / step);
+        const lonCell = Math.floor(coordinate.longitude / step);
+        if (!expand)
+            return [`${latCell}:${lonCell}`];
+        const keys = [];
+        for (let dLat = -1; dLat <= 1; dLat++) {
+            for (let dLon = -1; dLon <= 1; dLon++) {
+                keys.push(`${latCell + dLat}:${lonCell + dLon}`);
+            }
+        }
+        return keys;
+    };
+}
+/**
+ * An exact-value block key (the canonical address key, a postcode, an email domain…), normalized
+ * and optionally truncated to a leading `prefix` of characters (a cheaper, higher-recall rule). A
+ * missing or empty value produces no key.
+ */
+export function exactKey(extract, opts = {}) {
+    const normalize = opts.normalize ?? ((v) => v.trim().toLowerCase().replace(/\s+/g, " "));
+    return (record) => {
+        const value = extract(record);
+        if (!value)
+            return [];
+        const normalized = normalize(value);
+        if (!normalized)
+            return [];
+        return [opts.prefix ? normalized.slice(0, opts.prefix) : normalized];
+    };
+}
+/**
+ * A conjunctive block key — the cross-product of its sub-keys, joined (Geo-ER's "name AND
+ * distance"). A record is keyed by every combination of one sub-key from each input, so two records
+ * co-block only when they agree on _all_ inputs. Tighter blocks, lower recall — use when a single
+ * rule is too loose.
+ */
+export function conjunction(...keys) {
+    return (record) => {
+        let combos = [""];
+        for (const key of keys) {
+            const parts = key(record);
+            if (parts.length === 0)
+                return [];
+            combos = combos.flatMap((prefix) => parts.map((part) => (prefix ? `${prefix}&${part}` : part)));
+        }
+        return combos;
+    };
+}
+/**
+ * Generate candidate pairs from `records` via one or more blocking keys (their union). Builds an
+ * inverted index (key → records) and emits the unique within-block pairs. A block larger than
+ * `maxBlockSize` is skipped and reported in `droppedBlocks` rather than blowing up into a quadratic
+ * scan — an explicit, visible coverage limit, not a silent drop.
+ */
+export function block(records, blockingKeys, opts = {}) {
+    const keys = Array.isArray(blockingKeys) ? blockingKeys : [blockingKeys];
+    const maxBlockSize = opts.maxBlockSize ?? Infinity;
+    const index = new Map();
+    records.forEach((record, i) => {
+        const seen = new Set();
+        for (const keyFn of keys) {
+            for (const key of keyFn(record)) {
+                if (!key || seen.has(key))
+                    continue;
+                seen.add(key);
+                const bucket = index.get(key);
+                if (bucket)
+                    bucket.push(i);
+                else
+                    index.set(key, [i]);
+            }
+        }
+    });
+    const n = records.length;
+    const emitted = new Set();
+    const pairs = [];
+    const droppedBlocks = [];
+    for (const [key, bucket] of index) {
+        if (bucket.length < 2)
+            continue;
+        if (bucket.length > maxBlockSize) {
+            droppedBlocks.push({ key, size: bucket.length });
+            continue;
+        }
+        for (let a = 0; a < bucket.length; a++) {
+            for (let b = a + 1; b < bucket.length; b++) {
+                const lo = Math.min(bucket[a], bucket[b]);
+                const hi = Math.max(bucket[a], bucket[b]);
+                const id = lo * n + hi;
+                if (emitted.has(id))
+                    continue;
+                emitted.add(id);
+                pairs.push([records[lo], records[hi]]);
+            }
+        }
+    }
+    return { pairs, droppedBlocks };
+}
+//# sourceMappingURL=blocking.js.map

package/out/blocking.js.map

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

package/out/clustering.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Clustering — the third and final matcher stage: resolve scored pairs into canonical entities.
+ *
+ *   The pairwise scorer treats each pair independently, and its scores are NOT transitive: A~B at a
+ *   high weight and B~C at a high weight does not guarantee A~C is a match. So a distinct stage is
+ *   required to turn the graph of above-threshold links into coherent groups — skip it and your
+ *   "entities" quietly fracture or fuse.
+ *
+ *   This ships the standard baseline: connected components of the link graph (union-find), with the
+ *   link threshold as the precision/recall knob — raise it for tighter, purer clusters, lower it
+ *   for more recall. Its known weakness is over-merging via transitive chains (a string of weak
+ *   links can pull unrelated records into one component); the principled fix is
+ *   centroid-/average-linkage hierarchical clustering (Dedupe), which uses the full within-cluster
+ *   score matrix — a documented refinement, not this first cut. For a geocode-first matcher the
+ *   over-merge risk is already damped: blocking keeps candidate sets local, so chains can't run
+ *   across the whole dataset.
+ */
+/** A scored candidate pair: two records and the match weight (bits) the scorer assigned them. */
+export interface ScoredLink<R> {
+    a: R;
+    b: R;
+    weight: number;
+}
+/** Options for {@link cluster}. */
+export interface ClusterOptions {
+    /**
+     * Link two records only when their match weight is at or above this (bits) — the precision/recall
+     * knob.
+     */
+    threshold: number;
+}
+/**
+ * Cluster records into canonical entities by connected components of the above-threshold link
+ * graph. Every input record lands in exactly one cluster — a record with no qualifying link is a
+ * singleton. Links referencing a record not in `records` are ignored. Reference identity is used,
+ * so pass the same record objects to both arguments.
+ */
+export declare function cluster<R>(records: readonly R[], links: Iterable<ScoredLink<R>>, opts: ClusterOptions): R[][];
+/**
+ * Pick a cluster's most complete record as its canonical representative — the one with the fewest
+ * empty fields (`null` / `undefined` / `""`). Ties keep the earliest. A basic, generic
+ * canonicalizer; field-level merging across the cluster is the application's job (it knows which
+ * source to trust).
+ */
+export declare function representative<R extends object>(group: readonly R[]): R | undefined;
+//# sourceMappingURL=clustering.d.ts.map

package/out/clustering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clustering.d.ts","sourceRoot":"","sources":["../clustering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,iGAAiG;AACjG,MAAM,WAAW,UAAU,CAAC,CAAC;IAC5B,CAAC,EAAE,CAAC,CAAA;IACJ,CAAC,EAAE,CAAC,CAAA;IACJ,MAAM,EAAE,MAAM,CAAA;CACd;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,CAAC,EAAE,EAAE,CAgD7G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,GAAG,SAAS,CAgBnF"}

package/out/clustering.js

@@ -0,0 +1,101 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Clustering — the third and final matcher stage: resolve scored pairs into canonical entities.
+ *
+ *   The pairwise scorer treats each pair independently, and its scores are NOT transitive: A~B at a
+ *   high weight and B~C at a high weight does not guarantee A~C is a match. So a distinct stage is
+ *   required to turn the graph of above-threshold links into coherent groups — skip it and your
+ *   "entities" quietly fracture or fuse.
+ *
+ *   This ships the standard baseline: connected components of the link graph (union-find), with the
+ *   link threshold as the precision/recall knob — raise it for tighter, purer clusters, lower it
+ *   for more recall. Its known weakness is over-merging via transitive chains (a string of weak
+ *   links can pull unrelated records into one component); the principled fix is
+ *   centroid-/average-linkage hierarchical clustering (Dedupe), which uses the full within-cluster
+ *   score matrix — a documented refinement, not this first cut. For a geocode-first matcher the
+ *   over-merge risk is already damped: blocking keeps candidate sets local, so chains can't run
+ *   across the whole dataset.
+ */
+/**
+ * Cluster records into canonical entities by connected components of the above-threshold link
+ * graph. Every input record lands in exactly one cluster — a record with no qualifying link is a
+ * singleton. Links referencing a record not in `records` are ignored. Reference identity is used,
+ * so pass the same record objects to both arguments.
+ */
+export function cluster(records, links, opts) {
+    const index = new Map();
+    records.forEach((record, i) => index.set(record, i));
+    const parent = records.map((_, i) => i);
+    const rank = new Array(records.length).fill(0);
+    const find = (x) => {
+        let root = x;
+        while (parent[root] !== root)
+            root = parent[root];
+        // Path compression.
+        while (parent[x] !== root) {
+            const next = parent[x];
+            parent[x] = root;
+            x = next;
+        }
+        return root;
+    };
+    const union = (x, y) => {
+        const rx = find(x);
+        const ry = find(y);
+        if (rx === ry)
+            return;
+        if (rank[rx] < rank[ry])
+            parent[rx] = ry;
+        else if (rank[rx] > rank[ry])
+            parent[ry] = rx;
+        else {
+            parent[ry] = rx;
+            rank[rx]++;
+        }
+    };
+    for (const link of links) {
+        if (link.weight < opts.threshold)
+            continue;
+        const ia = index.get(link.a);
+        const ib = index.get(link.b);
+        if (ia === undefined || ib === undefined)
+            continue;
+        union(ia, ib);
+    }
+    const groups = new Map();
+    records.forEach((record, i) => {
+        const root = find(i);
+        const group = groups.get(root);
+        if (group)
+            group.push(record);
+        else
+            groups.set(root, [record]);
+    });
+    return [...groups.values()];
+}
+/**
+ * Pick a cluster's most complete record as its canonical representative — the one with the fewest
+ * empty fields (`null` / `undefined` / `""`). Ties keep the earliest. A basic, generic
+ * canonicalizer; field-level merging across the cluster is the application's job (it knows which
+ * source to trust).
+ */
+export function representative(group) {
+    let best;
+    let bestFilled = -1;
+    for (const record of group) {
+        let filled = 0;
+        for (const value of Object.values(record)) {
+            if (value !== null && value !== undefined && value !== "")
+                filled++;
+        }
+        if (filled > bestFilled) {
+            bestFilled = filled;
+            best = record;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=clustering.js.map

package/out/clustering.js.map

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

package/out/comparators.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   String comparators for the matcher's scoring stage.
+ *
+ *   The record-linkage literature (Winkler/Census; Belin 1993) settles on the prefix-weighted Jaro
+ *   comparator (Jaro-Winkler) as the default for names: it tolerates the typographical error real
+ *   data is full of better than raw character-edit distance. But J-W has a documented blind spot on
+ *   compound / double surnames (e.g. Hispanic `Garcia Lopez`): the second half of the compound
+ *   falls outside J-W's match window, so `Lopez` vs `Garcia Lopez` scores ~0. The fix the
+ *   literature prescribes is an edit-distance / token fallback for single-vs-compound pairs —
+ *   implemented in {@link nameSimilarity}.
+ *
+ *   These are pure similarity primitives in [0, 1]. The mapping of a similarity onto discrete
+ *   Fellegi-Sunter agreement levels (and the m/u weights) is the scorer's job, not theirs.
+ */
+/**
+ * Jaro similarity in [0, 1]. Two empty strings are identical (1); one empty is 0. Counts matching
+ * characters within a sliding window of `floor(max(len)/2) - 1`, discounting half-transpositions.
+ */
+export declare function jaro(a: string, b: string): number;
+/**
+ * Jaro-Winkler similarity in [0, 1]: Jaro with a bonus for a shared prefix — `jw = jaro + prefix *
+ * weight * (1 - jaro)`, prefix capped at `maxPrefix` (Winkler's standard 4), `weight` the scaling
+ * factor (standard 0.1). Only boosts when `jaro` already clears `boostThreshold` (0.7), per
+ * Winkler.
+ */
+export declare function jaroWinkler(a: string, b: string, opts?: {
+    weight?: number;
+    maxPrefix?: number;
+    boostThreshold?: number;
+}): number;
+/** Normalized Levenshtein similarity in [0, 1]: `1 - editDistance / max(len)`. */
+export declare function levenshteinSimilarity(a: string, b: string): number;
+/**
+ * Name-aware similarity in [0, 1]. Jaro-Winkler by default, with the compound-surname fallback the
+ * literature prescribes:
+ *
+ * - If one name's tokens are a strict subset of the other's (`Lopez` ⊂ `Garcia Lopez`), that is
+ *   strong partial agreement J-W misses — floor the score at 0.9.
+ * - Otherwise return the better of Jaro-Winkler and normalized edit similarity, so a single token
+ *   that is a substring of a longer compound (`Garcia` vs `Garcialopez`) still scores sensibly.
+ *
+ * Case- and whitespace-insensitive. Empty input scores 0.
+ */
+export declare function nameSimilarity(a: string, b: string): number;
+//# sourceMappingURL=comparators.d.ts.map

package/out/comparators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparators.d.ts","sourceRoot":"","sources":["../comparators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;GAGG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAqCjD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAC1B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACzE,MAAM,CAaR;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAe3D"}

package/out/comparators.js

@@ -0,0 +1,119 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   String comparators for the matcher's scoring stage.
+ *
+ *   The record-linkage literature (Winkler/Census; Belin 1993) settles on the prefix-weighted Jaro
+ *   comparator (Jaro-Winkler) as the default for names: it tolerates the typographical error real
+ *   data is full of better than raw character-edit distance. But J-W has a documented blind spot on
+ *   compound / double surnames (e.g. Hispanic `Garcia Lopez`): the second half of the compound
+ *   falls outside J-W's match window, so `Lopez` vs `Garcia Lopez` scores ~0. The fix the
+ *   literature prescribes is an edit-distance / token fallback for single-vs-compound pairs —
+ *   implemented in {@link nameSimilarity}.
+ *
+ *   These are pure similarity primitives in [0, 1]. The mapping of a similarity onto discrete
+ *   Fellegi-Sunter agreement levels (and the m/u weights) is the scorer's job, not theirs.
+ */
+import { distance as levenshteinDistance } from "fastest-levenshtein";
+/**
+ * Jaro similarity in [0, 1]. Two empty strings are identical (1); one empty is 0. Counts matching
+ * characters within a sliding window of `floor(max(len)/2) - 1`, discounting half-transpositions.
+ */
+export function jaro(a, b) {
+    if (a === b)
+        return 1;
+    const la = a.length;
+    const lb = b.length;
+    if (la === 0 || lb === 0)
+        return 0;
+    const window = Math.max(0, Math.floor(Math.max(la, lb) / 2) - 1);
+    const aMatched = new Array(la).fill(false);
+    const bMatched = new Array(lb).fill(false);
+    let matches = 0;
+    for (let i = 0; i < la; i++) {
+        const start = Math.max(0, i - window);
+        const end = Math.min(i + window + 1, lb);
+        for (let j = start; j < end; j++) {
+            if (bMatched[j] || a[i] !== b[j])
+                continue;
+            aMatched[i] = true;
+            bMatched[j] = true;
+            matches++;
+            break;
+        }
+    }
+    if (matches === 0)
+        return 0;
+    // Count transpositions: matched chars of `a` and `b`, in order, that disagree (halved).
+    let transpositions = 0;
+    let k = 0;
+    for (let i = 0; i < la; i++) {
+        if (!aMatched[i])
+            continue;
+        while (!bMatched[k])
+            k++;
+        if (a[i] !== b[k])
+            transpositions++;
+        k++;
+    }
+    transpositions /= 2;
+    return (matches / la + matches / lb + (matches - transpositions) / matches) / 3;
+}
+/**
+ * Jaro-Winkler similarity in [0, 1]: Jaro with a bonus for a shared prefix — `jw = jaro + prefix *
+ * weight * (1 - jaro)`, prefix capped at `maxPrefix` (Winkler's standard 4), `weight` the scaling
+ * factor (standard 0.1). Only boosts when `jaro` already clears `boostThreshold` (0.7), per
+ * Winkler.
+ */
+export function jaroWinkler(a, b, opts = {}) {
+    const weight = opts.weight ?? 0.1;
+    const maxPrefix = opts.maxPrefix ?? 4;
+    const boostThreshold = opts.boostThreshold ?? 0.7;
+    const base = jaro(a, b);
+    if (base < boostThreshold)
+        return base;
+    let prefix = 0;
+    const limit = Math.min(maxPrefix, a.length, b.length);
+    while (prefix < limit && a[prefix] === b[prefix])
+        prefix++;
+    return base + prefix * weight * (1 - base);
+}
+/** Normalized Levenshtein similarity in [0, 1]: `1 - editDistance / max(len)`. */
+export function levenshteinSimilarity(a, b) {
+    if (a === b)
+        return 1;
+    const longest = Math.max(a.length, b.length);
+    if (longest === 0)
+        return 1;
+    return 1 - levenshteinDistance(a, b) / longest;
+}
+/**
+ * Name-aware similarity in [0, 1]. Jaro-Winkler by default, with the compound-surname fallback the
+ * literature prescribes:
+ *
+ * - If one name's tokens are a strict subset of the other's (`Lopez` ⊂ `Garcia Lopez`), that is
+ *   strong partial agreement J-W misses — floor the score at 0.9.
+ * - Otherwise return the better of Jaro-Winkler and normalized edit similarity, so a single token
+ *   that is a substring of a longer compound (`Garcia` vs `Garcialopez`) still scores sensibly.
+ *
+ * Case- and whitespace-insensitive. Empty input scores 0.
+ */
+export function nameSimilarity(a, b) {
+    const x = a.trim().toLowerCase().replace(/\s+/g, " ");
+    const y = b.trim().toLowerCase().replace(/\s+/g, " ");
+    if (!x || !y)
+        return 0;
+    if (x === y)
+        return 1;
+    const jw = jaroWinkler(x, y);
+    const xTokens = new Set(x.split(" "));
+    const yTokens = new Set(y.split(" "));
+    const [small, big] = xTokens.size <= yTokens.size ? [xTokens, yTokens] : [yTokens, xTokens];
+    const subset = small.size < big.size && [...small].every((t) => big.has(t));
+    if (subset)
+        return Math.max(jw, 0.9);
+    return Math.max(jw, levenshteinSimilarity(x, y));
+}
+//# sourceMappingURL=comparators.js.map

package/out/comparators.js.map

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

package/out/distance.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Geographic distance as a scoring feature — the other half of geocode-first matching.
+ *
+ *   Blocking uses geography to _propose_ candidates; this scores them on it. The research is explicit
+ *   that an address must be matched as a SPATIAL attribute, not by string similarity (a
+ *   one-character edit can be 650 m apart), and that distance measurably helps as a comparison
+ *   feature. So we bucket the great-circle distance between two records' coordinates into ordered
+ *   Fellegi-Sunter agreement levels (Splink's `DistanceInKMAtThresholds`): "same building" / "same
+ *   block" / "same area" / far, each with its own m/u and weight.
+ *
+ *   Calibrate the bucket boundaries to the geocoder's OWN error, which is heavy-tailed and density-
+ *   dependent (≈38 m urban, ≈200 m rural). A weakening of this evidence by geocode quality (a
+ *   shared interpolated centroid is softer than a shared rooftop point) is the documented
+ *   refinement.
+ */
+import type { LatLon } from "./blocking.js";
+import type { Comparison, ComparisonLevel } from "./fellegi-sunter.js";
+/** Great-circle (haversine) distance in km between two coordinates. */
+export declare function haversineKm(a: LatLon, b: LatLon): number;
+/**
+ * A geo-distance comparison: bucket the great-circle distance between two records' coordinates into
+ * ordered agreement levels. Levels must be ordered NEAREST first by `maxKm`, the last acting as the
+ * `far` catch-all (`maxKm` omitted → unbounded). A missing/invalid coordinate on either side yields
+ * no evidence.
+ */
+export declare function distanceComparison<R>(config: {
+    name: string;
+    extract: (record: R) => LatLon | null | undefined;
+    levels: ComparisonLevel[];
+}): Comparison<R>;
+/**
+ * Default distance levels, nearest → far, with boundaries at rooftop / block / locality scale. The
+ * m/u are illustrative seeds (EM re-estimates them); the boundaries reflect typical geocoder
+ * error.
+ */
+export declare const DEFAULT_DISTANCE_LEVELS: ComparisonLevel[];
+//# sourceMappingURL=distance.d.ts.map

package/out/distance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distance.d.ts","sourceRoot":"","sources":["../distance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAKtE,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;IACjD,MAAM,EAAE,eAAe,EAAE,CAAA;CACzB,GAAG,UAAU,CAAC,CAAC,CAAC,CAmBhB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAAe,EAKpD,CAAA"}