@uwdata/mosaic-core 0.12.1 → 0.13.0

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.
    */
@@ -49,7 +62,8 @@ export class MosaicClient {
 
   /**
    * 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() {
     return null;
@@ -57,13 +71,19 @@ export class MosaicClient {
 
   /**
    * 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) { // eslint-disable-line no-unused-vars
     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.
@@ -122,7 +142,7 @@ 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.
    * @returns {Promise}
    */
   initialize() {

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;
   }
 

package/src/SelectionClause.js

@@ -40,7 +40,7 @@ export function clausePoint(field, 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.
@@ -75,7 +75,7 @@ export function clausePoints(fields, value, {
 /**
  * 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
@@ -93,7 +93,6 @@ export function clauseInterval(field, value, {
   scale,
   pixelSize = 1
 }) {
-  /** @type {ExprNode | null} */
   const predicate = value != null ? isBetween(field, value) : null;
   /** @type {import('./util/selection-types.js').IntervalMetadata} */
   const meta = { type: 'interval', scales: scale && [scale], bin, pixelSize };
@@ -103,7 +102,7 @@ export function clauseInterval(field, value, {
 /**
  * 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
@@ -122,7 +121,6 @@ export function clauseIntervals(fields, value, {
   scales = [],
   pixelSize = 1
 }) {
-  /** @type {ExprNode | null} */
   const predicate = value != null
     ? and(fields.map((f, i) => isBetween(f, value[i])))
     : null;
@@ -136,7 +134,7 @@ const MATCH_METHODS = { contains, prefix, suffix, regexp: regexp_matches };
 /**
  * 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

package/src/connectors/rest.js

@@ -21,9 +21,16 @@ export function restConnector(uri = 'http://localhost:3000/') {
         body: JSON.stringify(query)
       });
 
+
+      const res = await req;
+
+      if (!res.ok) {
+        throw new Error(`Query failed with HTTP status ${res.status}: ${await res.text()}`);
+      }
+
       return query.type === 'exec' ? req
-        : query.type === 'arrow' ? decodeIPC(await (await req).arrayBuffer())
-        : (await req).json();
+        : query.type === 'arrow' ? decodeIPC(await res.arrayBuffer())
+        : res.json();
     }
   };
 }

package/src/index-types.ts

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

package/src/index.js

@@ -1,4 +1,5 @@
 export { MosaicClient } from './MosaicClient.js';
+export { makeClient } from './make-client.js';
 export { Coordinator, coordinator } from './Coordinator.js';
 export { Selection, isSelection } from './Selection.js';
 export { Param, isParam } from './Param.js';
@@ -22,16 +23,6 @@ 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';
-
-/**
- * @typedef {import('./util/selection-types.js').ClauseMetadata} ClauseMetadata
- * @typedef {import('./util/selection-types.js').PointMetadata} PointMetadata
- * @typedef {import('./util/selection-types.js').MatchMethod} MatchMethod
- * @typedef {import('./util/selection-types.js').MatchMetadata} MatchMetadata
- * @typedef {import('./util/selection-types.js').ScaleType} ScaleType
- * @typedef {import('./util/selection-types.js').Extent} Extent
- * @typedef {import('./util/selection-types.js').Scale} Scale
- * @typedef {import('./util/selection-types.js').BinMethod} BinMethod
- * @typedef {import('./util/selection-types.js').IntervalMetadata} IntervalMetadata
- * @typedef {import('./util/selection-types.js').SelectionClause} SelectionClause
- */
+export { queryFieldInfo } from './util/field-info.js';
+export { jsType } from './util/js-type.js';
+export { isActivatable } from './util/is-activatable.js';

package/src/make-client.js

@@ -0,0 +1,64 @@
+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.
+ */
+
+/** 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) {
+  const coordinator = options.coordinator ?? defaultCoordinator();
+  const client = new ProxyClient({ ...options, coordinator });
+  coordinator.connect(client);
+  return client;
+}
+
+/** An internal class used to implement the makeClient API */
+class ProxyClient extends MosaicClient {
+  /** @param {MakeClientOptions} options */
+  constructor(options) {
+    super(options.selection);
+
+    /** @type {MakeClientOptions} */
+    this._options = { ...options };
+  }
+
+  async prepare() {
+    await this._options.prepare?.();
+  }
+
+  query(filter) {
+    return this._options.query(filter);
+  }
+
+  queryResult(data) {
+    this._options.queryResult?.(data);
+    return this;
+  }
+
+  queryPending() {
+    this._options.queryPending?.();
+    return this;
+  }
+
+  queryError(error) {
+    this._options.queryError?.(error);
+    return this;
+  }
+
+  destroy() {
+    this._options.coordinator.disconnect(this);
+  }
+}

package/src/preagg/sufficient-statistics.js

@@ -1,4 +1,4 @@
-import { AggregateNode, and, argmax, argmin, count, div, ExprNode, isNotNull, max, min, mul, pow, regrAvgX, regrAvgY, regrCount, sql, sqrt, sub, sum } from '@uwdata/mosaic-sql';
+import { AggregateNode, and, argmax, argmin, count, div, exp, ExprNode, isNotNull, ln, max, min, mul, pow, regrAvgX, regrAvgY, regrCount, sql, sqrt, sub, sum } from '@uwdata/mosaic-sql';
 import { fnv_hash } from '../util/hash.js';
 
 /**
@@ -18,6 +18,8 @@ export function sufficientStatistics(node, preagg, avg) {
       return sumExpr(preagg, node);
     case 'avg':
       return avgExpr(preagg, node);
+    case 'geomean':
+      return geomeanExpr(preagg, node);
     case 'arg_max':
       return argmaxExpr(preagg, node);
     case 'arg_min':
@@ -155,6 +157,24 @@ function avgExpr(preagg, node) {
   return div(sum(mul(as, name)), expr);
 }
 
+/**
+ * Generate an expression for calculating geometric means over data dimensions.
+ * This method uses log-based computations to ensure numerical stability. The
+ * geomean calculation uses two sufficient statistics: the sum of log values
+ * and the count of non-null values. As a side effect, this method adds columns
+ * for these statistics to the input *preagg* object.
+ * @param {Record<string, ExprNode>} preagg A map of columns (such as
+ *  sufficient statistics) to pre-aggregate.
+ * @param {AggregateNode} node The originating aggregate function call.
+ * @returns {ExprNode} An aggregate expression over pre-aggregated dimensions.
+ */
+function geomeanExpr(preagg, node) {
+  const x = node.args[0];
+  const expr = addStat(preagg, sum(ln(x)), node);
+  const { expr: n } = countExpr(preagg, node);
+  return exp(div(sum(expr), n));
+}
+
 /**
  * Generate an expression for calculating argmax over data dimensions.
  * As a side effect, this method adds a column to the input *preagg* object

package/src/types.ts

@@ -0,0 +1,64 @@
+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/src/util/field-info.js

@@ -1,4 +1,4 @@
-import { AggregateNode, Query, asTableRef, count, isNull, max, min, sql } from '@uwdata/mosaic-sql';
+import { AggregateNode, Query, asTableRef, count, isAggregateExpression, isNode, isNull, max, min, sql } from '@uwdata/mosaic-sql';
 import { jsType } from './js-type.js';
 
 export const Count = 'count';
@@ -9,7 +9,10 @@ export const Distinct = 'distinct';
 export const Stats = { Count, Nulls, Max, Min, Distinct };
 
 /**
- * @type {Record<string, (column: string) => AggregateNode>}
+ * @type {Record<
+ *  import('../types.js').Stat,
+ *  (column: import('../types.js').FieldRef) => AggregateNode
+ * >}
  */
 const statMap = {
   [Count]: count,
@@ -20,18 +23,26 @@ const statMap = {
 };
 
 /**
- *
- * @param {string} table
- * @param {string} column
- * @param {string[]|Set<string>} stats
- * @returns
+ * Get summary stats of the given column
+ * @param {import('../types.js').FieldInfoRequest} field
+ * @returns {Query}
  */
-function summarize(table, column, stats) {
+function summarize({ table, column, stats }) {
   return Query
     .from(table)
-    .select(Array.from(stats, s => ({[s]: statMap[s](column)})));
+    .select(Array.from(stats, s => ({ [s]: statMap[s](column) })));
 }
 
+/**
+ * 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 async function queryFieldInfo(mc, fields) {
   if (fields.length === 1 && fields[0].column === '*') {
     return getTableInfo(mc, fields[0].table);
@@ -42,13 +53,21 @@ export async function queryFieldInfo(mc, fields) {
   }
 }
 
+/**
+ * Get information about a single field of a table.
+ * @param {import('../Coordinator.js').Coordinator} mc A Mosaic coordinator.
+ * @param {import('../types.js').FieldInfoRequest} field
+ * @returns {Promise<import('../types.js').FieldInfo>}
+ */
 async function getFieldInfo(mc, { table, column, stats }) {
   // generate and issue a query for field metadata info
   // use GROUP BY ALL to differentiate & consolidate aggregates
   const q = Query
     .from({ source: table })
     .select({ column })
-    .groupby(column.aggregate ? sql`ALL` : []);
+    .groupby(isNode(column) && isAggregateExpression(column) ? sql`ALL` : []);
+
+  /** @type {import('../types.js').ColumnDescription[]} */
   const [desc] = Array.from(await mc.query(Query.describe(q)));
   const info = {
     table,
@@ -59,11 +78,11 @@ async function getFieldInfo(mc, { table, column, stats }) {
   };
 
   // no need for summary statistics
-  if (!(stats?.length || stats?.size)) return info;
+  if (!stats?.length) return info;
 
   // query for summary stats
   const [result] = await mc.query(
-    summarize(table, column, stats),
+    summarize({ table, column, stats }),
     { persist: true }
   );
 
@@ -71,9 +90,16 @@ async function getFieldInfo(mc, { table, column, stats }) {
   return Object.assign(info, result);
 }
 
+/**
+ * Get information about the fields of a table.
+ * @param {import('../Coordinator.js').Coordinator} mc A Mosaic coordinator.
+ * @param {string} table The table name.
+ * @returns {Promise<import('../types.js').FieldInfo[]>}
+ */
 async function getTableInfo(mc, table) {
-  const result = await mc.query(`DESCRIBE ${asTableRef(table)}`);
-  return Array.from(result).map(desc => ({
+  /** @type {import('../types.js').ColumnDescription[]} */
+  const result = Array.from(await mc.query(`DESCRIBE ${asTableRef(table)}`));
+  return result.map(desc => ({
     table,
     column: desc.column_name,
     sqlType: desc.column_type,

package/src/util/is-activatable.js

@@ -0,0 +1,8 @@
+/**
+ * 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) {
+  return typeof value?.activate === 'function' && value.activate.length === 0;
+}

package/src/util/js-type.js

@@ -1,3 +1,9 @@
+/**
+ * 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) {
   switch (type) {
     case 'BIGINT':

package/src/util/throttle.js

@@ -5,10 +5,12 @@ const NIL = {};
  * 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, debounce = false) {
   let curr;

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});