@uwdata/mosaic-core 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-core",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Scalable and extensible linked data views.",
   "keywords": [
     "mosaic",
@@ -13,7 +13,7 @@
   "author": "Jeffrey Heer (https://idl.uw.edu)",
   "type": "module",
   "exports": {
-    "types": "./dist/types/index-types.d.ts",
+    "types": "./dist/src/index-types.d.ts",
     "default": "./src/index.js"
   },
   "repository": {
@@ -22,20 +22,16 @@
   },
   "scripts": {
     "prebuild": "rimraf dist && mkdir dist",
-    "build": "npm run types",
-    "types": "tsc",
     "lint": "eslint src test",
-    "test": "vitest run && npm run tsc",
-    "tsc": "tsc -p jsconfig.json",
-    "prepublishOnly": "npm run test && npm run lint && npm run build"
+    "test": "vitest run && tsc",
+    "prepublishOnly": "npm run test && npm run lint && tsc"
   },
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.29.0",
     "@uwdata/flechette": "^2.0.0",
-    "@uwdata/mosaic-sql": "^0.16.1"
+    "@uwdata/mosaic-sql": "^0.17.0"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.16.1"
-  },
-  "gitHead": "e12af9927b0a35a0e3194850ef569d0d24a022ce"
+    "@uwdata/mosaic-duckdb": "^0.17.0"
+  }
 }

package/src/Coordinator.js

@@ -164,30 +164,6 @@ export class Coordinator {
     return this.query(query, { ...options, cache: true, priority: Priority.Low });
   }
 
-  /**
-   * Create a bundle of queries that can be loaded into the cache.
-   *
-   * @param {string} name The name of the bundle.
-   * @param {[string | {sql: string},  {alias: string}]} queries The queries to save into the bundle.
-   * @param {number} priority Request priority.
-   * @returns {QueryResult} A query result promise.
-   */
-  createBundle(name, queries, priority = Priority.Low) {
-    const options = { name, queries: queries.map(q => typeof q == 'string' ? {sql: q} : q) };
-    return this.manager.request({ type: 'create-bundle', options }, priority);
-  }
-
-  /**
-   * Load a bundle into the cache.
-   * @param {string} name The name of the bundle.
-   * @param {number} priority Request priority.
-   * @returns {QueryResult} A query result promise.
-   */
-  loadBundle(name, priority = Priority.High) {
-    const options = { name };
-    return this.manager.request({ type: 'load-bundle', options }, priority);
-  }
-
   // -- Client Management ----
 
   /**

package/src/index-types.ts

@@ -2,3 +2,4 @@ export * from './index.js';
 export * from './types.js';
 export * from './connectors/Connector.js';
 export * from './util/selection-types.js';
+export {QueryResult} from './util/query-result.js';

package/src/preagg/sufficient-statistics.js

@@ -15,6 +15,7 @@ import { fnv_hash } from '../util/hash.js';
 export function sufficientStatistics(node, preagg, avg) {
   switch (node.name) {
     case 'count':
+    case 'count_star':
       return sumCountExpr(preagg, node);
     case 'sum':
       return sumExpr(preagg, node);

package/tsconfig.json

@@ -1,11 +1,9 @@
 {
-  "include": ["src/**/*.js", "src/**/*.ts"],
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*"],
   "compilerOptions": {
-    "allowJs": true,
-    "declaration": true,
     "emitDeclarationOnly": true,
-    "outDir": "dist/types",
-    "module": "node16",
-    "skipLibCheck": true
-  }
-}
+    "outDir": "dist"
+  },
+  "references": [{ "path": "../sql" }]
+}

package/LICENSE

@@ -1,47 +0,0 @@
-BSD 3-Clause License
-
-Copyright (c) 2023, UW Interactive Data Lab
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
----
-
-Portions of this software are derived from Observable Plot, which is released
-under the ISC license.
-
-Copyright 2020-2023 Observable, Inc.
-
-Permission to use, copy, modify, and/or distribute this software for any purpose
-with or without fee is hereby granted, provided that the above copyright notice
-and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
-OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
-THIS SOFTWARE.

package/dist/types/Coordinator.d.ts

@@ -1,164 +0,0 @@
-/**
- * Set or retrieve the coordinator instance.
- * @param {Coordinator} [instance] the coordinator instance to set
- * @returns {Coordinator} the coordinator instance
- */
-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.
- */
-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?: Connector, { logger, manager, cache, consolidate, preagg }?: {
-        logger?: Logger;
-        manager?: QueryManager;
-        cache?: boolean;
-        consolidate?: boolean;
-        preagg?: PreAggregateOptions;
-    });
-    /** @type {QueryManager} */
-    manager: QueryManager;
-    preaggregator: PreAggregator;
-    /**
-     * Clear the coordinator state.
-     * @param {object} [options] Options object.
-     * @param {boolean} [options.clients=true] If true, disconnect all clients.
-     * @param {boolean} [options.cache=true] If true, clear the query cache.
-     */
-    clear({ clients, cache }?: {
-        clients?: boolean;
-        cache?: boolean;
-    }): void;
-    filterGroups: Map<any, any>;
-    clients: Set<any>;
-    /**
-     * Get or set the database connector.
-     * @param {Connector} [db] The database connector to use.
-     * @returns {Connector} The current database connector.
-     */
-    databaseConnector(db?: Connector): Connector;
-    /**
-     * Get or set the logger.
-     * @param {Logger} [logger] The logger to use.
-     * @returns {Logger} The current logger
-     */
-    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.
-     * @param {QueryResult[]} requests An array
-     *  of query result objects, such as those returned by the `query` method.
-     */
-    cancel(requests: QueryResult[]): void;
-    /**
-     * Issue a query for which no result (return value) is needed.
-     * @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: 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 {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
-     *  client-side within the QueryManager.
-     * @param {boolean} [options.persist] If true, request the database
-     *  server to persist a cached query server-side.
-     * @param {number} [options.priority] The query priority, defaults to
-     *  `Priority.Normal`.
-     * @returns {QueryResult} A query result promise.
-     */
-    query(query: QueryType, { type, cache, priority, ...options }?: {
-        type?: "arrow" | "json";
-        cache?: boolean;
-        persist?: boolean;
-        priority?: number;
-    }): QueryResult;
-    /**
-     * Issue a query to prefetch data for later use. The query result is cached
-     * for efficient future access.
-     * @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: QueryType, options?: {
-        type?: "arrow" | "json";
-    }): QueryResult;
-    /**
-     * Create a bundle of queries that can be loaded into the cache.
-     *
-     * @param {string} name The name of the bundle.
-     * @param {[string | {sql: string},  {alias: string}]} queries The queries to save into the bundle.
-     * @param {number} priority Request priority.
-     * @returns {QueryResult} A query result promise.
-     */
-    createBundle(name: string, queries: [string | {
-        sql: string;
-    }, {
-        alias: string;
-    }], priority?: number): QueryResult;
-    /**
-     * Load a bundle into the cache.
-     * @param {string} name The name of the bundle.
-     * @param {number} priority Request priority.
-     * @returns {QueryResult} A query result promise.
-     */
-    loadBundle(name: string, priority?: number): QueryResult;
-    /**
-     * Update client data by submitting the given query and returning the
-     * data (or error) to the client.
-     * @param {MosaicClient} client A Mosaic client.
-     * @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: 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 {QueryType | null} [query] The query to issue.
-     */
-    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;
-    /**
-     * Disconnect a client from the coordinator.
-     * @param {MosaicClient} client The Mosaic client to disconnect.
-     */
-    disconnect(client: MosaicClient): void;
-}
-import { QueryManager } from './QueryManager.js';
-import { PreAggregator } from './preagg/PreAggregator.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,143 +0,0 @@
-/**
- * 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 {
-    /**
-     * 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?: Selection);
-    /** @type {Selection | undefined} */
-    _filterBy: Selection | undefined;
-    _requestUpdate: (event: any) => void;
-    /** @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 | null);
-    /**
-     * @returns {Coordinator | null}  this client's connected 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>;
-    /**
-     * @returns {Selection | undefined} this client's filter 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 do not change the groupby domain of the client
-     * query.
-     */
-    get filterStable(): boolean;
-    /**
-     * 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>;
-    /**
-     * Return a query specifying the data needed by this client.
-     * @param {*} [filter] The filtering criteria to apply in the query.
-     * @returns {*} The client query
-     */
-    query(filter?: any): any;
-    /**
-     * Called by the coordinator to inform the client that a query is pending.
-     * @returns {this}
-     */
-    queryPending(): this;
-    /**
-     * Called by the coordinator to return a query result.
-     * @param {*} data The query result.
-     * @returns {this}
-     */
-    queryResult(data: any): this;
-    /**
-     * Called by the coordinator to report a query execution error.
-     * @param {*} error
-     * @returns {this}
-     */
-    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 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?: Query): Promise<any>;
-    /**
-     * Request that the coordinator perform a throttled update of this client
-     * 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, 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.
-     */
-    destroy(): void;
-    /**
-     * Requests a client update, for example to (re-)render an interface
-     * component.
-     * @returns {this | Promise<any>}
-     */
-    update(): this | Promise<any>;
-}
-import type { Selection } from './Selection.js';
-import type { Coordinator } from './Coordinator.js';
-import type { Query } from '@uwdata/mosaic-sql';

package/dist/types/Param.d.ts

@@ -1,47 +0,0 @@
-/**
- * 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.
- */
-export function isParam(x: any): x is Param;
-/**
- * Represents a dynamic parameter that dispatches updates
- * upon parameter changes.
- */
-export class Param extends AsyncDispatch {
-    /**
-     * Create a new Param instance with the given initial value.
-     * @param {*} value The initial value of the Param.
-     * @returns {Param} The new Param instance.
-     */
-    static value(value: any): Param;
-    /**
-     * 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.
-     */
-    static array(values: any): Param;
-    /**
-     * Create a new Param instance.
-     * @param {*} value The initial value of the Param.
-     */
-    constructor(value: any);
-    _value: any;
-    /**
-     * The current value of the Param.
-     */
-    get value(): any;
-    /**
-     * 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
-     *  should emit a 'value' event even if the internal value is unchanged.
-     * @returns {this} This Param instance.
-     */
-    update(value: any, { force }?: {
-        force?: boolean;
-    }): this;
-}
-import { AsyncDispatch } from './util/AsyncDispatch.js';

package/dist/types/QueryConsolidator.d.ts

@@ -1,9 +0,0 @@
-/**
- * Create a consolidator to combine structurally compatible queries.
- * @param {*} enqueue Query manager enqueue method
- * @param {*} cache Client-side query cache (sql -> data)
- * @returns A consolidator object
- */
-export function consolidator(enqueue: any, cache: any): {
-    add(entry: any, priority: any): void;
-};

package/dist/types/QueryManager.d.ts

@@ -1,91 +0,0 @@
-export const Priority: Readonly<{
-    High: 0;
-    Normal: 1;
-    Low: 2;
-}>;
-export class QueryManager {
-    constructor(maxConcurrentRequests?: number);
-    /** @type {PriorityQueue} */
-    queue: PriorityQueue;
-    /** @type {Connector} */
-    db: Connector;
-    /** @type {Cache} */
-    clientCache: Cache;
-    /** @type {Logger} */
-    _logger: Logger;
-    /** @type {boolean} */
-    _logQueries: boolean;
-    /** @type {ReturnType<typeof consolidator> | null} */
-    _consolidate: ReturnType<typeof consolidator> | null;
-    /**
-     * Requests pending with the query manager.
-     * @type {QueryResult[]}
-     */
-    pendingResults: QueryResult[];
-    /** @type {number} */
-    maxConcurrentRequests: number;
-    /** @type {boolean} */
-    pendingExec: boolean;
-    next(): void;
-    /**
-     * 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`.
-     */
-    enqueue(entry: {
-        request?: any;
-        result?: QueryResult;
-    }, priority?: number): void;
-    /**
-     * Submit the query to the connector.
-     * @param {*} request The request.
-     * @param {QueryResult} result The query result.
-     */
-    submit(request: any, result: QueryResult): Promise<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.
-     * @param {number} priority The query priority, defaults to `Priority.Normal`.
-     * @returns {QueryResult} A query result promise.
-     */
-    request(request: any, priority?: number): QueryResult;
-    cancel(requests: any): void;
-    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';