cmpstr 2.0.2 → 3.0.0

package/dist/types/metric/Levenshtein.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Levenshtein Distance
+ * src/metric/Levenshtein.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Levenshtein_distance
+ *
+ * The Levenshtein distance is a classic metric for measuring the minimum number
+ * of single-character edits (insertions, deletions, or substitutions) required
+ * to change one string into another.
+ *
+ * It is widely used in approximate string matching, spell checking, and natural
+ * language processing.
+ *
+ * @module Metric/LevenshteinDistance
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { MetricInput, MetricOptions, MetricCompute } from '../utils/Types';
+import { Metric } from './Metric';
+export interface LevenshteinRaw {
+    dist: number;
+    maxLen: number;
+}
+/**
+ * LevenshteinDistance class extends the Metric class to implement the Levenshtein distance algorithm.
+ */
+export declare class LevenshteinDistance extends Metric<LevenshteinRaw> {
+    /**
+     * Constructor for the Levenshtein class.
+     *
+     * Initializes the Levenshtein metric with two input strings
+     * or arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a: MetricInput, b: MetricInput, opt?: MetricOptions);
+    /**
+     * Calculates the Levenshtein distance between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<LevenshteinRaw>} - Object containing the similarity result and raw distance
+     */
+    protected compute(a: string, b: string, m: number, n: number, maxLen: number): MetricCompute<LevenshteinRaw>;
+}

package/dist/types/metric/Metric.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Abstract Metric
+ * src/metric/Metric.ts
+ *
+ * This module defines an abstract class for string metrics, providing a framework for
+ * computing various string similarity metrics. It includes methods for running metrics
+ * in different modes (single, batch, pairwise) synchronous or asynchronous and caching
+ * results to optimize performance. The class is designed to be extended by specific
+ * metric implementations like the Levenshtein distance or Jaro-Winkler similarity.
+ *
+ * It provides:
+ *  - A base class for string metrics with common functionality
+ *  - Methods for running metrics in different modes
+ *  - Pre-computation for trivial cases to optimize performance
+ *  - Caching of metric computations to avoid redundant calculations
+ *  - Support for symmetrical metrics (same result for inputs in any order)
+ *  - Performance tracking capabilities (Profiler)
+ *  - Asynchronous execution support for metrics
+ *
+ * This class is intended to be extended by specific metric implementations that will
+ * implement the `compute` method to define the specific metric computation logic.
+ *
+ * @module Metric
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { MetricMode, MetricInput, MetricOptions, MetricCompute, MetricRaw, MetricResult, RegistryService } from '../utils/Types';
+/**
+ * Abstract class representing a generic string metric.
+ *
+ * @abstract
+ * @template R - The type of the raw result, defaulting to `MetricRaw`.
+ */
+export declare abstract class Metric<R = MetricRaw> {
+    private static cache;
+    private readonly metric;
+    private readonly a;
+    private readonly b;
+    private origA;
+    private origB;
+    protected readonly options: MetricOptions;
+    protected readonly symmetric: boolean;
+    /**
+     * Result of the metric computation, which can be a single result or an array of results.
+     * This will be populated after running the metric.
+     */
+    private results;
+    /**
+     * Static method to clear the cache of metric computations.
+     */
+    static clear(): void;
+    /**
+     * Swaps two strings and their lengths if the first is longer than the second.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @returns {[string, string, number, number]} - Swapped strings and lengths
+     */
+    protected static swap(a: string, b: string, m: number, n: number): [
+        string,
+        string,
+        number,
+        number
+    ];
+    /**
+     * Clamps the similarity result between 0 and 1.
+     *
+     * @param {number} res - The input similarity to clamp
+     * @returns {number} - The clamped similarity (0 to 1)
+     */
+    protected static clamp(res: number): number;
+    /**
+     * Constructor for the Metric class.
+     * Initializes the metric with two inputs (strings or arrays of strings) and options.
+     *
+     * @param {string} metric - The name of the metric (e.g. 'levenshtein')
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     * @param {boolean} [symmetric=false] - Whether the metric is symmetric (same result for inputs in any order)
+     * @throws {Error} - If inputs `a` or `b` are empty
+     */
+    constructor(metric: string, a: MetricInput, b: MetricInput, opt?: MetricOptions, symmetric?: boolean);
+    /**
+     * Pre-compute the metric for two strings.
+     * This method is called before the actual computation to handle trivial cases.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @returns {MetricCompute<R>|undefined} - Pre-computed result or undefined if not applicable
+     */
+    protected preCompute(a: string, b: string, m: number, n: number): MetricCompute<R> | undefined;
+    /**
+     * Abstract method to be implemented by subclasses to perform the metric computation.
+     * This method should contain the logic for computing the metric between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @returns {MetricCompute<R>} - The result of the metric computation
+     * @throws {Error} - If not overridden in a subclass
+     */
+    protected compute(a: string, b: string, m: number, n: number, maxLen: number): MetricCompute<R>;
+    /**
+     * Run the metric computation for single inputs (two strings).
+     * Applies preCompute for trivial cases before cache lookup and computation.
+     *
+     * If the profiler is active, it will measure time and memory usage.
+     *
+     * @param {number} i - Pointer to the first string
+     * @param {number} j - Pointer to the second string
+     * @returns {MetricResultSingle<R>} - The result of the metric computation
+     */
+    private runSingle;
+    /**
+     * Run the metric computation for single inputs (two strings) asynchronously.
+     *
+     * @param {number} i - Pointer to the first string
+     * @param {number} j - Pointer to the second string
+     * @returns {Promise<MetricResultSingle<R>>} - Promise resolving the result of the metric computation
+     */
+    private runSingleAsync;
+    /**
+     * Run the metric computation for batch inputs (arrays of strings).
+     *
+     * It iterates through each string in the first array and computes the metric
+     * against each string in the second array.
+     */
+    private runBatch;
+    /**
+     * Run the metric computation for batch inputs (arrays of strings) asynchronously.
+     */
+    private runBatchAsync;
+    /**
+     * Run the metric computation for pairwise inputs (A[i] vs B[i]).
+     *
+     * This method assumes that both `a` and `b` are arrays of equal length
+     * and computes the metric only for corresponding index pairs.
+     */
+    private runPairwise;
+    /**
+     * Run the metric computation for pairwise inputs (A[i] vs B[i]) asynchronously.
+     */
+    private runPairwiseAsync;
+    /**
+     * Set the original inputs to which the results of the metric calculation will refer.
+     *
+     * @param {MetricInput} [a] - original input(s) for a
+     * @param {MetricInput} [b] - original input(s) for b
+     */
+    setOriginal(a?: MetricInput, b?: MetricInput): this;
+    /**
+     * Check if the inputs are in batch mode.
+     *
+     * This method checks if either `a` or `b` contains more than one string,
+     * indicating that the metric is being run in batch mode.
+     *
+     * @returns {boolean} - True if either input is an array with more than one element
+     */
+    isBatch(): boolean;
+    /**
+     * Check if the inputs are in single mode.
+     *
+     * This method checks if both `a` and `b` are single strings (not arrays),
+     * indicating that the metric is being run on a single pair of strings.
+     *
+     * @returns {boolean} - True if both inputs are single strings
+     */
+    isSingle(): boolean;
+    /**
+     * Check if the inputs are in pairwise mode.
+     *
+     * This method checks if both `a` and `b` are arrays of the same length,
+     * indicating that the metric is being run on corresponding pairs of strings.
+     *
+     * @returns {boolean} - True if both inputs are arrays of equal length
+     * @param {boolean} [safe=false] - If true, does not throw an error if lengths are not equal
+     * @throws {Error} - If `safe` is false and the lengths of `a` and `b` are not equal
+     */
+    isPairwise(safe?: boolean): boolean;
+    /**
+     * Check if the metric is symmetrical.
+     *
+     * This method returns whether the metric is symmetric, meaning it produces the same
+     * result regardless of the order of inputs (e.g., Levenshtein distance).
+     *
+     * @returns {boolean} - True if the metric is symmetric
+     */
+    isSymmetrical(): boolean;
+    /**
+     * Determine which mode to run the metric in.
+     *
+     * This method checks the provided mode or defaults to the mode specified in options.
+     * If no mode is specified, it defaults to 'default'.
+     *
+     * @param {MetricMode} [mode] - The mode to run the metric in (optional)
+     * @returns {MetricMode} - The determined mode
+     */
+    whichMode(mode?: MetricMode): MetricMode;
+    /**
+     * Clear the cached results of the metric.
+     *
+     * This method resets the `results` property to `undefined`, effectively clearing
+     * any previously computed results. It can be useful for re-running the metric
+     * with new inputs or options.
+     */
+    clear(): void;
+    /**
+     * Run the metric computation based on the specified mode.
+     *
+     * @param {MetricMode} [mode] - The mode to run the metric in (optional)
+     * @param {boolean} [clear=true] - Whether to clear previous results before running
+     * @throws {Error} - If an unsupported mode is specified
+     */
+    run(mode?: MetricMode, clear?: boolean): void;
+    /**
+     * Run the metric computation based on the specified mode asynchronously.
+     *
+     * @param {MetricMode} [mode] - The mode to run the metric in (optional)
+     * @param {boolean} [clear=true] - Whether to clear previous results before running
+     * @returns {Promise<void>} - A promise that resolves when the metric computation is complete
+     * @throws {Error} - If an unsupported mode is specified
+     */
+    runAsync(mode?: MetricMode, clear?: boolean): Promise<void>;
+    /**
+     * Get the name of the metric.
+     *
+     * @returns {string} - The name of the metric
+     */
+    getMetricName(): string;
+    /**
+     * Get the result of the metric computation.
+     *
+     * @returns {MetricResult<R>} - The result of the metric computation
+     * @throws {Error} - If `run()` has not been called before this method
+     */
+    getResults(): MetricResult<R>;
+}
+/**
+ * Metric registry service for managing metric implementations.
+ *
+ * This registry allows for dynamic registration and retrieval of metric classes,
+ * enabling the use of various string similarity metrics in a consistent manner.
+ */
+export declare const MetricRegistry: RegistryService<Metric<MetricRaw>>;
+/**
+ * Type definition for a class constructor that extends the Metric class.
+ *
+ * This type represents a constructor function for a class that extends the Metric
+ * class. It can be used to create instances of specific metric implementations,
+ * such as Levenshtein or Jaro-Winkler.
+ *
+ * @template R - The type of the raw result, defaulting to `MetricRaw`.
+ */
+export type MetricCls<R = MetricRaw> = new (...args: any[]) => Metric<R>;

package/dist/types/metric/NeedlemanWunsch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Needleman-Wunsch Algorithm
+ * src/metric/NeedlemanWunsch.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Needleman%E2%80%93Wunsch_algorithm
+ *
+ * The Needleman-Wunsch algorithm performs global alignment, aligning two strings
+ * entirely, including gaps. It is commonly used in bioinformatics for sequence
+ * alignment.
+ *
+ * @module Metric/NeedlemanWunsch
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { MetricInput, MetricOptions, MetricCompute } from '../utils/Types';
+import { Metric } from './Metric';
+export interface NeedlemanRaw {
+    score: number;
+    denum: number;
+}
+/**
+ * NeedlemanWunschDistance class extends the Metric class to implement the Needleman-Wunsch algorithm.
+ */
+export declare class NeedlemanWunschDistance extends Metric<NeedlemanRaw> {
+    /**
+     * Constructor for the NeedlemanWunsch class.
+     *
+     * Initializes the Needleman-Wunsch metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a: MetricInput, b: MetricInput, opt?: MetricOptions);
+    /**
+     * Calculates the Needleman-Wunsch global alignment score between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<NeedlemanRaw>} - Object containing the similarity result and raw score
+     */
+    protected compute(a: string, b: string, m: number, n: number, maxLen: number): MetricCompute<NeedlemanRaw>;
+}

package/dist/types/metric/SmithWaterman.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Smith-Waterman Algorithm
+ * src/metric/SmithWaterman.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Smith%E2%80%93Waterman_algorithm
+ *
+ * The Smith-Waterman algorithm performs local alignment, finding the best matching
+ * subsequence between two strings. It is commonly used in bioinformatics for local
+ * sequence alignment. Instead of looking at the entire sequence, the Smith–Waterman
+ * algorithm compares segments of all possible lengths and optimizes the similarity
+ * measure.
+ *
+ * @module Metric/SmithWatermanDistance
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { MetricInput, MetricOptions, MetricCompute } from '../utils/Types';
+import { Metric } from './Metric';
+export interface SmithWatermanRaw {
+    score: number;
+    denum: number;
+}
+/**
+ * SmithWatermanDistance class extends the Metric class to implement the Smith-Waterman algorithm.
+ */
+export declare class SmithWatermanDistance extends Metric<SmithWatermanRaw> {
+    /**
+     * Constructor for the SmithWaterman class.
+     *
+     * Initializes the Smith-Waterman metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a: MetricInput, b: MetricInput, opt?: MetricOptions);
+    /**
+     * Calculates the Smith-Waterman local alignment score between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @return {MetricCompute<SmithWatermanRaw>} - Object containing the similarity result and raw score
+     */
+    protected compute(a: string, b: string, m: number, n: number): MetricCompute<SmithWatermanRaw>;
+}

package/dist/types/metric/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Metric Registry Loader
+ * src/metric/index.ts
+ *
+ * This module serves as the central loader and registry for all string similarity metrics
+ * available in the CmpStr library. It ensures that all metric implementations are
+ * registered with the MetricRegistry and available for use throughout the application.
+ *
+ * Each metric algorithm (such as Levenshtein, Jaccard, Dice-Sørensen, etc.) is defined
+ * in its own module and is automatically registered with the MetricRegistry upon import.
+ * This design allows for easy extensibility: new metrics can be added simply by creating
+ * a new module and importing it here. The registry pattern enables dynamic lookup,
+ * instantiation, and management of all available metrics at runtime.
+ *
+ * Features:
+ *  - Centralized registration of all built-in string similarity metrics
+ *  - Automatic registration via side-effect imports
+ *  - Extensible: custom metrics can be registered at runtime via the MetricRegistry API
+ *  - Consistent interface for accessing, listing, and managing metrics
+ *  - Ensures that all metrics are available for use in the CmpStr API and utilities
+ *
+ * Native implemented metrics are highly optimized for performance and efficiency,
+ * providing fast and reliable string similarity calculations. They will use CmpStr's
+ * pooling system to manage resources effectively, ensuring minimal overhead
+ * and maximum performance.
+ *
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import './Cosine';
+import './DamerauLevenshtein';
+import './DiceSorensen';
+import './Hamming';
+import './Jaccard';
+import './JaroWinkler';
+import './LCS';
+import './Levenshtein';
+import './NeedlemanWunsch';
+import './qGram';
+import './SmithWaterman';
+export { MetricRegistry, Metric, MetricCls } from './Metric';

package/dist/types/metric/qGram.d.ts

@@ -0,0 +1,56 @@
+/**
+ * q-Gram Similarity
+ * src/metric/QGram.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Q-gram
+ *
+ * Q-gram similarity is a string-matching algorithm that compares two strings by
+ * breaking them into substrings (q-grams) of length Q. The similarity is computed
+ * as the size of the intersection of q-gram sets divided by the size of the larger
+ * set.
+ *
+ * This metric is widely used in approximate string matching, information retrieval,
+ * and computational linguistics.
+ *
+ * @module Metric/QGramSimilarity
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { MetricInput, MetricOptions, MetricCompute } from '../utils/Types';
+import { Metric } from './Metric';
+export interface QGramRaw {
+    intersection: number;
+    size: number;
+}
+/**
+ * QGramSimilarity class extends the Metric class to implement the q-Gram similarity algorithm.
+ */
+export declare class QGramSimilarity extends Metric<QGramRaw> {
+    /**
+     * Constructor for the QGramSimilarity class.
+     *
+     * Initializes the q-Gram similarity metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a: MetricInput, b: MetricInput, opt?: MetricOptions);
+    /**
+     * Converts a string into a set of q-grams (substrings of length q).
+     *
+     * @param {string} str - The input string
+     * @param {number} q - The length of each q-gram
+     * @return {Set<string>} - Set of q-grams
+     */
+    private _qGrams;
+    /**
+     * Calculates the q-Gram similarity between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @return {MetricCompute<QGramRaw>} - Object containing the similarity result and raw values
+     */
+    protected compute(a: string, b: string): MetricCompute<QGramRaw>;
+}

package/dist/types/phonetic/Cologne.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Cologne Phonetic Algorithm
+ * src/phonetic/Cologne.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Cologne_phonetics
+ *
+ * Cologne phonetics, also known as `Kölner Phonetik` or the `Cologne process`,
+ * is a phonetic algorithm that assigns a sequence of digits, referred to as the
+ * phonetic code, to words. The purpose of this method is to ensure that words
+ * with identical sounds receive the same code. This algorithm can facilitate a
+ * similarity search among words.
+ *
+ * Cologne phonetics is associated with the well-known Soundex phonetic algorithm,
+ * yet it is specifically optimized for the German language. This algorithm was
+ * introduced by Hans Joachim Postel in 1969.
+ *
+ * The Cologne phonetic algorithm works by mapping letters to digits, ignoring
+ * certain letters, and applying specific rules to handle character combinations.
+ *
+ * @module Phonetic/Cologne
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { PhoneticOptions } from '../utils/Types';
+import { Phonetic } from './Phonetic';
+/**
+ * Cologne class extends the Phonetic class to implement the Cologne phonetic algorithm.
+ */
+export declare class Cologne extends Phonetic {
+    protected static default: PhoneticOptions;
+    /**
+     * Constructor for the Cologne class.
+     *
+     * Initializes the Cologne phonetic algorithm with the mapping and options.
+     *
+     * @param {PhoneticOptions} [opt] - Options for the Cologne phonetic algorithm
+     */
+    constructor(opt?: PhoneticOptions);
+    /**
+     * Adjusts the phonetic code by removing all '0's except the first character.
+     *
+     * @param {string} code - The phonetic code to adjust
+     * @returns {string} - The adjusted phonetic code
+     */
+    protected adjustCode(code: string): string;
+}

package/dist/types/phonetic/Metaphone.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Metaphone Phonetic Algorithm
+ * src/phonetic/Metaphone.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Metaphone
+ *
+ * Metaphone is a phonetic algorithm for indexing words by their English pronunciation.
+ * It encodes words into a string of consonant symbols, allowing for the comparison of
+ * words based on their pronunciation rather than their spelling. Metaphone is more
+ * accurate than Soundex for English and is widely used in search, spell-checking,
+ * and fuzzy matching.
+ *
+ * This implementation uses a mapping and a comprehensive ruleset to efficiently
+ * transform input words into their Metaphone code. The algorithm drops or transforms
+ * letters according to context-sensitive rules, and only retains vowels at the start.
+ *
+ * @module Phonetic/Metaphone
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { PhoneticOptions } from '../utils/Types';
+import { Phonetic } from './Phonetic';
+/**
+ * Metaphone class extends the Phonetic class to implement the Metaphone phonetic algorithm.
+ */
+export declare class Metaphone extends Phonetic {
+    protected static default: PhoneticOptions;
+    /**
+     * Constructor for the Metaphone class.
+     *
+     * Initializes the Metaphone phonetic algorithm with the mapping and options.
+     *
+     * @param {PhoneticOptions} [opt] - Options for the Metaphone phonetic algorithm
+     */
+    constructor(opt?: PhoneticOptions);
+    /**
+     * Generates the Metaphone code for a given word.
+     *
+     * @param {string} word - The input word to be converted into a Metaphone code
+     * @returns {string} - The generated Metaphone code
+     */
+    protected encode(word: string): string;
+    /**
+     * Adjusts the Metaphone code by removing vowels except for the first letter.
+     *
+     * @param {string} code - The Metaphone code to be adjusted
+     * @returns {string} - The adjusted Metaphone code
+     */
+    protected adjustCode(code: string): string;
+}