@bernierllc/string-similarity

Pure, zero-dependency Unicode-aware string similarity primitives for the BernierLLC toolchain.

Given two strings or values, returns a normalized [0, 1] similarity score. Handles Unicode (NFC/NFD normalization), diacritic folding, and pluggable equivalence/nickname tables so comparators work across languages and scripts.

Installation

npm install @bernierllc/string-similarity

Features

• Zero runtime dependencies — pure ECMAScript built-ins only (String.prototype.normalize, Date.parse, Math)
• Unicode-aware — NFC normalization, diacritic folding, BOM stripping
• Pluggable — caller-supplied nickname tables; no anglocentric hard-coding
• Browser and Node.js — works in any ES2022 environment (Node >= 18)
• Strict TypeScript — no any in public API

Integration Status

| Integration | Status | Notes | |-------------|--------|-------| | Logger integration | not-applicable | Pure math functions with no I/O or async paths — nothing to log. Errors are thrown synchronously and propagated to callers. | | NeverHub integration | not-applicable | Core utility with no service lifecycle. Pure functions have no instance to register. | | NeverAdmin integration | not-applicable | No configuration or administration surface. |

Usage

import {
  jaroWinkler,
  levenshtein,
  compareName,
  compareEmail,
  comparePhone,
  compareDate,
} from '@bernierllc/string-similarity';

// Name matching with diacritics
compareName('Müller', 'Muller');   // > 0.8 (diacritics folded)
compareName('张伟', '张伟');        // 1.0 (identical CJK)

// Email normalization
compareName('[email protected]', '[email protected]'); // 1.0

// Date proximity
compareDate('2024-03-15', '2024-03-16', { toleranceDays: 3 }); // ~0.667

Quick Start

import {
  jaroWinkler,
  levenshtein,
  levenshteinRatio,
  compareName,
  normalizeEmail,
  compareEmail,
  normalizePhone,
  comparePhone,
  compareDate,
  resolveComparator,
} from '@bernierllc/string-similarity';

// Jaro-Winkler similarity
jaroWinkler('MARTHA', 'MARHTA'); // ~0.961
jaroWinkler('hello', 'hello');   // 1.0
jaroWinkler('abc', 'xyz');       // 0.0

// Levenshtein edit distance
levenshtein('kitten', 'sitting'); // 3

// Levenshtein similarity ratio [0, 1]
levenshteinRatio('kitten', 'kitten'); // 1.0
levenshteinRatio('kitten', 'sitten'); // ~0.833

API

jaroWinkler(a, b): number

Jaro-Winkler similarity. NFC-normalized and lowercased before comparison. Returns [0, 1].

jaroWinkler('MARTHA', 'MARHTA'); // ~0.961 (classic reference pair)
jaroWinkler('', '');             // 1.0 (identical)
jaroWinkler('abc', '');          // 0.0 (empty vs non-empty)

levenshtein(a, b): number

Raw Levenshtein edit distance (non-negative integer). Both inputs NFC-normalized. Iterative O(n·m) implementation — no stack overflow for strings up to tens of thousands of characters.

levenshtein('kitten', 'sitting'); // 3
levenshtein('', '');              // 0
levenshtein('abc', '');           // 3

levenshteinRatio(a, b): number

Levenshtein similarity ratio: 1 - distance / max(len(a), len(b)). Returns [0, 1].

levenshteinRatio('kitten', 'sitting'); // ~0.571
levenshteinRatio('hello', 'hello');    // 1.0
levenshteinRatio('abc', '');           // 0.0

compareName(a, b, opts?): number

Name similarity with Unicode diacritic folding and pluggable nickname tables.

Pipeline: NFC + BOM strip + lowercase → punctuation strip → optional diacritic fold → nickname resolve → Jaro-Winkler.

// Diacritic folding (default: on)
compareName('Müller', 'Muller');   // > 0.8
compareName('José', 'Jose');       // > 0.8
compareName('Ångström', 'Angstrom'); // > 0.8

// Custom nickname table
compareName('Bob', 'Robert', {
  nicknameTable: { robert: ['bob', 'rob', 'bobby'] },
}); // > 0.7

// CJK and Cyrillic: no crash, identical = 1.0
compareName('张伟', '张伟');   // 1.0
compareName('Иванов', 'Иванов'); // 1.0

// Disable diacritic folding (for scripts where diacritics change meaning)
compareName('Müller', 'Muller', { foldDiacritics: false }); // < folded score

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | nicknameTable | Record<string, string[]> | {} | Canonical → aliases map. All keys/values must be lowercase. | | foldDiacritics | boolean | true | Strip Unicode combining characters after NFC decomposition. |

A small English nickname table is also exported as DEFAULT_NICKNAME_TABLE for convenience, but is not used by default.

normalizeEmail(s): string

Normalize an email to canonical lowercase form. Strips +tag subaddress from local part. Returns "" on unparseable input (no throw).

normalizeEmail('[email protected]'); // '[email protected]'
normalizeEmail('[email protected]');     // '[email protected]'
normalizeEmail('not-an-email');         // ''

compareEmail(a, b): number

Normalize both addresses then exact-match (1.0 or 0.0). Returns 0.0 if either address is invalid.

compareEmail('[email protected]', '[email protected]'); // 1.0
compareEmail('[email protected]', '[email protected]');         // 1.0 (same mailbox)
compareEmail('[email protected]', '[email protected]');                 // 0.0

normalizePhone(s, region?): string

Strip all non-digit characters. With an optional ISO 3166-1 alpha-2 region hint, prepends the country code for local numbers (e.g. US 10-digit → prepend 1). Returns "" for empty/no-digit input.

normalizePhone('(555) 867-5309');           // '5558675309'
normalizePhone('+1 (555) 867-5309');        // '15558675309'
normalizePhone('555-867-5309', 'US');       // '15558675309'
normalizePhone('+44 20 7946 0958');         // '442079460958'
normalizePhone('20 7946 0958', 'GB');       // '442079460958'
normalizePhone('');                         // ''

comparePhone(a, b): number

Normalize both numbers then exact-match (1.0 or 0.0). Returns 0.0 if either normalizes to empty.

comparePhone('(555) 867-5309', '5558675309'); // 1.0
comparePhone('+44 20 7946 0958', '442079460958'); // 1.0
comparePhone('555-1111', '555-2222');         // 0.0

compareDate(a, b, opts?): number

Date proximity similarity. Parses ISO 8601 strings and Date objects via Date.parse. Score decays linearly from 1.0 (equal) to 0.0 (at or beyond toleranceDays). Returns 0.0 for unparseable input (no throw).

compareDate('2024-03-15', '2024-03-15');                          // 1.0
compareDate('2024-03-15', '2024-03-16', { toleranceDays: 3 });   // ~0.667
compareDate('2024-03-15', '2024-03-18', { toleranceDays: 3 });   // 0.0
compareDate('not-a-date', '2024-03-15');                          // 0.0

// Also accepts Date objects
compareDate(new Date('2024-03-15'), new Date('2024-03-16'));      // ~0.667

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | toleranceDays | number | 3 | Days within which scores decay linearly from 1.0 to 0.0. |

resolveComparator(name): Comparator

Resolve a built-in comparator name to its function. Enables entity-resolver and similar packages to accept ComparatorName | Comparator.

Throws StringSimilarityError with code UNKNOWN_COMPARATOR if the name is not recognized.

import { resolveComparator, StringSimilarityError } from '@bernierllc/string-similarity';

const fn = resolveComparator('jaroWinkler');
fn('hello', 'helo'); // ~0.933

try {
  resolveComparator('bogus' as never);
} catch (err) {
  if (err instanceof StringSimilarityError) {
    console.error(err.code); // 'UNKNOWN_COMPARATOR'
  }
}

Valid names: 'jaroWinkler' | 'levenshtein' | 'levenshteinRatio' | 'compareName' | 'compareEmail' | 'comparePhone' | 'compareDate'

Comparator type

type Comparator = (a: unknown, b: unknown) => number;

A function that returns a normalized [0, 1] similarity score. Inputs are typed as unknown so the caller may pass any value; implementations coerce to string via String(a).

Error Handling

| Class | Code | Description | Retryable | |-------|------|-------------|-----------| | StringSimilarityError | UNKNOWN_COMPARATOR | A comparator name supplied to resolveComparator was not found | No | | StringSimilarityError | INVALID_INPUT | Input is structurally invalid (default code; currently only used by constructor default) | No |

All other functions handle invalid input gracefully without throwing:

• normalizeEmail / normalizePhone return "" for invalid input
• compareDate returns 0.0 for unparseable dates
• jaroWinkler, levenshtein, levenshteinRatio, compareName, compareEmail, comparePhone handle empty strings without throwing

import { StringSimilarityError } from '@bernierllc/string-similarity';

try {
  resolveComparator(userSuppliedName);
} catch (err) {
  if (err instanceof StringSimilarityError && err.code === 'UNKNOWN_COMPARATOR') {
    // err.context.requested = the invalid name
    // err.context.available = array of valid names
  }
  throw err; // re-throw unknown errors; never catch-and-swallow
}

Unicode Details

• NFC normalization is applied before every comparison. This means 'é' (U+00E9, precomposed) and 'e' + combining acute (U+0065 U+0301, NFD) score identically.
• BOM stripping: leading U+FEFF is removed before comparison.
• Diacritic folding in compareName works by NFD decomposition followed by stripping all Unicode combining marks (\p{M}), making 'Müller' and 'Muller' near-identical.
• CJK, Arabic, Cyrillic, Hebrew, Thai: all scripts work correctly — Jaro-Winkler and Levenshtein operate on Unicode code points via Array.from, so multi-byte characters are handled as single units.

License

Copyright (c) 2025 Bernier LLC. Licensed under the Bernier LLC limited-use license.