@uwdata/mosaic-core/dist/src/MosaicClient.d.ts

Scalable and extensible linked data views.

import { FilterExpr, type Query } from '@uwdata/mosaic-sql';
import { type Coordinator } from './Coordinator.js';
import { type Selection } from './Selection.js';
export type ClientQuery = Query | string | null;
export declare function isMosaicClient(x: unknown): x is MosaicClient;
/**
 * A Mosaic client is a data consumer that indicates its data needs to a
 * Mosaic coordinator via the query method. The coordinator is responsible
 * for issuing queries and returning results to the client.
 *
 * The client life-cycle consists of connection to a coordinator,
 * initialization (potentially involving queries for data schema and summary
 * statistic information), and then interactive queries that may be driven by
 * an associated selection. When no longer needed, a client should be
 * disconnected from the coordinator.
 *
 * When enabled, a client will initialize and respond to query update requests.
 * If disabled, the client will delay initialization and not respond to queries
 * until enabled again. Disabling a client can improve system performance when
 * associated interface elements are offscreen or disabled.
 */
export declare class MosaicClient {
    _filterBy: Selection | undefined;
    _requestUpdate: () => void;
    _coordinator: Coordinator | null;
    _pending: Promise<unknown>;
    _enabled: boolean;
    _initialized: boolean;
    _request: Query | boolean | null;
    /**
     * Create a new client instance.
     * @param filterSelection An optional selection to
     *  interactively filter this client's data. If provided, a coordinator
     *  will re-query and update the client when the selection updates.
     */
    constructor(filterSelection?: Selection);
    /**
     * @returns this client's connected coordinator.
     */
    get coordinator(): Coordinator | null;
    /**
     * Set this client's connected coordinator.
     */
    set coordinator(coordinator: Coordinator | null);
    /**
     * Return this client's enabled state.
     */
    get enabled(): boolean;
    /**
     * Set this client's enabled state;
     */
    set enabled(state: boolean);
    /**
     * Return a Promise that resolves once the client has updated.
     */
    get pending(): Promise<unknown>;
    /**
     * @returns this client's filter selection.
     */
    get filterBy(): Selection | undefined;
    /**
     * Return a boolean indicating if the client query can be sped up with
     * materialized views of pre-aggregated data. Should return true if changes
     * to the filterBy selection do not change the groupby domain of the client
     * query.
     */
    get filterStable(): boolean;
    /**
     * Prepare the client before the `query()` method is called. Subclasses
     * should override this method as needed, potentially issuing one or more
     * queries to gather data or metadata needed prior to `query` calls.
     */
    prepare(): Promise<void>;
    /**
     * Return a query specifying the data needed by this client.
     * @param filter The filtering criteria to apply in the query.
     * @returns The client query
     */
    query(filter?: FilterExpr | null): ClientQuery;
    /**
     * Called by the coordinator to inform the client that a query is pending.
     * @returns this
     */
    queryPending(): this;
    /**
     * Called by the coordinator to return a query result.
     * @param data The query result.
     * @returns this
     */
    queryResult(data: unknown): this;
    /**
     * Called by the coordinator to report a query execution error.
     * @param error
     * @returns this
     */
    queryError(error: Error): this;
    /**
     * Request the coordinator to execute a query for this client.
     * If an explicit query is not provided, the client `query` method will
     * be called, filtered by the current `filterBy` selection. This method has
     * no effect if the client is not connected to a coordinator. If the client
     * is connected by currently disabled, the request will be serviced if the
     * client is later enabled.
     * @param query The query to request. If unspecified, the query
     *  will be determined by the client's `query` method and the current
     *  `filterBy` selection state.
     */
    requestQuery(query?: Query): Promise<unknown> | null;
    /**
     * Request that the coordinator perform a throttled update of this client
     * using the default query. Unlike requestQuery, for which every call results
     * in an executed query, multiple calls to requestUpdate may be consolidated
     * into a single update. This method has no effect if the client is not
     * connected to a coordinator. If the client is connected but currently
     * disabled, the request will be serviced if the client is later enabled.
     */
    requestUpdate(): void;
    /**
     * Reset this client, calling the prepare method and query requests. This
     * method has no effect if the client is not registered with a coordinator.
     */
    initialize(): void;
    /**
     * Remove this client: disconnect from the coordinator and free up any
     * resource use. This method has no effect if the client is not connected
     * to a coordinator.
     *
     * If overriding this method in a client subclass, be sure to also
     * disconnect from the coordinator.
     */
    destroy(): void;
    /**
     * Requests a client update, for example to (re-)render an interface
     * component.
     */
    update(): this | Promise<unknown>;
}
//# sourceMappingURL=MosaicClient.d.ts.map