@uwdata/mosaic-core 0.14.1 → 0.16.1

package/dist/types/Coordinator.d.ts

@@ -8,30 +8,23 @@ 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.
- * @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 {import('./preagg/PreAggregator.js').PreAggregateOptions} [options.preagg]
- *  Options for the Pre-aggregator.
  */
 export class Coordinator {
-    constructor(db?: {
-        readonly connected: boolean;
-        query(query: {
-            type?: "exec" | "arrow" | "json" | "create-bundle" | "load-bundle";
-            sql?: string;
-            queries?: string[];
-            name?: string;
-        }): Promise<any>;
-    }, { logger, manager, cache, consolidate, preagg }?: {
-        logger?: Console;
+    /**
+     * @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?: {};
+        preagg?: PreAggregateOptions;
     });
     /** @type {QueryManager} */
     manager: QueryManager;
@@ -50,17 +43,17 @@ export class Coordinator {
     clients: Set<any>;
     /**
      * 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?: any): any;
+    databaseConnector(db?: Connector): Connector;
     /**
      * 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: any, ...args: any[]): any;
-    _logger: any;
+    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.
@@ -70,22 +63,21 @@ export class Coordinator {
     cancel(requests: QueryResult[]): void;
     /**
      * Issue a query for which no result (return value) is needed.
-     * @param { import('./types.js').QueryType[] |
-     *  import('./types.js').QueryType} query The query or an array of queries.
+     * @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: import("./types.js").QueryType[] | import("./types.js").QueryType, { priority }?: {
+    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 {import('./types.js').QueryType} query The query as either a Query
-     *  builder object or a SQL string.
+     * @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
@@ -96,7 +88,7 @@ export class Coordinator {
      *  `Priority.Normal`.
      * @returns {QueryResult} A query result promise.
      */
-    query(query: import("./types.js").QueryType, { type, cache, priority, ...options }?: {
+    query(query: QueryType, { type, cache, priority, ...options }?: {
         type?: "arrow" | "json";
         cache?: boolean;
         persist?: boolean;
@@ -105,13 +97,13 @@ export class Coordinator {
     /**
      * Issue a query to prefetch data for later use. The query result is cached
      * for efficient future access.
-     * @param {import('./types.js').QueryType} query The query as either a Query
-     *  builder object or a SQL string.
+     * @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: import("./types.js").QueryType, options?: {
+    prefetch(query: QueryType, options?: {
         type?: "arrow" | "json";
     }): QueryResult;
     /**
@@ -138,25 +130,24 @@ export class Coordinator {
      * Update client data by submitting the given query and returning the
      * data (or error) to the client.
      * @param {MosaicClient} client A Mosaic client.
-     * @param {import('./types.js').QueryType} query The data query.
+     * @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: import("./types.js").QueryType, priority?: number): Promise<any>;
+    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 {import('./types.js').QueryType | null} [query] The query to issue.
+     * @param {QueryType | null} [query] The query to issue.
      */
-    requestQuery(client: MosaicClient, query?: import("./types.js").QueryType | null): Promise<any>;
+    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;
-    initializeClient(client: any): Promise<any>;
     /**
      * Disconnect a client from the coordinator.
      * @param {MosaicClient} client The Mosaic client to disconnect.
@@ -165,5 +156,9 @@ export class Coordinator {
 }
 import { QueryManager } from './QueryManager.js';
 import { PreAggregator } from './preagg/PreAggregator.js';
-import { QueryResult } from './util/query-result.js';
-import { MosaicClient } from './MosaicClient.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/MosaicClient.d.ts

@@ -1,58 +1,75 @@
 /**
- * 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: any);
-    /** @type {Selection} */
-    _filterBy: Selection;
+    constructor(filterSelection?: Selection);
+    /** @type {Selection | undefined} */
+    _filterBy: Selection | undefined;
     _requestUpdate: (event: any) => void;
-    /** @type {Coordinator} */
-    _coordinator: Coordinator;
+    /** @type {Coordinator | null} */
+    _coordinator: Coordinator | null;
     /** @type {Promise<any>} */
     _pending: Promise<any>;
+    /** @type {boolean} */
+    _enabled: boolean;
+    /** @type {boolean} */
+    _initialized: boolean;
+    /** @type {Query | boolean | null} */
+    _request: Query | boolean | null;
     /**
      * Set this client's connected coordinator.
      */
-    set coordinator(coordinator: Coordinator);
+    set coordinator(coordinator: Coordinator | null);
     /**
-     * Return this client's connected coordinator.
+     * @returns {Coordinator | null}  this client's connected coordinator.
      */
-    get coordinator(): Coordinator;
+    get coordinator(): Coordinator | null;
+    /**
+     * Set this client's enabled state;
+     */
+    set enabled(state: boolean);
+    /**
+     * Return this client's enabled state.
+     */
+    get enabled(): boolean;
     /**
      * Return a Promise that resolves once the client has updated.
      */
     get pending(): Promise<any>;
     /**
-     * Return this client's filter selection.
+     * @returns {Selection | undefined} this client's filter selection.
      */
-    get filterBy(): Selection;
+    get filterBy(): Selection | undefined;
     /**
      * 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(): boolean;
     /**
-     * Return an array of fields queried by this client.
-     * @returns {import('./types.js').FieldInfoRequest[] | null}
-     *  The fields to retrieve info for.
-     */
-    fields(): import("./types.js").FieldInfoRequest[] | 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: import("./types.js").FieldInfo[]): 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.
      */
     prepare(): Promise<void>;
     /**
@@ -80,26 +97,40 @@ export class MosaicClient {
     queryError(error: any): this;
     /**
      * 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: any): Promise<any>;
+    requestQuery(query?: Query): Promise<any>;
     /**
      * 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(): void;
     /**
-     * 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(): void;
+    /**
+     * 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.
      */
-    initialize(): Promise<any>;
+    destroy(): void;
     /**
      * Requests a client update, for example to (re-)render an interface
      * component.
@@ -107,5 +138,6 @@ export class MosaicClient {
      */
     update(): this | Promise<any>;
 }
-import { Selection } from './Selection.js';
-import { Coordinator } from './Coordinator.js';
+import type { Selection } from './Selection.js';
+import type { Coordinator } from './Coordinator.js';
+import type { Query } from '@uwdata/mosaic-sql';

package/dist/types/QueryManager.d.ts

@@ -7,19 +7,16 @@ export class QueryManager {
     constructor(maxConcurrentRequests?: number);
     /** @type {PriorityQueue} */
     queue: PriorityQueue;
-    db: any;
-    clientCache: any;
-    _logger: {
-        debug(..._: any[]): void;
-        info(..._: any[]): void;
-        log(..._: any[]): void;
-        warn(..._: any[]): void;
-        error(..._: any[]): void;
-    };
+    /** @type {Connector} */
+    db: Connector;
+    /** @type {Cache} */
+    clientCache: Cache;
+    /** @type {Logger} */
+    _logger: Logger;
+    /** @type {boolean} */
     _logQueries: boolean;
-    _consolidate: {
-        add(entry: any, priority: any): void;
-    };
+    /** @type {ReturnType<typeof consolidator> | null} */
+    _consolidate: ReturnType<typeof consolidator> | null;
     /**
      * Requests pending with the query manager.
      * @type {QueryResult[]}
@@ -47,11 +44,35 @@ export class QueryManager {
      * @param {QueryResult} result The query result.
      */
     submit(request: any, result: QueryResult): Promise<void>;
-    cache(value: any): any;
-    logger(value: any): any;
-    logQueries(value: any): boolean;
-    connector(connector: any): any;
-    consolidate(flag: any): 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.
@@ -63,4 +84,8 @@ export class QueryManager {
     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';

package/dist/types/Selection.d.ts

@@ -232,4 +232,4 @@ export class SelectionResolver {
 }
 import { Param } from './Param.js';
 import type { SelectionClause } from './util/selection-types.js';
-import { MosaicClient } from './MosaicClient.js';
+import type { MosaicClient } from './MosaicClient.js';

package/dist/types/SelectionClause.d.ts

@@ -102,4 +102,4 @@ export type Scale = import("./util/selection-types.js").Scale;
 export type Extent = import("./util/selection-types.js").Extent;
 export type MatchMethod = import("./util/selection-types.js").MatchMethod;
 export type BinMethod = import("./util/selection-types.js").BinMethod;
-import { MosaicClient } from './MosaicClient.js';
+import type { MosaicClient } from './MosaicClient.js';

package/dist/types/connectors/Connector.d.ts

@@ -0,0 +1,25 @@
+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/dist/types/connectors/rest.d.ts

@@ -1,17 +1,13 @@
-export function restConnector(uri?: string): {
-    /**
-     * 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: {
-        type?: "exec" | "arrow" | "json" | "create-bundle" | "load-bundle";
-        sql?: string;
-        queries?: string[];
-        name?: string;
-    }): Promise<any>;
-};
+/**
+ * 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, ipc, }?: {
+    uri?: string;
+    ipc?: ExtractionOptions;
+}): Connector;
+import type { ExtractionOptions } from '@uwdata/flechette';
+import type { Connector } from './Connector.js';

package/dist/types/connectors/socket.d.ts

@@ -1,18 +1,100 @@
-export function socketConnector(uri?: string): {
-    readonly connected: boolean;
+/**
+ * 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?: {
+    uri?: string;
+    ipc?: ExtractionOptions;
+}): SocketConnector;
+/**
+ * DuckDB socket connector.
+ * @implements {Connector}
+ */
+export class SocketConnector implements Connector {
     /**
-     * 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
+     * @param {object} [options] Connector options.
+     * @param {string} [options.uri] The URI for the DuckDB REST server.
+     * @param {ExtractionOptions} [options.ipc] Arrow IPC extraction options.
      */
-    query(query: {
-        type?: "exec" | "arrow" | "json" | "create-bundle" | "load-bundle";
-        sql?: string;
-        queries?: string[];
-        name?: string;
-    }): Promise<any>;
-};
+    constructor({ uri, ipc, }?: {
+        uri?: string;
+        ipc?: ExtractionOptions;
+    });
+    _uri: string;
+    _queue: any[];
+    _connected: boolean;
+    _request: any;
+    _ws: WebSocket;
+    _events: {
+        open(): void;
+        close(): void;
+        error(event: any): void;
+        message({ data }: {
+            data: any;
+        }): void;
+    };
+    get connected(): boolean;
+    init(): void;
+    enqueue(query: any, resolve: any, reject: any): void;
+    next(): void;
+    /**
+     * @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: ArrowQueryRequest): Promise<Table>;
+    /**
+     * @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: ExecQueryRequest): Promise<void>;
+    /**
+     * @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: JSONQueryRequest): Promise<Record<string, any>[]>;
+}
+import type { ExtractionOptions } from '@uwdata/flechette';
+import type { Connector } from './Connector.js';
+import type { ArrowQueryRequest } from './Connector.js';
+import type { Table } from '@uwdata/flechette';
+import type { ExecQueryRequest } from './Connector.js';
+import type { JSONQueryRequest } from './Connector.js';