Fuzzy Name Match

A lightweight and flexible fuzzy name matching library for Node.js, designed to handle variations, abbreviations, and reversed orders in personal names.

Features

• Name-Specific Matching: Handles reversed names, abbreviations, and spacing variations
• Configurable Thresholds: Control sensitivity of matches
• Abbreviation Support: Detects and matches initials against full names
• Flexible Comparison: Compare single pairs or batches of names
• Lightweight: No heavy dependencies, works fast with Node.js projects

Installation

npm install fuzzy-name-match

Quick Start

const { nameMatchResult } = require('fuzzy-name-match');

// Compare two names and get detailed result
const result = nameMatchResult('Mr. Adam George Clooney', 'Adam G Clooney');

console.log(result);
/*
{
  result: true,
  score: 84.85,
  name_1: 'Mr. Adam George Clooney',
  name_2: 'Adam G Clooney',
  normalised_name_1: 'adam george clooney',
  normalised_name_2: 'adam g clooney'
}
*/

Detailed Usage

With Initials

import { nameMatchResult } from "fuzzy-name-match";

const result = nameMatchResult("S. Tendulkar", "Sachin Tendulkar");

console.log(result.result); // true
console.log(result.score);  // ~85

No Match

const result = nameMatchResult("Virat Kohli", "Rohit Sharma");
console.log(result.result); // false

Configuration

You can fine-tune the matching behavior using an optional config object:

interface INameMatchConfig {
  firstNameWeightage?: number;     // Weight given to first name (default: 70)
  reverseScoreThreshold?: number;  // Threshold for reverse name order (default: 90)
  nameMatchThreshold?: number;     // Final match threshold (default: 80)
}

Example with Config

const result = nameMatchResult("Ramesh Kumar", "Kumar Ramesh", {
  nameMatchThreshold: 85,
  reverseScoreThreshold: 85,
});

console.log(result);
/*
{
  result: true,
  score: 90,
  ...
}
*/

Return Format

Each call to nameMatchResult returns:

interface INameMatchResult {
  result: boolean;          // true if names match above threshold
  score: number;            // similarity score (0–100)
  name_1: string;           // original input name 1
  name_2: string;           // original input name 2
  normalised_name_1: string; // lowercased + cleaned name1
  normalised_name_2: string; // lowercased + cleaned name2
}

Use Cases

• Data cleaning: Matching customer names across multiple databases.
• Banking/Finance: Identifying duplicate KYC records.
• Education: Matching student records where names are spelled differently.
• E-commerce: Deduplicating customer accounts.

Challenges Handled

• Reversed names (first last vs last, first)
• Abbreviations and initials
• Middle names and missing parts
• Spacing and case variations
• Common nickname handling (configurable)

License

MIT