TypeScript API

npm install goldenmatch

​

Quick Start

import { dedupe } from "goldenmatch";

const rows = [
  { id: 1, name: "John Smith", email: "john@example.com", zip: "12345" },
  { id: 2, name: "Jon Smith",  email: "john@example.com", zip: "12345" },
  { id: 3, name: "Jane Doe",   email: "jane@example.com", zip: "54321" },
];

const result = dedupe(rows, {
  fuzzy: { name: 0.85 },
  blocking: ["zip"],
  threshold: 0.85,
});

console.log(result.stats);

​

Two Entrypoints

• goldenmatch — edge-safe core. Works in browsers, Cloudflare Workers, Vercel Edge Runtime, Deno, Bun, and Node.
• goldenmatch/node — adds Node-only features: file I/O (CSV, JSON), HTTP servers, DB connectors.

// Edge-safe core (pure TS, no Node APIs)
import { dedupe, match, scoreStrings, applyTransforms } from "goldenmatch";

// Node-only additions
import { readFile, writeCsv, dedupeFile, startApiServer } from "goldenmatch/node";

​

Core API

​

dedupe(rows, options)

interface DedupeOptions {
  config?: GoldenMatchConfig;
  exact?: readonly string[];
  fuzzy?: Record<string, number>;
  blocking?: readonly string[];
  threshold?: number;
  llmScorer?: boolean;
}

interface DedupeResult {
  goldenRecords: readonly Row[];
  clusters: ReadonlyMap<number, ClusterInfo>;
  dupes: readonly Row[];
  unique: readonly Row[];
  stats: DedupeStats;
  scoredPairs: readonly ScoredPair[];
  config: GoldenMatchConfig;
}

​

match(target, reference, options)

​

scoreStrings(a, b, scorer?)

import { scoreStrings } from "goldenmatch";

const score = scoreStrings("MARTHA", "MARHTA", "jaro_winkler");
// 0.9611

​

applyTransforms(value, transforms)

import { applyTransforms } from "goldenmatch";

applyTransforms("  John Q. Smith  ", ["strip", "lowercase", "alpha_only"]);
// "johnqsmith"

​

Scorers

​

Optional WASM acceleration

import { dedupe, enableWasm, disableWasm } from "goldenmatch";

await enableWasm();        // async: loads + instantiates the .wasm once
const result = await dedupe(rows, { /* ... */ }); // covered scorers now run in WASM
disableWasm();             // back to pure-TS (e.g. for test isolation)

• Opt-in; pure-TS stays the default and the fallback. Default users download and parse zero wasm bytes (the loader/glue/bytes load only on enableWasm()). It returns false (pure-TS stays active) on any load failure; pass { require: true } to throw instead.
• Covered scorers: jaro_winkler / levenshtein / token_sort / exact — the ops score-core implements. Every other scorer always stays pure-TS, even when WASM is enabled. The swap is at the NxN block boundary (one JS↔WASM crossing per block, never per pair).
• Edge-safe + portable: Node, browsers, and Workers. The .wasm ships inside the npm package; the loader resolves it at runtime.
• Parity-guaranteed: the WASM kernel is rapidfuzz, and the pure-TS scorers are aligned with rapidfuzz to 4 decimals — so enabling WASM does not change results, it just runs them faster.

​

Blocking Strategies

• static — single blocking key with transforms
• multi_pass — multiple blocking keys, union of blocks
• sorted_neighborhood — sliding window over sorted data
• adaptive — static + auto-split oversized blocks
• ann — approximate nearest neighbor (requires hnswlib-node peer dep)
• canopy — TF-IDF canopy clustering
• learned — data-driven predicate selection

​

Golden Record Strategies

• most_complete — pick longest string
• majority_vote — pick most frequent
• source_priority — pick first non-null from priority list
• most_recent — pick value with most recent date
• first_non_null — pick first non-null

​

Transforms

​

CLI

# Dedupe a CSV
npx goldenmatch-js dedupe data.csv --output golden.csv

# Score two strings
npx goldenmatch-js score "MARTHA" "MARHTA" --scorer jaro_winkler
# jaro_winkler: 0.9611

# Match two datasets
npx goldenmatch-js match target.csv reference.csv -o matched.csv

# Profile a dataset
npx goldenmatch-js profile data.csv

# Launch interactive TUI (requires ink peer deps)
npx goldenmatch-js tui data.csv

​

Servers

​

MCP server (Claude Desktop / Claude Code)

npx goldenmatch-js mcp-serve

​

REST API server

npx goldenmatch-js serve --port 8000

​

A2A agent server

npx goldenmatch-js agent-serve --port 8200

​

Interactive TUI

npx goldenmatch-js tui

​

Optional Peer Dependencies

​

Advanced Features

• Probabilistic matching — Fellegi-Sunter with Splink-style EM
• Splink config converter — import-splink CLI / convert_splink_config MCP tool / fromSplink() API converts a Splink settings (or trained-model) JSON into a GoldenMatch config, importing trained m/u probabilities directly
• Negative evidence on Fellegi-Sunter matchkeys — goldenmatch-js 1.3.0 is a full FS-NE mirror of Python (trainEM / scoring / validation / loader matrix; new exports neFired, fsWeightRange, NegativeEvidenceUnsupportedError; the loader now parses negative_evidence for all matchkey types instead of silently dropping it). The TS pipeline (dedupe / matchRecords) throws on probabilistic+NE (its probabilistic scoring is a simplified weighted-style average), the continuous path rejects NE, and derive_from NE is rejected in TS — materialize the column first, or use Python
• PPRL — Privacy-preserving record linkage with SHA-256 bloom filters (3 security levels: standard, high, paranoid)
• Graph ER — Multi-table entity resolution with evidence propagation
• Streaming — Incremental single-record matching
• Memory — Persistent corrections + threshold learning
• Sensitivity analysis — Parameter sweep with CCMS / TWI cluster comparison
• Lineage tracking — Full provenance per field per golden record

​

Examples

​

Source

• npm: https://www.npmjs.com/package/goldenmatch
• GitHub: https://github.com/benseverndev-oss/goldenmatch/tree/main/packages/goldenmatch-js

​

Comparison With Python