@uwdata/mosaic-core 0.17.0 → 0.18.0

package/src/util/{query-result.js → query-result.ts}

@@ -5,23 +5,30 @@ export const QueryState = Object.freeze({
   done: Symbol('done')
 });
 
+type QueryStateType = typeof QueryState[keyof typeof QueryState];
+
 /**
  * A query result Promise that can allows external callers
  * to resolve or reject the Promise.
  */
-export class QueryResult extends Promise {
+export class QueryResult<T = unknown> extends Promise<T> {
+  private _resolve!: (value: T | PromiseLike<T>) => void;
+  private _reject!: (reason?: unknown) => void;
+  private _state: QueryStateType;
+  private _value: T | undefined;
+
   /**
    * Create a new query result Promise.
    */
   constructor() {
-    let resolve;
-    let reject;
+    let resolve: (value: T | PromiseLike<T>) => void;
+    let reject: (reason?: unknown) => void;
     super((r, e) => {
       resolve = r;
       reject = e;
     });
-    this._resolve = resolve;
-    this._reject = reject;
+    this._resolve = resolve!;
+    this._reject = reject!;
     this._state = QueryState.pending;
     this._value = undefined;
   }
@@ -29,10 +36,10 @@ export class QueryResult extends Promise {
   /**
    * Resolve the result Promise with a prepared value or the provided value.
    * This method will only succeed if either a value is provided or the promise is ready.
-   * @param {*} value The result value.
-   * @returns {this}
+   * @param value The result value.
+   * @returns This QueryResult instance.
    */
-  fulfill(value) {
+  fulfill(value?: T): this {
     if (this._value !== undefined) {
       if (value !== undefined) {
         throw Error('Promise is ready and fulfill has a provided value');
@@ -51,10 +58,10 @@ export class QueryResult extends Promise {
 
   /**
    * Prepare to resolve with the provided value.
-   * @param {*} value The result value.
-   * @returns {this}
+   * @param value The result value.
+   * @returns This QueryResult instance.
    */
-  ready(value) {
+  ready(value: T): this {
     this._state = QueryState.ready;
     this._value = value;
     return this;
@@ -62,10 +69,10 @@ export class QueryResult extends Promise {
 
   /**
    * Rejects the result Promise with the provided error.
-   * @param {*} error The error value.
-   * @returns {this}
+   * @param error The error value.
+   * @returns This QueryResult instance.
    */
-  reject(error) {
+  reject(error: unknown): this {
     this._state = QueryState.error;
     this._reject(error);
     return this;
@@ -73,12 +80,12 @@ export class QueryResult extends Promise {
 
   /**
    * Returns the state of this query result.
-   * @returns {symbol}
+   * @returns The current state symbol.
    */
-  get state() {
+  get state(): QueryStateType {
     return this._state;
   }
 }
 
 // necessary to make Promise subclass act like a Promise
-QueryResult.prototype.constructor = Promise;
+QueryResult.prototype.constructor = Promise;

package/src/util/synchronizer.ts

@@ -0,0 +1,56 @@
+/**
+ * Synchronizer class to aid synchronization of updates on multiple pending operations.
+ */
+export class Synchronizer<T = unknown> {
+  private _set: Set<T>;
+  private _done: () => void;
+  private _promise: Promise<void>;
+
+  /**
+   * Create a new synchronizer instance.
+   */
+  constructor() {
+    this._set = new Set<T>();
+    this._done = () => {};
+    this._promise = new Promise<void>(resolve => this._done = resolve);
+  }
+
+  /**
+   * Mark an item as pending.
+   * @param item An item to synchronize on.
+   */
+  pending(item: T): void {
+    this._set.add(item);
+  }
+
+  /**
+   * Mark a pending item as ready, indicating it is
+   * ready for a synchronized update.
+   * @param item An item to synchronize on.
+   * @returns True if the synchronizer is ready to
+   *  resolve, false otherwise.
+   */
+  ready(item: T): boolean {
+    this._set.delete(item);
+    return this._set.size === 0;
+  }
+
+  /**
+   * Resolve the current synchronization cycle, causing the synchronize
+   * promise to resolve and thereby trigger downstream updates.
+   */
+  resolve(): void {
+    this._promise = new Promise<void>(resolve => {
+      this._done();
+      this._done = resolve;
+    });
+  }
+
+  /**
+   * The promise for the current synchronization cycle.
+   * @returns The synchronization promise.
+   */
+  get promise(): Promise<void> {
+    return this._promise;
+  }
+}

package/src/util/throttle.ts

@@ -0,0 +1,59 @@
+const NIL = {};
+
+interface QueueItem<E> {
+  event: E;
+}
+
+/**
+ * Throttle invocations of a callback function. The callback must return
+ * 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 callback The callback function.
+ * @param debounce Flag indicating if invocations
+ *  should also be debounced within the current animation frame.
+ * @returns A new function that throttles access to the callback.
+ */
+export function throttle<E, T>(
+  callback: (event?: E) => Promise<T> | null,
+  debounce: boolean = false
+): (event?: E) => void {
+  let curr: Promise<unknown> | null;
+  let next: QueueItem<E> | undefined | null;
+  let pending: E | undefined | typeof NIL = NIL;
+
+  function invoke(event?: E): void {
+    curr = callback(event)
+      ?.catch(() => {})
+      .finally(() => {
+        if (next) {
+          const { event: value } = next;
+          next = null;
+          invoke(value);
+        } else {
+          curr = null;
+        }
+      }) || null;
+  }
+
+  function enqueue(event: E): void {
+    next = { event };
+  }
+
+  function process(event?: E): void {
+    if (curr) enqueue(event!); else invoke(event);
+  }
+
+  function delay(event?: E): void {
+    if (pending !== event) {
+      requestAnimationFrame(() => {
+        const e = pending as E;
+        pending = NIL;
+        process(e);
+      });
+    }
+    pending = event;
+  }
+
+  return debounce ? delay : process;
+}

package/src/util/to-data-columns.ts

@@ -0,0 +1,65 @@
+import { isArrowTable } from './is-arrow-table.js';
+import type { Table } from '@uwdata/flechette';
+
+/**
+ * An Array or TypedArray
+ */
+type Arrayish = Array<unknown> | Int8Array | Uint8Array | Uint8ClampedArray
+  | Int16Array | Uint16Array | Int32Array | Uint32Array
+  | Float32Array | Float64Array;
+
+/**
+ * Data columns structure with either named columns or values array
+ */
+type DataColumns =
+  | { numRows: number; columns: Record<string, Arrayish> }
+  | { numRows: number; values: Arrayish };
+
+/**
+ * Convert input data to a set of column arrays.
+ * @param data The input data.
+ * @returns An object with named column arrays.
+ */
+export function toDataColumns(data: unknown): DataColumns {
+  if (isArrowTable(data)) {
+    return arrowToColumns(data);
+  } else if (Array.isArray(data)) {
+    return arrayToColumns(data);
+  } else {
+    throw new Error('Unrecognized data format.');
+  }
+}
+
+/**
+ * Convert an Arrow table to a set of column arrays.
+ * @param data An Arrow Table.
+ * @returns An object with named column arrays.
+ */
+function arrowToColumns(data: Table): DataColumns {
+  const { numRows } = data;
+  return { numRows, columns: data.toColumns() as Record<string, Arrayish> };
+}
+
+/**
+ * Convert an array of values to a set of column arrays.
+ * If the array values are objects, build out named columns.
+ * We use the keys of the first object as the column names.
+ * Otherwise, use a special "values" array.
+ * @param data An array of data objects.
+ * @returns An object with named column arrays.
+ */
+function arrayToColumns(data: Record<string,unknown>[]): DataColumns {
+  const numRows = data.length;
+  if (typeof data[0] === 'object') {
+    const names = numRows ? Object.keys(data[0]!) : [];
+    const columns: Record<string, unknown[]> = {};
+    if (names.length > 0) {
+      names.forEach(name => {
+        columns[name] = data.map(d => d[name]);
+      });
+    }
+    return { numRows, columns };
+  } else {
+    return { numRows, values: data };
+  }
+}

package/src/util/void-logger.ts

@@ -0,0 +1,23 @@
+interface Logger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  log(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  group(label?: string): void;
+  groupCollapsed(label?: string): void;
+  groupEnd(): void;
+}
+
+export function voidLogger(): Logger {
+  return {
+    debug(): void {},
+    info(): void {},
+    log(): void {},
+    warn(): void {},
+    error(): void {},
+    group(): void {},
+    groupCollapsed(): void {},
+    groupEnd(): void {}
+  };
+}

package/src/Coordinator.js

@@ -1,313 +0,0 @@
-/** @import { Connector } from './connectors/Connector.js' */
-/** @import { PreAggregateOptions } from './preagg/PreAggregator.js' */
-/** @import { QueryResult } from './util/query-result.js' */
-/** @import { SelectionClause } from './util/selection-types.js' */
-/** @import { MosaicClient } from './MosaicClient.js' */
-/** @import { Selection } from './Selection.js' */
-/** @import { Logger, QueryType } from './types.js' */
-import { socketConnector } from './connectors/socket.js';
-import { PreAggregator } from './preagg/PreAggregator.js';
-import { voidLogger } from './util/void-logger.js';
-import { QueryManager, Priority } from './QueryManager.js';
-
-/**
- * The singleton Coordinator instance.
- * @type {Coordinator}
- */
-let _instance;
-
-/**
- * Set or retrieve the coordinator instance.
- * @param {Coordinator} [instance] the coordinator instance to set
- * @returns {Coordinator} the coordinator instance
- */
-export function coordinator(instance) {
-  if (instance) {
-    _instance = instance;
-  } else if (_instance == null) {
-    _instance = new Coordinator();
-  }
-  return _instance;
-}
-
-/**
- * A Mosaic Coordinator manages all database communication for clients and
- * handles selection updates. The Coordinator also performs optimizations
- * including query caching, consolidation, and pre-aggregation.
- */
-export class Coordinator {
-  /**
-   * @param {Connector} [db] Database connector. Defaults to a web socket connection.
-   * @param {object} [options] Coordinator options.
-   * @param {Logger} [options.logger=console] The logger to use, defaults to `console`.
-   * @param {QueryManager} [options.manager] The query manager to use.
-   * @param {boolean} [options.cache=true] Boolean flag to enable/disable query caching.
-   * @param {boolean} [options.consolidate=true] Boolean flag to enable/disable query consolidation.
-   * @param {PreAggregateOptions} [options.preagg] Options for the Pre-aggregator.
-   */
-  constructor(db = socketConnector(), {
-    logger = console,
-    manager = new QueryManager(),
-    cache = true,
-    consolidate = true,
-    preagg = {}
-  } = {}) {
-    /** @type {QueryManager} */
-    this.manager = manager;
-    this.manager.cache(cache);
-    this.manager.consolidate(consolidate);
-    this.databaseConnector(db);
-    this.logger(logger);
-    this.clear();
-    this.preaggregator = new PreAggregator(this, preagg);
-  }
-
-  /**
-   * Clear the coordinator state.
-   * @param {object} [options] Options object.
-   * @param {boolean} [options.clients=true] If true, disconnect all clients.
-   * @param {boolean} [options.cache=true] If true, clear the query cache.
-   */
-  clear({ clients = true, cache = true } = {}) {
-    this.manager.clear();
-    if (clients) {
-      this.filterGroups?.forEach(group => group.disconnect());
-      this.filterGroups = new Map;
-      this.clients?.forEach(client => this.disconnect(client));
-      this.clients = new Set;
-    }
-    if (cache) this.manager.cache().clear();
-  }
-
-  /**
-   * Get or set the database connector.
-   * @param {Connector} [db] The database connector to use.
-   * @returns {Connector} The current database connector.
-   */
-  databaseConnector(db) {
-    return this.manager.connector(db);
-  }
-
-  /**
-   * Get or set the logger.
-   * @param {Logger} [logger] The logger to use.
-   * @returns {Logger} The current logger
-   */
-  logger(logger) {
-    if (arguments.length) {
-      this._logger = logger || voidLogger();
-      this.manager.logger(this._logger);
-    }
-    return this._logger;
-  }
-
-  // -- Query Management ----
-
-  /**
-   * Cancel previosuly submitted query requests. These queries will be
-   * canceled if they are queued but have not yet been submitted.
-   * @param {QueryResult[]} requests An array
-   *  of query result objects, such as those returned by the `query` method.
-   */
-  cancel(requests) {
-    this.manager.cancel(requests);
-  }
-
-  /**
-   * Issue a query for which no result (return value) is needed.
-   * @param {QueryType[] | 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.
-   */
-  exec(query, { priority = Priority.Normal } = {}) {
-    query = Array.isArray(query) ? query.filter(x => x).join(';\n') : query;
-    return this.manager.request({ type: 'exec', query }, priority);
-  }
-
-  /**
-   * 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 objec
-   *   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
-   *  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, {
-    type = 'arrow',
-    cache = true,
-    priority = Priority.Normal,
-    ...options
-  } = {}) {
-    return this.manager.request({ type, query, cache, options }, priority);
-  }
-
-  /**
-   * 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 {object} [options] An options object.
-   * @param {'arrow' | 'json'} [options.type] The query result format type.
-   * @returns {QueryResult} A query result promise.
-   */
-  prefetch(query, options = {}) {
-    return this.query(query, { ...options, cache: true, priority: Priority.Low });
-  }
-
-  // -- Client Management ----
-
-  /**
-   * 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 {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 client._pending = this.query(query, { priority })
-      .then(
-        data => client.queryResult(data).update(),
-        err => { this._logger.error(err); client.queryError(err); }
-      )
-      .catch(err => this._logger.error(err));
-  }
-
-  /**
-   * 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.
-   */
-  requestQuery(client, query) {
-    this.preaggregator.clear();
-    return query
-      ? this.updateClient(client, query)
-      : Promise.resolve(client.update());
-  }
-
-  /**
-   * Connect a client to the coordinator.
-   * @param {MosaicClient} client The Mosaic client to connect.
-   */
-  connect(client) {
-    const { clients } = this;
-
-    if (clients.has(client)) {
-      throw new Error('Client already connected.');
-    }
-
-    // add client to client set
-    clients.add(client);
-
-    // register coordinator on client instance
-    client.coordinator = this;
-
-    // initialize client lifecycle
-    client.initialize();
-
-    // connect filter selection
-    connectSelection(this, client.filterBy, client);
-  }
-
-  /**
-   * Disconnect a client from the coordinator.
-   * @param {MosaicClient} client The Mosaic client to disconnect.
-   */
-  disconnect(client) {
-    const { clients, filterGroups } = this;
-    if (!clients.has(client)) return;
-    clients.delete(client);
-    client.coordinator = null;
-
-    const group = filterGroups.get(client.filterBy);
-    if (group) {
-      group.clients.delete(client);
-    }
-  }
-}
-
-/**
- * Connect a selection-client pair to the coordinator to process updates.
- * @param {Coordinator} mc The Mosaic coordinator.
- * @param {Selection} selection A selection.
- * @param {MosaicClient} client A Mosiac client that is filtered by the
- *  given selection.
- */
-function connectSelection(mc, selection, client) {
-  if (!selection) return;
-  let entry = mc.filterGroups.get(selection);
-  if (!entry) {
-    const activate = clause => activateSelection(mc, selection, clause);
-    const value = () => updateSelection(mc, selection);
-
-    selection.addEventListener('activate', activate);
-    selection.addEventListener('value', value);
-
-    entry = {
-      selection,
-      clients: new Set,
-      disconnect() {
-        selection.removeEventListener('activate', activate);
-        selection.removeEventListener('value', value);
-      }
-    };
-    mc.filterGroups.set(selection, entry);
-  }
-  entry.clients.add(client);
-}
-
-/**
- * Activate a selection, providing a clause indicative of potential
- * next updates. Activation provides a preview of likely next events,
- * enabling potential precomputation to optimize updates.
- * @param {Coordinator} mc The Mosaic coordinator.
- * @param {Selection} selection A selection.
- * @param {SelectionClause} clause A selection clause for the activation.
- */
-function activateSelection(mc, selection, clause) {
-  const { preaggregator, filterGroups } = mc;
-  const { clients } = filterGroups.get(selection);
-  for (const client of clients) {
-    if (client.enabled) {
-      preaggregator.request(client, selection, clause);
-    }
-  }
-}
-
-/**
- * Process an updated selection value, querying filtered data for any
- * associated clients.
- * @param {Coordinator} mc The Mosaic coordinator.
- * @param {Selection} selection A selection.
- * @returns {Promise} A Promise that resolves when the update completes.
- */
-function updateSelection(mc, selection) {
-  const { preaggregator, filterGroups } = mc;
-  const { clients } = filterGroups.get(selection);
-  const { active } = selection;
-  return Promise.allSettled(Array.from(clients, client => {
-    if (!client.enabled) return client.requestQuery();
-    const info = preaggregator.request(client, selection, active);
-    const filter = info ? null : selection.predicate(client);
-
-    // skip due to cross-filtering
-    if (info?.skip || (!info && !filter)) return;
-
-    // @ts-ignore
-    const query = info?.query(active.predicate) ?? client.query(filter);
-    return mc.updateClient(client, query);
-  }));
-}