cmpstr
Version:
CmpStr is a lightweight, fast and well performing package for calculating string similarity
310 lines (309 loc) • 16.3 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
* - Async structured data comparison by extracting object properties
* - Full compatibility with the synchronous CmpStr API
* - Designed for large-scale, high-performance, and server-side applications
*
* @module Main
* @name CmpStrAsync
* @author Paul Köhler (komed3)
* @license MIT
*/
import type { BatchResultLike, CmpStrOptions, CmpStrProcessors, CmpStrResult, FilterHooks, MetricInput, MetricMode, MetricRaw, MetricResult, NormalizeFlags, PhoneticOptions, ResultLike, StructuredDataOptions, StructuredResultLike } 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 {FilterHooks} [hook='input'] - The filter hook
* @returns {Promise< MetricInput >} - The filtered string(s)
*/
protected filterAsync(input: MetricInput, hook: FilterHooks): 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
* @throws {CmpStrInternalError} - If the computation fails due to internal errors
*/
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 ResultLike<R> = any>(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 BatchResultLike<R> = any>(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 BatchResultLike<R> = any>(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.
*
* Input arrays needs of the same length to perform pairwise comparison,
* otherwise the method will throw an error.
*
* @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 pairwise metric results
*/
pairsAsync<T extends BatchResultLike<R> = any>(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 BatchResultLike<R> = any>(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 BatchResultLike<R> = any>(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 BatchResultLike<R> = any>(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>;
/**
* ================================================================================-
* Public asynchronous methods for structured data comparison
* ================================================================================-
*
* These methods provide asynchronous interfaces for comparing arrays of
* structured objects by extracting and comparing specific properties.
*/
/**
* Asynchronously performs a batch comparison against structured data by extracting
* a specific property and returning results with original objects attached.
*
* @template T - The type of objects in the data array
* @param {string} query - The query string to compare against
* @param {T[]} data - The array of structured objects
* @param {keyof T} key - The property key to extract for comparison
* @param {StructuredDataOptions} [opt] - Optional lookup options
* @returns {Promise< StructuredResultLike< T, R > >} - Async batch results with original objects
*/
structuredLookupAsync<T = any>(query: string, data: T[], key: keyof T, opt?: StructuredDataOptions): Promise<StructuredResultLike<T, R>>;
/**
* Asynchronously performs a batch comparison and returns only results above
* the threshold for structured data.
*
* @template T - The type of objects in the data array
* @param {string} query - The query string to compare against
* @param {T[]} data - The array of structured objects
* @param {keyof T} key - The property key to extract for comparison
* @param {number} threshold - The similarity threshold (0..1)
* @param {StructuredDataLookupOptions} [opt] - Optional lookup options
* @returns {Promise< StructuredResultLike< T, R > >} - Async filtered batch results
*/
structuredMatchAsync<T = any>(query: string, data: T[], key: keyof T, threshold: number, opt?: StructuredDataOptions): Promise<StructuredResultLike<T, R>>;
/**
* Asynchronously returns the n closest matches from a batch comparison
* of structured data.
*
* @template T - The type of objects in the data array
* @param {string} query - The query string to compare against
* @param {T[]} data - The array of structured objects
* @param {keyof T} key - The property key to extract for comparison
* @param {number} [n=1] - Number of closest matches
* @param {StructuredDataOptions} [opt] - Optional lookup options
* @returns {Promise< StructuredResultLike< T, R > >} - Async closest matches
*/
structuredClosestAsync<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): Promise<StructuredResultLike<T, R>>;
/**
* Asynchronously returns the n furthest matches from a batch comparison
* of structured data.
*
* @template T - The type of objects in the data array
* @param {string} query - The query string to compare against
* @param {T[]} data - The array of structured objects
* @param {keyof T} key - The property key to extract for comparison
* @param {number} [n=1] - Number of furthest matches
* @param {StructuredDataOptions} [opt] - Optional lookup options
* @returns {Promise< StructuredResultLike< T, R > >} - Async furthest matches
*/
structuredFurthestAsync<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): Promise<StructuredResultLike<T, R>>;
/**
* Asynchronously performs a pairwise comparison between two arrays of structured objects
* by extracting specific properties and returning results with original objects attached.
*
* @template T - The type of objects in the arrays
* @template O - The type of objects in the other array
* @param {T[]} data - The array of structured objects
* @param {keyof T} key - The property key to extract for comparison
* @param {T[]} other - The other array of structured objects
* @param {keyof T} otherKey - The property key to extract from other array
* @param {StructuredDataOptions} [opt] - Optional lookup options
* @returns {Promise< StructuredResultLike< T, R > >} - Async pairwise results with original objects
*/
structuredPairsAsync<T = any, O = any>(data: T[], key: keyof T, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): Promise<StructuredResultLike<T, R>>;
}