Equivalency

Focus on the differences that matter.

Equivalency lets you declaratively define rules for string equivalence.

• Several useful rules are provided out of the box, for example, Unicode normalization, capitalization, common puncutation and diacritical marks.
• Custom rules can be created using plain strings, regexes, or functions.
• Comparing two strings via an equivalency returns whether the two strings are equivalent according to that equivalency's ruleset, and can optionally return
  • the edit distance between the two fully transformed strings using the damerau-levenshtein algorithm
  • reasons why the strings differ
• Equivalency instances can be cloned, making it easy to start with a root equivalency that takes care of universal concerns like Unicode normalization, then derive more specific equivalencies that are tailored to specific cases, like case- or punctuation-sensitivity.

Equivalency works in both Node and browsers back as far as IE 11 (full list of supported browsers).

Usage

const checker = require('equivalency');
const { Equivalency } = checker;

// Default rule is byte-equality.
checker.compare('a', 'a');
// { isEquivalent: true }

checker.compare('a', 'A');
// { isEquivalent: false }

// Specify which differences matter/don't matter.
checker.doesntMatter(Equivalency.CAPITALIZATION);
checker.compare('a', 'A');
// { isEquivalent: true }

checker.compare('Hot-dog', 'hotdog');
// { isEquivalent: false }

checker.doesntMatter(Equivalency.en.COMMON_PUNCTUATION);
checker.compare('Hot-dog', 'hotdog');
// { isEquivalent: true }

checker.compare('Go away, fly!', 'Go away; fly!');
// { isEquivalent: true }

checker.matters(',;');
checker.compare('Go away, fly!', 'Go away; fly!');
// { isEquivalent: false }

checker.compare('Go away, fly!', 'Go away; fly!',{giveReasons: true});
// { isEquivalent: false, reasons: [{name: ',;'}] }

// Return edit distance
const options = { calculateEditDistance: true };
checker.compare('show', 'shoe', options);
// { isEquivalent: false, editDistance: 1 }

const esChecker = new Equivalency();
esChecker.compare('adiós', 'adios');
// { isEquivalent: false }

const enChecker = new Equivalency();
enChecker.doesntMatter(Equivalency.ACCENTS);
enChecker.compare('adiós', 'adios');
// { isEquivalent: true }

// Root equivalency: normalizes Unicode, whitespace differences, and case.
const root = new Equivalency()
  .doesntMatter(Equivalency.UNICODE_NORMALIZATION)
  .doesntMatter(Equivalency.WHITESPACE_DIFFERENCES)
  .doesntMatter(Equivalency.CAPITALIZATION)

// Diacritic-blind equivalency cloned from root equivalency.
const equivalencyForDiacriticWarning = root
  .clone()
  .doesntMatter(Equivalency.COMMON_DIACRITICS);

const isMatch = root.compare(
  providedAnswer,
  expectedAnswer
).isEquivalent;

const isMatchExceptForDiacritics = equivalencyForDiacriticWarning.compare(
  providedAnswer,
  expectedAnswer
).isEquivalent;

Tests

Running tests

• local: yarn test
• Browserstack (for browser compatability, particular IE 11): BROWSER_STACK_ACCESS_KEY=<key> yarn run test:karma

Release steps

See the release doc.