name-match
Version:
A robust name matching library combining multiple algorithms for optimal performance
128 lines (94 loc) • 3.73 kB
Markdown
# Enhanced Name Matcher
A robust name matching library for Node.js that combines multiple string similarity algorithms for optimal name matching performance.
[](https://www.npmjs.com/package/name-match)
[](https://opensource.org/licenses/MIT)
## 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
```bash
npm install name-match
```
## Quick Start
```javascript
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
```javascript
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
```javascript
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
```javascript
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