Enhanced Name Matcher

A robust name matching library for Node.js that combines multiple string similarity algorithms for optimal name matching performance.

Features

• Combined Algorithms: Uses both Natural.js and a custom enhanced matcher for superior matching results
• Name-Specific Optimizations: Handles common name matching challenges like nicknames, middle names, and reversed order
• Comprehensive Approach: Considers multiple strategies and selects the best match
• Flexible Threshold: Configurable similarity threshold for matches
• Utility Functions: Includes name normalization, parsing, and standardization

Installation

npm install name-match

Quick Start

const { match, isMatch } = require('name-match');

// Get similarity score (0-1)
const score = match('John Smith', 'Smith, John');
console.log(score); // 0.87

// Check if names match (using default threshold of 0.75)
const matched = isMatch('Robert Johnson', 'Bob Johnson');
console.log(matched); // true

Detailed Usage

Creating a Matcher Instance

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

// Create matcher with custom threshold
const matcher = new EnhancedNaturalMatcher({ threshold: 0.75 });

// Calculate similarity score
const score = matcher.getSimilarity('William Jones', 'Bill Jones');
console.log(score); // 0.78

// Check if names match using custom threshold
const matched = matcher.isMatch('Michael Smith', 'Mike Smith');
console.log(matched); // true

Matching Groups of Names

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

// Check if all names in a group refer to the same person
const nameGroup = [
  'Aaron Charles Donovan',
  'Aaron Donovan',
  'Donovan Aaron C'
];

const result = matchGroup(nameGroup);
console.log(result.score); // 0.76
console.log(result.isMatch); // true
console.log(result.matches); // Detailed match information for each pair

Name Normalization

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

// Parse a name into components
const parsed = NameNormalizer.parseName('Dr. John William Smith Jr.');
console.log(parsed);
/*
{
  original: 'Dr. John William Smith Jr.',
  cleaned: 'dr john william smith jr',
  normalized: 'dr john william smith jr',
  prefixes: [ 'dr' ],
  firstName: 'john',
  middleNames: [ 'william' ],
  lastName: 'smith',
  suffixes: [ 'jr' ],
  initials: { first: 'j', middle: 'w', last: 's' }
}
*/

// Get name variations
const variations = NameNormalizer.getNameVariations('William Smith');
console.log(variations);
// [ 'william smith', 'will smith', 'bill smith', 'billy smith', 'willy smith' ]

Challenges Handled

The library is specifically designed to handle these common name matching challenges:

• Different name formats (first last vs. last, first)
• Middle names and initials
• Nicknames and formal names
• Suffixes (Jr, Sr, III)
• Titles and prefixes (Mr, Dr, etc.)
• Compound last names
• Hyphenated names
• Different character casing
• Special characters
• Spacing variations

How It Works

This library combines two powerful approaches:

1. Natural.js: Uses industry-standard string similarity algorithms (Jaro-Winkler, Dice, Levenshtein)
2. Enhanced Matcher: Uses name-specific strategies like token matching, initials comparison, and nickname handling

The final score is an average of these two approaches, providing more robust and accurate results than either method alone.

License

MIT