Asynchronous API

For scenarios involving large datasets, high-latency metrics, or deferred computation (e.g., via Web Workers or remote metric services), CmpStr provides a fully asynchronous API. All asynchronous methods mirror the synchronous core API in naming, parameters, and return structures — with the sole difference that results are returned as Promise objects.

Asynchronous comparison is particularly useful in performance-sensitive or UI-bound environments, as well as when chaining computations across I/O boundaries without blocking the main execution flow.

Instantiation and Options

Instances are created in the same way as with the synchronous API:

const cmpAsync = CmpStrAsync.create( options? );

All configuration and option management methods (setOptions, mergeOptions, setOption, getOptions, etc.) are inherited from CmpStr and behave identically. Instance-level options can be overridden per call without affecting global state.

Asynchronous Methods

Below is the complete set of methods provided by the asynchronous CmpStr API. All methods return Promise objects and are intended to be used with await or standard promise chaining.

Single and Pairwise Comparison

• testAsync ( a: string, b: string, opt? ) : Promise< ResultLike >
  Asynchronously compares two strings and returns a structured comparison result. Supports optional per-call configuration overrides.

• compareAsync ( a: string, b: string, opt? ) : Promise< number >
  Performs the same comparison as testAsync but resolves to the normalized similarity score (0..1) only.

• pairsAsync ( a: MetricInput, b: MetricInput, opt? ) : Promise< BatchResultLike >
  Performs index-wise pair comparisons between a[i] and b[i]. Both input arrays must have the same length.

Batch and Sorted Comparison

• batchTestAsync ( a: MetricInput, b: MetricInput, opt? ) : Promise< BatchResultLike >
  Performs a full cross-comparison of all elements in a against all elements in b (a × b).

• batchSortedAsync ( a: MetricInput, b: MetricInput, dir = 'desc', opt? ) : Promise< BatchResultLike >
  Identical to batchTestAsync, but resolves to a result set sorted by similarity score in ascending or descending order.

Threshold and Top-N Queries

• matchAsync ( a: MetricInput, b: MetricInput, threshold: number, opt? ) : Promise< BatchResultLike >
  Returns only those comparisons whose similarity score is greater than or equal to the specified threshold.

• closestAsync ( a: MetricInput, b: MetricInput, n = 1, opt? ) : Promise< BatchResultLike >
  Resolves to the n most similar matches with the highest scores.

• furthestAsync ( a: MetricInput, b: MetricInput, n = 1, opt? ) : Promise< BatchResultLike >
  Resolves to the n least similar matches with the lowest scores.

Matrix Computation

• matrixAsync ( input: string[], opt? ) : Promise< number[][] >
  Asynchronously computes a square similarity matrix for all pairwise combinations of the input values.

Phonetic and Text Utilities

• phoneticIndexAsync ( input: string, algo?: string, opt?: PhoneticOptions ) : Promise< string >
  Asynchronous method for determining phonetic indexes of given strings.

• searchAsync ( needle: string, haystack: string[], flags?: NormalizeFlags, processors?: CmpStrProcessors ) : Promise< string[] >
  Performs an asynchronous filtered and normalized substring search across the haystack array.

Structured Data

• structuredLookupAsync ( query: string, data: T[], key: keyof T, opt?: StructuredDataOptions ) : Promise< StructuredResultLike >
  Performs an asynchronous batch comparison against structured data by extracting a specific property and returning results with original objects attached.

• structuredMatchAsync ( query: string, data: T[], key: keyof T, threshold: number, opt?: StructuredDataOptions ) : Promise< StructuredResultLike >
  Performs an asynchronous batch comparison and returns only results above the threshold for structured data.

• structuredClosestAsync ( query: string, data: T[], key: keyof T, n: number = 1, opt?: StructuredDataOptions ) : Promise< StructuredResultLike >
  Returns the n closest matches from a batch comparison of structured data.

• structuredFurthestAsync ( query: string, data: T[], key: keyof T, n: number = 1, opt?: StructuredDataOptions ) : Promise< StructuredResultLike >
  Returns the n furthest matches from a batch comparison of structured data.

• structuredPairsAsync ( data: T[], key: keyof T, other: O[], otherKey: keyof O, opt?: StructuredDataOptions ) : Promise< StructuredResultLike >
  Performs an asynchronous pairwise comparison between two (different) arrays of structured objects by extracting specific properties and returning results with original objects attached.

Example Usage

import { CmpStrAsync } from 'cmpstr';

const cmp = CmpStrAsync.create( { metric: 'levenshtein', flags: 'i' } );

const result = await cmp.testAsync( 'kITTen', 'Sitting' );
// result: { source: 'kITTen', target: 'Sitting', match: 0.57142… }

const batch = await cmp.batchTestAsync( [ 'hello', 'Hallo' ], [ 'hey', 'hola' ] );
// batch: [ { source: 'hello', target: 'hey', match: 0.4 }, … ]

const matrix = await cmp.matrixAsync( [ 'foo', 'bar', 'baz' ] );
// matrix:  [ [ 1, 0, 0 ], [ 0, 1, 0.666… ], [ 0, 0.666…, 1 ] ]

Notes

• All configuration and option handling is inherited from the synchrounous API.
• All methods return Promise objects.
• The API is designed for use with async / await as well as .then() chaining.
• Method semantics and result structures are identical to their synchronous counterparts.

For further details, refer to the Wiki sections on similarity metrics, phonetic algorithms, normalization and filtering, and advanced extension points.