@uwdata/mosaic-core 0.11.0 → 0.12.0

package/dist/types/Coordinator.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Set or retrieve the coordinator instance.
+ * @param {Coordinator} [instance] the coordinator instance to set
+ * @returns {Coordinator} the coordinator instance
+ */
+export function coordinator(instance?: Coordinator): Coordinator;
+/**
+ * @typedef {import('@uwdata/mosaic-sql').Query | string} QueryType
+ */
+/**
+ * A Mosaic Coordinator manages all database communication for clients and
+ * handles selection updates. The Coordinator also performs optimizations
+ * including query caching, consolidation, and pre-aggregation.
+ * @param {*} [db] Database connector. Defaults to a web socket connection.
+ * @param {object} [options] Coordinator options.
+ * @param {*} [options.logger=console] The logger to use, defaults to `console`.
+ * @param {*} [options.manager] The query manager to use.
+ * @param {boolean} [options.cache=true] Boolean flag to enable/disable query caching.
+ * @param {boolean} [options.consolidate=true] Boolean flag to enable/disable query consolidation.
+ * @param {import('./preagg/PreAggregator.js').PreAggregateOptions} [options.preagg]
+ *  Options for the Pre-aggregator.
+ */
+export class Coordinator {
+    constructor(db?: {
+        readonly connected: boolean;
+        query(query: {
+            type?: "exec" | "arrow" | "json" | "create-bundle" | "load-bundle";
+            sql?: string;
+            queries?: string[];
+            name?: string;
+        }): Promise<any>;
+    }, { logger, manager, cache, consolidate, preagg }?: {
+        logger?: Console;
+        manager?: QueryManager;
+        cache?: boolean;
+        consolidate?: boolean;
+        preagg?: {};
+    });
+    /** @type {QueryManager} */
+    manager: QueryManager;
+    preaggregator: PreAggregator;
+    /**
+     * Clear the coordinator state.
+     * @param {object} [options] Options object.
+     * @param {boolean} [options.clients=true] If true, disconnect all clients.
+     * @param {boolean} [options.cache=true] If true, clear the query cache.
+     */
+    clear({ clients, cache }?: {
+        clients?: boolean;
+        cache?: boolean;
+    }): void;
+    filterGroups: Map<any, any>;
+    clients: Set<any>;
+    /**
+     * Get or set the database connector.
+     * @param {*} [db] The database connector to use.
+     * @returns The current database connector.
+     */
+    databaseConnector(db?: any): any;
+    /**
+     * Get or set the logger.
+     * @param {*} logger  The logger to use.
+     * @returns The current logger
+     */
+    logger(logger: any, ...args: any[]): any;
+    _logger: any;
+    /**
+     * Cancel previosuly submitted query requests. These queries will be
+     * canceled if they are queued but have not yet been submitted.
+     * @param {QueryResult[]} requests An array
+     *  of query result objects, such as those returned by the `query` method.
+     */
+    cancel(requests: QueryResult[]): void;
+    /**
+     * Issue a query for which no result (return value) is needed.
+     * @param {QueryType | QueryType[]} query The query or an array of queries.
+     *  Each query should be either a Query builder object or a SQL string.
+     * @param {object} [options] An options object.
+     * @param {number} [options.priority] The query priority, defaults to
+     *  `Priority.Normal`.
+     * @returns {QueryResult} A query result
+     *  promise.
+     */
+    exec(query: QueryType | QueryType[], { priority }?: {
+        priority?: number;
+    }): QueryResult;
+    /**
+     * Issue a query to the backing database. The submitted query may be
+     * consolidate with other queries and its results may be cached.
+     * @param {QueryType} query The query as either a Query builder object
+     *  or a SQL string.
+     * @param {object} [options] An options object.
+     * @param {'arrow' | 'json'} [options.type] The query result format type.
+     * @param {boolean} [options.cache=true] If true, cache the query result.
+     * @param {number} [options.priority] The query priority, defaults to
+     *  `Priority.Normal`.
+     * @returns {QueryResult} A query result promise.
+     */
+    query(query: QueryType, { type, cache, priority, ...options }?: {
+        type?: "arrow" | "json";
+        cache?: boolean;
+        priority?: number;
+    }): QueryResult;
+    /**
+     * Issue a query to prefetch data for later use. The query result is cached
+     * for efficient future access.
+     * @param {QueryType} query The query as either a Query builder object
+     *  or a SQL string.
+     * @param {object} [options] An options object.
+     * @param {'arrow' | 'json'} [options.type] The query result format type.
+     * @returns {QueryResult} A query result promise.
+     */
+    prefetch(query: QueryType, options?: {
+        type?: "arrow" | "json";
+    }): QueryResult;
+    /**
+     * Create a bundle of queries that can be loaded into the cache.
+     *
+     * @param {string} name The name of the bundle.
+     * @param {[string | {sql: string},  {alias: string}]} queries The queries to save into the bundle.
+     * @param {number} priority Request priority.
+     * @returns {QueryResult} A query result promise.
+     */
+    createBundle(name: string, queries: [string | {
+        sql: string;
+    }, {
+        alias: string;
+    }], priority?: number): QueryResult;
+    /**
+     * Load a bundle into the cache.
+     * @param {string} name The name of the bundle.
+     * @param {number} priority Request priority.
+     * @returns {QueryResult} A query result promise.
+     */
+    loadBundle(name: string, priority?: number): QueryResult;
+    /**
+     * Update client data by submitting the given query and returning the
+     * data (or error) to the client.
+     * @param {MosaicClient} client A Mosaic client.
+     * @param {QueryType} query The data query.
+     * @param {number} [priority] The query priority.
+     * @returns {Promise} A Promise that resolves upon completion of the update.
+     */
+    updateClient(client: MosaicClient, query: QueryType, priority?: number): Promise<any>;
+    /**
+     * Issue a query request for a client. If the query is null or undefined,
+     * the client is simply updated. Otherwise `updateClient` is called. As a
+     * side effect, this method clears the current preaggregator state.
+     * @param {MosaicClient} client The client to update.
+     * @param {QueryType | null} [query] The query to issue.
+     */
+    requestQuery(client: MosaicClient, query?: QueryType | null): Promise<any>;
+    /**
+     * Connect a client to the coordinator.
+     * @param {MosaicClient} client The Mosaic client to connect.
+     */
+    connect(client: MosaicClient): Promise<void>;
+    initializeClient(client: any): Promise<any>;
+    /**
+     * Disconnect a client from the coordinator.
+     * @param {MosaicClient} client The Mosaic client to disconnect.
+     */
+    disconnect(client: MosaicClient): void;
+}
+export type QueryType = import("@uwdata/mosaic-sql").Query | string;
+import { QueryManager } from './QueryManager.js';
+import { PreAggregator } from './preagg/PreAggregator.js';
+import { QueryResult } from './util/query-result.js';
+import { MosaicClient } from './MosaicClient.js';

package/dist/types/MosaicClient.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Base class for Mosaic clients.
+ */
+export class MosaicClient {
+    /**
+     * Constructor.
+     * @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: any);
+    _filterBy: any;
+    _requestUpdate: (event: any) => void;
+    _coordinator: any;
+    /**
+     * Set this client's connected coordinator.
+     */
+    set coordinator(coordinator: any);
+    /**
+     * Return this client's connected coordinator.
+     */
+    get coordinator(): any;
+    /**
+     * Return this client's filter selection.
+     */
+    get filterBy(): any;
+    /**
+     * 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 does not change the groupby domain of the client
+     * query.
+     */
+    get filterStable(): boolean;
+    /**
+     * Return an array of fields queried by this client.
+     * @returns {object[]|null} The fields to retrieve info for.
+     */
+    fields(): object[] | null;
+    /**
+     * Called by the coordinator to set the field info for this client.
+     * @param {*} info The field info result.
+     * @returns {this}
+     */
+    fieldInfo(info: any): this;
+    /**
+     * 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?: any): any;
+    /**
+     * 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: any): this;
+    /**
+     * Called by the coordinator to report a query execution error.
+     * @param {*} error
+     * @returns {this}
+     */
+    queryError(error: any): 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.
+     * @returns {Promise}
+     */
+    requestQuery(query: any): Promise<any>;
+    /**
+     * Request that the coordinator perform a throttled update of this client
+     * using the default query. Unlike requestQuery, for which every call will
+     * result in an executed query, multiple calls to requestUpdate may be
+     * consolidated into a single update.
+     */
+    requestUpdate(): void;
+    /**
+     * Reset this client, initiating new field info and query requests.
+     * @returns {Promise}
+     */
+    initialize(): Promise<any>;
+    /**
+     * Requests a client update.
+     * For example to (re-)render an interface component.
+     *
+     * @returns {this | Promise<any>}
+     */
+    update(): this | Promise<any>;
+}

package/dist/types/Param.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Test if a value is a Param instance.
+ * @param {*} x The value to test.
+ * @returns {x is Param} True if the input is a Param, false otherwise.
+ */
+export function isParam(x: any): x is Param;
+/**
+ * Represents a dynamic parameter that dispatches updates
+ * upon parameter changes.
+ */
+export class Param extends AsyncDispatch {
+    /**
+     * Create a new Param instance with the given initial value.
+     * @param {*} value The initial value of the Param.
+     * @returns {Param} The new Param instance.
+     */
+    static value(value: any): Param;
+    /**
+     * Create a new Param instance over an array of initial values,
+     * which may contain nested Params.
+     * @param {*} values The initial values of the Param.
+     * @returns {Param} The new Param instance.
+     */
+    static array(values: any): Param;
+    /**
+     * Create a new Param instance.
+     * @param {*} value The initial value of the Param.
+     */
+    constructor(value: any);
+    _value: any;
+    /**
+     * The current value of the Param.
+     */
+    get value(): any;
+    /**
+     * Update the Param value
+     * @param {*} value The new value of the Param.
+     * @param {object} [options] The update options.
+     * @param {boolean} [options.force] A boolean flag indicating if the Param
+     *  should emit a 'value' event even if the internal value is unchanged.
+     * @returns {this} This Param instance.
+     */
+    update(value: any, { force }?: {
+        force?: boolean;
+    }): this;
+}
+import { AsyncDispatch } from './util/AsyncDispatch.js';

package/dist/types/QueryConsolidator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Create a consolidator to combine structurally compatible queries.
+ * @param {*} enqueue Query manager enqueue method
+ * @param {*} cache Client-side query cache (sql -> data)
+ * @returns A consolidator object
+ */
+export function consolidator(enqueue: any, cache: any): {
+    add(entry: any, priority: any): void;
+};

package/dist/types/QueryManager.d.ts

@@ -0,0 +1,64 @@
+export const Priority: Readonly<{
+    High: 0;
+    Normal: 1;
+    Low: 2;
+}>;
+export class QueryManager {
+    constructor(maxConcurrentRequests?: number);
+    queue: PriorityQueue;
+    db: any;
+    clientCache: any;
+    _logger: {
+        debug(..._: any[]): void;
+        info(..._: any[]): void;
+        log(..._: any[]): void;
+        warn(..._: any[]): void;
+        error(..._: any[]): void;
+    };
+    _logQueries: boolean;
+    _consolidate: {
+        add(entry: any, priority: any): void;
+    };
+    /**
+     * Requests pending with the query manager.
+     *
+     * @type {QueryResult[]}
+     */
+    pendingResults: QueryResult[];
+    maxConcurrentRequests: number;
+    pendingExec: boolean;
+    next(): void;
+    /**
+     * Add an entry to the query queue with a priority.
+     * @param {object} entry The entry to add.
+     * @param {*} [entry.request] The query request.
+     * @param {QueryResult} [entry.result] The query result.
+     * @param {number} priority The query priority, defaults to `Priority.Normal`.
+     */
+    enqueue(entry: {
+        request?: any;
+        result?: QueryResult;
+    }, priority?: number): void;
+    /**
+     * Submit the query to the connector.
+     * @param {*} request The request.
+     * @param {QueryResult} result The query result.
+     */
+    submit(request: any, result: QueryResult): Promise<void>;
+    cache(value: any): any;
+    logger(value: any): any;
+    logQueries(value: any): boolean;
+    connector(connector: any): any;
+    consolidate(flag: any): void;
+    /**
+     * Request a query result.
+     * @param {*} request The request.
+     * @param {number} priority The query priority, defaults to `Priority.Normal`.
+     * @returns {QueryResult} A query result promise.
+     */
+    request(request: any, priority?: number): QueryResult;
+    cancel(requests: any): void;
+    clear(): void;
+}
+import { PriorityQueue } from './util/priority-queue.js';
+import { QueryResult } from './util/query-result.js';

package/dist/types/Selection.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Test if a value is a Selection instance.
+ * @param {*} x The value to test.
+ * @returns {x is Selection} True if the input is a Selection, false otherwise.
+ */
+export function isSelection(x: any): x is Selection;
+/**
+ * Represents a dynamic set of query filter predicates.
+ */
+export class Selection extends Param {
+    /**
+     * Create a new Selection instance with an
+     * intersect (conjunction) resolution strategy.
+     * @param {object} [options] The selection options.
+     * @param {boolean} [options.cross=false] Boolean flag indicating
+     *  cross-filtered resolution. If true, selection clauses will not
+     *  be applied to the clients they are associated with.
+     * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+     *  of clauses should correspond to an empty selection with no records. This
+     *  setting determines the default selection state.
+     * @param {Selection|Selection[]} [options.include] 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.
+     * @returns {Selection} The new Selection instance.
+     */
+    static intersect({ cross, empty, include }?: {
+        cross?: boolean;
+        empty?: boolean;
+        include?: Selection | Selection[];
+    }): Selection;
+    /**
+     * Create a new Selection instance with a
+     * union (disjunction) resolution strategy.
+     * @param {object} [options] The selection options.
+     * @param {boolean} [options.cross=false] Boolean flag indicating
+     *  cross-filtered resolution. If true, selection clauses will not
+     *  be applied to the clients they are associated with.
+     * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+     *  of clauses should correspond to an empty selection with no records. This
+     *  setting determines the default selection state.
+     * @param {Selection|Selection[]} [options.include] 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.
+     * @returns {Selection} The new Selection instance.
+     */
+    static union({ cross, empty, include }?: {
+        cross?: boolean;
+        empty?: boolean;
+        include?: Selection | Selection[];
+    }): Selection;
+    /**
+     * Create a new Selection instance with a singular resolution strategy
+     * that keeps only the most recent selection clause.
+     * @param {object} [options] The selection options.
+     * @param {boolean} [options.cross=false] Boolean flag indicating
+     *  cross-filtered resolution. If true, selection clauses will not
+     *  be applied to the clients they are associated with.
+     * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+     *  of clauses should correspond to an empty selection with no records. This
+     *  setting determines the default selection state.
+     * @param {Selection|Selection[]} [options.include] 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.
+     * @returns {Selection} The new Selection instance.
+     */
+    static single({ cross, empty, include }?: {
+        cross?: boolean;
+        empty?: boolean;
+        include?: Selection | Selection[];
+    }): Selection;
+    /**
+     * Create a new Selection instance with a
+     * cross-filtered intersect resolution strategy.
+     * @param {object} [options] The selection options.
+     * @param {boolean} [options.empty=false] Boolean flag indicating if a lack
+     *  of clauses should correspond to an empty selection with no records. This
+     *  setting determines the default selection state.
+     * @param {Selection|Selection[]} [options.include] 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.
+     * @returns {Selection} The new Selection instance.
+     */
+    static crossfilter({ empty, include }?: {
+        empty?: boolean;
+        include?: Selection | Selection[];
+    }): Selection;
+    /**
+     * Create a new Selection instance.
+     * @param {SelectionResolver} [resolver] The selection resolution
+     *  strategy to apply.
+     * @param {Selection[]} [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[]);
+    _resolved: any;
+    _resolver: SelectionResolver;
+    /** @type {Set<Selection>} */
+    _relay: Set<Selection>;
+    /**
+     * Create a cloned copy of this Selection instance.
+     * @returns {Selection} 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 {Selection} A cloned and updated Selection.
+     */
+    remove(source: any): 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(): any;
+    /**
+     * The current active (most recently updated) selection clause.
+     */
+    get active(): any;
+    /**
+     * 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: any): any;
+    /**
+     * Emit an activate event with the given selection clause.
+     * @param {*} clause The clause repesenting the potential activation.
+     */
+    activate(clause: any): void;
+    /**
+     * Update the selection with a new selection clause.
+     * @param {*} clause The selection clause to add.
+     * @returns {this} This Selection instance.
+     */
+    update(clause: any): this;
+    /**
+     * 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 selection clause.
+     * @param {*} clause The client to test.
+     * @returns True if the client should be skipped, false otherwise.
+     */
+    skip(client: any, clause: any): any;
+    /**
+     * Return a selection query predicate for the given client.
+     * @param {*} client The client whose data may be filtered.
+     * @param {boolean} [noSkip=false] 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: any, noSkip?: boolean): any;
+}
+/**
+ * Implements selection clause resolution strategies.
+ */
+export class SelectionResolver {
+    /**
+     * Create a new selection resolved instance.
+     * @param {object} [options] The resolution strategy options.
+     * @param {boolean} [options.union=false] Boolean flag to indicate a union strategy.
+     *  If false, an intersection strategy is used.
+     * @param {boolean} [options.cross=false] Boolean flag to indicate cross-filtering.
+     * @param {boolean} [options.single=false] Boolean flag to indicate single clauses only.
+     * @param {boolean} [options.empty=false] 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 }?: {
+        union?: boolean;
+        cross?: boolean;
+        single?: boolean;
+        empty?: boolean;
+    });
+    union: boolean;
+    cross: boolean;
+    single: boolean;
+    empty: boolean;
+    /**
+     * 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: any[], clause: any, reset?: boolean): any[];
+    /**
+     * Indicates if a selection clause should not be applied to a given client.
+     * The return value depends on the resolution strategy.
+     * @param {*} client The selection clause.
+     * @param {*} clause The client to test.
+     * @returns True if the client should be skipped, false otherwise.
+     */
+    skip(client: any, clause: any): any;
+    /**
+     * Return a selection query predicate for the given client.
+     * @param {import('./util/selection-types.js').SelectionClause[]} clauseList
+     *  An array of selection clauses.
+     * @param {import('./util/selection-types.js').SelectionClause} active
+     *  The current active selection clause.
+     * @param {MosaicClient} client The client whose data may be filtered.
+     * @returns {*} The query predicate for filtering client data,
+     *  based on the current state of this selection.
+     */
+    predicate(clauseList: import("./util/selection-types.js").SelectionClause[], active: import("./util/selection-types.js").SelectionClause, client: MosaicClient): any;
+    /**
+     * Returns a filter function for queued selection updates.
+     * @param {*} value The new event value that will be enqueued.
+     * @returns {(value: *) => boolean|null} A dispatch queue filter
+     *  function, or null if all unemitted event values should be filtered.
+     */
+    queueFilter(value: any): (value: any) => boolean | null;
+}
+import { Param } from './Param.js';
+import { MosaicClient } from './MosaicClient.js';