@uwdata/mosaic-core 0.16.2 → 0.18.0

package/src/{MosaicClient.js → MosaicClient.ts}

@@ -1,8 +1,14 @@
-/** @import { Query } from '@uwdata/mosaic-sql' */
-/** @import { Coordinator } from './Coordinator.js' */
-/** @import { Selection } from './Selection.js' */
+import { FilterExpr, type Query } from '@uwdata/mosaic-sql';
+import { type Coordinator } from './Coordinator.js';
+import { type Selection } from './Selection.js';
 import { throttle } from './util/throttle.js';
 
+export type ClientQuery = Query | string | null;
+
+export function isMosaicClient(x: unknown): x is MosaicClient {
+  return x instanceof MosaicClient;
+}
+
 /**
  * A Mosaic client is a data consumer that indicates its data needs to a
  * Mosaic coordinator via the query method. The coordinator is responsible
@@ -20,53 +26,55 @@ import { throttle } from './util/throttle.js';
  * associated interface elements are offscreen or disabled.
  */
 export class MosaicClient {
+  _filterBy: Selection | undefined;
+  _requestUpdate: () => void;
+  _coordinator: Coordinator | null;
+  _pending: Promise<unknown>;
+  _enabled: boolean;
+  _initialized: boolean;
+  _request: Query | boolean | null;
+
   /**
    * Create a new client instance.
-   * @param {Selection} [filterSelection] An optional selection to
+   * @param filterSelection An optional selection to
    *  interactively filter this client's data. If provided, a coordinator
    *  will re-query and update the client when the selection updates.
    */
-  constructor(filterSelection) {
-    /** @type {Selection | undefined} */
+  constructor(filterSelection?: Selection) {
     this._filterBy = filterSelection;
     this._requestUpdate = throttle(() => this.requestQuery(), true);
-    /** @type {Coordinator | null} */
     this._coordinator = null;
-    /** @type {Promise<any>} */
     this._pending = Promise.resolve();
-    /** @type {boolean} */
     this._enabled = true;
-    /** @type {boolean} */
     this._initialized = false;
-    /** @type {Query | boolean | null} */
     this._request = null;
   }
 
   /**
-   * @returns {Coordinator | null}  this client's connected coordinator.
+   * @returns this client's connected coordinator.
    */
-  get coordinator() {
+  get coordinator(): Coordinator | null {
     return this._coordinator;
   }
 
   /**
    * Set this client's connected coordinator.
    */
-  set coordinator(coordinator) {
+  set coordinator(coordinator: Coordinator | null) {
     this._coordinator = coordinator;
   }
 
   /**
    * Return this client's enabled state.
    */
-  get enabled() {
+  get enabled(): boolean {
     return this._enabled;
   }
 
   /**
    * Set this client's enabled state;
    */
-  set enabled(state) {
+  set enabled(state: boolean) {
     state = !!state; // ensure boolean
     if (this._enabled !== state) {
       this._enabled = state;
@@ -86,14 +94,14 @@ export class MosaicClient {
   /**
    * Return a Promise that resolves once the client has updated.
    */
-  get pending() {
+  get pending(): Promise<unknown> {
     return this._pending;
   }
 
   /**
-   * @returns {Selection | undefined} this client's filter selection.
+   * @returns this client's filter selection.
    */
-  get filterBy() {
+  get filterBy(): Selection | undefined {
     return this._filterBy;
   }
 
@@ -103,7 +111,7 @@ export class MosaicClient {
    * to the filterBy selection do not change the groupby domain of the client
    * query.
    */
-  get filterStable() {
+  get filterStable(): boolean {
     return true;
   }
 
@@ -112,41 +120,41 @@ export class MosaicClient {
    * should override this method as needed, potentially issuing one or more
    * queries to gather data or metadata needed prior to `query` calls.
    */
-  async prepare() {
+  async prepare(): Promise<void> {
   }
 
   /**
    * Return a query specifying the data needed by this client.
-   * @param {*} [filter] The filtering criteria to apply in the query.
-   * @returns {*} The client query
+   * @param filter The filtering criteria to apply in the query.
+   * @returns The client query
    */
-  query(filter) { // eslint-disable-line no-unused-vars
+  query(filter?: FilterExpr | null): ClientQuery { // eslint-disable-line @typescript-eslint/no-unused-vars
     return null;
   }
 
   /**
    * Called by the coordinator to inform the client that a query is pending.
-   * @returns {this}
+   * @returns this
    */
-  queryPending() {
+  queryPending(): this {
     return this;
   }
 
   /**
    * Called by the coordinator to return a query result.
-   * @param {*} data The query result.
-   * @returns {this}
+   * @param data The query result.
+   * @returns this
    */
-  queryResult(data) { // eslint-disable-line no-unused-vars
+  queryResult(data: unknown): this { // eslint-disable-line @typescript-eslint/no-unused-vars
     return this;
   }
 
   /**
    * Called by the coordinator to report a query execution error.
-   * @param {*} error
-   * @returns {this}
+   * @param error
+   * @returns this
    */
-  queryError(error) { // eslint-disable-line no-unused-vars
+  queryError(error: Error): this { // eslint-disable-line @typescript-eslint/no-unused-vars
     // do nothing, the coordinator logs the error
     return this;
   }
@@ -158,15 +166,14 @@ export class MosaicClient {
    * 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
+   * @param query The query to request. If unspecified, the query
+   *  will be determined by the client's `query` method and the current
    *  `filterBy` selection state.
-   * @returns {Promise}
    */
-  requestQuery(query) {
+  requestQuery(query?: Query): Promise<unknown> | null {
     if (this._enabled) {
       const q = query || this.query(this.filterBy?.predicate(this));
-      return this._coordinator?.requestQuery(this, q);
+      return this._coordinator!.requestQuery(this, q);
     } else {
       this._request = query ?? true;
       return null;
@@ -181,7 +188,7 @@ export class MosaicClient {
    * connected to a coordinator. If the client is connected but currently
    * disabled, the request will be serviced if the client is later enabled.
    */
-  requestUpdate() {
+  requestUpdate(): void {
     if (this._enabled) {
       this._requestUpdate();
     } else {
@@ -193,7 +200,7 @@ export class MosaicClient {
    * 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() {
+  initialize(): void {
     if (!this._enabled) {
       // clear flag so we initialize when enabled again
       this._initialized = false;
@@ -212,16 +219,15 @@ export class MosaicClient {
    * If overriding this method in a client subclass, be sure to also
    * disconnect from the coordinator.
    */
-  destroy() {
+  destroy(): void {
     this.coordinator?.disconnect(this);
   }
 
   /**
    * Requests a client update, for example to (re-)render an interface
    * component.
-   * @returns {this | Promise<any>}
    */
-  update() {
+  update(): this | Promise<unknown> {
     return this;
   }
-}
+}

package/src/{Param.js → Param.ts}

@@ -3,10 +3,10 @@ import { distinct } from './util/distinct.js';
 
 /**
  * Test if a value is a Param instance.
- * @param {*} x The value to test.
- * @returns {x is Param} True if the input is a Param, false otherwise.
+ * @param x The value to test.
+ * @returns True if the input is a Param, false otherwise.
  */
-export function isParam(x) {
+export function isParam<T>(x: unknown): x is Param<T> {
   return x instanceof Param;
 }
 
@@ -14,61 +14,62 @@ export function isParam(x) {
  * Represents a dynamic parameter that dispatches updates
  * upon parameter changes.
  */
-export class Param extends AsyncDispatch {
+export class Param<T> extends AsyncDispatch<T> {
+  protected _value?: T;
 
   /**
    * Create a new Param instance.
-   * @param {*} value The initial value of the Param.
+   * @param value The initial value of the Param.
    */
-  constructor(value) {
+  constructor(value?: T) {
     super();
     this._value = value;
   }
 
   /**
    * Create a new Param instance with the given initial value.
-   * @param {*} value The initial value of the Param.
-   * @returns {Param} The new Param instance.
+   * @param value The initial value of the Param.
+   * @returns The new Param instance.
    */
-  static value(value) {
+  static value<T>(value: T): Param<T> {
     return new Param(value);
   }
 
   /**
    * Create a new Param instance over an array of initial values,
    * which may contain nested Params.
-   * @param {*} values The initial values of the Param.
-   * @returns {Param} The new Param instance.
+   * @param values The initial values of the Param.
+   * @returns The new Param instance.
    */
-  static array(values) {
+  static array<T>(values: (T|Param<T>)[]): Param<T[]> {
     if (values.some(v => isParam(v))) {
-      const p = new Param();
-      const update = () => {
-        p.update(values.map(v => isParam(v) ? v.value : v));
+      const p = new Param<T[]>();
+      const update = (): void => {
+        p.update(values.map(v => isParam<T>(v) ? v.value! : v));
       };
       update();
       values.forEach(v => isParam(v) ? v.addEventListener('value', update) : 0);
       return p;
     }
-    return new Param(values);
+    return new Param(values) as Param<T[]>;
   }
 
   /**
    * The current value of the Param.
    */
-  get value() {
+  get value(): T | undefined {
     return this._value;
   }
 
   /**
    * Update the Param value
-   * @param {*} value The new value of the Param.
-   * @param {object} [options] The update options.
-   * @param {boolean} [options.force] A boolean flag indicating if the Param
+   * @param value The new value of the Param.
+   * @param options The update options.
+   * @param options.force A boolean flag indicating if the Param
    *  should emit a 'value' event even if the internal value is unchanged.
-   * @returns {this} This Param instance.
+   * @returns This Param instance.
    */
-  update(value, { force } = {}) {
+  update(value: T, { force }: { force?: boolean } = {}): this {
     const shouldEmit = distinct(this._value, value) || force;
     if (shouldEmit) {
       this.emit('value', value);
@@ -81,14 +82,14 @@ export class Param extends AsyncDispatch {
   /**
    * Upon value-typed updates, sets the current value to the input value
    * immediately prior to the event value being emitted to listeners.
-   * @param {string} type The event type.
-   * @param {*} value The input event value.
-   * @returns {*} The input event value.
+   * @param type The event type.
+   * @param value The input event value.
+   * @returns The input event value.
    */
-  willEmit(type, value) {
+  willEmit(type: string, value: T): T {
     if (type === 'value') {
-      this._value = value;
+      this._value = value as T;
     }
     return value;
   }
-}
+}

package/src/{QueryConsolidator.js → QueryConsolidator.ts}

@@ -1,26 +1,45 @@
-/** @import { DescribeQuery, Query } from '@uwdata/mosaic-sql' */
+import type { ExprNode, Query, SelectQuery } from '@uwdata/mosaic-sql';
+import type { Table } from '@uwdata/flechette';
 import { isAggregateExpression, isColumnRef, isDescribeQuery, isSelectQuery } from '@uwdata/mosaic-sql';
 import { QueryResult } from './util/query-result.js';
+import type { Cache, QueryEntry, QueryType } from './types.js';
 
-function wait(callback) {
-  const method = typeof requestAnimationFrame !== 'undefined'
-    ? requestAnimationFrame
-    : typeof setImmediate !== 'undefined' ? setImmediate : setTimeout;
-  // @ts-ignore
-  return method(callback);
+interface GroupEntry {
+  entry: QueryEntry;
+  priority: number;
+  index: number;
+}
+
+interface QueryGroup extends Array<GroupEntry> {
+  query?: Query;
+  result?: QueryResult;
+  maps?: Array<Array<[string, string]>>;
+}
+
+function wait(callback: () => void): unknown {
+  if (typeof requestAnimationFrame !== 'undefined') {
+    return requestAnimationFrame(callback);
+  } else if (typeof setImmediate !== 'undefined') {
+    return setImmediate(callback);
+  } else {
+    return setTimeout(callback);
+  }
 }
 
 /**
  * Create a consolidator to combine structurally compatible queries.
- * @param {*} enqueue Query manager enqueue method
- * @param {*} cache Client-side query cache (sql -> data)
+ * @param enqueue Query manager enqueue method
+ * @param cache Client-side query cache (sql -> data)
  * @returns A consolidator object
  */
-export function consolidator(enqueue, cache) {
-  let pending = [];
-  let id = 0;
+export function consolidator(
+  enqueue: (entry: QueryEntry, priority?: number) => void,
+  cache: Cache
+) {
+  let pending: GroupEntry[] = [];
+  let id: unknown = 0;
 
-  function run() {
+  function run(): void {
     // group queries into bundles that can be consolidated
     const groups = entryGroups(pending, cache);
     pending = [];
@@ -34,37 +53,38 @@ export function consolidator(enqueue, cache) {
   }
 
   return {
-    add(entry, priority) {
+    add(entry: QueryEntry, priority: number): void {
       if (entry.request.type === 'arrow') {
         // wait one frame, gather an ordered list of queries
         // only Apache Arrow is supported, so we can project efficiently
-        id = id || wait(() => run());
+        id ||= wait(() => run());
         pending.push({ entry, priority, index: pending.length });
       } else {
         enqueue(entry, priority);
       }
     }
-  }
+  };
 }
 
 /**
  * Segment query requests into consolidation-compatible groups.
- * @param {*} entries Query request entries ({ request, result } objects)
+ * @param entries Query request entries ({ request, result } objects)
+ * @param cache Client-side query cache
  * @returns An array of grouped entry arrays
  */
-function entryGroups(entries, cache) {
-  const groups = [];
-  const groupMap = new Map;
+function entryGroups(entries: GroupEntry[], cache: Cache): QueryGroup[] {
+  const groups: QueryGroup[] = [];
+  const groupMap = new Map<string, QueryGroup>();
 
   for (const query of entries) {
     const { entry: { request } } = query;
     const key = consolidationKey(request.query, cache);
     if (!groupMap.has(key)) {
-      const list = [];
+      const list: QueryGroup = [];
       groups.push(list);
       groupMap.set(key, list);
     }
-    groupMap.get(key).push(query);
+    groupMap.get(key)!.push(query);
   }
 
   return groups;
@@ -75,11 +95,11 @@ function entryGroups(entries, cache) {
  * Queries with matching keys are conosolidation-compatible.
  * If a query is found in the cache, it is exempted from consolidation,
  * which is indicated by returning the precise query SQL as the key.
- * @param {Query | DescribeQuery} query The input query.
- * @param {*} cache The query cache (sql -> data).
+ * @param query The input query.
+ * @param cache The query cache (sql -> data).
  * @returns a key string
  */
-function consolidationKey(query, cache) {
+function consolidationKey(query: QueryType, cache: Cache): string {
   const sql = `${query}`;
   if (isSelectQuery(query) && !cache.get(sql)) {
     if (
@@ -99,11 +119,11 @@ function consolidationKey(query, cache) {
     // we resolve these against the true grouping expressions
     const groupby = query._groupby;
     if (groupby.length) {
-      const map = {}; // expression map (alias -> expr)
+      const map: Record<string, ExprNode> = {}; // expression map (alias -> expr)
       query._select.forEach(({ alias, expr }) => map[alias] = expr);
       q.setGroupby(groupby.map(e => (isColumnRef(e) && map[e.column]) || e));
     }
-    else if (query._select.some(e => isAggregateExpression(e.expr))) {
+    else if (query._select.some(e => isAggregateExpression(e.expr!))) {
       // if query is an ungrouped aggregate, add an explicit groupby to
       // prevent improper consolidation with non-aggregate queries
       q.setGroupby('ALL');
@@ -119,10 +139,13 @@ function consolidationKey(query, cache) {
 
 /**
  * Issue queries, consolidating where possible.
- * @param {*} group Array of bundled query entries
- * @param {*} enqueue Add entry to query queue
+ * @param group Array of bundled query entries
+ * @param enqueue Add entry to query queue
  */
-function consolidate(group, enqueue) {
+function consolidate(
+  group: QueryGroup,
+  enqueue: (entry: QueryEntry, priority?: number) => void
+): void {
   if (shouldConsolidate(group)) {
     // issue a single consolidated query
     enqueue({
@@ -143,11 +166,11 @@ function consolidate(group, enqueue) {
 
 /**
  * Check if a group contains multiple distinct queries.
- * @param {*} group Array of bundled query entries
+ * @param group Array of bundled query entries
  * @returns false if group contains a single (possibly repeated) query,
  *  otherwise true
  */
-function shouldConsolidate(group) {
+function shouldConsolidate(group: QueryGroup): boolean {
   if (group.length > 1) {
     const sql = `${group[0].entry.request.query}`;
     for (let i = 1; i < group.length; ++i) {
@@ -161,37 +184,39 @@ function shouldConsolidate(group) {
 
 /**
  * Create a consolidated query for a group.
- * @param {*} group Array of bundled query entries
+ * @param group Array of bundled query entries
  * @returns A consolidated Query instance
  */
-function consolidatedQuery(group) {
-  const maps = group.maps = [];
-  const fields = new Map;
+function consolidatedQuery(group: QueryGroup): Query {
+  const maps: Array<Array<[string, string]>> = group.maps = [];
+  const fields = new Map<string, [string, ExprNode]>();
 
   // gather select fields
   for (const item of group) {
-    const { query } = item.entry.request;
-    const fieldMap = [];
+    const query = item.entry.request.query as SelectQuery;
+    const fieldMap: Array<[string, string]> = [];
     maps.push(fieldMap);
     for (const { alias, expr } of query._select) {
       const e = `${expr}`;
       if (!fields.has(e)) {
         fields.set(e, [`col${fields.size}`, expr]);
       }
-      const [name] = fields.get(e);
+      const [name] = fields.get(e)!;
       fieldMap.push([name, alias]);
     }
   }
 
   // use a cloned query as a starting point
-  const query = group[0].entry.request.query.clone();
+  const query = (group[0].entry.request.query as SelectQuery).clone();
 
   // update group by statement as needed
   const groupby = query._groupby;
   if (groupby.length) {
-    const map = {};
+    const map: Record<string, string> = {};
     group.maps[0].forEach(([name, as]) => map[as] = name);
-    query.setGroupby(groupby.map(e => (isColumnRef(e) && map[e.column]) || e));
+    query.setGroupby(
+      groupby.map((e: ExprNode) => (isColumnRef(e) && map[e.column]) || e)
+    );
   }
 
   // update select statement and return
@@ -200,10 +225,10 @@ function consolidatedQuery(group) {
 
 /**
  * Process query results, dispatch results to original requests
- * @param {*} group Array of query requests
- * @param {*} cache Client-side query cache (sql -> data)
+ * @param group Array of query requests
+ * @param cache Client-side query cache (sql -> data)
  */
-async function processResults(group, cache) {
+async function processResults(group: QueryGroup, cache: Cache): Promise<void> {
   const { maps, query, result } = group;
 
   // exit early if no consolidation performed
@@ -211,9 +236,9 @@ async function processResults(group, cache) {
   if (!maps) return;
 
   // await consolidated query result, pass errors if needed
-  let data;
+  let data: Table;
   try {
-    data = await result;
+    data = await result as Table;
   } catch (err) {
     // pass error to consolidated queries
     for (const { entry } of group) {
@@ -224,7 +249,7 @@ async function processResults(group, cache) {
 
   // extract result for each query in the consolidation group
   // update cache and pass extract to original issuer
-  const describe = isDescribeQuery(query);
+  const describe = isDescribeQuery(query!);
   group.forEach(({ entry }, index) => {
     const { request, result } = entry;
     const map = maps[index];
@@ -240,29 +265,27 @@ async function processResults(group, cache) {
 
 /**
  * Project a consolidated result to a client result
- * @param {import('@uwdata/flechette').Table} data
- *  Consolidated query result, as an Arrow Table
- * @param {[string, string][]} map Column name map as [source, target] pairs
+ * @param data Consolidated query result, as an Arrow Table
+ * @param map Column name map as [source, target] pairs
  * @returns the projected Apache Arrow table
  */
-function projectResult(data, map) {
+function projectResult(data: Table, map: Array<[string, string]>): Table {
   return data.select(map.map(x => x[0]), map.map(x => x[1]));
 }
 
 /**
  * Filter a consolidated describe query result to a client result
- * @param {import('@uwdata/flechette').Table} data
- *  Consolidated query result, as an Arrow Table
- * @param {[string, string][]} map Column name map as [source, target] pairs
+ * @param data Consolidated query result, as an Arrow Table
+ * @param map Column name map as [source, target] pairs
  * @returns the filtered table data
  */
-function filterResult(data, map) {
+function filterResult(data: Table, map: Array<[string, string]>): unknown[] {
   const lookup = new Map(map);
-  const result = [];
+  const result: unknown[] = [];
   for (const d of data) {
     if (lookup.has(d.column_name)) {
       result.push({ ...d, column_name: lookup.get(d.column_name) })
     }
   }
   return result;
-}
+}