@uwdata/mosaic-core 0.12.2 → 0.14.0

package/src/Selection.js

@@ -1,3 +1,4 @@
+/** @import {SelectionClause} from './util/selection-types.js' */
 import { literal, or } from '@uwdata/mosaic-sql';
 import { Param } from './Param.js';
 import { MosaicClient } from './MosaicClient.js';
@@ -187,7 +188,7 @@ export class Selection extends Param {
 
   /**
    * 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) {
     this.emit('activate', clause);
@@ -196,7 +197,7 @@ export class Selection extends Param {
 
   /**
    * 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) {
@@ -208,6 +209,23 @@ export class Selection extends Param {
     return super.update(this._resolved);
   }
 
+  /**
+   * 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) {
+    clauses ??= this._resolved;
+    clauses.forEach(c => c.source?.reset?.());
+    this._resolved = this._resolved.filter(c => clauses.includes(c));
+    this._relay.forEach(sel => sel.reset(clauses));
+    return super.update(this._resolved = []);
+  }
+
   /**
    * Upon value-typed updates, sets the current clause list to the
    * input value and returns the active clause value.

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';
@@ -24,16 +25,4 @@ 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';
-
-/**
- * @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 { 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/PreAggregator.js

@@ -1,4 +1,4 @@
-import { Query, and, asNode, ceil, collectColumns, createTable, float64, floor, isBetween, int32, mul, round, scaleTransform, sub, isSelectQuery, ExprNode, SelectQuery } from '@uwdata/mosaic-sql';
+import { Query, and, asNode, ceil, collectColumns, createTable, float64, floor, isBetween, int32, mul, round, scaleTransform, sub, isSelectQuery, ExprNode, SelectQuery, isAggregateExpression, ColumnNameRefNode } from '@uwdata/mosaic-sql';
 import { preaggColumns } from './preagg-columns.js';
 import { fnv_hash } from '../util/hash.js';
 
@@ -157,6 +157,10 @@ export class PreAggregator {
 
     // if cached active columns are unset, analyze the active clause
     if (!active) {
+      // if active clause predicate is null, we can't analyze it
+      // return null to backoff to standard client query
+      // non-null clauses may come later, so don't set active state
+      if (activeClause.predicate == null) return null;
       // generate active dimension columns to select over
       // will return an object with null source if it has unstable filters
       this.active = active = activeColumns(activeClause);
@@ -331,20 +335,45 @@ function preaggregateInfo(clientQuery, active, preaggCols, schema) {
 
 /**
  * Push column selections down to subqueries.
+ * @param {Query} query The (sub)query to push down to.
+ * @param {string[]} cols The column names to push down.
  */
 function subqueryPushdown(query, cols) {
   const memo = new Set;
   const pushdown = q => {
+    // it is possible to have duplicate subqueries
+    // so we memoize and exit early if already seen
     if (memo.has(q)) return;
     memo.add(q);
+
     if (isSelectQuery(q) && q._from.length) {
+      // select the pushed down columns
+      // note that the select method will deduplicate for us
       q.select(cols);
+      if (isAggregateQuery(q)) {
+        // if an aggregation query, we need to push to groupby as well
+        // we also deduplicate as the column may already be present
+        const set = new Set(
+          q._groupby.flatMap(x => x instanceof ColumnNameRefNode ? x.name : []
+        ));
+        q.groupby(cols.filter(c => !set.has(c)));
+      }
     }
     q.subqueries.forEach(pushdown);
   };
   pushdown(query);
 }
 
+/**
+ * Test if a query performs aggregation.
+ * @param {SelectQuery} query
+ * @returns {boolean}
+ */
+function isAggregateQuery(query) {
+  return query._groupby.length > 0
+    || query._select.some(node => isAggregateExpression(node));
+}
+
 /**
  * Metadata and query generator for materialized views of pre-aggregated data.
  * This object provides the information needed to generate and query the

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, coalesce, 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';
 
 /**
@@ -14,10 +14,13 @@ import { fnv_hash } from '../util/hash.js';
 export function sufficientStatistics(node, preagg, avg) {
   switch (node.name) {
     case 'count':
+      return sumCountExpr(preagg, node);
     case 'sum':
       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':
@@ -126,11 +129,24 @@ function addStat(preagg, expr, node) {
  */
 function countExpr(preagg, node) {
   const name = addStat(preagg, count(node.args[0]), node);
-  return { expr: sum(name), name };
+  return { expr: coalesce(sum(name), 0), name };
 }
 
 /**
- * Generate an expression for calculating counts or sums over data dimensions.
+ * Generate an expression for calculating counts over data dimensions.
+ * The expression is a summation with an additional coalesce operation
+ * to map null sums to zero-valued counts.
+ * @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 sumCountExpr(preagg, node) {
+  return coalesce(sumExpr(preagg, node), 0);
+}
+
+/**
+ * Generate an expression for calculating sums over data dimensions.
  * @param {Record<string, ExprNode>} preagg A map of columns (such as
  *  sufficient statistics) to pre-aggregate.
  * @param {AggregateNode} node The originating aggregate function call.
@@ -155,6 +171,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

@@ -1,4 +1,10 @@
-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 =
@@ -46,3 +52,13 @@ 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/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/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({});