@uwdata/mosaic-core 0.15.0 → 0.16.2

package/dist/types/util/void-logger.d.ts

@@ -4,4 +4,7 @@ export function voidLogger(): {
     log(..._: any[]): void;
     warn(..._: any[]): void;
     error(..._: any[]): void;
+    group(label: any): void;
+    groupCollapsed(label: any): void;
+    groupEnd(): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-core",
-  "version": "0.15.0",
+  "version": "0.16.2",
   "description": "Scalable and extensible linked data views.",
   "keywords": [
     "mosaic",
@@ -32,10 +32,10 @@
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.29.0",
     "@uwdata/flechette": "^2.0.0",
-    "@uwdata/mosaic-sql": "^0.15.0"
+    "@uwdata/mosaic-sql": "^0.16.2"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.15.0"
+    "@uwdata/mosaic-duckdb": "^0.16.2"
   },
-  "gitHead": "671ad1ba86749a8435bd4aa7e722e2a8553f2cb0"
+  "gitHead": "26d2719f4bcab471d2831145e1f03f39f3509869"
 }

package/src/Coordinator.js

@@ -1,9 +1,10 @@
+/** @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 { QueryType } from './types.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';
@@ -33,15 +34,17 @@ export function coordinator(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.
- * @param {*} [db] Database connector. Defaults to a web socket connection.
- * @param {object} [options] Coordinator options.
- * @param {*} [options.logger=console] The logger to use, defaults to `console`.
- * @param {*} [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.
  */
 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(),
@@ -78,8 +81,8 @@ export class Coordinator {
 
   /**
    * Get or set the database connector.
-   * @param {*} [db] The database connector to use.
-   * @returns The current database connector.
+   * @param {Connector} [db] The database connector to use.
+   * @returns {Connector} The current database connector.
    */
   databaseConnector(db) {
     return this.manager.connector(db);
@@ -87,8 +90,8 @@ export class Coordinator {
 
   /**
    * Get or set the logger.
-   * @param {*} logger  The logger to use.
-   * @returns The current logger
+   * @param {Logger} [logger] The logger to use.
+   * @returns {Logger} The current logger
    */
   logger(logger) {
     if (arguments.length) {

package/src/MosaicClient.js

@@ -27,10 +27,10 @@ export class MosaicClient {
    *  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();
@@ -38,12 +38,12 @@ export class MosaicClient {
     this._enabled = true;
     /** @type {boolean} */
     this._initialized = false;
-    /** @type {Query | boolean} */
+    /** @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;
@@ -91,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;
@@ -204,6 +204,18 @@ export class MosaicClient {
     }
   }
 
+  /**
+   * 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);
+  }
+
   /**
    * Requests a client update, for example to (re-)render an interface
    * component.

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)
+    );
+  }
 }