cmpstr
Version:
CmpStr is a lightweight, fast and well performing package for calculating string similarity
234 lines (233 loc) • 11.7 kB
TypeScript
/**
* CmpStrAsync Asynchronous API
* src/CmpStrAsync.ts
*
* The CmpStrAsync class provides a fully asynchronous, Promise-based interface for
* advanced string comparison, similarity measurement, phonetic indexing, filtering
* and normalization. It extends the CmpStr class and overrides all relevant methods
* to support non-blocking, scalable, and I/O-friendly workloads.
*
* Features:
* - Asynchronous normalization, filtering, and metric computation
* - Async batch, pairwise, and single string comparison with detailed results
* - Async phonetic indexing and phonetic-aware search and comparison
* - Full compatibility with the synchronous CmpStr API
* - Designed for large-scale, high-performance, and server-side applications
*
* @module CmpStrAsync
* @author Paul Köhler (komed3)
* @license MIT
*/
import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch } from './utils/Types';
import { CmpStr } from './CmpStr';
/**
* The CmpStrAsync class provides a fully asynchronous API for string comparison,
* phonetic indexing, filtering and normalization.
*
* @template R - The type of the metric result, defaults to MetricRaw
*/
export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
/**
* --------------------------------------------------------------------------------
* Instanciate the CmpStrAsync class
* --------------------------------------------------------------------------------
*
* Methods to create a new CmpStrAsync instance with the given options.
* Using the static `create` method is recommended to ensure proper instantiation.
*/
/**
* Creates a new CmpStrAsync instance with the given options.
*
* @param {string|CmpStrOptions} [opt] - Optional serialized or options object
* @returns {CmpStrAsync<R>} - A new CmpStrAsync instance
*/
static create<R = MetricRaw>(opt?: string | CmpStrOptions): CmpStrAsync<R>;
/**
* Creates a new CmpStrAsync instance calliing the super constructor.
*
* @param {string|CmpStrOptions} [opt] - Optional serialized or options object
*/
protected constructor(opt?: string | CmpStrOptions);
/**
* ---------------------------------------------------------------------------------
* Protected asynchronously utility methods for internal use
* ---------------------------------------------------------------------------------
*
* These methods provide asynchronous normalization, filtering, and metric
* computation capabilities, allowing for non-blocking operations.
*/
/**
* Asynchronously normalizes the input string or array using the configured or provided flags.
*
* @param {MetricInput} input - The input string or array
* @param {NormalizeFlags} [flags] - Normalization flags
* @returns {Promise<MetricInput>} - The normalized input
*/
protected normalizeAsync(input: MetricInput, flags?: NormalizeFlags): Promise<MetricInput>;
/**
* Asynchronously applies all active filters to the input string or array.
*
* @param {MetricInput} input - The input string or array
* @param {string} [hook='input'] - The filter hook
* @returns {Promise<MetricInput>} - The filtered string(s)
*/
protected filterAsync(input: MetricInput, hook: string): Promise<MetricInput>;
/**
* Asynchronously prepares the input by normalizing and filtering.
*
* @param {MetricInput} [input] - The input string or array
* @param {CmpStrOptions} [opt] - Optional options to use
* @returns {Promise<MetricInput>} - The prepared input
*/
protected prepareAsync(input: MetricInput, opt?: CmpStrOptions): Promise<MetricInput>;
/**
* Asynchronously computes the phonetic index for the given input using
* the specified phonetic algorithm.
*
* @param {MetricInput} input - The input string or array
* @param {{ algo: string, opt?: PhoneticOptions }} options - The phonetic algorithm and options
* @returns {Promise<MetricInput>} - The phonetic index for the given input
*/
protected indexAsync(input: MetricInput, { algo, opt }: {
algo: string;
opt?: PhoneticOptions;
}): Promise<MetricInput>;
/**
* Asynchronously computes the metric result for the given inputs, applying
* normalization and filtering as configured.
*
* @template T - The type of the metric result
* @param {MetricInput} a - The first input string or array
* @param {MetricInput} b - The second input string or array
* @param {CmpStrOptions} [opt] - Optional options to use
* @param {MetricMode} [mode='single'] - The metric mode to use
* @param {boolean} [raw=false] - Whether to return raw results
* @param {boolean} [skip=false] - Whether to skip normalization and filtering
* @returns {Promise<T>} - The computed metric result
*/
protected computeAsync<T extends MetricResult<R> | CmpStrResult | CmpStrResult[]>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions, mode?: MetricMode, raw?: boolean, skip?: boolean): Promise<T>;
/**
* ---------------------------------------------------------------------------------
* Public asynchronously core methods for string comparison
* ---------------------------------------------------------------------------------
*
* These methods provide the asynchronous core functionality for string comparison,
* phonetic indexing and text search, allowing for non-blocking operations.
*/
/**
* Asynchronously performs a single metric comparison.
*
* @template T - The type of the metric result
* @param {string} a - The source string
* @param {string} b - The target string
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The metric result
*/
testAsync<T extends CmpStrResult | MetricResultSingle<R>>(a: string, b: string, opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously performs a single metric comparison returning the numeric score.
*
* @param {string} a - The source string
* @param {string} b - The target string
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<number>} - The similarity score (0..1)
*/
compareAsync(a: string, b: string, opt?: CmpStrOptions): Promise<number>;
/**
* Asynchronously performs a batch metric comparison between source and target
* strings or array of strings.
*
* @template T - The type of the metric result
* @param {MetricInput} a - The source string or array of strings
* @param {MetricInput} b - The target string or array of strings
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The batch metric results
*/
batchTestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously performs a batch metric comparison and returns results sorted by score.
*
* @template T - The type of the metric result
* @param {MetricInput} a - The source string or array of strings
* @param {MetricInput} b - The target string or array of strings
* @param {'desc'|'asc'} [dir='desc'] - Sort direction (desc, asc)
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The sorted batch results
*/
batchSortedAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously performs a pairwise metric comparison between source and target
* strings or array of strings.
*
* @template T - The type of the metric result
* Input arrays needs of the same length to perform pairwise comparison,
* otherwise the method will throw an error.
*
* @param {MetricInput} a - The source string or array of strings
* @param {MetricInput} b - The target string or array of strings
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The pairwise metric results
*/
pairsAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously performs a batch comparison and returns only results above the threshold.
*
* @template T - The type of the metric result
* @param {MetricInput} a - The source string or array of strings
* @param {MetricInput} b - The target string or array of strings
* @param {number} threshold - The similarity threshold (0..1)
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The filtered batch results
*/
matchAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously returns the n closest matches from a batch comparison.
*
* @template T - The type of the metric result
* @param {MetricInput} a - The source string or array of strings
* @param {MetricInput} b - The target string or array of strings
* @param {number} [n=1] - Number of closest matches
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The closest matches
*/
closestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously returns the n furthest matches from a batch comparison.
*
* @template T - The type of the metric result
* @param {MetricInput} a - The source string or array of strings
* @param {MetricInput} b - The target string or array of strings
* @param {number} [n=1] - Number of furthest matches
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<T>} - The furthest matches
*/
furthestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
/**
* Asynchronously performs a normalized and filtered substring search.
*
* @param {string} needle - The search string
* @param {string[]} haystack - The array to search in
* @param {NormalizeFlags} [flags] - Normalization flags
* @param {CmpStrProcessors} [processors] - Pre-processors to apply
* @returns {Promise<string[]>} - Array of matching entries
*/
searchAsync(needle: string, haystack: string[], flags?: NormalizeFlags, processors?: CmpStrProcessors): Promise<string[]>;
/**
* Asynchronously computes a similarity matrix for the given input array.
*
* @param {string[]} input - The input array
* @param {CmpStrOptions} [opt] - Optional options
* @returns {Promise<number[][]>} - The similarity matrix
*/
matrixAsync(input: string[], opt?: CmpStrOptions): Promise<number[][]>;
/**
* Asynchronously computes the phonetic index for a string using the
* configured or given algorithm.
*
* @param {string} [input] - The input string
* @param {string} [algo] - The phonetic algorithm to use
* @param {PhoneticOptions} [opt] - Optional phonetic options
* @returns {Promise<string>} - The phonetic index as a string
*/
phoneticIndexAsync(input: string, algo?: string, opt?: PhoneticOptions): Promise<string>;
}