@uwdata/mosaic-core 0.14.1 → 0.15.0

package/dist/types/Coordinator.d.ts

@@ -14,8 +14,7 @@ export function coordinator(instance?: Coordinator): Coordinator;
  * @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.
+ * @param {PreAggregateOptions} [options.preagg] Options for the Pre-aggregator.
  */
 export class Coordinator {
     constructor(db?: {
@@ -70,22 +69,21 @@ export class Coordinator {
     cancel(requests: QueryResult[]): void;
     /**
      * Issue a query for which no result (return value) is needed.
-     * @param { import('./types.js').QueryType[] |
-     *  import('./types.js').QueryType} query The query or an array of queries.
+     * @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: import("./types.js").QueryType[] | import("./types.js").QueryType, { priority }?: {
+    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 {import('./types.js').QueryType} query The query as either a Query
-     *  builder object or a SQL string.
+     * @param {QueryType} query The query as either a Query builder objec
+     *   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
@@ -96,7 +94,7 @@ export class Coordinator {
      *  `Priority.Normal`.
      * @returns {QueryResult} A query result promise.
      */
-    query(query: import("./types.js").QueryType, { type, cache, priority, ...options }?: {
+    query(query: QueryType, { type, cache, priority, ...options }?: {
         type?: "arrow" | "json";
         cache?: boolean;
         persist?: boolean;
@@ -105,13 +103,13 @@ export class Coordinator {
     /**
      * Issue a query to prefetch data for later use. The query result is cached
      * for efficient future access.
-     * @param {import('./types.js').QueryType} query The query as either a Query
-     *  builder object or a SQL string.
+     * @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: import("./types.js").QueryType, options?: {
+    prefetch(query: QueryType, options?: {
         type?: "arrow" | "json";
     }): QueryResult;
     /**
@@ -138,25 +136,24 @@ export class Coordinator {
      * Update client data by submitting the given query and returning the
      * data (or error) to the client.
      * @param {MosaicClient} client A Mosaic client.
-     * @param {import('./types.js').QueryType} query The data query.
+     * @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: import("./types.js").QueryType, priority?: number): Promise<any>;
+    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 {import('./types.js').QueryType | null} [query] The query to issue.
+     * @param {QueryType | null} [query] The query to issue.
      */
-    requestQuery(client: MosaicClient, query?: import("./types.js").QueryType | null): Promise<any>;
+    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): void;
-    initializeClient(client: any): Promise<any>;
     /**
      * Disconnect a client from the coordinator.
      * @param {MosaicClient} client The Mosaic client to disconnect.
@@ -165,5 +162,6 @@ export class Coordinator {
 }
 import { QueryManager } from './QueryManager.js';
 import { PreAggregator } from './preagg/PreAggregator.js';
-import { QueryResult } from './util/query-result.js';
-import { MosaicClient } from './MosaicClient.js';
+import type { QueryResult } from './util/query-result.js';
+import type { QueryType } from './types.js';
+import type { MosaicClient } from './MosaicClient.js';

package/dist/types/MosaicClient.d.ts

@@ -1,14 +1,27 @@
 /**
- * Base class for Mosaic clients.
+ * 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 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.
+     * Create a new client instance.
+     * @param {Selection} [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);
+    constructor(filterSelection?: Selection);
     /** @type {Selection} */
     _filterBy: Selection;
     _requestUpdate: (event: any) => void;
@@ -16,6 +29,12 @@ export class MosaicClient {
     _coordinator: Coordinator;
     /** @type {Promise<any>} */
     _pending: Promise<any>;
+    /** @type {boolean} */
+    _enabled: boolean;
+    /** @type {boolean} */
+    _initialized: boolean;
+    /** @type {Query | boolean} */
+    _request: Query | boolean;
     /**
      * Set this client's connected coordinator.
      */
@@ -24,6 +43,14 @@ export class MosaicClient {
      * Return this client's connected coordinator.
      */
     get coordinator(): Coordinator;
+    /**
+     * Set this client's enabled state;
+     */
+    set enabled(state: boolean);
+    /**
+     * Return this client's enabled state.
+     */
+    get enabled(): boolean;
     /**
      * Return a Promise that resolves once the client has updated.
      */
@@ -34,25 +61,15 @@ export class MosaicClient {
     get filterBy(): Selection;
     /**
      * 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
+     * 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;
     /**
-     * Return an array of fields queried by this client.
-     * @returns {import('./types.js').FieldInfoRequest[] | null}
-     *  The fields to retrieve info for.
-     */
-    fields(): import("./types.js").FieldInfoRequest[] | null;
-    /**
-     * Called by the coordinator to set the field info for this client.
-     * @param {import('./types.js').FieldInfo[]} info The field info result.
-     * @returns {this}
-     */
-    fieldInfo(info: import("./types.js").FieldInfo[]): this;
-    /**
-     * Prepare the client before the query() method is called.
+     * 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>;
     /**
@@ -80,26 +97,31 @@ export class MosaicClient {
     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. This method
-     * has no effect if the client is not registered with a coordinator.
+     * 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} [query] The query to request. If unspecified, the query
+     *  will be determind by the client's `query` method and the current
+     *  `filterBy` selection state.
      * @returns {Promise}
      */
-    requestQuery(query: any): Promise<any>;
+    requestQuery(query?: Query): 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.
+     * 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, initiating new field info, call the prepare method,
-     * and query requests. This method has no effect if the client is not
-     * registered with a coordinator.
-     * @returns {Promise}
+     * 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(): Promise<any>;
+    initialize(): void;
     /**
      * Requests a client update, for example to (re-)render an interface
      * component.
@@ -107,5 +129,6 @@ export class MosaicClient {
      */
     update(): this | Promise<any>;
 }
-import { Selection } from './Selection.js';
-import { Coordinator } from './Coordinator.js';
+import type { Selection } from './Selection.js';
+import type { Coordinator } from './Coordinator.js';
+import type { Query } from '@uwdata/mosaic-sql';

package/dist/types/make-client.d.ts

@@ -1,48 +1,78 @@
 /**
  * @typedef {Object} MakeClientOptions
- * @property {import('./Coordinator.js').Coordinator} [coordinator] - Mosaic coordinator. Default to the global coordinator.
- * @property {import('./Selection.js').Selection|null} [selection] - A selection whose predicates will be fed into the query function to produce the SQL query.
- * @property {function(): Promise<void>} [prepare] - An async function to prepare the client before running queries.
- * @property {function(any): any} query - A function that returns a query from a list of selection predicates.
- * @property {function(any): void} [queryResult] - Called by the coordinator to return a query result.
- * @property {function(): void} [queryPending] - Called by the coordinator to report a query execution error.
- * @property {function(any): void} [queryError] - Called by the coordinator to inform the client that a query is pending.
+ * @property {Coordinator} [coordinator] Mosaic coordinator.
+ *  Defaults to the global coordinator.
+ * @property {Selection|null} [selection] A selection whose predicates are
+ *  fed into the query function to produce the SQL query.
+ * @property {boolean} [enabled] A flag (default `true`) indicating if the
+ *  client should initially be enabled or not.
+ * @property {boolean} [filterStable] A flag (default `true`) indicating if the
+ *  if client queries can be sped up using pre-aggregated data. Should be set
+ *  to `false` if filtering changes the groupby domain of the query.
+ * @property {function(): Promise<void>} [prepare]
+ *  An async function to prepare the client before running queries.
+ * @property {function(any): any} [query]
+ *  A function that returns a query from a list of selection predicates.
+ * @property {function(any): void} [queryResult]
+ *  Called by the coordinator to return a query result.
+ * @property {function(): void} [queryPending]
+ *  Called by the coordinator to report a query execution error.
+ * @property {function(any): void} [queryError]
+ *  Called by the coordinator to inform the client that a query is pending.
  */
-/** Make a new client with the given options, and connect the client to the provided coordinator.
- * @param {MakeClientOptions} options - The options for making the client
- * @returns {MosaicClient & { destroy: () => void }} - The result object with methods to request an update or destroy the client.
+/**
+ * Make a new client with the given options, and connect the client to the
+ * provided coordinator.
+ * @param {MakeClientOptions} options The options for making the client.
+ * @returns {MosaicClient & { destroy: () => void }} The resulting client,
+ *  along with a method to destroy the client when no longer needed.
  */
 export function makeClient(options: MakeClientOptions): MosaicClient & {
     destroy: () => void;
 };
 export type MakeClientOptions = {
     /**
-     * - Mosaic coordinator. Default to the global coordinator.
+     * Mosaic coordinator.
+     * Defaults to the global coordinator.
+     */
+    coordinator?: Coordinator;
+    /**
+     * A selection whose predicates are
+     * fed into the query function to produce the SQL query.
+     */
+    selection?: Selection | null;
+    /**
+     * A flag (default `true`) indicating if the
+     * client should initially be enabled or not.
      */
-    coordinator?: import("./Coordinator.js").Coordinator;
+    enabled?: boolean;
     /**
-     * - A selection whose predicates will be fed into the query function to produce the SQL query.
+     * A flag (default `true`) indicating if the
+     * if client queries can be sped up using pre-aggregated data. Should be set
+     * to `false` if filtering changes the groupby domain of the query.
      */
-    selection?: import("./Selection.js").Selection | null;
+    filterStable?: boolean;
     /**
-     * - An async function to prepare the client before running queries.
+     * An async function to prepare the client before running queries.
      */
     prepare?: () => Promise<void>;
     /**
-     * - A function that returns a query from a list of selection predicates.
+     * A function that returns a query from a list of selection predicates.
      */
-    query: (arg0: any) => any;
+    query?: (arg0: any) => any;
     /**
-     * - Called by the coordinator to return a query result.
+     * Called by the coordinator to return a query result.
      */
     queryResult?: (arg0: any) => void;
     /**
-     * - Called by the coordinator to report a query execution error.
+     * Called by the coordinator to report a query execution error.
      */
     queryPending?: () => void;
     /**
-     * - Called by the coordinator to inform the client that a query is pending.
+     * Called by the coordinator to inform the client that a query is pending.
      */
     queryError?: (arg0: any) => void;
 };
-import { MosaicClient } from "./MosaicClient.js";
+import { MosaicClient } from './MosaicClient.js';
+import type { Coordinator } from './Coordinator.js';
+import type { Selection } from './Selection.js';

package/dist/types/preagg/PreAggregator.d.ts

@@ -27,17 +27,17 @@
 export class PreAggregator {
     /**
      * Create a new manager of materialized views of pre-aggregated data.
-     * @param {import('../Coordinator.js').Coordinator} coordinator A Mosaic coordinator.
+     * @param {Coordinator} coordinator A Mosaic coordinator.
      * @param {PreAggregateOptions} [options] Pre-aggregation options.
      */
-    constructor(coordinator: import("../Coordinator.js").Coordinator, { schema, enabled }?: PreAggregateOptions);
-    /** @type {Map<import('../MosaicClient.js').MosaicClient, PreAggregateInfo | Skip | null>} */
-    entries: Map<import("../MosaicClient.js").MosaicClient, PreAggregateInfo | {
+    constructor(coordinator: Coordinator, { schema, enabled }?: PreAggregateOptions);
+    /** @type {Map<MosaicClient, PreAggregateInfo | Skip | null>} */
+    entries: Map<MosaicClient, PreAggregateInfo | {
         skip: boolean;
         result: any;
     } | null>;
     active: any;
-    mc: import("../Coordinator.js").Coordinator;
+    mc: Coordinator;
     _schema: string;
     _enabled: boolean;
     /**
@@ -88,16 +88,14 @@ export class PreAggregator {
      * client-selection pair, or null if the client has unstable filters.
      * This method has multiple possible side effects, including materialized
      * view creation and updating internal caches.
-     * @param {import('../MosaicClient.js').MosaicClient} client A Mosaic client.
-     * @param {import('../Selection.js').Selection} selection A Mosaic selection
-     *  to filter the client by.
-     * @param {import('../util/selection-types.js').SelectionClause} activeClause
-     *  A representative active selection clause for which to (possibly) generate
-     *  materialized views of pre-aggregates.
+     * @param {MosaicClient} client A Mosaic client.
+     * @param {Selection} selection A Mosaic selection to filter the client by.
+     * @param {SelectionClause} activeClause A representative active selection
+     *  clause for which to generate materialized views of pre-aggregates.
      * @returns {PreAggregateInfo | Skip | null} Information and query generator
      * for pre-aggregated tables, or null if the client has unstable filters.
      */
-    request(client: import("../MosaicClient.js").MosaicClient, selection: import("../Selection.js").Selection, activeClause: import("../util/selection-types.js").SelectionClause): PreAggregateInfo | {
+    request(client: MosaicClient, selection: Selection, activeClause: SelectionClause): PreAggregateInfo | {
         skip: boolean;
         result: any;
     } | null;
@@ -157,11 +155,10 @@ export class PreAggregateInfo {
     skip: boolean;
     /**
      * Generate a materialized view query for the given predicate.
-     * @param {import('@uwdata/mosaic-sql').ExprNode} predicate The current
-     *  active clause predicate.
+     * @param {ExprNode} predicate The current active clause predicate.
      * @returns {SelectQuery} A materialized view query.
      */
-    query(predicate: import("@uwdata/mosaic-sql").ExprNode): SelectQuery;
+    query(predicate: ExprNode): SelectQuery;
 }
 export type PreAggregateOptions = {
     /**
@@ -175,4 +172,9 @@ export type PreAggregateOptions = {
      */
     enabled?: boolean;
 };
+import type { MosaicClient } from '../MosaicClient.js';
+import type { Coordinator } from '../Coordinator.js';
+import type { Selection } from '../Selection.js';
+import type { SelectionClause } from '../util/selection-types.js';
 import { SelectQuery } from '@uwdata/mosaic-sql';
+import type { ExprNode } from '@uwdata/mosaic-sql';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-core",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Scalable and extensible linked data views.",
   "keywords": [
     "mosaic",
@@ -32,10 +32,10 @@
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.29.0",
     "@uwdata/flechette": "^2.0.0",
-    "@uwdata/mosaic-sql": "^0.14.1"
+    "@uwdata/mosaic-sql": "^0.15.0"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.14.1"
+    "@uwdata/mosaic-duckdb": "^0.15.0"
   },
-  "gitHead": "5959cb169e95bd8467e1e5d7a9b98954f09474f3"
+  "gitHead": "671ad1ba86749a8435bd4aa7e722e2a8553f2cb0"
 }

package/src/Coordinator.js

@@ -1,9 +1,12 @@
+/** @import { PreAggregateOptions } from './preagg/PreAggregator.js' */
+/** @import { QueryResult } from './util/query-result.js' */
+/** @import { SelectionClause } from './util/selection-types.js' */
+/** @import { MosaicClient } from './MosaicClient.js' */
+/** @import { Selection } from './Selection.js' */
+/** @import { QueryType } from './types.js' */
 import { socketConnector } from './connectors/socket.js';
 import { PreAggregator } from './preagg/PreAggregator.js';
-import { queryFieldInfo } from './util/field-info.js';
-import { QueryResult } from './util/query-result.js';
 import { voidLogger } from './util/void-logger.js';
-import { MosaicClient } from './MosaicClient.js';
 import { QueryManager, Priority } from './QueryManager.js';
 
 /**
@@ -36,8 +39,7 @@ export function coordinator(instance) {
  * @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.
+ * @param {PreAggregateOptions} [options.preagg] Options for the Pre-aggregator.
  */
 export class Coordinator {
   constructor(db = socketConnector(), {
@@ -110,8 +112,7 @@ export class Coordinator {
 
   /**
    * Issue a query for which no result (return value) is needed.
-   * @param { import('./types.js').QueryType[] |
-   *  import('./types.js').QueryType} query The query or an array of queries.
+   * @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
@@ -126,8 +127,8 @@ export class Coordinator {
   /**
    * Issue a query to the backing database. The submitted query may be
    * consolidate with other queries and its results may be cached.
-   * @param {import('./types.js').QueryType} query The query as either a Query
-   *  builder object or a SQL string.
+   * @param {QueryType} query The query as either a Query builder objec
+   *   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
@@ -150,8 +151,8 @@ export class Coordinator {
   /**
    * Issue a query to prefetch data for later use. The query result is cached
    * for efficient future access.
-   * @param {import('./types.js').QueryType} query The query as either a Query
-   *  builder object or a SQL string.
+   * @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.
@@ -190,7 +191,7 @@ export class Coordinator {
    * Update client data by submitting the given query and returning the
    * data (or error) to the client.
    * @param {MosaicClient} client A Mosaic client.
-   * @param {import('./types.js').QueryType} query The data query.
+   * @param {QueryType} query The data query.
    * @param {number} [priority] The query priority.
    * @returns {Promise} A Promise that resolves upon completion of the update.
    */
@@ -209,7 +210,7 @@ export class Coordinator {
    * 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 {import('./types.js').QueryType | null} [query] The query to issue.
+   * @param {QueryType | null} [query] The query to issue.
    */
   requestQuery(client, query) {
     this.preaggregator.clear();
@@ -236,26 +237,12 @@ export class Coordinator {
     client.coordinator = this;
 
     // initialize client lifecycle
-    client._pending = this.initializeClient(client);
+    client.initialize();
 
     // connect filter selection
     connectSelection(this, client.filterBy, client);
   }
 
-  async initializeClient(client) {
-    // retrieve field statistics
-    const fields = client.fields();
-    if (fields?.length) {
-      client.fieldInfo(await queryFieldInfo(this, fields));
-    }
-
-    // prepare the client
-    await client.prepare();
-
-    // request data query
-    return client.requestQuery();
-  }
-
   /**
    * Disconnect a client from the coordinator.
    * @param {MosaicClient} client The Mosaic client to disconnect.
@@ -276,7 +263,7 @@ export class Coordinator {
 /**
  * Connect a selection-client pair to the coordinator to process updates.
  * @param {Coordinator} mc The Mosaic coordinator.
- * @param {import('./Selection.js').Selection} selection A selection.
+ * @param {Selection} selection A selection.
  * @param {MosaicClient} client A Mosiac client that is filtered by the
  *  given selection.
  */
@@ -308,15 +295,16 @@ function connectSelection(mc, selection, client) {
  * next updates. Activation provides a preview of likely next events,
  * enabling potential precomputation to optimize updates.
  * @param {Coordinator} mc The Mosaic coordinator.
- * @param {import('./Selection.js').Selection} selection A selection.
- * @param {import('./util/selection-types.js').SelectionClause} clause A
- *  selection clause representative of the activation.
+ * @param {Selection} selection A selection.
+ * @param {SelectionClause} clause A selection clause for the activation.
  */
 function activateSelection(mc, selection, clause) {
   const { preaggregator, filterGroups } = mc;
   const { clients } = filterGroups.get(selection);
   for (const client of clients) {
-    preaggregator.request(client, selection, clause);
+    if (client.enabled) {
+      preaggregator.request(client, selection, clause);
+    }
   }
 }
 
@@ -324,7 +312,7 @@ function activateSelection(mc, selection, clause) {
  * Process an updated selection value, querying filtered data for any
  * associated clients.
  * @param {Coordinator} mc The Mosaic coordinator.
- * @param {import('./Selection.js').Selection} selection A selection.
+ * @param {Selection} selection A selection.
  * @returns {Promise} A Promise that resolves when the update completes.
  */
 function updateSelection(mc, selection) {
@@ -332,6 +320,7 @@ function updateSelection(mc, selection) {
   const { clients } = filterGroups.get(selection);
   const { active } = selection;
   return Promise.allSettled(Array.from(clients, client => {
+    if (!client.enabled) return client.requestQuery();
     const info = preaggregator.request(client, selection, active);
     const filter = info ? null : selection.predicate(client);
 

package/src/MosaicClient.js

@@ -1,16 +1,30 @@
-import { Coordinator } from './Coordinator.js';
-import { Selection } from './Selection.js';
+/** @import { Query } from '@uwdata/mosaic-sql' */
+/** @import { Coordinator } from './Coordinator.js' */
+/** @import { Selection } from './Selection.js' */
 import { throttle } from './util/throttle.js';
 
 /**
- * Base class for Mosaic clients.
+ * 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 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.
+   * Create a new client instance.
+   * @param {Selection} [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) {
     /** @type {Selection} */
@@ -20,6 +34,12 @@ export class MosaicClient {
     this._coordinator = null;
     /** @type {Promise<any>} */
     this._pending = Promise.resolve();
+    /** @type {boolean} */
+    this._enabled = true;
+    /** @type {boolean} */
+    this._initialized = false;
+    /** @type {Query | boolean} */
+    this._request = null;
   }
 
   /**
@@ -36,6 +56,33 @@ export class MosaicClient {
     this._coordinator = coordinator;
   }
 
+  /**
+   * Return this client's enabled state.
+   */
+  get enabled() {
+    return this._enabled;
+  }
+
+  /**
+   * Set this client's enabled state;
+   */
+  set enabled(state) {
+    state = !!state; // ensure boolean
+    if (this._enabled !== state) {
+      this._enabled = state;
+      if (state) {
+        if (!this._initialized) {
+          // initialization includes a query request
+          this.initialize();
+        } else if (this._request) {
+          // request query now if requested while disabled
+          this.requestQuery(this._request === true ? undefined : this._request);
+        }
+        this._request = null;
+      }
+    }
+  }
+
   /**
    * Return a Promise that resolves once the client has updated.
    */
@@ -52,8 +99,8 @@ export class MosaicClient {
 
   /**
    * 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
+   * 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() {
@@ -61,25 +108,9 @@ export class MosaicClient {
   }
 
   /**
-   * Return an array of fields queried by this client.
-   * @returns {import('./types.js').FieldInfoRequest[] | null}
-   *  The fields to retrieve info for.
-   */
-  fields() {
-    return null;
-  }
-
-  /**
-   * Called by the coordinator to set the field info for this client.
-   * @param {import('./types.js').FieldInfo[]} info The field info result.
-   * @returns {this}
-   */
-  fieldInfo(info) { // eslint-disable-line no-unused-vars
-    return this;
-  }
-
-  /**
-   * Prepare the client before the query() method is called.
+   * 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.
    */
   async prepare() {
   }
@@ -122,34 +153,55 @@ export class MosaicClient {
 
   /**
    * 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 registered with a coordinator.
+   * 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} [query] The query to request. If unspecified, the query
+   *  will be determind by the client's `query` method and the current
+   *  `filterBy` selection state.
    * @returns {Promise}
    */
   requestQuery(query) {
-    const q = query || this.query(this.filterBy?.predicate(this));
-    return this._coordinator?.requestQuery(this, q);
+    if (this._enabled) {
+      const q = query || this.query(this.filterBy?.predicate(this));
+      return this._coordinator?.requestQuery(this, q);
+    } else {
+      this._request = query ?? true;
+      return null;
+    }
   }
 
   /**
    * 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.
+   * 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() {
-    this._requestUpdate();
+    if (this._enabled) {
+      this._requestUpdate();
+    } else {
+      this.requestQuery();
+    }
   }
 
   /**
-   * Reset this client, initiating new field info, call the prepare method,
-   * and query requests. This method has no effect if the client is not
-   * registered with a coordinator.
-   * @returns {Promise}
+   * 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() {
-    return this._coordinator?.initializeClient(this);
+    if (!this._enabled) {
+      // clear flag so we initialize when enabled again
+      this._initialized = false;
+    } else if (this._coordinator) {
+      // if connected, let's initialize
+      this._initialized = true;
+      this._pending = this.prepare().then(() => this.requestQuery());
+    }
   }
 
   /**

package/src/make-client.js

@@ -1,64 +1,105 @@
-import { MosaicClient } from "./MosaicClient.js";
-import {
-  coordinator as defaultCoordinator,
-} from "./Coordinator.js";
+/** @import { Coordinator } from './Coordinator.js' */
+/** @import { Selection } from './Selection.js' */
+import { MosaicClient } from './MosaicClient.js';
+import { coordinator as defaultCoordinator } from './Coordinator.js';
 
 /**
  * @typedef {Object} MakeClientOptions
- * @property {import('./Coordinator.js').Coordinator} [coordinator] - Mosaic coordinator. Default to the global coordinator.
- * @property {import('./Selection.js').Selection|null} [selection] - A selection whose predicates will be fed into the query function to produce the SQL query.
- * @property {function(): Promise<void>} [prepare] - An async function to prepare the client before running queries.
- * @property {function(any): any} query - A function that returns a query from a list of selection predicates.
- * @property {function(any): void} [queryResult] - Called by the coordinator to return a query result.
- * @property {function(): void} [queryPending] - Called by the coordinator to report a query execution error.
- * @property {function(any): void} [queryError] - Called by the coordinator to inform the client that a query is pending.
+ * @property {Coordinator} [coordinator] Mosaic coordinator.
+ *  Defaults to the global coordinator.
+ * @property {Selection|null} [selection] A selection whose predicates are
+ *  fed into the query function to produce the SQL query.
+ * @property {boolean} [enabled] A flag (default `true`) indicating if the
+ *  client should initially be enabled or not.
+ * @property {boolean} [filterStable] A flag (default `true`) indicating if the
+ *  if client queries can be sped up using pre-aggregated data. Should be set
+ *  to `false` if filtering changes the groupby domain of the query.
+ * @property {function(): Promise<void>} [prepare]
+ *  An async function to prepare the client before running queries.
+ * @property {function(any): any} [query]
+ *  A function that returns a query from a list of selection predicates.
+ * @property {function(any): void} [queryResult]
+ *  Called by the coordinator to return a query result.
+ * @property {function(): void} [queryPending]
+ *  Called by the coordinator to report a query execution error.
+ * @property {function(any): void} [queryError]
+ *  Called by the coordinator to inform the client that a query is pending.
  */
 
-/** Make a new client with the given options, and connect the client to the provided coordinator.
- * @param {MakeClientOptions} options - The options for making the client
- * @returns {MosaicClient & { destroy: () => void }} - The result object with methods to request an update or destroy the client.
+/**
+ * Make a new client with the given options, and connect the client to the
+ * provided coordinator.
+ * @param {MakeClientOptions} options The options for making the client.
+ * @returns {MosaicClient & { destroy: () => void }} The resulting client,
+ *  along with a method to destroy the client when no longer needed.
  */
 export function makeClient(options) {
-  const coordinator = options.coordinator ?? defaultCoordinator();
-  const client = new ProxyClient({ ...options, coordinator });
+  const {
+    coordinator = defaultCoordinator(),
+    ...clientOptions
+  } = options;
+  const client = new ProxyClient(clientOptions);
   coordinator.connect(client);
   return client;
 }
 
-/** An internal class used to implement the makeClient API */
+/**
+ * An internal class used to implement the makeClient API.
+ */
 class ProxyClient extends MosaicClient {
-  /** @param {MakeClientOptions} options */
-  constructor(options) {
-    super(options.selection);
+  /**
+   * @param {MakeClientOptions} options The options for making the client.
+   */
+  constructor({
+    selection = undefined,
+    enabled = true,
+    filterStable = true,
+    ...methods
+  }) {
+    super(selection);
+    this.enabled = enabled;
+
+    /**
+     * @type {MakeClientOptions}
+     * @readonly
+     */
+    this._methods = methods;
+
+    /**
+     * @type {boolean}
+     * @readonly
+     */
+    this._filterStable = filterStable;
+  }
 
-    /** @type {MakeClientOptions} */
-    this._options = { ...options };
+  get filterStable() {
+    return this._filterStable;
   }
 
   async prepare() {
-    await this._options.prepare?.();
+    await this._methods.prepare?.();
   }
 
   query(filter) {
-    return this._options.query(filter);
+    return this._methods.query?.(filter) ?? null;
   }
 
   queryResult(data) {
-    this._options.queryResult?.(data);
+    this._methods.queryResult?.(data);
     return this;
   }
 
   queryPending() {
-    this._options.queryPending?.();
+    this._methods.queryPending?.();
     return this;
   }
 
   queryError(error) {
-    this._options.queryError?.(error);
+    this._methods.queryError?.(error);
     return this;
   }
 
   destroy() {
-    this._options.coordinator.disconnect(this);
+    this.coordinator.disconnect(this);
   }
 }

package/src/preagg/PreAggregator.js

@@ -1,4 +1,9 @@
-import { Query, and, asNode, ceil, collectColumns, createTable, float64, floor, isBetween, int32, mul, round, scaleTransform, sub, isSelectQuery, ExprNode, SelectQuery, isAggregateExpression, ColumnNameRefNode } from '@uwdata/mosaic-sql';
+/** @import { ExprNode } from '@uwdata/mosaic-sql' */
+/** @import { Coordinator } from '../Coordinator.js' */
+/** @import { MosaicClient } from '../MosaicClient.js' */
+/** @import { Selection } from '../Selection.js' */
+/** @import { BinMethod, Scale, SelectionClause } from '../util/selection-types.js' */
+import { Query, and, asNode, ceil, collectColumns, createTable, float64, floor, isBetween, int32, mul, round, scaleTransform, sub, isSelectQuery, SelectQuery, isAggregateExpression, ColumnNameRefNode } from '@uwdata/mosaic-sql';
 import { preaggColumns } from './preagg-columns.js';
 import { fnv_hash } from '../util/hash.js';
 
@@ -34,14 +39,14 @@ const Skip = { skip: true, result: null };
 export class PreAggregator {
   /**
    * Create a new manager of materialized views of pre-aggregated data.
-   * @param {import('../Coordinator.js').Coordinator} coordinator A Mosaic coordinator.
+   * @param {Coordinator} coordinator A Mosaic coordinator.
    * @param {PreAggregateOptions} [options] Pre-aggregation options.
    */
   constructor(coordinator, {
     schema = 'mosaic',
     enabled = true
   } = {}) {
-    /** @type {Map<import('../MosaicClient.js').MosaicClient, PreAggregateInfo | Skip | null>} */
+    /** @type {Map<MosaicClient, PreAggregateInfo | Skip | null>} */
     this.entries = new Map();
     this.active = null;
     this.mc = coordinator;
@@ -123,12 +128,10 @@ export class PreAggregator {
    * client-selection pair, or null if the client has unstable filters.
    * This method has multiple possible side effects, including materialized
    * view creation and updating internal caches.
-   * @param {import('../MosaicClient.js').MosaicClient} client A Mosaic client.
-   * @param {import('../Selection.js').Selection} selection A Mosaic selection
-   *  to filter the client by.
-   * @param {import('../util/selection-types.js').SelectionClause} activeClause
-   *  A representative active selection clause for which to (possibly) generate
-   *  materialized views of pre-aggregates.
+   * @param {MosaicClient} client A Mosaic client.
+   * @param {Selection} selection A Mosaic selection to filter the client by.
+   * @param {SelectionClause} activeClause A representative active selection
+   *  clause for which to generate materialized views of pre-aggregates.
    * @returns {PreAggregateInfo | Skip | null} Information and query generator
    * for pre-aggregated tables, or null if the client has unstable filters.
    */
@@ -205,8 +208,7 @@ export class PreAggregator {
  * function for the active dimensions of a pre-aggregated materialized view.
  * If the active clause is not indexable or is missing metadata, this method
  * returns an object with a null source property.
- * @param {import('../util/selection-types.js').SelectionClause} clause
- *  The active selection clause to analyze.
+ * @param {SelectionClause} clause The active selection clause to analyze.
  */
 function activeColumns(clause) {
   const { source, meta } = clause;
@@ -261,12 +263,12 @@ const BIN = { ceil, round };
 
 /**
  * Returns a bin function generator to discretize a selection interval domain.
- * @param {import('../util/selection-types.js').Scale} scale A scale that maps
- *  domain values to the output range (typically pixels).
+ * @param {Scale} scale A scale that maps domain values to the output range
+ *  (typically pixels).
  * @param {number} pixelSize The interactive pixel size. This value indicates
  *  the bin step size and may be greater than an actual screen pixel.
- * @param {import('../util/selection-types.js').BinMethod} bin The binning
- *  method to apply, one of `floor`, `ceil', or `round`.
+ * @param {BinMethod} bin The binning method to apply, one of `floor`,
+ *  `ceil', or `round`.
  * @returns {(value: any) => ExprNode} A bin function generator.
  */
 function binInterval(scale, pixelSize, bin) {
@@ -426,8 +428,7 @@ export class PreAggregateInfo {
 
   /**
    * Generate a materialized view query for the given predicate.
-   * @param {import('@uwdata/mosaic-sql').ExprNode} predicate The current
-   *  active clause predicate.
+   * @param {ExprNode} predicate The current active clause predicate.
    * @returns {SelectQuery} A materialized view query.
    */
   query(predicate) {