how-similar

How Similar

A zero-dependency TypeScript module that compares strings and returns a similarity score from 0 to 1 using normalised Levenshtein distance.

import { similarity } from 'how-similar'

similarity('Dublin', 'Doblin') // 0.833

Requirements

• Node.js ≥ 22 (uses native --experimental-strip-types for zero-build dev)

Install

npm install how-similar

Usage

import { similarity, stringSimilarity, stringArraySimilarity } from 'how-similar'
import type { SimilarityOptions, SimilarityResult } from 'how-similar'

Compare two strings

similarity('Dublin', 'Doblin')  // 0.833
similarity('Dublin', 'Dublin')  // 1

Compare a string against an array

Returns results sorted by similarity descending:

similarity('Dublin', ['Doblin', 'Devlin', 'Duuublin', 'Dublin'])
// [
//   { key: 'Dublin',   value: 1     },
//   { key: 'Doblin',   value: 0.875 },
//   { key: 'Devlin',   value: 0.75  },
//   { key: 'Duuublin', value: 0.75  }
// ]

Options

All options are optional and can be combined:

Option	Type	Description
ignorecase	boolean	Normalise both strings to lower-case before comparing
stem	boolean	Apply Porter stemming to each word before comparing
except	string[]	Words to strip from both strings before comparing

// Ignore case
similarity('Dublin', 'dublin', { ignorecase: true })  // 1

// Stem words
similarity('Trying', 'Try', { stem: true })  // 1

// Exclude words
similarity('should be equal', 'should equal', { except: ['be'] })  // 1

// All options together
similarity('Trying to Be equal', 'try equal', {
  except: ['to', 'be'],
  ignorecase: true,
  stem: true
})  // 1

Scripts

npm test          # Run tests directly from .ts source (no build needed)
npm run typecheck # Full tsc type-check
npm run build     # Emit dist/ with .js, .d.ts, and .map files

License

Copyright 2019, Juan Convers. Released under the MIT License.