nhb-toolbox/dist/dts/array/Finder.d.ts

A versatile collection of smart, efficient, and reusable utility functions and classes for everyday development needs.

import type { OwnKeys } from '../types/index';
import type { FindOptions } from './types';
type KeySelector<T> = Extract<OwnKeys<T>, string | number> | ((item: T) => string | number);
/**
 * The `Finder` class performs optimized searching on arrays.
 * It supports binary search, fuzzy search, and smart caching with TTL.
 */
export declare class Finder<T> {
    #private;
    /**
     * * Creates a new `Finder` instance with a static array of items.
     *
     * @param data An array of items to initialize the search dataset.
     * @param ttl Optional time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.
     */
    constructor(data: T[], ttl?: number);
    /**
     * * Creates a new `Finder` instance with a lazy-evaluated item provider.
     *
     * @param cb A function returning an array of items to initialize the search dataset.
     * @param ttl Time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.
     */
    constructor(cb: () => T[], ttl?: number);
    /**
     * @instance Clears cache globally or for a specific key.
     * @param key Optional key to clear only a specific cache entry.
     */
    clearCache(key?: string): void;
    /**
     * @instance Finds all items that match the provided matcher using optional caching or fuzzy logic.
     * @param matcher The value to match against.
     * @param keySelector Property key or selector function.
     * @param options Optional settings for search behavior and source list.
     */
    findAll(matcher: string | number, keySelector: KeySelector<T>, options?: FindOptions<T>): T[];
    /**
     * @instance Finds first matching item that matches the provided matcher using optional caching or fuzzy logic.
     * @param matcher The value to match.
     * @param keySelector Property key or selector function.
     * @param options Optional behavior flags and item source.
     */
    findOne(matcher: string | number, keySelector: KeySelector<T>, options?: FindOptions<T>): T | undefined;
    /**
     * @instance Asynchronous variant of `findAll` that accepts a promise-based data supplier.
     * @param supplier Async function resolving the items list.
     * @param matcher The value to match.
     * @param keySelector Property key or selector function.
     * @param options Optional settings for search behavior and cache.
     */
    findAllAsync(supplier: () => Promise<T[]>, matcher: string | number, keySelector: KeySelector<T>, options?: Omit<FindOptions<T>, 'items'>): Promise<T[]>;
    /**
     * @instance Asynchronous variant of `findOne`.
     * @param supplier Async function resolving the items list.
     * @param matcher The value to match.
     * @param keySelector Property key or selector function.
     * @param options Optional settings for behavior and cache.
     */
    findOneAsync(supplier: () => Promise<T[]>, matcher: string | number, keySelector: KeySelector<T>, options?: Omit<FindOptions<T>, 'items'>): Promise<T | undefined>;
    /**
     * @instance Performs a binary search on a sorted array using a custom key selector.
     *
     * @param sorted - The sorted array of items to search.
     * @param matcher - The value to search for.
     * @param keySelector - A function that extracts the comparable key from each item.
     * @param caseInsensitive - Whether to compare string keys ignoring case.
     * @returns The first matching item if found; otherwise, undefined.
     */
    binarySearch(sorted: T[], matcher: string | number, keySelector: (item: T) => string | number, caseInsensitive: boolean): T | undefined;
    /**
     * @instance Performs a fuzzy search on an array by matching characters in sequence.
     *
     * @param array - The array of items to search.
     * @param matcher - The fuzzy search string to match against.
     * @param keySelector - A function that extracts the key to search from each item.
     * @param caseInsensitive - Whether to compare ignoring case for string values.
     * @returns The first fuzzy-matching item if found; otherwise, undefined.
     */
    fuzzySearch(array: T[], matcher: string, keySelector: (item: T) => string | number, caseInsensitive: boolean): T | undefined;
}
export {};
//# sourceMappingURL=Finder.d.ts.map