@uwdata/mosaic-core 0.17.0 → 0.19.0

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,19 +95,19 @@ 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 (
-      query._orderby.length || query._where.length ||
-      query._qualify.length || query._having.length
+      query._where.length || query._qualify.length || query._having.length ||
+      query._orderby.length || query._distinct
     ) {
-      // do not try to analyze if query includes clauses
-      // that may refer to *derived* columns we can't resolve
+      // bail if query includes clauses that may refer to *derived* columns
+      // that we can't resolve. also do not consolidate distinct queries
       return sql;
     }
 
@@ -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;
-}
+}

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

@@ -1,5 +1,5 @@
-/** @import { Connector } from './connectors/Connector.js' */
-/** @import { Cache, Logger } from './types.js' */
+import type { Connector } from './connectors/Connector.js';
+import type { Cache, Logger, QueryEntry, QueryRequest } from './types.js';
 import { consolidator } from './QueryConsolidator.js';
 import { lruCache, voidCache } from './util/cache.js';
 import { PriorityQueue } from './util/priority-queue.js';
@@ -9,38 +9,38 @@ import { voidLogger } from './util/void-logger.js';
 export const Priority = Object.freeze({ High: 0, Normal: 1, Low: 2 });
 
 export class QueryManager {
-  constructor(
-    maxConcurrentRequests = 32
-  ) {
-    /** @type {PriorityQueue} */
+  private queue: PriorityQueue<QueryEntry>;
+  private db: Connector | null;
+  private clientCache: Cache | null;
+  private _logger: Logger;
+  private _logQueries: boolean;
+  private _consolidate: ReturnType<typeof consolidator> | null;
+  /** Requests pending with the query manager. */
+  public pendingResults: QueryResult[];
+  private maxConcurrentRequests: number;
+  private pendingExec: boolean;
+
+  constructor(maxConcurrentRequests: number = 32) {
     this.queue = new PriorityQueue(3);
-    /** @type {Connector} */
     this.db = null;
-    /** @type {Cache} */
     this.clientCache = null;
-    /** @type {Logger} */
     this._logger = voidLogger();
-    /** @type {boolean} */
     this._logQueries = false;
-    /** @type {ReturnType<typeof consolidator> | null} */
     this._consolidate = null;
-    /**
-     * Requests pending with the query manager.
-     * @type {QueryResult[]}
-     */
     this.pendingResults = [];
-    /** @type {number} */
     this.maxConcurrentRequests = maxConcurrentRequests;
-    /** @type {boolean} */
     this.pendingExec = false;
   }
 
-  next() {
+  next(): void {
     if (this.queue.isEmpty() || this.pendingResults.length > this.maxConcurrentRequests || this.pendingExec) {
       return;
     }
 
-    const { request, result } = this.queue.next();
+    const entry = this.queue.next();
+    if (!entry) return;
+
+    const { request, result } = entry;
 
     this.pendingResults.push(result);
     if (request.type === 'exec') this.pendingExec = true;
@@ -48,7 +48,7 @@ export class QueryManager {
     this.submit(request, result).finally(() => {
       // return from the queue all requests that are ready
       while (this.pendingResults.length && this.pendingResults[0].state !== QueryState.pending) {
-        const result = this.pendingResults.shift();
+        const result = this.pendingResults.shift()!;
         if (result.state === QueryState.ready) {
           result.fulfill();
         } else if (result.state === QueryState.done) {
@@ -62,29 +62,27 @@ export class QueryManager {
 
   /**
    * 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`.
+   * @param entry The entry to add.
+   * @param priority The query priority, defaults to `Priority.Normal`.
    */
-  enqueue(entry, priority = Priority.Normal) {
+  enqueue(entry: QueryEntry, priority: number = Priority.Normal): void {
     this.queue.insert(entry, priority);
     this.next();
   }
 
   /**
    * Submit the query to the connector.
-   * @param {*} request The request.
-   * @param {QueryResult} result The query result.
+   * @param request The request.
+   * @param result The query result.
    */
-  async submit(request, result) {
+  async submit(request: QueryRequest, result: QueryResult): Promise<void> {
     try {
       const { query, type, cache = false, options } = request;
       const sql = query ? `${query}` : null;
 
       // check query cache
       if (cache) {
-        const cached = this.clientCache.get(sql);
+        const cached = this.clientCache!.get(sql!);
         if (cached) {
           const data = await cached;
           this._logger.debug('Cache');
@@ -99,12 +97,13 @@ export class QueryManager {
         this._logger.debug('Query', { type, sql, ...options });
       }
 
-      const promise = this.db.query({ type, sql, ...options });
-      if (cache) this.clientCache.set(sql, promise);
+      // @ts-expect-error type may be exec | json | arrow
+      const promise = this.db!.query({ type, sql: sql!, ...options });
+      if (cache) this.clientCache!.set(sql!, promise);
 
       const data = await promise;
 
-      if (cache) this.clientCache.set(sql, data);
+      if (cache) this.clientCache!.set(sql!, data);
 
       this._logger.debug(`Request: ${(performance.now() - t0).toFixed(1)}`);
       result.ready(type === 'exec' ? null : data);
@@ -115,10 +114,12 @@ export class QueryManager {
 
   /**
    * Get or set the current query cache.
-   * @param {Cache | boolean} [value]
-   * @returns {Cache}
+   * @param value Cache value to set
+   * @returns Current cache
    */
-  cache(value) {
+  cache(): Cache | null;
+  cache(value: Cache | boolean): Cache;
+  cache(value?: Cache | boolean): Cache | null {
     return value !== undefined
       ? (this.clientCache = value === true ? lruCache() : (value || voidCache()))
       : this.clientCache;
@@ -126,38 +127,44 @@ export class QueryManager {
 
   /**
    * Get or set the current logger.
-   * @param {Logger} [value]
-   * @returns {Logger}
+   * @param value Logger to set
+   * @returns Current logger
    */
-  logger(value) {
+  logger(): Logger;
+  logger(value: Logger): Logger;
+  logger(value?: Logger): Logger {
     return value ? (this._logger = value) : this._logger;
   }
 
   /**
    * Get or set if queries should be logged.
-   * @param {boolean} [value]
-   * @returns {boolean}
+   * @param value Whether to log queries
+   * @returns Current logging state
    */
-  logQueries(value) {
+  logQueries(): boolean;
+  logQueries(value: boolean): boolean;
+  logQueries(value?: boolean): boolean {
     return value !== undefined ? this._logQueries = !!value : this._logQueries;
   }
 
   /**
    * Get or set the database connector.
-   * @param {Connector} [connector]
-   * @returns {Connector}
+   * @param connector Connector to set
+   * @returns Current connector
    */
-  connector(connector) {
+  connector(): Connector | null;
+  connector(connector: Connector): Connector;
+  connector(connector?: Connector): Connector | null {
     return connector ? (this.db = connector) : this.db;
   }
 
   /**
    * Indicate if query consolidation should be performed.
-   * @param {boolean} flag
+   * @param flag Whether to enable consolidation
    */
-  consolidate(flag) {
+  consolidate(flag: boolean): void {
     if (flag && !this._consolidate) {
-      this._consolidate = consolidator(this.enqueue.bind(this), this.clientCache);
+      this._consolidate = consolidator(this.enqueue.bind(this), this.clientCache!);
     } else if (!flag && this._consolidate) {
       this._consolidate = null;
     }
@@ -165,11 +172,11 @@ export class QueryManager {
 
   /**
    * Request a query result.
-   * @param {*} request The request.
-   * @param {number} priority The query priority, defaults to `Priority.Normal`.
-   * @returns {QueryResult} A query result promise.
+   * @param request The request.
+   * @param priority The query priority, defaults to `Priority.Normal`.
+   * @returns A query result promise.
    */
-  request(request, priority = Priority.Normal) {
+  request(request: QueryRequest, priority: number = Priority.Normal): QueryResult {
     const result = new QueryResult();
     const entry = { request, result };
     if (this._consolidate) {
@@ -180,7 +187,7 @@ export class QueryManager {
     return result;
   }
 
-  cancel(requests) {
+  cancel(requests: QueryResult[]): void {
     const set = new Set(requests);
     if (set.size) {
       this.queue.remove(({ result }) => {
@@ -199,7 +206,7 @@ export class QueryManager {
     }
   }
 
-  clear() {
+  clear(): void {
     this.queue.remove(({ result }) => {
       result.reject('Cleared');
       return true;
@@ -210,4 +217,4 @@ export class QueryManager {
     }
     this.pendingResults = [];
   }
-}
+}