@equinor/fusion-query/dist/types/client/QueryClient.d.ts

Reactive data fetching and caching library with observable streams and comprehensive event system

import { Observable, Subscription } from 'rxjs';
import { type ActionMap, type Actions } from './actions';
import { QueryClientError } from './QueryClientError';
import type { QueryClientState, RetryOptions, QueryFn, QueryClientResult, QueryClientRequest } from './types';
import { QueryClientJob } from './QueryClientJob';
import { QueryClientEvent, type QueryClientEventData, type QueryClientEvents } from './events';
/**
 * Options for configuring the behavior of the `QueryClient`.
 *
 * @property {AbortSignal} [signal] - An instance of AbortSignal to cancel the request. [optional]
 * @property {Partial<RetryOptions>} [retry] - Configuration for retry behavior, including number of retries and delay strategy.
 * @property {string} [ref] - A reference string to associate with a query, which can be used for cancellation or tracking purposes.
 */
export type QueryClientOptions = {
    signal?: AbortSignal;
    retry?: Partial<RetryOptions>;
    /** Reference to a query for tracking or cancellation. */
    ref?: string;
};
export type QueryClientCtorOptions = {
    /** Configuration for retry behavior, including number of retries and delay strategy. */
    retry?: Partial<RetryOptions>;
};
/**
 * QueryClient is a generic class that manages the state of asynchronous queries
 * and their lifecycle. It extends Observable to allow subscribers to react to state changes.
 *
 * It uses a FlowSubject to manage a stream of actions that describe the state changes and
 * side effects such as logging. The internal state is managed by a reducer function that
 * processes these actions.
 *
 * The QueryClient provides several specialized Observables (success$, error$, etc.) to
 * observe particular aspects of the query lifecycle, such as successful results or errors.
 *
 * @template TType The type of the data returned by the query function.
 * @template TArgs The type of the arguments passed to the query function.
 */
export declare class QueryClient<TType, TArgs> extends Observable<QueryClientState<TArgs>> {
    #private;
    /**
     * Protected method to emit QueryClient lifecycle events.
     *
     * This method creates and emits events that track the various stages of query execution,
     * allowing external observers to monitor query progress, success, failure, and cancellation.
     *
     * @template TType - The specific event type from QueryClientEvents
     * @param type - The event type identifier
     * @param transaction - Unique transaction identifier for the query operation
     * @param data - Optional event-specific data payload (type-safe based on event type)
     * @protected
     */
    protected _registerEvent<TType extends keyof QueryClientEvents>(type: TType, transaction: string, data?: QueryClientEventData<TType>): void;
    /**
     * Indicates whether the QueryClient has been closed and is no longer accepting new actions.
     * @returns {boolean} A boolean value indicating if the state is closed.
     */
    get closed(): boolean;
    /**
     * An Observable of the current state. It emits the current state of the query client
     * whenever it changes.
     * @returns {Observable<QueryClientState<TArgs>>} An Observable stream of the current state.
     */
    get state$(): Observable<QueryClientState<TArgs>>;
    /**
     * An Observable stream of dispatched actions. It allows subscribers to react to
     * specific actions that are dispatched in the system.
     * @returns {Observable<Actions<TType, TArgs>>} An Observable stream of actions.
     */
    get action$(): Observable<Actions<TType, TArgs>>;
    /**
     * An Observable stream of QueryClient lifecycle events.
     *
     * This stream emits events that track the various stages of query execution,
     * including job requested, executing, completed, failed, canceled, and error events.
     * Subscribers can monitor query progress and handle different lifecycle events.
     *
     * @returns An Observable stream of QueryClient events
     */
    get event$(): Observable<QueryClientEvent>;
    /**
     * An Observable stream of successful query results. It emits the result of a query
     * when it completes successfully.
     * @returns {Observable<TType>} An Observable stream of successful results.
     */
    get success$(): Observable<TType>;
    /**
     * An Observable stream of query errors. It emits an instance of QueryClientError
     * when a query fails to complete.
     * @returns {Observable<QueryClientError>} An Observable stream of query errors.
     */
    get error$(): Observable<QueryClientError<TArgs>>;
    /**
     * Creates an instance of QueryClient.
     * @param {QueryFn<TType, TArgs>} queryFn A function that performs the asynchronous query.
     * @param {QueryClientCtorOptions} [options] Optional configuration options for the QueryClient.
     */
    constructor(queryFn: QueryFn<TType, TArgs>, options?: QueryClientCtorOptions);
    /**
     * Dispatches an action to the internal state subject, which will be processed by the reducer
     * and any registered effects.
     * @param {Actions} action The action to dispatch.
     */
    next(action: Actions): void;
    /**
     * Initiates a query with the provided arguments and options. It returns a QueryClientJob
     * which is an Observable that represents the lifecycle of the query.
     * @param {TArgs} args Call arguments for the query function.
     * @param {Partial<QueryClientOptions>} [opt] Query options.
     * @returns {QueryClientJob<TType, TArgs>} The QueryClientJob representing the initiated query.
     */
    query(args: TArgs, opt?: Partial<QueryClientOptions>): QueryClientJob<TType, TArgs>;
    /**
     * Initiates a query and returns a promise that resolves with the result of the query.
     * It is a convenience method that wraps the query method for use with async/await syntax.
     * @param {TArgs} args Call arguments for the query function.
     * @param {QueryClientOptions} [opt] Query options.
     * @returns {Promise<QueryClientResult<TType>>} A promise that resolves with the result of the query.
     */
    nextAsync(args: TArgs, opt?: QueryClientOptions): Promise<QueryClientResult<TType>>;
    /**
     * Retrieves the request associated with the specified transaction.
     *
     * @param transaction - The transaction identifier.
     * @returns The request associated with the specified transaction.
     */
    getRequest(transaction: string): QueryClientRequest<TArgs> | undefined;
    /**
     * Retrieves the request associated with the specified reference string.
     *
     * @param ref - The reference identifier to search for.
     * @returns The request matching the reference, or `undefined` if not found.
     */
    getRequestByRef(ref: string): QueryClientRequest<TArgs> | undefined;
    /**
     * Cancels a task by its reference string. If a reason is provided, it will be included
     * in the cancellation effect.
     * @param {string} ref The reference string of the task to cancel.
     * @param {string} [reason] The reason for cancellation.
     */
    cancelTaskByRef(ref: string, reason?: string): void;
    /**
     * Cancels a query. If a transaction id is provided, it cancels the specific query.
     * Otherwise, it cancels all queries.
     * @param {string} [transaction] The transaction id of the query to cancel.
     * @param {string} [reason] The reason for cancellation.
     */
    cancel(transaction?: string, reason?: string): void;
    /**
     * Registers a callback to be executed when an action of the specified type is dispatched.
     * It allows for custom behavior to be defined in response to specific actions.
     * @template TAction The type of the action to listen for.
     * @param {TAction} type The type of the action.
     * @param {(action: ActionMap[TAction], subject: QueryClient<TType, TArgs>) => void} cb The callback to execute.
     * @returns {Subscription} A Subscription that can be used to unregister the effect.
     */
    on<TAction extends keyof ActionMap>(type: TAction, cb: (action: ActionMap[TAction], subject: QueryClient<TType, TArgs>) => void): Subscription;
    /**
     * Completes the QueryClient's internal state subject, effectively cleaning up all
     * resources and subscriptions. After calling complete, the QueryClient will no longer
     * accept new actions or emit new state changes.
     */
    complete(): void;
}
export default QueryClient;