string-similarity-ts

Fast, zero-dependency string similarity (Sørensen–Dice coefficient) in TypeScript. A maintained, drop-in replacement for the archived string-similarity package.

string-similarity has 2M+ weekly downloads but its repository was archived in 2023 — no bug fixes, no types, no ESM. string-similarity-ts is a fresh implementation of the same API:

• ✅ Drop-in compatible — same compareTwoStrings / findBestMatch API, same results
• ⚡ Faster — integer-packed bigram keys instead of substring allocation (see benchmark)
• 🦺 TypeScript-first — types shipped, no @types/* needed
• 📦 Dual ESM + CJS, zero dependencies, tiny footprint
• 🇰🇷 Hangul-aware mode — optional jamo decomposition for better Korean matching

Install

npm install string-similarity-ts

Usage

import { compareTwoStrings, findBestMatch } from "string-similarity-ts";

compareTwoStrings("healed", "sealed");
// → 0.8

findBestMatch("aple", ["apple pie", "apple", "grape", "pineapple"]);
// → {
//     ratings: [ ... ],
//     bestMatch: { target: "apple", rating: 0.857... },
//     bestMatchIndex: 1
//   }

Migrating from string-similarity

Change the import. That's it — the compatibility API returns identical values:

- const stringSimilarity = require("string-similarity");
+ const stringSimilarity = require("string-similarity-ts");

Works with both require and import.

API

compareTwoStrings(first, second): number

Returns a similarity score between 0 (completely different) and 1 (identical), based on the Sørensen–Dice coefficient over character bigrams. Whitespace is ignored; comparison is case-sensitive — exactly like the original package.

findBestMatch(mainString, targetStrings, options?): BestMatch

Compares mainString against every string in targetStrings.

interface BestMatch {
  ratings: { target: string; rating: number }[];
  bestMatch: { target: string; rating: number };
  bestMatchIndex: number;
}

similarity(first, second, options?): number

Same as compareTwoStrings, plus options:

interface SimilarityOptions {
  caseSensitive?: boolean; // default true
  stripSpaces?: boolean;   // default true
  hangul?: boolean;        // default false — decompose Hangul syllables into jamo
}

similarity("HELLO", "hello", { caseSensitive: false }); // → 1

Hangul-aware matching 🇰🇷

Korean syllables are single code points, so a one-jamo typo makes two bigrams mismatch at once and tanks the score. With hangul: true, syllables are decomposed into jamo before comparison:

similarity("삼성전자", "샴성전자");                 // → 0.33
similarity("삼성전자", "샴성전자", { hangul: true }); // → 0.8+

decomposeHangul(str): string

The decomposition helper, exported for direct use. Non-Hangul characters pass through untouched.

Benchmark

npm run bench — Node.js v20, tinybench. Higher is better.

| Scenario | string-similarity (archived) | string-similarity-ts | Speedup | | --- | ---: | ---: | :---: | | compareTwoStrings — 1,000 short pairs | 1,596 ops/s | 3,052 ops/s | 1.9× | | compareTwoStrings — long text (400+ chars) | 23,767 ops/s | 65,604 ops/s | 2.8× | | findBestMatch — 500 targets | 2,554 ops/s | 5,628 ops/s | 2.2× |

Same results, roughly 2–3× the throughput — bigrams are packed into integer map keys instead of allocating a substring per bigram.

Why not Levenshtein?

Dice bigram similarity is length-normalized, order-tolerant ("apple pie" vs "pie apple" still scores high), and runs in linear time — which is why the original string-similarity chose it. If you need edit distance specifically, use a Levenshtein library; if you need "how alike do these look", this is the right tool.

License

MIT © creepem

The API design follows the archived string-similarity package by Akash Kurdekar (MIT). This is an independent reimplementation.

한국어

아카이브된 string-similarity 패키지의 유지보수 대체재입니다. 동일한 API에 TypeScript 타입, ESM/CJS 듀얼 지원, 더 빠른 구현을 제공하며, hangul 옵션으로 한글 자모 분해 기반의 정밀한 유사도 비교를 지원합니다.