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

Scalable and extensible linked data views.

import { type MosaicClient } from './MosaicClient.js';
import { type ExprNode, MaybeArray } from '@uwdata/mosaic-sql';
import { Param } from './Param.js';
import { ClauseSource, SelectionClause } from './SelectionClause.js';
export interface SelectionOptions {
    /** Boolean flag indicating cross-filtered resolution. If true, selection clauses will not be applied to the clients they are associated with. */
    cross?: boolean;
    /** Boolean flag indicating if a lack of clauses should correspond to an empty selection with no records. This setting determines the default selection state. */
    empty?: boolean;
    /** Upstream selections whose clauses should be included as part of the new selection. Any clauses published to upstream selections will be relayed to the new selection. */
    include?: Selection | Selection[];
}
export interface SelectionResolverOptions extends Pick<SelectionOptions, "empty" | "cross"> {
    /** Boolean flag to indicate a union strategy. If false, an intersection strategy is used. */
    union?: boolean;
    /** Boolean flag to indicate single clauses only. */
    single?: boolean;
}
/**
 * Test if a value is a Selection instance.
 * @param x The value to test.
 * @returns True if the input is a Selection, false otherwise.
 */
export declare function isSelection(x: unknown): x is Selection;
type SelectionClauseArray = SelectionClause[] & {
    active?: SelectionClause;
};
type ResolvedPredicate = MaybeArray<string | boolean | ExprNode> | undefined;
/**
 * Represents a dynamic set of query filter predicates.
 */
export declare class Selection extends Param<SelectionClauseArray> {
    _resolved: SelectionClauseArray;
    _resolver: SelectionResolver;
    _relay: Set<Selection>;
    /**
     * Create a new Selection instance with an
     * intersect (conjunction) resolution strategy.
     * @param options The selection options.
     * @returns The new Selection instance.
     */
    static intersect({ cross, empty, include }?: SelectionOptions): Selection;
    /**
     * Create a new Selection instance with a
     * union (disjunction) resolution strategy.
     * @param options The selection options.
     * @returns The new Selection instance.
     */
    static union({ cross, empty, include }?: SelectionOptions): Selection;
    /**
     * Create a new Selection instance with a singular resolution strategy
     * that keeps only the most recent selection clause.
     * @param options The selection options.
     * @returns The new Selection instance.
     */
    static single({ cross, empty, include }?: SelectionOptions): Selection;
    /**
     * Create a new Selection instance with a
     * cross-filtered intersect resolution strategy.
     * @param options The selection options.
     * @returns The new Selection instance.
     */
    static crossfilter({ empty, include }?: Omit<SelectionOptions, 'cross'>): Selection;
    /**
     * Create a new Selection instance.
     * @param resolver The selection resolution
     *  strategy to apply.
     * @param include Upstream selections whose clauses
     * should be included as part of this selection. Any clauses published
     * to these upstream selections will be relayed to this selection.
     */
    constructor(resolver?: SelectionResolver, include?: Selection[]);
    /**
     * Create a cloned copy of this Selection instance.
     * @returns A clone of this selection.
     */
    clone(): Selection;
    /**
     * Create a clone of this Selection with clauses corresponding
     * to the provided source removed.
     * @param source The clause source to remove.
     * @returns A cloned and updated Selection.
     */
    remove(source: ClauseSource): Selection;
    /**
     * The selection clause resolver.
     */
    get resolver(): SelectionResolver;
    /**
     * Indicate if this selection has a single resolution strategy.
     */
    get single(): boolean;
    /**
     * The current array of selection clauses.
     */
    get clauses(): SelectionClauseArray;
    /**
     * The current active (most recently updated) selection clause.
     */
    get active(): SelectionClause;
    /**
     * The value corresponding to the current active selection clause.
     * This method ensures compatibility where a normal Param is expected.
     */
    get value(): unknown;
    /**
     * The value corresponding to a given source. Returns undefined if
     * this selection does not include a clause from this source.
     * @param source The clause source to look up the value for.
     */
    valueFor(source: unknown): unknown;
    /**
     * Emit an activate event with the given selection clause.
     * @param clause The clause representing the potential activation.
     */
    activate(clause: SelectionClause): void;
    /**
     * Update the selection with a new selection clause.
     * @param clause The selection clause to add.
     * @returns This Selection instance.
     */
    update(clause: SelectionClause): this;
    /**
     * Reset the selection state by removing all provided clauses. If no clause
     * array is provided as an argument, all current clauses are removed. The
     * reset method (if defined) is invoked on all corresponding clause sources.
     * The reset is relayed to downstream selections that include this selection.
     * @param clauses The clauses to remove. If unspecified, all current clauses are removed.
     * @returns This selection instance.
     */
    reset(clauses?: SelectionClause[]): this;
    /**
     * Upon value-typed updates, sets the current clause list to the
     * input value and returns the active clause value.
     * @param type The event type.
     * @param value The input event value.
     * @returns For value-typed events, returns the active clause
     *  values. Otherwise returns the input event value as-is.
     */
    willEmit(type: string, value: unknown): unknown;
    /**
     * Upon value-typed updates, returns a dispatch queue filter function.
     * The return value depends on the selection resolution strategy.
     * @param type The event type.
     * @param value The new event value that will be enqueued.
     * @returns A dispatch queue filter function. For non-value events,
     *  returns a function that always returns null (no filtering).
     */
    emitQueueFilter(type: string, value: SelectionClauseArray): ((value: SelectionClauseArray) => boolean) | null;
    /**
     * Indicates if a selection clause should not be applied to a given client.
     * The return value depends on the selection resolution strategy.
     * @param client The client to test. If null or undefined, return false.
     * @param clause The selection clause.
     * @returns True if the client should be skipped, false otherwise.
     */
    skip(client: MosaicClient | null | undefined, clause: SelectionClause): boolean;
    /**
     * Return a selection query predicate for the given client.
     * @param client The client whose data may be filtered. If null or undefined, return a predicate with all clauses.
     * @param noSkip Disable skipping of active
     *  cross-filtered sources. If set true, the source of the active
     *  clause in a cross-filtered selection will not be skipped.
     * @returns The query predicate for filtering client data,
     *  based on the current state of this selection.
     */
    predicate(client?: MosaicClient | null | undefined, noSkip?: boolean): ResolvedPredicate;
}
/**
 * Implements selection clause resolution strategies.
 */
export declare class SelectionResolver {
    union: boolean;
    cross: boolean;
    single: boolean;
    empty: boolean;
    /**
     * Create a new selection resolved instance.
     * @param options The resolution strategy options.
     * @param options.union Boolean flag to indicate a union strategy.
     *  If false, an intersection strategy is used.
     * @param options.cross Boolean flag to indicate cross-filtering.
     * @param options.single Boolean flag to indicate single clauses only.
     * @param options.empty Boolean flag indicating if a lack
     *  of clauses should correspond to an empty selection with no records. This
     *  setting determines the default selection state.
     */
    constructor({ union, cross, single, empty }?: SelectionResolverOptions);
    /**
     * Resolve a list of selection clauses according to the resolution strategy.
     * @param clauseList An array of selection clauses.
     * @param clause A new selection clause to add.
     * @returns An updated array of selection clauses.
     */
    resolve(clauseList: SelectionClause[], clause: SelectionClause, reset?: boolean): SelectionClause[];
    /**
     * Indicates if a selection clause should not be applied to a given client.
     * The return value depends on the resolution strategy.
     * @param client The client to test. If null or undefined, return false.
     * @param clause The selection clause.
     * @returns True if the client should be skipped, false otherwise.
     */
    skip(client: MosaicClient | null | undefined, clause: SelectionClause): boolean;
    /**
     * Return a selection query predicate for the given client.
     * @param clauseList An array of selection clauses.
     * @param active The current active selection clause.
     * @param client The client whose data may be filtered. If null or undefined, return all clauses.
     * @returns The query predicate for filtering client data,
     *  based on the current state of this selection.
     */
    predicate(clauseList: SelectionClause[], active: SelectionClause, client: MosaicClient | null | undefined): ResolvedPredicate;
    /**
     * Returns a filter function for queued selection updates.
     * @param value The new event value that will be enqueued.
     * @returns A dispatch queue filter
     *  function, or null if all unemitted event values should be filtered.
     */
    queueFilter(value: SelectionClauseArray): ((value: SelectionClauseArray) => boolean) | null;
}
export {};
//# sourceMappingURL=Selection.d.ts.map