@uwdata/mosaic-core 0.12.2 → 0.14.0

package/dist/types/Coordinator.d.ts

@@ -70,22 +70,22 @@ 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
@@ -96,7 +96,7 @@ export class Coordinator {
      *  `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;
@@ -105,13 +105,13 @@ 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.
      */
-    prefetch(query: QueryType, options?: {
+    prefetch(query: import("./types.js").QueryType, options?: {
         type?: "arrow" | "json";
     }): QueryResult;
     /**
@@ -138,24 +138,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 {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.
      */
-    connect(client: MosaicClient): Promise<void>;
+    connect(client: MosaicClient): void;
     initializeClient(client: any): Promise<any>;
     /**
      * Disconnect a client from the coordinator.
@@ -163,7 +163,6 @@ export class Coordinator {
      */
     disconnect(client: MosaicClient): void;
 }
-export type QueryType = import("@uwdata/mosaic-sql").Query | import("@uwdata/mosaic-sql").DescribeQuery | 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
@@ -43,6 +51,10 @@ export class MosaicClient {
      * @returns {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.
@@ -69,7 +81,8 @@ 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.
+     * be called, filtered by the current filterBy selection. This method
+     * has no effect if the client is not registered with a coordinator.
      * @returns {Promise}
      */
     requestQuery(query: any): Promise<any>;
@@ -81,15 +94,18 @@ 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. This method has no effect if the client is not
+     * registered with a coordinator.
      * @returns {Promise}
      */
     initialize(): Promise<any>;
     /**
-     * Requests a client update.
-     * For example to (re-)render an interface component.
-     *
+     * Requests a client update, for example to (re-)render an interface
+     * component.
      * @returns {this | Promise<any>}
      */
     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/Selection.d.ts

@@ -133,15 +133,25 @@ export class Selection extends Param {
     valueFor(source: any): any;
     /**
      * Emit an activate event with the given selection clause.
-     * @param {*} clause The clause repesenting the potential activation.
+     * @param {SelectionClause} clause The clause repesenting the potential activation.
      */
-    activate(clause: any): void;
+    activate(clause: SelectionClause): void;
     /**
      * Update the selection with a new selection clause.
-     * @param {*} clause The selection clause to add.
+     * @param {SelectionClause} clause The selection clause to add.
      * @returns {this} This Selection instance.
      */
-    update(clause: any): this;
+    update(clause: SelectionClause): this;
+    /**
+     * Reset the selection state by removing all provided clauses. If no clause
+     * array is provided as an argument, all current clauses are removed. The
+     * reset method (if defined) is invoked on all corresponding clause sources.
+     * The reset is relayed to downstream selections that include this selection.
+     * @param {SelectionClause[]} [clauses] The clauses to remove. If
+     *  unspecified, all current clauses are removed.
+     * @returns {this} This selection instance.
+     */
+    reset(clauses?: SelectionClause[]): this;
     /**
      * Indicates if a selection clause should not be applied to a given client.
      * The return value depends on the selection resolution strategy.
@@ -221,4 +231,5 @@ export class SelectionResolver {
     queueFilter(value: any): (value: any) => boolean | null;
 }
 import { Param } from './Param.js';
+import type { SelectionClause } from './util/selection-types.js';
 import { MosaicClient } from './MosaicClient.js';

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";
@@ -11,16 +12,7 @@ export { throttle } from "./util/throttle.js";
 export { toDataColumns } from "./util/to-data-columns.js";
 export { queryFieldInfo } from "./util/field-info.js";
 export { jsType } from "./util/js-type.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 { 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

@@ -1,4 +1,6 @@
-import type { ExprNode } from '@uwdata/mosaic-sql';
+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. */
@@ -29,3 +31,12 @@ export interface ColumnDescription {
     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/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/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.2",
+  "version": "0.14.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.2"
+    "@uwdata/flechette": "^2.0.0",
+    "@uwdata/mosaic-sql": "^0.14.0"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.12.2"
+    "@uwdata/mosaic-duckdb": "^0.14.0"
   },
-  "gitHead": "0ca741d840b98039255f26a5ceedf10be66f790e"
+  "gitHead": "a882aab60867e4e9d9738bc950aa9de32729a806"
 }

package/src/Coordinator.js

@@ -6,12 +6,6 @@ import { voidLogger } from './util/void-logger.js';
 import { MosaicClient } from './MosaicClient.js';
 import { QueryManager, Priority } from './QueryManager.js';
 
-/**
- * @typedef {import('@uwdata/mosaic-sql').Query
- *  | import('@uwdata/mosaic-sql').DescribeQuery
- *  | string} QueryType
- */
-
 /**
  * The singleton Coordinator instance.
  * @type {Coordinator}
@@ -116,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;
@@ -132,8 +126,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 {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
@@ -156,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.
@@ -196,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); }
@@ -215,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();
@@ -228,17 +222,21 @@ export class Coordinator {
    * Connect a client to the coordinator.
    * @param {MosaicClient} client The Mosaic client to connect.
    */
-  async connect(client) {
+  connect(client) {
     const { clients } = this;
 
     if (clients.has(client)) {
       throw new Error('Client already connected.');
     }
-    clients.add(client); // mark as connected
+
+    // add client to client set
+    clients.add(client);
+
+    // register coordinator on client instance
     client.coordinator = this;
 
     // initialize client lifecycle
-    this.initializeClient(client);
+    client._pending = this.initializeClient(client);
 
     // connect filter selection
     connectSelection(this, client.filterBy, client);
@@ -251,6 +249,9 @@ export class Coordinator {
       client.fieldInfo(await queryFieldInfo(this, fields));
     }
 
+    // prepare the client
+    await client.prepare();
+
     // request data query
     return client.requestQuery();
   }

package/src/MosaicClient.js

@@ -1,3 +1,5 @@
+import { Coordinator } from './Coordinator.js';
+import { Selection } from './Selection.js';
 import { throttle } from './util/throttle.js';
 
 /**
@@ -11,9 +13,13 @@ export class MosaicClient {
    *  the client when the selection updates.
    */
   constructor(filterSelection) {
+    /** @type {Selection} */
     this._filterBy = filterSelection;
     this._requestUpdate = throttle(() => this.requestQuery(), true);
+    /** @type {Coordinator} */
     this._coordinator = null;
+    /** @type {Promise<any>} */
+    this._pending = Promise.resolve();
   }
 
   /**
@@ -30,6 +36,13 @@ export class MosaicClient {
     this._coordinator = coordinator;
   }
 
+  /**
+   * Return a Promise that resolves once the client has updated.
+   */
+  get pending() {
+    return this._pending;
+  }
+
   /**
    * Return this client's filter selection.
    */
@@ -65,6 +78,12 @@ export class MosaicClient {
     return this;
   }
 
+  /**
+   * Prepare the client before the query() method is called.
+   */
+  async prepare() {
+  }
+
   /**
    * Return a query specifying the data needed by this client.
    * @param {*} [filter] The filtering criteria to apply in the query.
@@ -104,12 +123,13 @@ 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.
+   * be called, filtered by the current filterBy selection. This method
+   * has no effect if the client is not registered with a coordinator.
    * @returns {Promise}
    */
   requestQuery(query) {
     const q = query || this.query(this.filterBy?.predicate(this));
-    return this._coordinator.requestQuery(this, q);
+    return this._coordinator?.requestQuery(this, q);
   }
 
   /**
@@ -123,17 +143,18 @@ export class MosaicClient {
   }
 
   /**
-   * Reset this client, initiating new field info and query requests.
+   * 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}
    */
   initialize() {
-    return this._coordinator.initializeClient(this);
+    return this._coordinator?.initializeClient(this);
   }
 
   /**
-   * Requests a client update.
-   * For example to (re-)render an interface component.
-   *
+   * Requests a client update, for example to (re-)render an interface
+   * component.
    * @returns {this | Promise<any>}
    */
   update() {

package/src/QueryManager.js

@@ -10,6 +10,7 @@ export class QueryManager {
   constructor(
     maxConcurrentRequests = 32
   ) {
+    /** @type {PriorityQueue} */
     this.queue = new PriorityQueue(3);
     this.db = null;
     this.clientCache = null;
@@ -18,11 +19,12 @@ export class QueryManager {
     this._consolidate = null;
     /**
      * Requests pending with the query manager.
-     * 
      * @type {QueryResult[]}
      */
     this.pendingResults = [];
+    /** @type {number} */
     this.maxConcurrentRequests = maxConcurrentRequests;
+    /** @type {boolean} */
     this.pendingExec = false;
   }