Jaro-Winkler for TypeScript

1.0.1 · active · verified Sun Apr 19

jaro-winkler-typescript provides a pure TypeScript implementation of the Jaro and Jaro-Winkler string similarity algorithms. These algorithms are widely used to measure the edit distance or similarity between two strings, returning a score typically ranging from 0 (completely dissimilar) to 1 (identical). The current stable version is 1.0.1. As a utility library for a well-defined algorithm, its release cadence is expected to be slow, with new versions primarily addressing bug fixes, performance improvements, or minor enhancements. A key differentiator is its explicit TypeScript implementation, offering strong type safety and an improved developer experience in modern TypeScript projects. It serves as a direct, unopinionated implementation focused solely on accurately calculating these specific string similarity scores.

Common errors

```
TypeError: (0 , jaro_winkler_typescript__WEBPACK_IMPORTED_MODULE_0__.jaro) is not a function
```
cause Attempting to import `jaro` or `jaroWinkler` using CommonJS `require()` syntax in an environment that expects ESM, or incorrect destructuring.

fix Ensure your project is configured for ESM and use `import { jaro } from 'jaro-winkler-typescript';`. If using CommonJS, it may require transpilation or a different package.
```
TypeError: jaro is not a function
```
cause This typically occurs when trying to access `jaro` or `jaroWinkler` after using a default import (`import jaro from '...'`) for a package that only provides named exports, or attempting `const jaro = require(...)` without destructuring.

fix Use named imports: `import { jaro, jaroWinkler } from 'jaro-winkler-typescript';`
```
Argument of type 'number' is not assignable to parameter of type 'string'.
```
cause Passing a non-string value (e.g., a number or null) to the `jaro` or `jaroWinkler` function, which expects two string arguments.

fix Ensure both arguments passed to `jaro` and `jaroWinkler` are strings. Validate input types before calling the functions.

Warnings

gotcha By default, both `jaro` and `jaroWinkler` functions are case-sensitive. 'Apple' and 'apple' will yield a similarity score of 0 (or close to 0) unless `caseSensitive: false` is explicitly set in the options.
Fix: Pass `{ caseSensitive: false }` as the third argument to the `jaro` or `jaroWinkler` function for case-insensitive comparisons.
gotcha The Jaro-Winkler algorithm, while generally effective, tends to perform better with shorter strings, especially proper nouns, due to its prefix scaling feature. For very long strings or different types of string comparison needs, other algorithms like Levenshtein distance might be more suitable.
Fix: Understand the characteristics of different string similarity algorithms and choose the one best suited for your specific data and use case. Jaro-Winkler is often preferred for human names or dictionary words.
gotcha The similarity scores returned are floating-point numbers between 0 and 1. Direct equality checks on these values might fail due to floating-point precision issues. For display, consider rounding the results.
Fix: When comparing scores, use a small epsilon for tolerance (e.g., `Math.abs(score1 - score2) < EPSILON`). For displaying results, use `toFixed()` or `Math.round()`.

Install

npm install jaro-winkler-typescript npm
yarn add jaro-winkler-typescript yarn
pnpm add jaro-winkler-typescript pnpm

Imports

jaro
wrong:
```
const { jaro } = require('jaro-winkler-typescript');
```
correct:
```
import { jaro } from 'jaro-winkler-typescript';
```
This package is designed for ESM/TypeScript; CommonJS require() syntax for named exports is not directly supported and can lead to runtime errors.
jaroWinkler
wrong:
```
import jaroWinkler from 'jaro-winkler-typescript';
```
correct:
```
import { jaroWinkler } from 'jaro-winkler-typescript';
```
Both `jaro` and `jaroWinkler` are named exports. Attempting a default import will result in 'undefined' or a 'TypeError'.
JaroWinklerOptions
```
import type { JaroWinklerOptions } from 'jaro-winkler-typescript';
```
When only importing types for type annotations, use `import type` for clarity and to ensure it's removed during compilation if not needed at runtime.

Quickstart

Demonstrates basic usage of Jaro and Jaro-Winkler algorithms, including case-sensitive and case-insensitive comparisons, and interpretation of similarity scores.

import { jaro, jaroWinkler } from "jaro-winkler-typescript";

// Example 1: Basic comparison for Jaro similarity
const stringA = "MARTHA";
const stringB = "MARHTA";
const similarityJaro = jaro(stringA, stringB);
console.log(`Jaro similarity between "${stringA}" and "${stringB}": ${similarityJaro.toFixed(4)}`);
// Expected output: Jaro similarity between "MARTHA" and "MARHTA": 0.9444

// Example 2: Basic comparison for Jaro-Winkler similarity
const stringC = "DWAYNE";
const stringD = "DUANE";
const similarityJaroWinkler = jaroWinkler(stringC, stringD);
console.log(`Jaro-Winkler similarity between "${stringC}" and "${stringD}": ${similarityJaroWinkler.toFixed(4)}`);
// Expected output: Jaro-Winkler similarity between "DWAYNE" and "DUANE": 0.8400

// Example 3: Case-insensitive comparison
const name1 = "JavaScript";
const name2 = "javascript";
const insensitiveJaro = jaro(name1, name2, { caseSensitive: false });
console.log(`Case-insensitive Jaro similarity between "${name1}" and "${name2}": ${insensitiveJaro.toFixed(4)}`);
// Expected output: Case-insensitive Jaro similarity between "JavaScript" and "javascript": 1.0000

// Example 4: Comparing strings with significant differences
const word1 = "hello";
const word2 = "world";
const jaroScore = jaro(word1, word2);
const jaroWinklerScore = jaroWinkler(word1, word2);
console.log(`Jaro score for "${word1}" and "${word2}": ${jaroScore.toFixed(4)}`);
console.log(`Jaro-Winkler score for "${word1}" and "${word2}": ${jaroWinklerScore.toFixed(4)}`);
// Expected output: Jaro score for "hello" and "world": 0.4444, Jaro-Winkler score for "hello" and "world": 0.4444

view raw JSON →