@uwdata/mosaic-core 0.12.1 → 0.12.2

package/dist/types/Coordinator.d.ts

@@ -4,9 +4,6 @@
  * @returns {Coordinator} the coordinator instance
  */
 export function coordinator(instance?: Coordinator): Coordinator;
-/**
- * @typedef {import('@uwdata/mosaic-sql').Query | string} QueryType
- */
 /**
  * A Mosaic Coordinator manages all database communication for clients and
  * handles selection updates. The Coordinator also performs optimizations
@@ -91,7 +88,10 @@ export class Coordinator {
      *  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.
+     * @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.
@@ -99,6 +99,7 @@ export class Coordinator {
     query(query: QueryType, { type, cache, priority, ...options }?: {
         type?: "arrow" | "json";
         cache?: boolean;
+        persist?: boolean;
         priority?: number;
     }): QueryResult;
     /**
@@ -162,7 +163,7 @@ export class Coordinator {
      */
     disconnect(client: MosaicClient): void;
 }
-export type QueryType = import("@uwdata/mosaic-sql").Query | string;
+export type QueryType = import("@uwdata/mosaic-sql").Query | import("@uwdata/mosaic-sql").DescribeQuery | string;
 import { QueryManager } from './QueryManager.js';
 import { PreAggregator } from './preagg/PreAggregator.js';
 import { QueryResult } from './util/query-result.js';

package/dist/types/MosaicClient.d.ts

@@ -33,15 +33,16 @@ export class MosaicClient {
     get filterStable(): boolean;
     /**
      * Return an array of fields queried by this client.
-     * @returns {object[]|null} The fields to retrieve info for.
+     * @returns {import('./types.js').FieldInfoRequest[] | null}
+     *  The fields to retrieve info for.
      */
-    fields(): object[] | null;
+    fields(): import("./types.js").FieldInfoRequest[] | null;
     /**
      * Called by the coordinator to set the field info for this client.
-     * @param {*} info The field info result.
+     * @param {import('./types.js').FieldInfo[]} info The field info result.
      * @returns {this}
      */
-    fieldInfo(info: any): this;
+    fieldInfo(info: import("./types.js").FieldInfo[]): this;
     /**
      * Return a query specifying the data needed by this client.
      * @param {*} [filter] The filtering criteria to apply in the query.

package/dist/types/SelectionClause.d.ts

@@ -23,7 +23,7 @@ export function clausePoint(field: import("@uwdata/mosaic-sql").ExprValue, value
 /**
  * Generate a selection clause for multiple selected point values.
  * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {any[][] | undefined} value The selected values, as an array of
+ * @param {any[][] | null | undefined} value The selected values, as an array of
  *  arrays. Each subarray contains values for each *fields* entry.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
@@ -32,14 +32,14 @@ export function clausePoint(field: import("@uwdata/mosaic-sql").ExprValue, value
  *  cross-filtering contexts.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clausePoints(fields: import("@uwdata/mosaic-sql").ExprValue[], value: any[][] | undefined, { source, clients }: {
+export function clausePoints(fields: import("@uwdata/mosaic-sql").ExprValue[], value: any[][] | null | undefined, { source, clients }: {
     source: any;
     clients?: Set<MosaicClient>;
 }): SelectionClause;
 /**
  * Generate a selection clause for a selected 1D interval.
  * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {Extent} value The selected interval as a [lo, hi] array.
+ * @param {Extent | null | undefined} value The selected interval as a [lo, hi] array.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -50,7 +50,7 @@ export function clausePoints(fields: import("@uwdata/mosaic-sql").ExprValue[], v
  * @param {number} [options.pixelSize=1] The interactive pixel size.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, value: Extent, { source, clients, bin, scale, pixelSize }: {
+export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, value: Extent | null | undefined, { source, clients, bin, scale, pixelSize }: {
     source: any;
     clients?: Set<MosaicClient>;
     scale?: Scale;
@@ -60,7 +60,7 @@ export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, va
 /**
  * Generate a selection clause for multiple selected intervals.
  * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {Extent[]} value The selected intervals, as an array of extents.
+ * @param {Extent[] | null | undefined} value The selected intervals, as an array of extents.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -72,7 +72,7 @@ export function clauseInterval(field: import("@uwdata/mosaic-sql").ExprValue, va
  * @param {number} [options.pixelSize=1] The interactive pixel size.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[], value: Extent[], { source, clients, bin, scales, pixelSize }: {
+export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[], value: Extent[] | null | undefined, { source, clients, bin, scales, pixelSize }: {
     source: any;
     clients?: Set<MosaicClient>;
     scales?: Scale[];
@@ -82,7 +82,7 @@ export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[]
 /**
  * Generate a selection clause for text search matching.
  * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {string} value The selected text search query string.
+ * @param {string | null | undefined} value The selected text search query string.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -92,7 +92,7 @@ export function clauseIntervals(fields: import("@uwdata/mosaic-sql").ExprValue[]
  *  text matching method to use. Defaults to `'contains'`.
  * @returns {SelectionClause} The generated selection clause.
  */
-export function clauseMatch(field: import("@uwdata/mosaic-sql").ExprValue, value: string, { source, clients, method }: {
+export function clauseMatch(field: import("@uwdata/mosaic-sql").ExprValue, value: string | null | undefined, { source, clients, method }: {
     source: any;
     clients?: Set<MosaicClient>;
     method?: MatchMethod;

package/dist/types/index.d.ts

@@ -9,6 +9,8 @@ export { isArrowTable } from "./util/is-arrow-table.js";
 export { synchronizer } from "./util/synchronizer.js";
 export { throttle } from "./util/throttle.js";
 export { toDataColumns } from "./util/to-data-columns.js";
+export { queryFieldInfo } from "./util/field-info.js";
+export { jsType } from "./util/js-type.js";
 export type ClauseMetadata = import("./util/selection-types.js").ClauseMetadata;
 export type PointMetadata = import("./util/selection-types.js").PointMetadata;
 export type MatchMethod = import("./util/selection-types.js").MatchMethod;

package/dist/types/types.d.ts

@@ -0,0 +1,31 @@
+import type { ExprNode } from '@uwdata/mosaic-sql';
+/** String indicating a JavaScript data type. */
+export type JSType = 'number' | 'date' | 'boolean' | 'string' | 'array' | 'object';
+/** String indicating a requested summary statistic. */
+export type Stat = 'count' | 'nulls' | 'max' | 'min' | 'distinct';
+/** A reference to a database column or expression. */
+export type FieldRef = string | ExprNode;
+/**
+ * A request for metadata information about a database column.
+ */
+export interface FieldInfoRequest {
+    table: string;
+    column: FieldRef;
+    stats?: Stat[];
+}
+/**
+ * A response with metadata information about a database column.
+ */
+export interface FieldInfo extends Partial<Record<Stat, number>> {
+    table: string;
+    column: string;
+    sqlType: string;
+    type: JSType;
+    nullable: boolean;
+}
+/** A result row from a DESCRIBE query. */
+export interface ColumnDescription {
+    column_name: string;
+    column_type: string;
+    null: 'YES' | 'NO';
+}

package/dist/types/util/field-info.d.ts

@@ -1,4 +1,14 @@
-export function queryFieldInfo(mc: any, fields: any): Promise<any[]>;
+/**
+ * Queries information about fields of a table.
+ * If the `fields` array contains a single field with the column set to '*',
+ * 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[]>}
+ */
+export function queryFieldInfo(mc: import("../Coordinator.js").Coordinator, fields: import("../types.js").FieldInfoRequest[]): Promise<import("../types.js").FieldInfo[]>;
 export const Count: "count";
 export const Nulls: "nulls";
 export const Max: "max";

package/dist/types/util/js-type.d.ts

@@ -1 +1,7 @@
-export function jsType(type: any): "string" | "number" | "date" | "boolean" | "array" | "object";
+/**
+ * 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.
+ */
+export function jsType(type: string): import("../types.js").JSType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-core",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Scalable and extensible linked data views.",
   "keywords": [
     "mosaic",
@@ -32,10 +32,10 @@
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.29.0",
     "@uwdata/flechette": "^1.1.1",
-    "@uwdata/mosaic-sql": "^0.12.1"
+    "@uwdata/mosaic-sql": "^0.12.2"
   },
   "devDependencies": {
-    "@uwdata/mosaic-duckdb": "^0.12.1"
+    "@uwdata/mosaic-duckdb": "^0.12.2"
   },
-  "gitHead": "fe3a7c34352da54ec36a1ebf557846f46a649782"
+  "gitHead": "0ca741d840b98039255f26a5ceedf10be66f790e"
 }

package/src/Coordinator.js

@@ -6,6 +6,12 @@ import { voidLogger } from './util/void-logger.js';
 import { MosaicClient } from './MosaicClient.js';
 import { QueryManager, Priority } from './QueryManager.js';
 
+/**
+ * @typedef {import('@uwdata/mosaic-sql').Query
+ *  | import('@uwdata/mosaic-sql').DescribeQuery
+ *  | string} QueryType
+ */
+
 /**
  * The singleton Coordinator instance.
  * @type {Coordinator}
@@ -26,10 +32,6 @@ export function coordinator(instance) {
   return _instance;
 }
 
-/**
- * @typedef {import('@uwdata/mosaic-sql').Query | string} QueryType
- */
-
 /**
  * A Mosaic Coordinator manages all database communication for clients and
  * handles selection updates. The Coordinator also performs optimizations
@@ -134,7 +136,10 @@ export class Coordinator {
    *  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.
+   * @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.

package/src/MosaicClient.js

@@ -49,7 +49,8 @@ export class MosaicClient {
 
   /**
    * Return an array of fields queried by this client.
-   * @returns {object[]|null} The fields to retrieve info for.
+   * @returns {import('./types.js').FieldInfoRequest[] | null}
+   *  The fields to retrieve info for.
    */
   fields() {
     return null;
@@ -57,7 +58,7 @@ export class MosaicClient {
 
   /**
    * Called by the coordinator to set the field info for this client.
-   * @param {*} info The field info result.
+   * @param {import('./types.js').FieldInfo[]} info The field info result.
    * @returns {this}
    */
   fieldInfo(info) { // eslint-disable-line no-unused-vars

package/src/SelectionClause.js

@@ -40,7 +40,7 @@ export function clausePoint(field, value, {
 /**
  * Generate a selection clause for multiple selected point values.
  * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {any[][] | undefined} value The selected values, as an array of
+ * @param {any[][] | null | undefined} value The selected values, as an array of
  *  arrays. Each subarray contains values for each *fields* entry.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
@@ -75,7 +75,7 @@ export function clausePoints(fields, value, {
 /**
  * Generate a selection clause for a selected 1D interval.
  * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {Extent} value The selected interval as a [lo, hi] array.
+ * @param {Extent | null | undefined} value The selected interval as a [lo, hi] array.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -93,7 +93,6 @@ export function clauseInterval(field, value, {
   scale,
   pixelSize = 1
 }) {
-  /** @type {ExprNode | null} */
   const predicate = value != null ? isBetween(field, value) : null;
   /** @type {import('./util/selection-types.js').IntervalMetadata} */
   const meta = { type: 'interval', scales: scale && [scale], bin, pixelSize };
@@ -103,7 +102,7 @@ export function clauseInterval(field, value, {
 /**
  * Generate a selection clause for multiple selected intervals.
  * @param {import('@uwdata/mosaic-sql').ExprValue[]} fields The table columns or expressions to select.
- * @param {Extent[]} value The selected intervals, as an array of extents.
+ * @param {Extent[] | null | undefined} value The selected intervals, as an array of extents.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated
@@ -122,7 +121,6 @@ export function clauseIntervals(fields, value, {
   scales = [],
   pixelSize = 1
 }) {
-  /** @type {ExprNode | null} */
   const predicate = value != null
     ? and(fields.map((f, i) => isBetween(f, value[i])))
     : null;
@@ -136,7 +134,7 @@ const MATCH_METHODS = { contains, prefix, suffix, regexp: regexp_matches };
 /**
  * Generate a selection clause for text search matching.
  * @param {import('@uwdata/mosaic-sql').ExprValue} field The table column or expression to select.
- * @param {string} value The selected text search query string.
+ * @param {string | null | undefined} value The selected text search query string.
  * @param {object} options Additional clause properties.
  * @param {*} options.source The source component generating this clause.
  * @param {Set<MosaicClient>} [options.clients] The Mosaic clients associated

package/src/index.js

@@ -22,6 +22,8 @@ export { isArrowTable } from './util/is-arrow-table.js';
 export { synchronizer } from './util/synchronizer.js';
 export { throttle } from './util/throttle.js';
 export { toDataColumns } from './util/to-data-columns.js';
+export { queryFieldInfo } from './util/field-info.js';
+export { jsType } from './util/js-type.js';
 
 /**
  * @typedef {import('./util/selection-types.js').ClauseMetadata} ClauseMetadata

package/src/types.ts

@@ -0,0 +1,48 @@
+import type { ExprNode } from '@uwdata/mosaic-sql';
+
+/** String indicating a JavaScript data type. */
+export type JSType =
+  | 'number'
+  | 'date'
+  | 'boolean'
+  | 'string'
+  | 'array'
+  | 'object';
+
+/** String indicating a requested summary statistic. */
+export type Stat =
+  | 'count'
+  | 'nulls'
+  | 'max'
+  | 'min'
+  | 'distinct';
+
+/** A reference to a database column or expression. */
+export type FieldRef = string | ExprNode;
+
+/**
+ * A request for metadata information about a database column.
+ */
+export interface FieldInfoRequest {
+  table: string;
+  column: FieldRef;
+  stats?: Stat[];
+}
+
+/**
+ * A response with metadata information about a database column.
+ */
+export interface FieldInfo extends Partial<Record<Stat, number>> {
+  table: string,
+  column: string,
+  sqlType: string,
+  type: JSType,
+  nullable: boolean
+}
+
+/** A result row from a DESCRIBE query. */
+export interface ColumnDescription {
+  column_name: string,
+  column_type: string,
+  null: 'YES' | 'NO'
+}

package/src/util/field-info.js

@@ -1,4 +1,4 @@
-import { AggregateNode, Query, asTableRef, count, isNull, max, min, sql } from '@uwdata/mosaic-sql';
+import { AggregateNode, Query, asTableRef, count, isAggregateExpression, isNode, isNull, max, min, sql } from '@uwdata/mosaic-sql';
 import { jsType } from './js-type.js';
 
 export const Count = 'count';
@@ -9,7 +9,10 @@ export const Distinct = 'distinct';
 export const Stats = { Count, Nulls, Max, Min, Distinct };
 
 /**
- * @type {Record<string, (column: string) => AggregateNode>}
+ * @type {Record<
+ *  import('../types.js').Stat,
+ *  (column: import('../types.js').FieldRef) => AggregateNode
+ * >}
  */
 const statMap = {
   [Count]: count,
@@ -20,18 +23,26 @@ const statMap = {
 };
 
 /**
- *
- * @param {string} table
- * @param {string} column
- * @param {string[]|Set<string>} stats
- * @returns
+ * Get summary stats of the given column
+ * @param {import('../types.js').FieldInfoRequest} field
+ * @returns {Query}
  */
-function summarize(table, column, stats) {
+function summarize({ table, column, stats }) {
   return Query
     .from(table)
-    .select(Array.from(stats, s => ({[s]: statMap[s](column)})));
+    .select(Array.from(stats, s => ({ [s]: statMap[s](column) })));
 }
 
+/**
+ * Queries information about fields of a table.
+ * If the `fields` array contains a single field with the column set to '*',
+ * 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[]>}
+ */
 export async function queryFieldInfo(mc, fields) {
   if (fields.length === 1 && fields[0].column === '*') {
     return getTableInfo(mc, fields[0].table);
@@ -42,13 +53,21 @@ export async function queryFieldInfo(mc, fields) {
   }
 }
 
+/**
+ * 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>}
+ */
 async function getFieldInfo(mc, { table, column, stats }) {
   // generate and issue a query for field metadata info
   // use GROUP BY ALL to differentiate & consolidate aggregates
   const q = Query
     .from({ source: table })
     .select({ column })
-    .groupby(column.aggregate ? sql`ALL` : []);
+    .groupby(isNode(column) && isAggregateExpression(column) ? sql`ALL` : []);
+
+  /** @type {import('../types.js').ColumnDescription[]} */
   const [desc] = Array.from(await mc.query(Query.describe(q)));
   const info = {
     table,
@@ -59,11 +78,11 @@ async function getFieldInfo(mc, { table, column, stats }) {
   };
 
   // no need for summary statistics
-  if (!(stats?.length || stats?.size)) return info;
+  if (!stats?.length) return info;
 
   // query for summary stats
   const [result] = await mc.query(
-    summarize(table, column, stats),
+    summarize({ table, column, stats }),
     { persist: true }
   );
 
@@ -71,9 +90,16 @@ async function getFieldInfo(mc, { table, column, stats }) {
   return Object.assign(info, result);
 }
 
+/**
+ * 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[]>}
+ */
 async function getTableInfo(mc, table) {
-  const result = await mc.query(`DESCRIBE ${asTableRef(table)}`);
-  return Array.from(result).map(desc => ({
+  /** @type {import('../types.js').ColumnDescription[]} */
+  const result = Array.from(await mc.query(`DESCRIBE ${asTableRef(table)}`));
+  return result.map(desc => ({
     table,
     column: desc.column_name,
     sqlType: desc.column_type,

package/src/util/js-type.js

@@ -1,3 +1,9 @@
+/**
+ * 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.
+ */
 export function jsType(type) {
   switch (type) {
     case 'BIGINT':