Home

Welcome to the official documentation of CmpStr — a modern, modular, and fully typed TypeScript library for advanced string comparison and similarity analysis. It combines similarity metrics, phonetic indexing, normalization and filtering, and basic text analysis into a single, consistent API.

The library is designed for development and research environments and supports a wide range of comparison workflows, including single, batch, and pairwise comparisons. CmpStr is lightweight, extensible, and available as both a synchronous and an asynchronous API.

Check out the technical documentation created with TypeDoc, which exposes all classes, methods and types.

Introduction

CmpStr provides a uniform interface for similarity calculations, distance measurements and comparison operations. Its extensible metrics system includes well-known algorithms such as Levenshtein, Jaro-Winkler, Cosine, Dice, Hamming, and the Longest Common Subsequence (LCS).

In addition to metric-based comparison, CmpStr supports multiple phonetic algorithms, including Cologne Phonetics, Soundex, and Metaphone. A flexible registration and configuration system allows custom phonetic algorithms and mappings to be integrated seamlessly.

A configurable normalization and filtering pipeline ensures consistent and reproducible input preprocessing. This enables reliable comparisons across heterogeneous data sources and text formats.

The API supports precise single, batch, and pairwise comparison modes, with both raw and post-processed result formats. Phonetic search and comparison can be combined with metric-based approaches to identify pronunciation-based similarities.

CmpStr also includes tools for text analysis and diffing, such as word and sentence statistics, frequency analysis, readability metrics, and unified-diff style text comparison. While the diff tool is not intended to replace dedicated diff utilities, it provides a practical and lightweight solution for programmatic text comparison.

Designed for modern TypeScript projects, CmpStr offers full type safety, a modular architecture, and an optional asynchronous API for non-blocking and high-performance workflows.

Why use CmpStr?

CmpStr enables flexible and precise string comparison across many domains. Typical use cases include search and ranking, duplicate detection, data cleansing, linguistic analysis, and similarity-based matching in structured or unstructured data.

CLI Tool

CmpStr can also be used directly from the command line. The CmpStr CLI exposes many core features of the library via the cmpstr command and is suitable for interactive use, scripting, and automated processing.

First Steps

Getting started with CmpStr is straightforward: install the npm package, import the library, and begin comparing strings. CmpStr supports browser environments as well as ESM and CommonJS, without relying on external runtime dependencies.

The Quick Start guide provides concise examples for common usage scenarios. For additional help, consult the FAQ or open an issue on GitHub to report bugs, ask questions, or suggest improvements. Information about recent changes is available in the Changelog.