@uwdata/mosaic-core 0.17.0 → 0.18.0

package/src/util/{AsyncDispatch.js → AsyncDispatch.ts}

@@ -1,43 +1,57 @@
+type EventCallback<T = unknown> = (value: T) => void | Promise<unknown>;
+
+interface DispatchEntry<T = unknown> {
+  callbacks: Set<EventCallback<T>>;
+  pending: Promise<unknown> | null;
+  queue: DispatchQueue<T>;
+}
+
+interface QueueNode<T = unknown> {
+  value: T;
+  next?: QueueNode<T> | null;
+}
+
 /**
  * Event dispatcher supporting asynchronous updates. If an event handler
  * callback returns a Promise, the dispatcher waits for all such Promises
  * to settle before dispatching future events of the same type.
  */
-export class AsyncDispatch {
+export class AsyncDispatch<T> {
+  _callbacks: Map<string, DispatchEntry<T>>;
 
   /**
    * Create a new asynchronous dispatcher instance.
    */
   constructor() {
-    this._callbacks = new Map;
+    this._callbacks = new Map();
   }
 
   /**
    * Add an event listener callback for the provided event type.
-   * @param {string} type The event type.
-   * @param {(value: *) => void | Promise} callback The event handler
+   * @param type The event type.
+   * @param callback The event handler
    *  callback function to add. If the callback has already been
    *  added for the event type, this method has no effect.
    */
-  addEventListener(type, callback) {
+  addEventListener(type: string, callback: EventCallback<T>): void {
     if (!this._callbacks.has(type)) {
       this._callbacks.set(type, {
-        callbacks: new Set,
+        callbacks: new Set<EventCallback<T>>(),
         pending: null,
-        queue: new DispatchQueue()
+        queue: new DispatchQueue<T>()
       });
     }
-    const entry = this._callbacks.get(type);
+    const entry = this._callbacks.get(type)!;
     entry.callbacks.add(callback);
   }
 
   /**
    * Remove an event listener callback for the provided event type.
-   * @param {string} type The event type.
-   * @param {(value: *) => void | Promise} callback The event handler
+   * @param type The event type.
+   * @param callback The event handler
    *  callback function to remove.
    */
-  removeEventListener(type, callback) {
+  removeEventListener(type: string, callback: EventCallback<T>): void {
     const entry = this._callbacks.get(type);
     if (entry) {
       entry.callbacks.delete(callback);
@@ -49,11 +63,11 @@ export class AsyncDispatch {
    * This default implementation simply returns the input value as-is.
    * Subclasses may override this method to implement custom transformations
    * prior to emitting an event value to all listeners.
-   * @param {string} type The event type.
-   * @param {*} value The event value.
+   * @param type The event type.
+   * @param value The event value.
    * @returns The (possibly transformed) event value to emit.
    */
-  willEmit(type, value) {
+  willEmit(type: string, value: T): T {
     return value;
   }
 
@@ -61,35 +75,38 @@ export class AsyncDispatch {
    * Lifecycle method that returns a filter function for updating the
    * queue of unemitted event values prior to enqueueing a new value.
    * This default implementation simply returns null, indicating that
-   * any other unemitted event values should be dropped (that is, all
+   * unknown other unemitted event values should be dropped (that is, all
    * queued events are filtered).
-   * @param {string} type The event type.
-   * @param {*} value The new event value that will be enqueued.
-   * @returns {(value: *) => boolean|null} A dispatch queue filter
+   * @param type The event type.
+   * @param value The new event value that will be enqueued.
+   * @returns A dispatch queue filter
    *  function, or null if all unemitted event values should be filtered.
    */
-  emitQueueFilter(type, value) { // eslint-disable-line no-unused-vars
+  emitQueueFilter(
+    _type: string, // eslint-disable-line @typescript-eslint/no-unused-vars
+    _value: unknown // eslint-disable-line @typescript-eslint/no-unused-vars
+  ): ((value: unknown) => boolean | null) | null {
     // removes all pending items
     return null;
   }
 
   /**
    * Cancel all unemitted event values for the given event type.
-   * @param {string} type The event type.
+   * @param type The event type.
    */
-  cancel(type) {
+  cancel(type: string): void {
     const entry = this._callbacks.get(type);
     entry?.queue.clear();
   }
 
   /**
-   * Returns a promise that resolves when any pending updates complete for
+   * Returns a promise that resolves when unknown pending updates complete for
    * the event of the given type currently being processed. The Promise will
    * resolve immediately if the queue for the given event type is empty.
-   * @param {string} type The event type to wait for.
-   * @returns {Promise} A pending event promise.
+   * @param type The event type to wait for.
+   * @returns A pending event promise.
    */
-  async pending(type) {
+  async pending(type: string): Promise<void> {
     await this._callbacks.get(type)?.pending;
   }
 
@@ -99,11 +116,11 @@ export class AsyncDispatch {
    * will be queued to be emitted later.
    * The actual event value given to listeners will be the result
    * of passing the input value through the emitValue() method.
-   * @param {string} type The event type.
-   * @param {*} value The event value.
+   * @param type The event type.
+   * @param value The event value.
    */
-  emit(type, value) {
-    const entry = this._callbacks.get(type) || {};
+  emit(type: string, value: T): void {
+    const entry = this._callbacks.get(type) || {} as DispatchEntry<T>;
     if (entry.pending) {
       // an earlier emit is still processing
       // enqueue the current update, possibly filtering other pending updates
@@ -118,7 +135,7 @@ export class AsyncDispatch {
         entry.pending = Promise.allSettled(callbackValues).then(() => {
           entry.pending = null;
           if (!queue.isEmpty()) {
-            this.emit(type, queue.dequeue());
+            this.emit(type, queue.dequeue()!);
           }
         });
       }
@@ -129,7 +146,8 @@ export class AsyncDispatch {
 /**
  * Queue for managing unemitted event values.
  */
-export class DispatchQueue {
+export class DispatchQueue<T = unknown> {
+  next: QueueNode<T> | null = null;
 
   /**
    * Create a new dispatch queue instance.
@@ -141,33 +159,34 @@ export class DispatchQueue {
   /**
    * Clear the queue state of all event values.
    */
-  clear() {
+  clear(): void {
     this.next = null;
   }
 
   /**
    * Indicate if the queue is empty.
-   * @returns {boolean} True if queue is empty, false otherwise.
+   * @returns True if queue is empty, false otherwise.
    */
-  isEmpty() {
+  isEmpty(): boolean {
     return !this.next;
   }
 
   /**
    * Add a new value to the queue, and optionally filter the
    * current queue content in response.
-   * @param {*} value The value to add.
-   * @param {(value: *) => boolean} [filter] An optional filter
+   * @param value The value to add.
+   * @param filter An optional filter
    *  function to apply to existing queue content. If unspecified
    *  or falsy, all previously queued values are removed. Otherwise,
    *  the provided function is applied to all queue entries. The
    *  entry is retained if the filter function returns a truthy value,
    *  otherwise the entry is removed.
    */
-  enqueue(value, filter) {
-    const tail = { value };
+  enqueue(value: T, filter?: ((value: T) => boolean | null) | null): void {
+    const tail: QueueNode<T> = { value };
     if (filter && this.next) {
-      let curr = this;
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      let curr: QueueNode<T> | DispatchQueue<T> = this;
       while (curr.next) {
         if (filter(curr.next.value)) {
           curr = curr.next;
@@ -183,11 +202,11 @@ export class DispatchQueue {
 
   /**
    * Remove and return the next queued event value.
-   * @returns {*} The next event value in the queue.
+   * @returns The next event value in the queue.
    */
-  dequeue() {
+  dequeue(): T | undefined {
     const { next } = this;
-    this.next = next?.next;
+    this.next = next?.next || null;
     return next?.value;
   }
-}
+}

package/src/util/{cache.js → cache.ts}

@@ -1,14 +1,19 @@
-/** @import { Cache } from '../types.js' */
+import type { Cache } from '../types.js';
 
 const requestIdle = typeof requestIdleCallback !== 'undefined'
   ? requestIdleCallback
   : setTimeout;
 
+interface CacheEntry<T = unknown> {
+  last: number;
+  value: T;
+}
+
 /**
  * Create a new cache that ignores all values.
- * @returns {Cache}
+ * @returns A void cache implementation.
  */
-export function voidCache() {
+export function voidCache(): Cache {
   return {
     get: () => undefined,
     set: (key, value) => value,
@@ -18,20 +23,23 @@ export function voidCache() {
 
 /**
  * Create a new cache that uses an LRU eviction policy.
- * @param {object} [options] Cache options.
- * @param {number} [options.max] Maximum number of cache entries.
- * @param {number} [options.ttl] Time-to-live for cache entries.
- * @returns {Cache}
+ * @param options Cache options.
+ * @param options.max Maximum number of cache entries.
+ * @param options.ttl Time-to-live for cache entries.
+ * @returns An LRU cache implementation.
  */
 export function lruCache({
   max = 1000, // max entries
   ttl = 3 * 60 * 60 * 1000 // time-to-live, default 3 hours
-} = {}) {
-  let cache = new Map;
+}: {
+  max?: number;
+  ttl?: number;
+} = {}): Cache {
+  let cache = new Map<string, CacheEntry>();
 
-  function evict() {
+  function evict(): void {
     const expire = performance.now() - ttl;
-    let lruKey = null;
+    let lruKey: string | null = null;
     let lruLast = Infinity;
 
     for (const [key, value] of cache) {
@@ -56,18 +64,20 @@ export function lruCache({
   }
 
   return {
-    get(key) {
+    get(key: string): unknown {
       const entry = cache.get(key);
       if (entry) {
         entry.last = performance.now();
         return entry.value;
       }
     },
-    set(key, value) {
+    set(key: string, value: unknown): unknown {
       cache.set(key, { last: performance.now(), value });
       if (cache.size > max) requestIdle(evict);
       return value;
     },
-    clear() { cache = new Map; }
+    clear(): void {
+      cache = new Map();
+    }
   };
-}
+}

package/src/util/decode-ipc.ts

@@ -0,0 +1,15 @@
+import type { ExtractionOptions, Table } from '@uwdata/flechette';
+import { tableFromIPC } from '@uwdata/flechette';
+
+/**
+ * Decode Arrow IPC bytes to a table instance.
+ * The default options map date and timestamp values to JS Date objects.
+ * @param data Arrow IPC bytes.
+ * @param options Arrow IPC extraction options.
+ *  If unspecified, the default options will extract date and timestamp
+ *  values to JS Date objects.
+ * @returns A table instance.
+ */
+export function decodeIPC(data: ArrayBuffer | Uint8Array, options: ExtractionOptions = { useDate: true }): Table {
+  return tableFromIPC(data, options);
+}

package/src/util/{distinct.js → distinct.ts}

@@ -1,14 +1,14 @@
-export function distinct(a, b) {
+export function distinct(a: unknown, b: unknown): boolean {
   return a === b ? false
     : a instanceof Date && b instanceof Date ? +a !== +b
     : Array.isArray(a) && Array.isArray(b) ? distinctArray(a, b)
     : true;
 }
 
-export function distinctArray(a, b) {
+export function distinctArray(a: unknown[], b: unknown[]): boolean {
   if (a.length !== b.length) return true;
   for (let i = 0; i < a.length; ++i) {
     if (a[i] !== b[i]) return true;
   }
   return false;
-}
+}

package/src/util/{field-info.js → field-info.ts}

@@ -1,6 +1,9 @@
-/** @import { AggregateNode } from '@uwdata/mosaic-sql' */
+import type { AggregateNode } from '@uwdata/mosaic-sql';
 import { Query, asTableRef, count, isAggregateExpression, isNode, isNull, max, min, sql } from '@uwdata/mosaic-sql';
 import { jsType } from './js-type.js';
+import type { Coordinator } from '../Coordinator.js';
+import type { FieldInfoRequest, FieldInfo, Stat, FieldRef, ColumnDescription } from '../types.js';
+import { Table } from '@uwdata/flechette';
 
 export const Count = 'count';
 export const Nulls = 'nulls';
@@ -9,13 +12,7 @@ export const Min = 'min';
 export const Distinct = 'distinct';
 export const Stats = { Count, Nulls, Max, Min, Distinct };
 
-/**
- * @type {Record<
- *  import('../types.js').Stat,
- *  (column: import('../types.js').FieldRef) => AggregateNode
- * >}
- */
-const statMap = {
+const statMap: Record<Stat, (column: FieldRef) => AggregateNode> = {
   [Count]: count,
   [Distinct]: column => count(column).distinct(),
   [Max]: max,
@@ -25,13 +22,13 @@ const statMap = {
 
 /**
  * Get summary stats of the given column
- * @param {import('../types.js').FieldInfoRequest} field
- * @returns {Query}
+ * @param field Field information request
+ * @returns Query for field statistics
  */
-function summarize({ table, column, stats }) {
+function summarize({ table, column, stats }: FieldInfoRequest): Query {
   return Query
     .from(table)
-    .select(Array.from(stats, s => ({ [s]: statMap[s](column) })));
+    .select(Array.from(stats!, s => ({ [s]: statMap[s](column) })));
 }
 
 /**
@@ -40,27 +37,27 @@ function summarize({ table, column, stats }) {
  * 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[]>}
+ * @param mc A Mosaic coordinator.
+ * @param fields Array of field information requests.
+ * @returns Promise resolving to array of field information.
  */
-export async function queryFieldInfo(mc, fields) {
+export async function queryFieldInfo(mc: Coordinator, fields: FieldInfoRequest[]): Promise<FieldInfo[]> {
   if (fields.length === 1 && fields[0].column === '*') {
     return getTableInfo(mc, fields[0].table);
   } else {
     return (await Promise
       .all(fields.map(f => getFieldInfo(mc, f))))
-      .filter(x => x);
+      .filter((x): x is FieldInfo => x !== undefined);
   }
 }
 
 /**
  * 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>}
+ * @param mc A Mosaic coordinator.
+ * @param field Field information request.
+ * @returns Promise resolving to field information.
  */
-async function getFieldInfo(mc, { table, column, stats }) {
+async function getFieldInfo(mc: Coordinator, { table, column, stats }: FieldInfoRequest): Promise<FieldInfo> {
   // generate and issue a query for field metadata info
   // use GROUP BY ALL to differentiate & consolidate aggregates
   const q = Query
@@ -68,9 +65,10 @@ async function getFieldInfo(mc, { table, column, stats }) {
     .select({ column })
     .groupby(isNode(column) && isAggregateExpression(column) ? sql`ALL` : []);
 
-  /** @type {import('../types.js').ColumnDescription[]} */
-  const [desc] = Array.from(await mc.query(Query.describe(q)));
-  const info = {
+  const [desc] = Array.from(
+    await mc.query(Query.describe(q)) as Table
+  ) as ColumnDescription[];
+  const info: FieldInfo = {
     table,
     column: `${column}`,
     sqlType: desc.column_type,
@@ -85,7 +83,7 @@ async function getFieldInfo(mc, { table, column, stats }) {
   const [result] = await mc.query(
     summarize({ table, column, stats }),
     { persist: true }
-  );
+  ) as Table;
 
   // extract summary stats, copy to field info, and return
   return Object.assign(info, result);
@@ -93,13 +91,14 @@ async function getFieldInfo(mc, { table, column, stats }) {
 
 /**
  * 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[]>}
+ * @param mc A Mosaic coordinator.
+ * @param table The table name.
+ * @returns Promise resolving to array of field information.
  */
-async function getTableInfo(mc, table) {
-  /** @type {import('../types.js').ColumnDescription[]} */
-  const result = Array.from(await mc.query(`DESCRIBE ${asTableRef(table)}`));
+async function getTableInfo(mc: Coordinator, table: string): Promise<FieldInfo[]> {
+  const result = Array.from(
+    await mc.query(`DESCRIBE ${asTableRef(table)}`) as Table
+  ) as ColumnDescription[];
   return result.map(desc => ({
     table,
     column: desc.column_name,
@@ -107,4 +106,4 @@ async function getTableInfo(mc, table) {
     type: jsType(desc.column_type),
     nullable: desc.null === 'YES'
   }));
-}
+}

package/src/util/{hash.js → hash.ts}

@@ -1,5 +1,5 @@
 // Fowler/Noll/Vo hashing.
-export function fnv_hash(v) {
+export function fnv_hash(v: string): number {
   let a = 2166136261;
   for (let i = 0, n = v.length; i < n; ++i) {
     const c = v.charCodeAt(i);
@@ -11,16 +11,16 @@ export function fnv_hash(v) {
 }
 
 // a * 16777619 mod 2**32
-function fnv_multiply(a) {
+function fnv_multiply(a: number): number {
   return a + (a << 1) + (a << 4) + (a << 7) + (a << 8) + (a << 24);
 }
 
 // See https://web.archive.org/web/20131019013225/http://home.comcast.net/~bretm/hash/6.html
-function fnv_mix(a) {
+function fnv_mix(a: number): number {
   a += a << 13;
   a ^= a >>> 7;
   a += a << 3;
   a ^= a >>> 17;
   a += a << 5;
   return a & 0xffffffff;
-}
+}

package/src/util/is-activatable.ts

@@ -0,0 +1,11 @@
+import type { Activatable } from '../types.js';
+
+/**
+ * Test if a value implements the Activatable interface.
+ * @param value The value to test.
+ * @returns True if value implements Activatable interface.
+ */
+export function isActivatable(value: unknown): value is Activatable {
+  // @ts-expect-error check properties of unknown value
+  return typeof value?.activate === 'function' && value.activate.length === 0;
+}

package/src/util/is-arrow-table.ts

@@ -0,0 +1,12 @@
+import type { Table } from '@uwdata/flechette';
+
+/**
+ * Test if a value is a Flechette Arrow table.
+ * We use a "duck typing" approach and check for a getChild function.
+ * @param values The value to test
+ * @returns true if the value duck types as Arrow data
+ */
+export function isArrowTable(values: unknown): values is Table {
+  // @ts-expect-error check property of unknown value
+  return typeof values?.getChild === 'function';
+}

package/src/util/{js-type.js → js-type.ts}

@@ -1,10 +1,12 @@
+import type { JSType } from '../types.js';
+
 /**
  * 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.
+ * @param type The name of a SQL data type
+ * @returns The corresponding JavaScript type name
+ * @throws Throws an error if the given SQL type name is unsupported or unrecognized.
  */
-export function jsType(type) {
+export function jsType(type: string): JSType {
   switch (type) {
     case 'BIGINT':
     case 'HUGEINT':
@@ -52,4 +54,4 @@ export function jsType(type) {
       }
       throw new Error(`Unsupported type: ${type}`);
   }
-}
+}

package/src/util/{priority-queue.js → priority-queue.ts}

@@ -1,60 +1,72 @@
-export class PriorityQueue {
+interface ListNode<T> {
+  item: T;
+  next: ListNode<T> | null;
+}
+
+interface List<T> {
+  head: ListNode<T> | null;
+  tail: ListNode<T> | null;
+}
+
+export class PriorityQueue<T = unknown> {
+  private queue: List<T>[];
+
   /**
    * Create a new priority queue instance.
-   * @param {number} ranks An integer number of rank-order priority levels.
+   * @param ranks An integer number of rank-order priority levels.
    */
-  constructor(ranks) {
+  constructor(ranks: number) {
     // one list for each integer priority level
     this.queue = Array.from(
-		{ length: ranks },
-		() => ({ head: null, tail: null })
-	);
+      { length: ranks },
+      (): List<T> => ({ head: null, tail: null })
+    );
   }
 
   /**
    * Indicate if the queue is empty.
-   * @returns {boolean} true if empty, false otherwise.
+   * @returns true if empty, false otherwise.
    */
-  isEmpty() {
+  isEmpty(): boolean {
     return this.queue.every(list => !list.head);
   }
 
   /**
    * Insert an item into the queue with a given priority rank.
-   * @param {*} item The item to add.
-   * @param {number} rank The integer priority rank.
+   * @param item The item to add.
+   * @param rank The integer priority rank.
    * Priority ranks are integers starting at zero.
    * Lower ranks indicate higher priority.
    */
-  insert(item, rank) {
+  insert(item: T, rank: number): void {
     const list = this.queue[rank];
     if (!list) {
       throw new Error(`Invalid queue priority rank: ${rank}`);
     }
 
-    const node = { item, next: null };
+    const node: ListNode<T> = { item, next: null };
     if (list.head === null) {
       list.head = list.tail = node;
     } else {
-      list.tail = list.tail.next = node;
+      list.tail = list.tail!.next = node;
     }
   }
 
   /**
    * Remove a set of items from the queue, regardless of priority rank.
    * If a provided item is not in the queue it will be ignored.
-   * @param {(item: *) => boolean} test A predicate function to test
+   * @param test A predicate function to test
    * if an item should be removed (true to drop, false to keep).
    */
-  remove(test) {
+  remove(test: (item: T) => boolean): void {
     for (const list of this.queue) {
       let { head, tail } = list;
-      for (let prev = null, curr = head; curr; prev = curr, curr = curr.next) {
+      for (let prev: ListNode<T> | null = null, curr = head; curr; prev = curr, curr = curr.next) {
         if (test(curr.item)) {
           if (curr === head) {
             head = curr.next;
           } else {
-            prev.next = curr.next;
+            prev!.next = curr.next;
           }
           if (curr === tail) tail = prev || head;
         }
@@ -66,10 +78,10 @@ export class PriorityQueue {
 
   /**
    * Remove and return the next highest priority item.
-   * @returns {*} The next item in the queue,
+   * @returns The next item in the queue,
    * or undefined if this queue is empty.
    */
-  next() {
+  next(): T | undefined {
     for (const list of this.queue) {
       const { head } = list;
       if (head !== null) {
@@ -81,4 +93,4 @@ export class PriorityQueue {
       }
     }
   }
-}
+}