@uwdata/mosaic-core 0.16.2 → 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/dist/types/Coordinator.d.ts

@@ -1,164 +0,0 @@
-/**
- * Set or retrieve the coordinator instance.
- * @param {Coordinator} [instance] the coordinator instance to set
- * @returns {Coordinator} the coordinator instance
- */
-export function coordinator(instance?: Coordinator): Coordinator;
-/**
- * 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?: Connector, { logger, manager, cache, consolidate, preagg }?: {
-        logger?: Logger;
-        manager?: QueryManager;
-        cache?: boolean;
-        consolidate?: boolean;
-        preagg?: PreAggregateOptions;
-    });
-    /** @type {QueryManager} */
-    manager: QueryManager;
-    preaggregator: PreAggregator;
-    /**
-     * 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, cache }?: {
-        clients?: boolean;
-        cache?: boolean;
-    }): void;
-    filterGroups: Map<any, any>;
-    clients: Set<any>;
-    /**
-     * Get or set the database connector.
-     * @param {Connector} [db] The database connector to use.
-     * @returns {Connector} The current database connector.
-     */
-    databaseConnector(db?: Connector): Connector;
-    /**
-     * Get or set the logger.
-     * @param {Logger} [logger] The logger to use.
-     * @returns {Logger} The current logger
-     */
-    logger(logger?: Logger, ...args: any[]): Logger;
-    _logger: Logger;
-    /**
-     * 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: QueryResult[]): void;
-    /**
-     * 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: QueryType[] | 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 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: QueryType, { type, cache, priority, ...options }?: {
-        type?: "arrow" | "json";
-        cache?: boolean;
-        persist?: boolean;
-        priority?: number;
-    }): QueryResult;
-    /**
-     * 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: QueryType, options?: {
-        type?: "arrow" | "json";
-    }): QueryResult;
-    /**
-     * Create a bundle of queries that can be loaded into the cache.
-     *
-     * @param {string} name The name of the bundle.
-     * @param {[string | {sql: string},  {alias: string}]} queries The queries to save into the bundle.
-     * @param {number} priority Request priority.
-     * @returns {QueryResult} A query result promise.
-     */
-    createBundle(name: string, queries: [string | {
-        sql: string;
-    }, {
-        alias: string;
-    }], priority?: number): QueryResult;
-    /**
-     * Load a bundle into the cache.
-     * @param {string} name The name of the bundle.
-     * @param {number} priority Request priority.
-     * @returns {QueryResult} A query result promise.
-     */
-    loadBundle(name: string, priority?: number): QueryResult;
-    /**
-     * 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: MosaicClient, query: 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.
-     */
-    requestQuery(client: MosaicClient, query?: QueryType | null): Promise<any>;
-    /**
-     * Connect a client to the coordinator.
-     * @param {MosaicClient} client The Mosaic client to connect.
-     */
-    connect(client: MosaicClient): void;
-    /**
-     * Disconnect a client from the coordinator.
-     * @param {MosaicClient} client The Mosaic client to disconnect.
-     */
-    disconnect(client: MosaicClient): void;
-}
-import { QueryManager } from './QueryManager.js';
-import { PreAggregator } from './preagg/PreAggregator.js';
-import type { Connector } from './connectors/Connector.js';
-import type { Logger } from './types.js';
-import type { QueryResult } from './util/query-result.js';
-import type { QueryType } from './types.js';
-import type { MosaicClient } from './MosaicClient.js';
-import type { PreAggregateOptions } from './preagg/PreAggregator.js';

package/dist/types/Param.d.ts

@@ -1,47 +0,0 @@
-/**
- * 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.
- */
-export function isParam(x: any): x is Param;
-/**
- * Represents a dynamic parameter that dispatches updates
- * upon parameter changes.
- */
-export class Param extends AsyncDispatch {
-    /**
-     * Create a new Param instance with the given initial value.
-     * @param {*} value The initial value of the Param.
-     * @returns {Param} The new Param instance.
-     */
-    static value(value: any): Param;
-    /**
-     * 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.
-     */
-    static array(values: any): Param;
-    /**
-     * Create a new Param instance.
-     * @param {*} value The initial value of the Param.
-     */
-    constructor(value: any);
-    _value: any;
-    /**
-     * The current value of the Param.
-     */
-    get value(): any;
-    /**
-     * 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
-     *  should emit a 'value' event even if the internal value is unchanged.
-     * @returns {this} This Param instance.
-     */
-    update(value: any, { force }?: {
-        force?: boolean;
-    }): this;
-}
-import { AsyncDispatch } from './util/AsyncDispatch.js';

package/dist/types/QueryConsolidator.d.ts

@@ -1,9 +0,0 @@
-/**
- * Create a consolidator to combine structurally compatible queries.
- * @param {*} enqueue Query manager enqueue method
- * @param {*} cache Client-side query cache (sql -> data)
- * @returns A consolidator object
- */
-export function consolidator(enqueue: any, cache: any): {
-    add(entry: any, priority: any): void;
-};

package/dist/types/QueryManager.d.ts

@@ -1,91 +0,0 @@
-export const Priority: Readonly<{
-    High: 0;
-    Normal: 1;
-    Low: 2;
-}>;
-export class QueryManager {
-    constructor(maxConcurrentRequests?: number);
-    /** @type {PriorityQueue} */
-    queue: PriorityQueue;
-    /** @type {Connector} */
-    db: Connector;
-    /** @type {Cache} */
-    clientCache: Cache;
-    /** @type {Logger} */
-    _logger: Logger;
-    /** @type {boolean} */
-    _logQueries: boolean;
-    /** @type {ReturnType<typeof consolidator> | null} */
-    _consolidate: ReturnType<typeof consolidator> | null;
-    /**
-     * Requests pending with the query manager.
-     * @type {QueryResult[]}
-     */
-    pendingResults: QueryResult[];
-    /** @type {number} */
-    maxConcurrentRequests: number;
-    /** @type {boolean} */
-    pendingExec: boolean;
-    next(): void;
-    /**
-     * Add an entry to the query queue with a priority.
-     * @param {object} entry The entry to add.
-     * @param {*} [entry.request] The query request.
-     * @param {QueryResult} [entry.result] The query result.
-     * @param {number} priority The query priority, defaults to `Priority.Normal`.
-     */
-    enqueue(entry: {
-        request?: any;
-        result?: QueryResult;
-    }, priority?: number): void;
-    /**
-     * Submit the query to the connector.
-     * @param {*} request The request.
-     * @param {QueryResult} result The query result.
-     */
-    submit(request: any, result: QueryResult): Promise<void>;
-    /**
-     * Get or set the current query cache.
-     * @param {Cache | boolean} [value]
-     * @returns {Cache}
-     */
-    cache(value?: Cache | boolean): Cache;
-    /**
-     * Get or set the current logger.
-     * @param {Logger} [value]
-     * @returns {Logger}
-     */
-    logger(value?: Logger): Logger;
-    /**
-     * Get or set if queries should be logged.
-     * @param {boolean} [value]
-     * @returns {boolean}
-     */
-    logQueries(value?: boolean): boolean;
-    /**
-     * Get or set the database connector.
-     * @param {Connector} [connector]
-     * @returns {Connector}
-     */
-    connector(connector?: Connector): Connector;
-    /**
-     * Indicate if query consolidation should be performed.
-     * @param {boolean} flag
-     */
-    consolidate(flag: boolean): void;
-    /**
-     * Request a query result.
-     * @param {*} request The request.
-     * @param {number} priority The query priority, defaults to `Priority.Normal`.
-     * @returns {QueryResult} A query result promise.
-     */
-    request(request: any, priority?: number): QueryResult;
-    cancel(requests: any): void;
-    clear(): void;
-}
-import { PriorityQueue } from './util/priority-queue.js';
-import type { Connector } from './connectors/Connector.js';
-import type { Cache } from './types.js';
-import type { Logger } from './types.js';
-import { consolidator } from './QueryConsolidator.js';
-import { QueryResult } from './util/query-result.js';