@uwdata/mosaic-core 0.12.1 → 0.13.0

package/dist/types/Coordinator.d.ts

@@ -4,9 +4,6 @@
  * @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
@@ -73,44 +70,48 @@ export class Coordinator {
     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.
+     * @param { import('./types.js').QueryType[] |
+     *  import('./types.js').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.
+     * @returns {QueryResult} A query result promise.
      */
-    exec(query: QueryType | QueryType[], { priority }?: {
+    exec(query: import("./types.js").QueryType[] | import("./types.js").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 {import('./types.js').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 {boolean} [options.cache=true] If true, cache the query result
+     *  client-side within the QueryManager.
+     * @param {boolean} [options.persist] If true, request the database
+     *  server to persist a cached query server-side.
      * @param {number} [options.priority] The query priority, defaults to
      *  `Priority.Normal`.
      * @returns {QueryResult} A query result promise.
      */
-    query(query: QueryType, { type, cache, priority, ...options }?: {
+    query(query: import("./types.js").QueryType, { type, cache, priority, ...options }?: {
         type?: "arrow" | "json";
         cache?: boolean;
+        persist?: 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 {import('./types.js').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?: {
+    prefetch(query: import("./types.js").QueryType, options?: {
         type?: "arrow" | "json";
     }): QueryResult;
     /**
@@ -137,19 +138,19 @@ 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 {QueryType} query The data query.
+     * @param {import('./types.js').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>;
+    updateClient(client: MosaicClient, query: import("./types.js").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.
+     * @param {import('./types.js').QueryType | null} [query] The query to issue.
      */
-    requestQuery(client: MosaicClient, query?: QueryType | null): Promise<any>;
+    requestQuery(client: MosaicClient, query?: import("./types.js").QueryType | null): Promise<any>;
     /**
      * Connect a client to the coordinator.
      * @param {MosaicClient} client The Mosaic client to connect.
@@ -162,7 +163,6 @@ export class Coordinator {
      */
     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';

package/dist/types/MosaicClient.d.ts

@@ -9,21 +9,29 @@ export class MosaicClient {
      *  the client when the selection updates.
      */
     constructor(filterSelection: any);
-    _filterBy: any;
+    /** @type {Selection} */
+    _filterBy: Selection;
     _requestUpdate: (event: any) => void;
-    _coordinator: any;
+    /** @type {Coordinator} */
+    _coordinator: Coordinator;
+    /** @type {Promise<any>} */
+    _pending: Promise<any>;
     /**
      * Set this client's connected coordinator.
      */
-    set coordinator(coordinator: any);
+    set coordinator(coordinator: Coordinator);
     /**
      * Return this client's connected coordinator.
      */
-    get coordinator(): any;
+    get coordinator(): Coordinator;
+    /**
+     * Return a Promise that resolves once the client has updated.
+     */
+    get pending(): Promise<any>;
     /**
      * Return this client's filter selection.
      */
-    get filterBy(): any;
+    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
@@ -33,15 +41,20 @@ export class MosaicClient {
     get filterStable(): boolean;
     /**
      * Return an array of fields queried by this client.
-     * @returns {object[]|null} The fields to retrieve info for.
+     * @returns {import('./types.js').FieldInfoRequest[] | null}
+     *  The fields to retrieve info for.
      */
-    fields(): object[] | null;
+    fields(): import("./types.js").FieldInfoRequest[] | null;
     /**
      * Called by the coordinator to set the field info for this client.
-     * @param {*} info The field info result.
+     * @param {import('./types.js').FieldInfo[]} info The field info result.
      * @returns {this}
      */
-    fieldInfo(info: any): this;
+    fieldInfo(info: import("./types.js").FieldInfo[]): this;
+    /**
+     * Prepare the client before the query() method is called.
+     */
+    prepare(): Promise<void>;
     /**
      * Return a query specifying the data needed by this client.
      * @param {*} [filter] The filtering criteria to apply in the query.
@@ -80,7 +93,7 @@ export class MosaicClient {
      */
     requestUpdate(): void;
     /**
-     * Reset this client, initiating new field info and query requests.
+     * Reset this client, initiating new field info, call the prepare method, and query requests.
      * @returns {Promise}
      */
     initialize(): Promise<any>;
@@ -92,3 +105,5 @@ export class MosaicClient {
      */
     update(): this | Promise<any>;
 }
+import { Selection } from './Selection.js';
+import { Coordinator } from './Coordinator.js';

package/dist/types/QueryManager.d.ts

@@ -5,6 +5,7 @@ export const Priority: Readonly<{
 }>;
 export class QueryManager {
     constructor(maxConcurrentRequests?: number);
+    /** @type {PriorityQueue} */
     queue: PriorityQueue;
     db: any;
     clientCache: any;
@@ -21,11 +22,12 @@ export class QueryManager {
     };
     /**
      * Requests pending with the query manager.
-     *
      * @type {QueryResult[]}
      */
     pendingResults: QueryResult[];
+    /** @type {number} */
     maxConcurrentRequests: number;
+    /** @type {boolean} */
     pendingExec: boolean;
     next(): void;
     /**

package/dist/types/SelectionClause.d.ts

@@ -23,7 +23,7 @@ export function clausePoint(field: import("@uwdata/mosaic-sql").ExprValue, value
 /**
  * Generate a selection clause for multiple selected point values.
  * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {any[][] | undefined} value The selected values, as an array of
+ * @param {any[][] | null | undefined} value The selected values, as an array of
  *  arrays. Each subarray contains values for each *fields* entry.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
@@ -32,14 +32,14 @@ export function clausePoint(field: import("@uwdata/mosaic-sql").ExprValue, value
  *  cross-filtering contexts.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clausePoints(fields: import("@uwdata/mosaic-sql").ExprValue[], value: any[][] | undefined, { source, clients }: {
+export function clausePoints(fields: import("@uwdata/mosaic-sql").ExprValue[], value: any[][] | null | undefined, { source, clients }: {
     source: any;
     clients?: Set<MosaicClient>;
 }): SelectionClause;
 /**
  * Generate a selection clause for a selected 1D interval.
  * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {Extent} value The selected interval as a [lo, hi] array.
+ * @param {Extent | null | undefined} value The selected interval as a [lo, hi] array.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -50,7 +50,7 @@ export function clausePoints(fields: import("@uwdata/mosaic-sql").ExprValue[], v
  * @param {number} [options.pixelSize=1] The interactive pixel size.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, value: Extent, { source, clients, bin, scale, pixelSize }: {
+export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, value: Extent | null | undefined, { source, clients, bin, scale, pixelSize }: {
     source: any;
     clients?: Set<MosaicClient>;
     scale?: Scale;
@@ -60,7 +60,7 @@ export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, va
 /**
  * Generate a selection clause for multiple selected intervals.
  * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {Extent[]} value The selected intervals, as an array of extents.
+ * @param {Extent[] | null | undefined} value The selected intervals, as an array of extents.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -72,7 +72,7 @@ export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, va
  * @param {number} [options.pixelSize=1] The interactive pixel size.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[], value: Extent[], { source, clients, bin, scales, pixelSize }: {
+export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[], value: Extent[] | null | undefined, { source, clients, bin, scales, pixelSize }: {
     source: any;
     clients?: Set<MosaicClient>;
     scales?: Scale[];
@@ -82,7 +82,7 @@ export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[]
 /**
  * Generate a selection clause for text search matching.
  * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {string} value The selected text search query string.
+ * @param {string | null | undefined} value The selected text search query string.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -92,7 +92,7 @@ export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[]
  *  text matching method to use. Defaults to `'contains'`.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clauseMatch(field: import("@uwdata/mosaic-sql").ExprValue, value: string, { source, clients, method }: {
+export function clauseMatch(field: import("@uwdata/mosaic-sql").ExprValue, value: string | null | undefined, { source, clients, method }: {
     source: any;
     clients?: Set<MosaicClient>;
     method?: MatchMethod;

package/dist/types/index-types.d.ts

@@ -0,0 +1,3 @@
+export * from './index.js';
+export * from './types.js';
+export * from './util/selection-types.js';

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export { MosaicClient } from "./MosaicClient.js";
+export { makeClient } from "./make-client.js";
 export { Priority } from "./QueryManager.js";
 export { restConnector } from "./connectors/rest.js";
 export { socketConnector } from "./connectors/socket.js";
@@ -9,16 +10,9 @@ export { isArrowTable } from "./util/is-arrow-table.js";
 export { synchronizer } from "./util/synchronizer.js";
 export { throttle } from "./util/throttle.js";
 export { toDataColumns } from "./util/to-data-columns.js";
-export type ClauseMetadata = import("./util/selection-types.js").ClauseMetadata;
-export type PointMetadata = import("./util/selection-types.js").PointMetadata;
-export type MatchMethod = import("./util/selection-types.js").MatchMethod;
-export type MatchMetadata = import("./util/selection-types.js").MatchMetadata;
-export type ScaleType = import("./util/selection-types.js").ScaleType;
-export type Extent = import("./util/selection-types.js").Extent;
-export type Scale = import("./util/selection-types.js").Scale;
-export type BinMethod = import("./util/selection-types.js").BinMethod;
-export type IntervalMetadata = import("./util/selection-types.js").IntervalMetadata;
-export type SelectionClause = import("./util/selection-types.js").SelectionClause;
+export { queryFieldInfo } from "./util/field-info.js";
+export { jsType } from "./util/js-type.js";
+export { isActivatable } from "./util/is-activatable.js";
 export { Coordinator, coordinator } from "./Coordinator.js";
 export { Selection, isSelection } from "./Selection.js";
 export { Param, isParam } from "./Param.js";

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

@@ -0,0 +1,48 @@
+/**
+ * @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.
+ */
+/** 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.
+ */
+export function makeClient(options: MakeClientOptions): MosaicClient & {
+    destroy: () => void;
+};
+export type MakeClientOptions = {
+    /**
+     * - Mosaic coordinator. Default to the global coordinator.
+     */
+    coordinator?: import("./Coordinator.js").Coordinator;
+    /**
+     * - A selection whose predicates will be fed into the query function to produce the SQL query.
+     */
+    selection?: import("./Selection.js").Selection | null;
+    /**
+     * - 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.
+     */
+    query: (arg0: any) => any;
+    /**
+     * - Called by the coordinator to return a query result.
+     */
+    queryResult?: (arg0: any) => void;
+    /**
+     * - 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.
+     */
+    queryError?: (arg0: any) => void;
+};
+import { MosaicClient } from "./MosaicClient.js";

package/dist/types/types.d.ts

@@ -0,0 +1,42 @@
+import type { DescribeQuery, ExprNode, Query } from '@uwdata/mosaic-sql';
+/** Query type accepted by a coordinator. */
+export type QueryType = string | Query | DescribeQuery;
+/** String indicating a JavaScript data type. */
+export type JSType = 'number' | 'date' | 'boolean' | 'string' | 'array' | 'object';
+/** String indicating a requested summary statistic. */
+export type Stat = 'count' | 'nulls' | 'max' | 'min' | 'distinct';
+/** A reference to a database column or expression. */
+export type FieldRef = string | ExprNode;
+/**
+ * A request for metadata information about a database column.
+ */
+export interface FieldInfoRequest {
+    table: string;
+    column: FieldRef;
+    stats?: Stat[];
+}
+/**
+ * A response with metadata information about a database column.
+ */
+export interface FieldInfo extends Partial<Record<Stat, number>> {
+    table: string;
+    column: string;
+    sqlType: string;
+    type: JSType;
+    nullable: boolean;
+}
+/** A result row from a DESCRIBE query. */
+export interface ColumnDescription {
+    column_name: string;
+    column_type: string;
+    null: 'YES' | 'NO';
+}
+/**
+ * Interface for components that perform selection activation.
+ */
+export interface Activatable {
+    /**
+     * Activate the selection that this component publishes to.
+     */
+    activate(): void;
+}

package/dist/types/util/field-info.d.ts

@@ -1,4 +1,14 @@
-export function queryFieldInfo(mc: any, fields: any): Promise<any[]>;
+/**
+ * Queries information about fields of a table.
+ * If the `fields` array contains a single field with the column set to '*',
+ * the function will retrieve and return the table information using `getTableInfo`.
+ * Otherwise, it will query individual field information using `getFieldInfo`
+ * for each field in the `fields` array.
+ * @param {import('../Coordinator.js').Coordinator} mc A Mosaic coordinator.
+ * @param {import('../types.js').FieldInfoRequest[]} fields
+ * @returns {Promise<import('../types.js').FieldInfo[]>}
+ */
+export function queryFieldInfo(mc: import("../Coordinator.js").Coordinator, fields: import("../types.js").FieldInfoRequest[]): Promise<import("../types.js").FieldInfo[]>;
 export const Count: "count";
 export const Nulls: "nulls";
 export const Max: "max";

package/dist/types/util/is-activatable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Test if a value implements the Activatable interface.
+ * @param {*} value The value to test.
+ * @returns {value is import('../types.js').Activatable}
+ */
+export function isActivatable(value: any): value is import("../types.js").Activatable;

package/dist/types/util/js-type.d.ts

@@ -1 +1,7 @@
-export function jsType(type: any): "string" | "number" | "date" | "boolean" | "array" | "object";
+/**
+ * Maps a SQL data type to its corresponding JavaScript type.
+ * @param {string} type The name of a SQL data type
+ * @returns {import('../types.js').JSType} The corresponding JavaScript type name
+ * @throws {Error} Throws an error if the given SQL type name is unsupported or unrecognized.
+ */
+export function jsType(type: string): import("../types.js").JSType;

package/dist/types/util/throttle.d.ts

@@ -3,9 +3,11 @@
  * a Promise. Upon repeated invocation, the callback will not be invoked
  * until a prior Promise resolves. If multiple invocations occurs while
  * waiting, only the most recent invocation will be pending.
- * @param {(event: *) => Promise} callback The callback function.
+ * @template E, T
+ * @param {(event: E) => Promise<T>} callback The callback function.
  * @param {boolean} [debounce=true] Flag indicating if invocations
  *  should also be debounced within the current animation frame.
- * @returns A new function that throttles access to the callback.
+ * @returns {(event: E) => void} A new function that throttles
+ *  access to the callback.
  */
-export function throttle(callback: (event: any) => Promise<any>, debounce?: boolean): (event: any) => void;
+export function throttle<E, T>(callback: (event: E) => Promise<T>, debounce?: boolean): (event: E) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-core",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Scalable and extensible linked data views.",
   "keywords": [
     "mosaic",
@@ -12,30 +12,30 @@
   "license": "BSD-3-Clause",
   "author": "Jeffrey Heer (https://idl.uw.edu)",
   "type": "module",
-  "main": "src/index.js",
-  "module": "src/index.js",
-  "jsdelivr": "dist/mosaic-core.min.js",
-  "unpkg": "dist/mosaic-core.min.js",
-  "types": "dist/types/index.d.ts",
+  "exports": {
+    "types": "./dist/types/index-types.d.ts",
+    "default": "./src/index.js"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/uwdata/mosaic.git"
   },
   "scripts": {
     "prebuild": "rimraf dist && mkdir dist",
-    "build": "npm run types && node ../../esbuild.js mosaic-core",
+    "build": "npm run types",
     "types": "tsc",
     "lint": "eslint src test",
-    "test": "vitest run && tsc -p jsconfig.json",
+    "test": "vitest run && npm run tsc",
+    "tsc": "tsc -p jsconfig.json",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.29.0",
-    "@uwdata/flechette": "^1.1.1",
-    "@uwdata/mosaic-sql": "^0.12.1"
+    "@uwdata/flechette": "^2.0.0",
+    "@uwdata/mosaic-sql": "^0.13.0"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.12.1"
+    "@uwdata/mosaic-duckdb": "^0.13.0"
   },
-  "gitHead": "fe3a7c34352da54ec36a1ebf557846f46a649782"
+  "gitHead": "b5a0e03e200c0f04c46562a288f084ffc9f6ad55"
 }

package/src/Coordinator.js

@@ -26,10 +26,6 @@ export function coordinator(instance) {
   return _instance;
 }
 
-/**
- * @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
@@ -114,13 +110,13 @@ export class Coordinator {
 
   /**
    * Issue a query for which no result (return value) is needed.
-   * @param {QueryType | QueryType[]} query The query or an array of queries.
+   * @param { import('./types.js').QueryType[] |
+   *  import('./types.js').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.
+   * @returns {QueryResult} A query result promise.
    */
   exec(query, { priority = Priority.Normal } = {}) {
     query = Array.isArray(query) ? query.filter(x => x).join(';\n') : query;
@@ -130,11 +126,14 @@ 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 {QueryType} query The query as either a Query builder object
-   *  or a SQL string.
+   * @param {import('./types.js').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 {boolean} [options.cache=true] If true, cache the query result
+   *  client-side within the QueryManager.
+   * @param {boolean} [options.persist] If true, request the database
+   *  server to persist a cached query server-side.
    * @param {number} [options.priority] The query priority, defaults to
    *  `Priority.Normal`.
    * @returns {QueryResult} A query result promise.
@@ -151,8 +150,8 @@ export class Coordinator {
   /**
    * 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 {import('./types.js').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.
@@ -191,13 +190,13 @@ 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 {QueryType} query The data query.
+   * @param {import('./types.js').QueryType} query The data query.
    * @param {number} [priority] The query priority.
    * @returns {Promise} A Promise that resolves upon completion of the update.
    */
   updateClient(client, query, priority = Priority.Normal) {
     client.queryPending();
-    return this.query(query, { priority })
+    return client._pending = this.query(query, { priority })
       .then(
         data => client.queryResult(data).update(),
         err => { this._logger.error(err); client.queryError(err); }
@@ -210,7 +209,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 {QueryType | null} [query] The query to issue.
+   * @param {import('./types.js').QueryType | null} [query] The query to issue.
    */
   requestQuery(client, query) {
     this.preaggregator.clear();
@@ -233,7 +232,7 @@ export class Coordinator {
     client.coordinator = this;
 
     // initialize client lifecycle
-    this.initializeClient(client);
+    client._pending = this.initializeClient(client);
 
     // connect filter selection
     connectSelection(this, client.filterBy, client);
@@ -246,6 +245,9 @@ export class Coordinator {
       client.fieldInfo(await queryFieldInfo(this, fields));
     }
 
+    // prepare the client
+    await client.prepare();
+
     // request data query
     return client.requestQuery();
   }