@uwdata/mosaic-core 0.14.1 → 0.16.1

package/src/MosaicClient.js

@@ -1,29 +1,49 @@
-import { Coordinator } from './Coordinator.js';
-import { Selection } from './Selection.js';
+/** @import { Query } from '@uwdata/mosaic-sql' */
+/** @import { Coordinator } from './Coordinator.js' */
+/** @import { Selection } from './Selection.js' */
 import { throttle } from './util/throttle.js';
 
 /**
- * Base class for Mosaic clients.
+ * A Mosaic client is a data consumer that indicates its data needs to a
+ * Mosaic coordinator via the query method. The coordinator is responsible
+ * for issuing queries and returning results to the client.
+ *
+ * The client life-cycle consists of connection to a coordinator,
+ * initialization (potentially involving queries for data schema and summary
+ * statistic information), and then interactive queries that may be driven by
+ * an associated selection. When no longer needed, a client should be
+ * disconnected from the coordinator.
+ *
+ * When enabled, a client will initialize and respond to query update requests.
+ * If disabled, the client will delay initialization and not respond to queries
+ * until enabled again. Disabling a client can improve system performance when
+ * associated interface elements are offscreen or disabled.
  */
 export class MosaicClient {
   /**
-   * Constructor.
-   * @param {*} filterSelection An optional selection to interactively filter
-   *  this client's data. If provided, a coordinator will re-query and update
-   *  the client when the selection updates.
+   * Create a new client instance.
+   * @param {Selection} [filterSelection] An optional selection to
+   *  interactively filter this client's data. If provided, a coordinator
+   *  will re-query and update the client when the selection updates.
    */
   constructor(filterSelection) {
-    /** @type {Selection} */
+    /** @type {Selection | undefined} */
     this._filterBy = filterSelection;
     this._requestUpdate = throttle(() => this.requestQuery(), true);
-    /** @type {Coordinator} */
+    /** @type {Coordinator | null} */
     this._coordinator = null;
     /** @type {Promise<any>} */
     this._pending = Promise.resolve();
+    /** @type {boolean} */
+    this._enabled = true;
+    /** @type {boolean} */
+    this._initialized = false;
+    /** @type {Query | boolean | null} */
+    this._request = null;
   }
 
   /**
-   * Return this client's connected coordinator.
+   * @returns {Coordinator | null}  this client's connected coordinator.
    */
   get coordinator() {
     return this._coordinator;
@@ -36,6 +56,33 @@ export class MosaicClient {
     this._coordinator = coordinator;
   }
 
+  /**
+   * Return this client's enabled state.
+   */
+  get enabled() {
+    return this._enabled;
+  }
+
+  /**
+   * Set this client's enabled state;
+   */
+  set enabled(state) {
+    state = !!state; // ensure boolean
+    if (this._enabled !== state) {
+      this._enabled = state;
+      if (state) {
+        if (!this._initialized) {
+          // initialization includes a query request
+          this.initialize();
+        } else if (this._request) {
+          // request query now if requested while disabled
+          this.requestQuery(this._request === true ? undefined : this._request);
+        }
+        this._request = null;
+      }
+    }
+  }
+
   /**
    * Return a Promise that resolves once the client has updated.
    */
@@ -44,7 +91,7 @@ export class MosaicClient {
   }
 
   /**
-   * Return this client's filter selection.
+   * @returns {Selection | undefined} this client's filter selection.
    */
   get filterBy() {
     return this._filterBy;
@@ -52,8 +99,8 @@ export class MosaicClient {
 
   /**
    * Return a boolean indicating if the client query can be sped up with
-   * materialized views of pre-aggregated data. Should return true if changes to
-   * the filterBy selection does not change the groupby domain of the client
+   * materialized views of pre-aggregated data. Should return true if changes
+   * to the filterBy selection do not change the groupby domain of the client
    * query.
    */
   get filterStable() {
@@ -61,25 +108,9 @@ export class MosaicClient {
   }
 
   /**
-   * Return an array of fields queried by this client.
-   * @returns {import('./types.js').FieldInfoRequest[] | null}
-   *  The fields to retrieve info for.
-   */
-  fields() {
-    return null;
-  }
-
-  /**
-   * Called by the coordinator to set the field info for this client.
-   * @param {import('./types.js').FieldInfo[]} info The field info result.
-   * @returns {this}
-   */
-  fieldInfo(info) { // eslint-disable-line no-unused-vars
-    return this;
-  }
-
-  /**
-   * Prepare the client before the query() method is called.
+   * Prepare the client before the `query()` method is called. Subclasses
+   * should override this method as needed, potentially issuing one or more
+   * queries to gather data or metadata needed prior to `query` calls.
    */
   async prepare() {
   }
@@ -122,34 +153,67 @@ export class MosaicClient {
 
   /**
    * Request the coordinator to execute a query for this client.
-   * If an explicit query is not provided, the client query method will
-   * be called, filtered by the current filterBy selection. This method
-   * has no effect if the client is not registered with a coordinator.
+   * If an explicit query is not provided, the client `query` method will
+   * be called, filtered by the current `filterBy` selection. This method has
+   * no effect if the client is not connected to a coordinator. If the client
+   * is connected by currently disabled, the request will be serviced if the
+   * client is later enabled.
+   * @param {Query} [query] The query to request. If unspecified, the query
+   *  will be determind by the client's `query` method and the current
+   *  `filterBy` selection state.
    * @returns {Promise}
    */
   requestQuery(query) {
-    const q = query || this.query(this.filterBy?.predicate(this));
-    return this._coordinator?.requestQuery(this, q);
+    if (this._enabled) {
+      const q = query || this.query(this.filterBy?.predicate(this));
+      return this._coordinator?.requestQuery(this, q);
+    } else {
+      this._request = query ?? true;
+      return null;
+    }
   }
 
   /**
    * Request that the coordinator perform a throttled update of this client
-   * using the default query. Unlike requestQuery, for which every call will
-   * result in an executed query, multiple calls to requestUpdate may be
-   * consolidated into a single update.
+   * using the default query. Unlike requestQuery, for which every call results
+   * in an executed query, multiple calls to requestUpdate may be consolidated
+   * into a single update. This method has no effect if the client is not
+   * connected to a coordinator. If the client is connected but currently
+   * disabled, the request will be serviced if the client is later enabled.
    */
   requestUpdate() {
-    this._requestUpdate();
+    if (this._enabled) {
+      this._requestUpdate();
+    } else {
+      this.requestQuery();
+    }
   }
 
   /**
-   * Reset this client, initiating new field info, call the prepare method,
-   * and query requests. This method has no effect if the client is not
-   * registered with a coordinator.
-   * @returns {Promise}
+   * Reset this client, calling the prepare method and query requests. This
+   * method has no effect if the client is not registered with a coordinator.
    */
   initialize() {
-    return this._coordinator?.initializeClient(this);
+    if (!this._enabled) {
+      // clear flag so we initialize when enabled again
+      this._initialized = false;
+    } else if (this._coordinator) {
+      // if connected, let's initialize
+      this._initialized = true;
+      this._pending = this.prepare().then(() => this.requestQuery());
+    }
+  }
+
+  /**
+   * Remove this client: disconnect from the coordinator and free up any
+   * resource use. This method has no effect if the client is not connected
+   * to a coordinator.
+   *
+   * If overriding this method in a client subclass, be sure to also
+   * disconnect from the coordinator.
+   */
+  destroy() {
+    this.coordinator?.disconnect(this);
   }
 
   /**

package/src/QueryConsolidator.js

@@ -1,4 +1,5 @@
-import { DescribeQuery, isAggregateExpression, isColumnRef, isDescribeQuery, isSelectQuery, Query } from '@uwdata/mosaic-sql';
+/** @import { DescribeQuery, Query } from '@uwdata/mosaic-sql' */
+import { isAggregateExpression, isColumnRef, isDescribeQuery, isSelectQuery } from '@uwdata/mosaic-sql';
 import { QueryResult } from './util/query-result.js';
 
 function wait(callback) {

package/src/QueryManager.js

@@ -1,3 +1,5 @@
+/** @import { Connector } from './connectors/Connector.js' */
+/** @import { Cache, Logger } from './types.js' */
 import { consolidator } from './QueryConsolidator.js';
 import { lruCache, voidCache } from './util/cache.js';
 import { PriorityQueue } from './util/priority-queue.js';
@@ -12,10 +14,15 @@ export class QueryManager {
   ) {
     /** @type {PriorityQueue} */
     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.
@@ -106,24 +113,48 @@ export class QueryManager {
     }
   }
 
+  /**
+   * Get or set the current query cache.
+   * @param {Cache | boolean} [value]
+   * @returns {Cache}
+   */
   cache(value) {
     return value !== undefined
       ? (this.clientCache = value === true ? lruCache() : (value || voidCache()))
       : this.clientCache;
   }
 
+  /**
+   * Get or set the current logger.
+   * @param {Logger} [value]
+   * @returns {Logger}
+   */
   logger(value) {
     return value ? (this._logger = value) : this._logger;
   }
 
+  /**
+   * Get or set if queries should be logged.
+   * @param {boolean} [value]
+   * @returns {boolean}
+   */
   logQueries(value) {
     return value !== undefined ? this._logQueries = !!value : this._logQueries;
   }
 
+  /**
+   * Get or set the database connector.
+   * @param {Connector} [connector]
+   * @returns {Connector}
+   */
   connector(connector) {
     return connector ? (this.db = connector) : this.db;
   }
 
+  /**
+   * Indicate if query consolidation should be performed.
+   * @param {boolean} flag
+   */
   consolidate(flag) {
     if (flag && !this._consolidate) {
       this._consolidate = consolidator(this.enqueue.bind(this), this.clientCache);

package/src/Selection.js

@@ -1,7 +1,9 @@
-/** @import {SelectionClause} from './util/selection-types.js' */
+/**
+ * @import { MosaicClient } from './MosaicClient.js'
+ * @import { SelectionClause } from './util/selection-types.js'
+ */
 import { literal, or } from '@uwdata/mosaic-sql';
 import { Param } from './Param.js';
-import { MosaicClient } from './MosaicClient.js';
 
 /**
  * Test if a value is a Selection instance.

package/src/SelectionClause.js

@@ -1,5 +1,8 @@
-import { ExprNode, and, contains, isBetween, isIn, isNotDistinct, literal, or, prefix, regexp_matches, suffix } from '@uwdata/mosaic-sql';
-import { MosaicClient } from './MosaicClient.js';
+/**
+ * @import { ExprNode } from '@uwdata/mosaic-sql'
+ * @import { MosaicClient } from './MosaicClient.js'
+ */
+import { and, contains, isBetween, isIn, isNotDistinct, literal, or, prefix, regexp_matches, suffix } from '@uwdata/mosaic-sql';
 
 /**
  * @typedef {import('./util/selection-types.js').SelectionClause} SelectionClause

package/src/connectors/Connector.ts

@@ -0,0 +1,30 @@
+import type { Table } from '@uwdata/flechette';
+
+export interface QueryRequest {
+  /** The query type. */
+  type?: string;
+  /** A SQL query string. */
+  sql: string;
+}
+
+export interface ArrowQueryRequest extends QueryRequest {
+  /** The query type. */
+  type?: 'arrow';
+}
+
+export interface ExecQueryRequest extends QueryRequest {
+  /** The query type. */
+  type: 'exec';
+}
+
+export interface JSONQueryRequest extends QueryRequest {
+  /** The query type. */
+  type: 'json';
+}
+
+export interface Connector {
+  /** Issue a query and return the result. */
+  query(query: ArrowQueryRequest): Promise<Table>;
+  query(query: ExecQueryRequest): Promise<void>;
+  query(query: JSONQueryRequest): Promise<Record<string, any>[]>;
+}

package/src/connectors/rest.js

@@ -1,16 +1,19 @@
+/** @import { ExtractionOptions } from '@uwdata/flechette' */
+/** @import { Connector } from './Connector.js' */
 import { decodeIPC } from '../util/decode-ipc.js';
 
-export function restConnector(uri = 'http://localhost:3000/') {
+/**
+ * Connect to a DuckDB server over an HTTP REST interface.
+ * @param {object} [options] Connector options.
+ * @param {string} [options.uri] The URI for the DuckDB REST server.
+ * @param {ExtractionOptions} [options.ipc] Arrow IPC extraction options.
+ * @returns {Connector} A connector instance.
+ */
+export function restConnector({
+  uri = 'http://localhost:3000/',
+  ipc = undefined,
+} = {}) {
   return {
-    /**
-     * Query the DuckDB server.
-     * @param {object} query
-     * @param {'exec' | 'arrow' | 'json' | 'create-bundle' | 'load-bundle'} [query.type] The query type.
-     * @param {string} [query.sql] A SQL query string.
-     * @param {string[]} [query.queries] The queries used to create a bundle.
-     * @param {string} [query.name] The name of a bundle to create or load.
-     * @returns the query result
-     */
     async query(query) {
       const req = fetch(uri, {
         method: 'POST',
@@ -21,7 +24,6 @@ export function restConnector(uri = 'http://localhost:3000/') {
         body: JSON.stringify(query)
       });
 
-
       const res = await req;
 
       if (!res.ok) {
@@ -29,7 +31,7 @@ export function restConnector(uri = 'http://localhost:3000/') {
       }
 
       return query.type === 'exec' ? req
-        : query.type === 'arrow' ? decodeIPC(await res.arrayBuffer())
+        : query.type === 'arrow' ? decodeIPC(await res.arrayBuffer(), ipc)
         : res.json();
     }
   };

package/src/connectors/socket.js

@@ -1,100 +1,135 @@
+/** @import { ExtractionOptions, Table } from '@uwdata/flechette' */
+/** @import { ArrowQueryRequest, Connector, ExecQueryRequest, JSONQueryRequest } from './Connector.js' */
 import { decodeIPC } from '../util/decode-ipc.js';
 
-export function socketConnector(uri = 'ws://localhost:3000/') {
-  const queue = [];
-  let connected = false;
-  let request = null;
-  let ws;
+/**
+ * Connect to a DuckDB server over a WebSocket interface.
+ * @param {object} [options] Connector options.
+ * @param {string} [options.uri] The URI for the DuckDB REST server.
+ * @param {ExtractionOptions} [options.ipc] Arrow IPC extraction options.
+ * @returns {SocketConnector} A connector instance.
+ */
+export function socketConnector(options) {
+  return new SocketConnector(options);
+}
 
-  const events = {
-    open() {
-      connected = true;
-      next();
-    },
+/**
+ * DuckDB socket connector.
+ * @implements {Connector}
+ */
+export class SocketConnector {
+  /**
+   * @param {object} [options] Connector options.
+   * @param {string} [options.uri] The URI for the DuckDB REST server.
+   * @param {ExtractionOptions} [options.ipc] Arrow IPC extraction options.
+   */
+  constructor({
+    uri = 'ws://localhost:3000/',
+    ipc = undefined,
+  } = {}) {
+    this._uri = uri;
+    this._queue = [];
+    this._connected = false;
+    this._request = null;
+    this._ws = null;
 
-    close() {
-      connected = false;
-      request = null;
-      ws = null;
-      while (queue.length) {
-        queue.shift().reject('Socket closed');
-      }
-    },
+    const c = this;
+    this._events = {
+      open() {
+        c._connected = true;
+        c.next();
+      },
 
-    error(event) {
-      if (request) {
-        const { reject } = request;
-        request = null;
-        next();
-        reject(event);
-      } else {
-        console.error('WebSocket error: ', event);
-      }
-    },
+      close() {
+        c._connected = false;
+        c._request = null;
+        c._ws = null;
+        while (c._queue.length) {
+          c._queue.shift().reject('Socket closed');
+        }
+      },
 
-    message({ data }) {
-      if (request) {
-        const { query, resolve, reject } = request;
+      error(event) {
+        if (c._request) {
+          const { reject } = c._request;
+          c._request = null;
+          c.next();
+          reject(event);
+        } else {
+          console.error('WebSocket error: ', event);
+        }
+      },
 
-        // clear state, start next request
-        request = null;
-        next();
+      message({ data }) {
+        if (c._request) {
+          const { query, resolve, reject } = c._request;
 
-        // process result
-        if (typeof data === 'string') {
-          const json = JSON.parse(data);
-          json.error ? reject(json.error) : resolve(json);
-        } else if (query.type === 'exec') {
-          resolve();
-        } else if (query.type === 'arrow') {
-          resolve(decodeIPC(data));
+          // clear state, start next request
+          c._request = null;
+          c.next();
+
+          // process result
+          if (typeof data === 'string') {
+            const json = JSON.parse(data);
+            json.error ? reject(json.error) : resolve(json);
+          } else if (query.type === 'exec') {
+            resolve();
+          } else if (query.type === 'arrow') {
+            resolve(decodeIPC(data, ipc));
+          } else {
+            throw new Error(`Unexpected socket data: ${data}`);
+          }
         } else {
-          throw new Error(`Unexpected socket data: ${data}`);
+          console.log('WebSocket message: ', data);
         }
-      } else {
-        console.log('WebSocket message: ', data);
       }
     }
   }
 
-  function init() {
-    ws = new WebSocket(uri);
-    ws.binaryType = 'arraybuffer';
-    for (const type in events) {
-      ws.addEventListener(type, events[type]);
+  get connected() {
+    return this._connected;
+  }
+
+  init() {
+    this._ws = new WebSocket(this._uri);
+    this._ws.binaryType = 'arraybuffer';
+    for (const type in this._events) {
+      this._ws.addEventListener(type, this._events[type]);
     }
   }
 
-  function enqueue(query, resolve, reject) {
-    if (ws == null) init();
-    queue.push({ query, resolve, reject });
-    if (connected && !request) next();
+  enqueue(query, resolve, reject) {
+    if (this._ws == null) this.init();
+    this._queue.push({ query, resolve, reject });
+    if (this._connected && !this._request) this.next();
   }
 
-  function next() {
-    if (queue.length) {
-      request = queue.shift();
-      ws.send(JSON.stringify(request.query));
+  next() {
+    if (this._queue.length) {
+      this._request = this._queue.shift();
+      this._ws.send(JSON.stringify(this._request.query));
     }
   }
 
-  return {
-    get connected() {
-      return connected;
-    },
-    /**
-     * Query the DuckDB server.
-     * @param {object} query
-     * @param {'exec' | 'arrow' | 'json' | 'create-bundle' | 'load-bundle'} [query.type] The query type.
-     * @param {string} [query.sql] A SQL query string.
-     * @param {string[]} [query.queries] The queries used to create a bundle.
-     * @param {string} [query.name] The name of a bundle to create or load.
-     * @returns the query result
-     */
-    query(query) {
-      return new Promise(
-        (resolve, reject) => enqueue(query, resolve, reject)
-      );
-    }
-  };
+  /**
+   * @overload
+   * @param {ArrowQueryRequest} query
+   * @returns {Promise<Table>}
+   *
+   * @overload
+   * @param {ExecQueryRequest} query
+   * @returns {Promise<void>}
+   *
+   * @overload
+   * @param {JSONQueryRequest} query
+   * @returns {Promise<Record<string, any>[]>}
+   *
+   * @param {ArrowQueryRequest | ExecQueryRequest | JSONQueryRequest} query
+   * @returns {Promise<Table | void | Record<string, any>[]>}}
+   */
+  query(query) {
+    return new Promise(
+      (resolve, reject) => this.enqueue(query, resolve, reject)
+    );
+  }
 }