search-client/es/SearchClient.d.ts

Javascript library for executing searches in the Haive search-index via the SearchManager REST interface.

import { AuthToken, IAuthentication } from './Authentication';
import { Autocomplete } from './Autocomplete';
import { Categorize } from './Categorize';
import { CategorizationType, DateSpecification, Fetch, Filter, IQuery, OrderBy, SearchType } from './Common';
import { ICategory, IGroup } from './Data';
import { Find } from './Find';
import { ISettings } from './Settings';
export * from './Authentication';
export * from './Autocomplete';
export * from './Categorize';
export * from './Common';
export * from './Data';
export * from './Find';
export * from './Settings';
/**
 * This is the "main class" of this package. Please read the <a href="https://the-haive.github.io/search-client/">getting-started section</a>"
 * for a proper introduction.
 *
 * The SearchClient manages a range of other services:
 *   * Authentication,
 *   * Autocomplete,
 *   * Categorize
 *   * Find
 *
 * Each of the above services can be used independently, but it is highly recommended to use the SearchClient instead.
 *
 * The SearchClient allows you to have an advanced search with minimal effort in regards to setup and logics. instead
 * of having to write all the logics yourself the SearchClient exposes the following methods for managing your search:
 *   1. Configure callbacks in your settings-object that you pass to the SearchClient.
 *   2. Configure triggers to define when to do server-lookups and not (if you need to deviate from the defaults)
 *   3. Set query-values real-time (queryText, filters, date-ranges, etc.)
 *   4. Receive autocomplete-suggestions, matches and categories in your callback handlers when the data is available.
 *
 * What happens is that any query-changes that arrive are checked in regards to trigger-settings. If they are to trigger
 * and a callback has been set up then the server is requested and when the data is received it is sent to the callback
 * registered in the settings-object.
 */
export declare class SearchClient implements AuthToken {
    /**
     * Holds a reference to the setup Authentication service.
     */
    authentication: IAuthentication;
    /**
     * Holds a reference to the setup Autocomplete service.
     */
    autocomplete: Autocomplete;
    /**
     * Holds a reference to the setup Categorize service.
     */
    categorize: Categorize;
    /**
     * Holds a reference to the setup Find service.
     */
    find: Find;
    /**
     * Holds a reference to method resolving jwt access token.
     */
    tokenResolver: () => string;
    protected settings: ISettings;
    private _query;
    private _origSettings;
    private _origFetchMethod;
    /**
     * Holds a reference to the currently set authentication token.
     */
    get authenticationToken(): string;
    /**
     * Creates a SearchClient instance using the supplied settings object. Please see <a href="https://the-haive.github.io/search-client/">getting-started section</a>
     * for an introduction on how to set up the instance.
     *
     * @param settings A settings object that indicates how the search-client instance is to behave.
     */
    constructor(settings: ISettings | string, fetchMethod?: Fetch);
    /**
     * This method is typically called when the user clicks the search-button in the UI.
     *
     * For query-fields that accepts enter the default queryChangeInstantRegex catches enter.
     * When they don't take enter you will have to set up something that either catches the default enter or a user clicks
     * on a "Search"-button or similar. You can choose to use the already current query, or you can pass it in. If you
     * include the query then the internal updates are suppressed while changing the query-properties, to make sure that
     * only one update per service is made (if any of their trigger-checks returned true).
     *
     * @param query If passed in then the query object will update the internal query-object and any updates will trigger
     * (but only once). The consecutive overriding service params are ignored when this parameter has a value. If the
     * query is empty/null/undefined then the services will force an update, but allows the bool params to override this.
     * @param autocomplete Allows turning off updates for the Autocomplete service (if the service is enabled in the
     * settings). Only effective when query is not set.
     * @param categorize Allows turning off updates for the Categorize service (if the service is enabled in the settings).
     * Only effective when query is not set.
     * @param find Allows turning off updates for the Find service (if the service is enabled in the settings). Only
     * effective when query is not set.
     */
    update(query?: IQuery, autocomplete?: boolean, categorize?: boolean, find?: boolean): void;
    /**
     * This method is called when you want to force an update call to be made for the services.
     *
     * It may force an update based on the existing this.query value or you can provide a new query object to be used.
     * After having set the value the services will be called, unless they are disabled in their respective configs
     * or turned off in the params to this method.
     *
     * @param query If passed in then the query object will update the internal query-object without triggering any updates,
     * but will just after this force an update on all enabled services, that are not turned off by the consecutive params.
     * @param autocomplete Allows turning off updates for the Autocomplete service (if the service is enabled in the
     * settings).
     * @param categorize Allows turning off updates for the Categorize service (if the service is enabled in the settings).
     * @param find Allows turning off updates for the Find service (if the service is enabled in the settings).
     */
    forceUpdate(query?: IQuery, autocomplete?: boolean, categorize?: boolean, find?: boolean): void;
    /**
     * Resets the SearchClient instance (filters, queryText, categoryPresentations++) to initial values.
     */
    reset(): void;
    /**
     * Returns true if the passed argument is a filter.
     * Typically used to visually indicate that a category is also a filter.
     */
    isFilter(category: string[] | ICategory | Filter): boolean;
    /**
     * Checks whether any child-node of the given category has a filter defined for it.
     * Typically used to visually show in the tree that a child-node has an active filter.
     */
    hasChildFilter(category: string[] | ICategory): boolean;
    /**
     * Add the given filter, if it isn't already there.
     *
     * Will run trigger-checks and potentially update services.
     */
    filterAdd(filter: string[] | ICategory | Filter): boolean;
    /**
     * Remove the given filter, if it is already set.
     *
     * Will run trigger-checks and potentially update services.
     */
    filterRemove(filter: string[] | ICategory | Filter): boolean;
    /**
     * Toggle the given filter.
     *
     * Will run trigger-checks and potentially update services.
     *
     * @param filter Is either string[], Filter or Category. When string array it expects the equivalent of the Category.categoryName property, which is like this: ["Author", "Normann"].
     * @return true if the filter was added, false if it was removed.
     */
    filterToggle(filter: string[] | ICategory | Filter): boolean;
    /**
     * Toggles the expansion/collapsed state for the given group/category
     *
     * @param node The node that is to be expanded.
     * @return The new state of the node.
     */
    toggleCategoryExpansion(node: string[] | ICategory | IGroup, state?: boolean): boolean;
    /**
     * Decides whether an update should be executed or not. Typically used to temporarily turn
     * off update-execution. When turned back on the second param can be used to indicate whether
     * pending updates should be executed or not.
     *
     * **Note:** Changes deferring of updates for all components (Autocomplete, Categorize and Find).
     * Use the service properties of the SearchClient instance to control deferring for each service.
     *
     * @example Some examples:
     *
     *     // Example 1: Defer updates to avoid multiple updates:
     *     searchClient.deferUpdates(true);
     *
     *     // Example 2: Change some props that triggers may be listening for
     *     searchClient.dateFrom = { M: -1};
     *     searchClient.dateTo = { M: 0};
     *     // When calling deferUpdates with (false) the above two update-events are now executed as one instead (both value-changes are accounted for though)
     *     searchClient.deferUpdates(false);
     *
     *     // Example 3: Suppress updates (via deferUpdates):
     *     searchClient.deferUpdates(true);
     *     // Change a prop that should trigger updates
     *     searchClient.queryText = "some text";
     *     // Call deferUpdates with (false, true), to skip the pending update.
     *     searchClient.deferUpdates(false, true);
     *
     *     // Example 4: Defer update only for one service (Categorize in this sample):
     *     searchClient.categorize.deferUpdates(true);
     *
     * @param state Turns on or off deferring of updates.
     * @param skipPending Used to indicate if a pending update is to be executed or skipped when deferring
     * is turned off. The param is ignored for `state=true`. Default is false.
     */
    deferUpdates(state: boolean, skipPending?: boolean): void;
    /**
     * Find the category based on the category-name array.
     *
     * @param categoryName The category array that identifies the category.
     * @returns The Category object if found or null.
     */
    findCategory(categoryName: string[]): IGroup | ICategory | null;
    /**
     * Gets the previous page of match-results.
     * Will run trigger-checks and potentially update services.
     */
    matchPagePrev(): boolean;
    /**
     * Gets the next page of match-results (if any).
     * Will run trigger-checks and potentially update services.
     */
    matchPageNext(): boolean;
    /**
     * Gets the currently active categorizationType value.
     */
    get categorizationType(): CategorizationType;
    /**
     * Sets the currently active categorizationType.
     *
     * Will run trigger-checks and potentially update services.
     */
    set categorizationType(categorizationType: CategorizationType);
    /**
     * Gets the currently active client-id value.
     */
    get clientId(): string;
    /**
     * Sets the currently active client-id.
     *
     * Will run trigger-checks and potentially update services.
     */
    set clientId(clientId: string);
    /**
     * Gets the currently active date-from value.
     */
    get dateFrom(): DateSpecification;
    /**
     * Sets the from-date for matches to be used.
     *
     * Will run trigger-checks and potentially update services.
     */
    set dateFrom(dateFrom: DateSpecification);
    /**
     * Gets the currently active date-to value.
     */
    get dateTo(): DateSpecification;
    /**
     * Sets the to-date for matches to be used.
     *
     * Will run trigger-checks and potentially update services.
     */
    set dateTo(dateTo: DateSpecification);
    /**
     * Gets the currently active filters.
     */
    get filters(): Filter[];
    /**
     * Sets the filters to be used.
     *
     * Will run trigger-checks and potentially update services.
     */
    set filters(filters: Filter[]);
    /**
     * Gets the currently active match generateContent setting.
     */
    get matchGenerateContent(): boolean;
    /**
     * Sets whether the results should generate the content or not.
     *
     * **Note:** Requires the backend IndexManager to have the option enabled in its configuration too.
     *
     * Will run trigger-checks and potentially update services.
     */
    set matchGenerateContent(generateContent: boolean);
    /**
     * Gets the currently active match generateContentHighlights setting.
     */
    get matchGenerateContentHighlights(): boolean;
    /**
     * Sets whether the results should generate the content-highlight tags or not.
     *
     * **Note:** See the matchGenerateContent property in regards to IndexManager requirements.
     *
     * Will run trigger-checks and potentially update services.
     */
    set matchGenerateContentHighlights(generateContentHighlights: boolean);
    /**
     * Gets the currently active match grouping mode.
     */
    get matchGrouping(): boolean;
    /**
     * Sets whether the results should be grouped or not.
     *
     * **Note:** Requires the search-service to have the option enabled in it's configuration too.
     *
     * Will run trigger-checks and potentially update services.
     */
    set matchGrouping(useGrouping: boolean);
    /**
     * Gets the currently active match-page.
     */
    get matchPage(): number;
    /**
     * Sets the match-page to get.
     * Will run trigger-checks and potentially update services.
     */
    set matchPage(page: number);
    /**
     * Gets the currently active match page-size.
     */
    get matchPageSize(): number;
    /**
     * Sets the match page-size to be used.
     * Will run trigger-checks and potentially update services.
     */
    set matchPageSize(pageSize: number);
    /**
     * Gets the currently active match order.
     */
    get matchOrderBy(): OrderBy;
    /**
     * Sets the match sorting mode to be used.
     * Will run trigger-checks and potentially update services.
     */
    set matchOrderBy(orderBy: OrderBy);
    /**
     * Gets the currently active max number of autocomplete suggestions to get.
     */
    get maxSuggestions(): number;
    /**
     * Sets the max number of autocomplete suggestions to get.
     * Will run trigger-checks and potentially update services.
     */
    set maxSuggestions(maxSuggestions: number);
    /**
     * Returns the currently active query.
     */
    get query(): IQuery;
    /**
     * Sets the query to use. Consider using the queryText-property for query-text-changes instead.
     *
     * **Note:** Changing the `query` property will likely lead to multiple trigger-checks and potential updates.
     * This is because changing the whole value will lead to each of the query-objects' properties to trigger individual
     * events.
     *
     * To avoid multiple updates, call `deferUpdates(true)` before and deferUpdates(false) afterwards. Then at max
     * only one update will be generated.
     */
    set query(query: IQuery);
    /**
     * Gets the currently active query-object.
     */
    get queryText(): string;
    /**
     * Sets the query-text to be used.
     * Will run trigger-checks and potentially update services.
     */
    set queryText(queryText: string);
    /**
     * Gets the currently active search-type value.
     */
    get searchType(): SearchType;
    /**
     * Sets the search-type to be used.
     * Will run trigger-checks and potentially update services.
     */
    set searchType(searchType: SearchType);
    /**
     * Gets the currently active match generateContent setting.
     */
    get uiLanguageCode(): string;
    /**
     * Sets the language that the client uses. Affects category-names (and in the future maybe metadata too).
     * The expected values should be according to the https://www.wikiwand.com/en/IETF_language_tag standard.
     *
     * Changes will run trigger-checks and potentially update services.
     */
    set uiLanguageCode(uiLanguageCode: string);
    private doFilterAdd;
    private doFilterRemove;
    private setup;
}