@mailwoman/match 4.8.1

package/out/tf.js

@@ -0,0 +1,66 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Term-frequency adjustment — making a rare-value agreement count more than a common one.
+ *
+ *   Two people both named "Vijayan" is far stronger evidence of a match than two both named "Smith",
+ *   because "Smith" agreements happen by chance all the time and "Vijayan" agreements don't. The
+ *   Fellegi-Sunter `m` (how often a true match agrees) is roughly the same either way; what differs
+ *   is `u` — the chance a _non_-match agrees — which for an exact agreement on value `v` is just
+ *   how common `v` is. So we leave `m`, and replace the level's average `u` with `frequency(v)`,
+ *   adding `log2(u_level / frequency(v))` to the weight: a big positive bump for rare values, a
+ *   penalty for common ones.
+ *
+ *   Crucially for a label-free matcher: the frequencies are computed ON-THE-FLY from the input column
+ *   (the Splink approach) — no external Census table required. Build a {@link TermFrequencyTable}
+ *   from the values you're matching, then attach it to a comparison with {@link withTermFrequency}.
+ */
+const defaultNormalize = (value) => value.trim().toLowerCase().replace(/\s+/g, " ");
+/**
+ * Build a {@link TermFrequencyTable} from an iterable of values (e.g. every `given` name in the
+ * dataset). Values are normalized (default: trim + lowercase + collapse whitespace) before
+ * counting, and `frequency()` normalizes its argument the same way, so callers pass raw field
+ * values.
+ */
+export function buildTermFrequencyTable(values, opts = {}) {
+    const normalize = opts.normalize ?? defaultNormalize;
+    const counts = new Map();
+    let total = 0;
+    for (const value of values) {
+        if (value == null)
+            continue;
+        const key = normalize(value);
+        if (!key)
+            continue;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+        total++;
+    }
+    return {
+        total,
+        distinct: counts.size,
+        frequency(value) {
+            if (total === 0)
+                return 0;
+            return (counts.get(normalize(value)) ?? 0) / total;
+        },
+    };
+}
+/**
+ * Attach a term-frequency adjustment to a comparison. By default it applies to the exact level
+ * (index 0) and looks up the value via `value(a, b)` — usually the agreeing field extracted from
+ * one side. Returns a new comparison; the underlying `assess` and levels are untouched, so this
+ * composes with EM (which re-estimates the base `m`/`u` the adjustment sits on top of).
+ */
+export function withTermFrequency(comparison, config) {
+    const adjustment = {
+        frequency: (value) => config.table.frequency(value),
+        levels: new Set(config.levels ?? [0]),
+        value: config.value,
+        weight: config.weight,
+        minimumFrequency: config.minimumFrequency,
+    };
+    return { ...comparison, termFrequency: adjustment };
+}
+//# sourceMappingURL=tf.js.map

package/out/tf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tf.js","sourceRoot":"","sources":["../tf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAcH,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEnG;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACtC,MAA2C,EAC3C,OAAkD,EAAE;IAEpD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,CAAA;IACpD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IACxC,IAAI,KAAK,GAAG,CAAC,CAAA;IAEb,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,IAAI,IAAI;YAAE,SAAQ;QAC3B,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;QAC5B,IAAI,CAAC,GAAG;YAAE,SAAQ;QAClB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QAC3C,KAAK,EAAE,CAAA;IACR,CAAC;IAED,OAAO;QACN,KAAK;QACL,QAAQ,EAAE,MAAM,CAAC,IAAI;QACrB,SAAS,CAAC,KAAK;YACd,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,CAAC,CAAA;YACzB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAA;QACnD,CAAC;KACD,CAAA;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAChC,UAAyB,EACzB,MASC;IAED,MAAM,UAAU,GAA+B;QAC9C,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC;QACnD,MAAM,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;KACzC,CAAA;IAED,OAAO,EAAE,GAAG,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,CAAA;AACpD,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mailwoman/match",
+  "version": "4.8.1",
+  "description": "The geocode-first record matcher: block → score → cluster. This first cut ships the string comparators (Jaro / Jaro-Winkler + an edit-distance fallback for compound surnames) that the Fellegi-Sunter scorer is built on.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "match"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js",
+    "./blocking": "./out/blocking.js",
+    "./clustering": "./out/clustering.js",
+    "./comparators": "./out/comparators.js",
+    "./distance": "./out/distance.js",
+    "./fellegi-sunter": "./out/fellegi-sunter.js",
+    "./em": "./out/em.js",
+    "./tf": "./out/tf.js"
+  },
+  "dependencies": {
+    "fastest-levenshtein": "^1.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}