search-fuzzy/fuzzy/fuzzy.d.ts

A simple fuzzy search algorithm that uses the Levenshtein distance algorithm to find the closest match to a given string.

/**
 * Defines the available credential options for making API requests.
 * @property {string} "omit" -
 * @property {string} "same-origin" -
 * @property {string} "include" -
 */
declare enum Credentials {
    Omit = "omit",
    SameOrigin = "same-origin",
    Include = "include"
}
/**
 * Defines the options for configuring a fuzzy search operation.
 * @property {number} [threshold]  - Default 0.6, The minimum score threshold for a result to be included.
 * @property {number} [maxResults] - Default 10, The maximum number of results to return.
 * @property {boolean} [ignoreCase] -  Default false, Whether to ignore case sensitivity when matching.
 * @property {boolean} [ignoreDiacritics] - Default false, Whether to ignore diacritical marks when matching.
 * @property {boolean} [ignorePunctuation] - Default false, Whether to ignore punctuation when matching.
 * @property {boolean} [ignoreWhitespace] - Default false, Whether to ignore whitespace when matching.
 * @property {boolean} [ignoreNumbers] -Default false, Whether to ignore numbers when matching.
 * @property {boolean} [ignoreSymbols] - Default false, Whether to ignore symbols when matching.
 * @property {boolean} [ignoreAccents] - Default false, Whether to ignore accents when matching.
 * @property {boolean} [ignoreCaseSensitive] - Default false, Whether to ignore case sensitivity when matching.
 * @property {boolean} [ignoreDiacriticSensitive] - Default false, Whether to ignore diacritical marks when matching.
 * @property {boolean} [ignorePunctuationSensitive] - Default false, Whether to ignore punctuation when matching.
 * @property {boolean} [ignoreWhitespaceSensitive] - Default false, Whether to ignore whitespace when matching.
 * @property {boolean} [ignoreNumbersSensitive] - Default false, Whether to ignore numbers when matching.
 * @property {boolean} [ignoreSymbolsSensitive] - Default false, Whether to ignore symbols when matching.
 * @property {boolean} [ignoreAccentsSensitive] - Default false, Whether to ignore accents when matching.
 * @property {boolean} [ignoreCaseSensitiveSensitive] - Default false, Whether to ignore case sensitivity when matching.
 * @property {boolean} [ignoreDiacriticSensitiveSensitive] - Default false, Whether to ignore diacritical marks when matching.
 * @property {boolean} [ignorePunctuationSensitiveSensitive] - Default false, Whether to ignore punctuation when matching.
 * @property {boolean} [ignoreWhitespaceSensitiveSensitive] - Default false, Whether to ignore whitespace when matching.
 * @property {boolean} [ignoreNumbersSensitiveSensitive] - Default false, Whether to ignore numbers when matching.
 * @property {boolean} [ignoreSymbolsSensitiveSensitive] - Default false, Whether to ignore symbols when matching.
 * @property {boolean} [ignoreAccentsSensitiveSensitive] - Default false, Whether to ignore accents when matching.
 * @property {boolean} [ignoreCaseSensitiveSensitiveSensitive] - Default false, Whether to ignore case sensitivity when matching.
 * @property {boolean} [ignoreDiacriticSensitiveSensitiveSensitive] - Default false, Whether to ignore diacritical marks when matching.
 
**/
interface FuzzySearchOptions {
    threshold?: number;
    maxResults?: number;
    ignoreCase?: boolean;
    ignoreDiacritics?: boolean;
    ignorePunctuation?: boolean;
    ignoreWhitespace?: boolean;
    ignoreNumbers?: boolean;
    ignoreSymbols?: boolean;
    ignoreAccents?: boolean;
    ignoreCaseSensitive?: boolean;
    ignoreDiacriticSensitive?: boolean;
    ignorePunctuationSensitive?: boolean;
    ignoreWhitespaceSensitive?: boolean;
    ignoreNumbersSensitive?: boolean;
    ignoreSymbolsSensitive?: boolean;
    ignoreAccentsSensitive?: boolean;
    ignoreCaseSensitiveSensitive?: boolean;
    ignoreDiacriticSensitiveSensitive?: boolean;
    ignorePunctuationSensitiveSensitive?: boolean;
    ignoreWhitespaceSensitiveSensitive?: boolean;
    ignoreNumbersSensitiveSensitive?: boolean;
    ignoreSymbolsSensitiveSensitive?: boolean;
    ignoreAccentsSensitiveSensitive?: boolean;
    ignoreCaseSensitiveSensitiveSensitive?: boolean;
    ignoreDiacriticSensitiveSensitiveSensitive?: boolean;
}
/**
 * Represents an array of items of type `T`.
 */
type Data<T> = T[];
/**
 * Represents an array of keys of type `T`.
 */
type Fields<T> = (keyof T)[];
/**
 * Represents the configuration options for an API request.
 *
 * @property {boolean} [useApi] - Whether to use the API or not.
 * @property {string} url - The URL for the HTTP request.
 * @property {string} token - The authentication token.
 * @property {Credentials} [credentials] - The credentials for the request.
 * @property {Record<string, string>} [headers] - The optional headers for the request.
 * @property {boolean} [keepalive] - Whether to keep the connection alive.
 * @property {any} [body] - The optional request body.
 * @property {Record<string, string>} [params] - The optional query parameters.
 *
 */
interface ApiConfig {
    useApi?: boolean;
    url: string;
    token?: any;
    credentials?: Credentials;
    headers?: Record<string, any>;
    keepalive?: boolean;
    body?: any;
    params?: Record<string, any>;
}
/**
 * Represents a search query.
 *
 * @property {string} query - The search query string.
 */
interface Query {
    query: string;
}
/**
 * Represents the result of a fuzzy search, including the matched items and their corresponding scores.
 *
 * @template T - The type of the items in the search result.
 * @property {T[]} item - The array of items that matched the search query.
 * @property {number} score - The score indicating the relevance of the search result.
 */
interface FuzzySearchResult<T> {
    item: T[];
    score: number;
}

/**
 * Performs a fuzzy search on a dataset, potentially fetching data from an API if configured.
 * The search is based on a given query and can be customized with various options.
 *
 * @template T - The type of objects in the dataset.
 *
 * @param data - The local dataset to search through. If `apiConfig` is provided, this will be used as a fallback.
 * @param fields - The fields of each item in the dataset to be included in the search. If empty, all fields will be searched.
 * @param query - The search query to match against the dataset. This contains the search string and any additional configuration.
 * @param apiConfig - Optional configuration for fetching data from an API. Includes details such as URL, method, headers, and parameters.
 * @param options - Optional settings for the fuzzy search, such as maximum results or any other custom options.
 *
 * @returns A Promise that resolves to an array of objects from the dataset that match the query, sorted by relevance.
 *
 * @throws Error if there is an issue with fetching data from the API or if data is empty and no API is provided.
 */
declare function fuzzySearch<T extends object>(data: Data<T>, fields: Fields<T>, query: Query, apiConfig?: ApiConfig, options?: FuzzySearchOptions): Promise<T[]>;

export { type ApiConfig, Credentials, type Data, type Fields, type FuzzySearchOptions, type FuzzySearchResult, type Query, fuzzySearch };