stringwise

stringwise is a fast and lightweight TypeScript library for comparing string similarity using multiple algorithms like bigrams, Levenshtein, Jaro-Winkler, and Ratcliff/Obershelp. It’s ideal for fuzzy searching, intelligent suggestions, and natural language processing tasks where accuracy and performance matter.

✨ Why Use stringwise?

• ⚡️ Efficient and Lightweight: Built for real-time performance in search and suggestion engines.
• 🧠 Multiple Algorithms: Choose from default, levenshtein, jaro-winkler, or ratcliff-obershelp.
• 🎯 Precise Similarity Control: Use round option to control rating precision.
• 🔍 Fuzzy Matching Made Easy: Quickly identify the best match among multiple strings.
• 🔒 Fully Typed: Built with TypeScript for a safer developer experience.
• 📦 Modular Structure: Ready to scale with your application needs.

📦 Installation

Install via npm or yarn:

npm install stringwise

or

yarn add stringwise

🚀 Usage

Importing

import { compareTwoStrings, findBestMatch, getSimilarityFn } from "stringwise";

Compare Two Strings

compareTwoStrings("hello", "h3llo"); // e.g. 0.5

Find Best Match

const result = findBestMatch("hello", ["halo", "hell", "hello", "world"]);

console.log(result.bestMatch);
// { target: 'hello', rating: 1 }

console.log(result.ratings);
/*
[
  { target: 'halo', rating: 0.2857142857142857 },
  { target: 'hell', rating: 0.8571428571428571 },
  { target: 'hello', rating: 1 },
  { target: 'world', rating: 0 }
]
*/

Use with Options

const result = findBestMatch("kitten", ["sitting"], {
  algorithm: "levenshtein",
  round: 3,
});

Direct Algorithm Access

const sim = getSimilarityFn("jaro-winkler");
console.log(sim("MARTHA", "MARHTA")); // ~0.9611

🧠 API

compareTwoStrings(a: string, b: string): number

Returns a similarity score between 0 and 1 using bigram overlap.

findBestMatch(main: string, targets: string[], options?: FindBestMatchOptions): FindBestMatchResult

Returns an object containing:

• bestMatch: The string with the highest similarity
• bestMatchIndex: Index in the original list
• ratings: All similarity scores

Options:

type FindBestMatchOptions = {
  round?: number; // Decimal places
  algorithm?: "default" | "levenshtein" | "jaro-winkler" | "ratcliff-obershelp";
};

getSimilarityFn(algorithm: string): (a: string, b: string) => number

Returns the similarity function for a given algorithm name.

Types

type MatchRating = {
  target: string;
  rating: number;
};

type FindBestMatchResult = {
  bestMatch: MatchRating;
  bestMatchIndex: number;
  ratings: MatchRating[];
};

✅ Requirements

• Node.js v14.0.0 or newer
• TypeScript (recommended)

🛡 License

Licensed under the MIT License. See the LICENSE file for more details.

🤝 Contributing

Contributions are welcome! Whether it's a bug fix, feature, or idea — feel free to open a pull request.

1. Fork the repo
2. Create your branch: git checkout -b my-feature
3. Commit your changes: git commit -m 'feat: awesome feature'
4. Push and open a PR on GitHub

👤 Author

Created by Kledenai
📫 me@kledenai.com
🌍 github.com/kledenai

[1.0.1] - 2025-04-20

Added

• Multiple similarity algorithms:
  • levenshtein (normalized)
  • jaro-winkler
  • ratcliff-obershelp (custom implementation)
  • Default remains the original bigram method
• Options support in findBestMatch:
  • algorithm: select which similarity strategy to use
  • round: control the precision of the output rating (e.g., 2 decimal places)
• Exported getSimilarityFn for direct algorithm access:
  • Enables low-level comparisons without using findBestMatch
• New test suites for:
  • Each similarity algorithm
  • Round precision behavior
  • Utility ratcliffObershelp isolated
  • Exported API surface coverage

Improved

• Refactored internal architecture for better modularity and separation of concerns:
  • Moved algorithm definitions to similarity.ts
  • Separated types into types.ts
  • Isolated ratcliffObershelp in utils
• Aligned default behavior of bigram algorithm with expected string normalization
• Improved project metadata:
  • Updated keywords and description in package.json for better discoverability

Fixed

• Correct handling of empty strings in ratcliffObershelp to prevent NaN errors

Notes

• This version lays the groundwork for future support of:
  • Case-insensitive comparison
  • Threshold-based result filtering
  • Custom user-defined similarity functions
  • Locale-aware string comparison

[1.0.0] - 2025-04-20

Added

• Initial release of stringwise, a lightweight and efficient string similarity library written in TypeScript.
• Core functionality to:
  • Compare two strings using bigram-based similarity and return a score between 0 and 1.
  • Find the best match for a given string among an array of candidates based on similarity score.
• TypeScript type definitions for MatchRating and BestMatchResult.
• Validation utility isValidInput for internal input integrity checks.
• Example usage and API documentation included in the README.
• ESLint configuration for consistent code quality.
• Jest setup for unit testing all core functionalities.
• License (MIT).
• Scripts for building, testing, linting, and cleaning in package.json.

Fixed

• Handled edge cases where strings are too short (less than 2 characters) or empty.
• Removed whitespace before comparison to ensure consistent results.

Notes

• Initial release includes complete comparison and matching functionalities based on bigram similarity.
• Future updates may include advanced NLP techniques, custom scoring algorithms, and locale-aware comparisons.