Add improved TypeScript support.

.github/workflows/deploy.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Build
         run: npm run docs:build
 
-      - uses: actions/configure-pages@v4
+      - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v3
         with:
           path: docs/.vitepress/dist

bin/prepare-examples.js

@@ -14,13 +14,21 @@ import { parse } from 'yaml';
 const specDir = join('specs', 'yaml');
 const esmTestDir = join('specs', 'esm');
 const jsonTestDir = join('specs', 'json');
+const tsTestDir = join('specs', 'ts');
 
 const docsDir = 'docs';
 const yamlDocsDir = join(docsDir, 'public', 'specs', 'yaml');
 const jsonDocsDir = join(docsDir, 'public', 'specs', 'json');
 const esmDocsDir = join(docsDir, 'public', 'specs', 'esm');
 const exampleDir = join(docsDir, 'examples');
 
+const specToTS = spec => {
+  return `import { Spec } from '@uwdata/mosaic-spec';
+
+export const spec : Spec = ${JSON.stringify(spec, 0, 2)};
+`;
+}
+
 const files = await Promise.allSettled((await readdir(specDir))
   .filter(name => extname(name) === '.yaml')
   .map(async name => {
@@ -43,6 +51,11 @@ const files = await Promise.allSettled((await readdir(specDir))
           resolve(jsonTestDir, `${base}.json`),
           JSON.stringify(ast.toJSON(), 0, 2)
         ),
+        // write TS JSON spec to tests
+        writeFile(
+          resolve(tsTestDir, `${base}.ts`),
+          specToTS(spec)
+        ),
         // copy YAML file to docs
         copyFile(file, resolve(yamlDocsDir, `${base}.yaml`)),
         // write JSON spec to docs

package.json

@@ -27,13 +27,13 @@
     "eslint": "^8.57.0",
     "eslint-plugin-jsdoc": "^48.2.1",
     "lerna": "^8.1.2",
-    "mocha": "^10.3.0",
+    "mocha": "^10.4.0",
     "nodemon": "^3.1.0",
     "rimraf": "^5.0.5",
     "timezone-mock": "^1.3.6",
-    "typescript": "^5.3.3",
-    "vite": "^5.1.6",
-    "vitepress": "1.0.0-rc.45",
+    "typescript": "^5.4.3",
+    "vite": "^5.2.6",
+    "vitepress": "1.0.1",
     "yaml": "^2.4.1"
   },
   "workspaces": [

packages/core/src/Coordinator.js

@@ -8,8 +8,7 @@ let _instance;
 
 /**
  * Set or retrieve the coordinator instance.
- *
- * @param {Coordinator} instance the coordinator instance to set
+ * @param {Coordinator} [instance] the coordinator instance to set
  * @returns {Coordinator} the coordinator instance
  */
 export function coordinator(instance) {
@@ -42,7 +41,15 @@ export class Coordinator {
     return this._logger;
   }
 
-  configure({ cache = true, consolidate = true, indexes = true }) {
+  /**
+   * Set configuration options for this coordinator.
+   * @param {object} [options] Configration options.
+   * @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 {boolean|object} [options.indexes=true] Boolean flag to enable/disable
+   *  automatic data cube indexes or an index options object.
+   */
+  configure({ cache = true, consolidate = true, indexes = true } = {}) {
     this.manager.cache(cache);
     this.manager.consolidate(consolidate);
     this.indexes = indexes;
@@ -116,7 +123,6 @@ export class Coordinator {
 
   /**
    * Connect a client to the coordinator.
-   *
    * @param {import('./MosaicClient.js').MosaicClient} client the client to disconnect
    */
   async connect(client) {

packages/core/src/MosaicClient.js

@@ -48,45 +48,51 @@ export class MosaicClient {
 
   /**
    * Return an array of fields queried by this client.
+   * @returns {object[]|null} The fields to retrieve info for.
    */
   fields() {
     return null;
   }
 
   /**
    * Called by the coordinator to set the field info for this client.
+   * @param {*} info The field info result.
    * @returns {this}
    */
-  fieldInfo() {
+  fieldInfo(info) { // eslint-disable-line no-unused-vars
     return this;
   }
 
   /**
    * 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() {
+  query(filter) { // eslint-disable-line no-unused-vars
     return null;
   }
 
   /**
    * Called by the coordinator to inform the client that a query is pending.
+   * @returns {this}
    */
   queryPending() {
     return this;
   }
 
   /**
    * Called by the coordinator to return a query result.
-   *
-   * @param {*} data the query result
+   * @param {*} data The query result.
    * @returns {this}
    */
-  queryResult() {
+  queryResult(data) { // eslint-disable-line no-unused-vars
     return this;
   }
 
   /**
    * Called by the coordinator to report a query execution error.
+   * @param {*} error
+   * @returns {this}
    */
   queryError(error) {
     console.error(error);
@@ -116,6 +122,8 @@ export class MosaicClient {
   /**
    * Requests a client update.
    * For example to (re-)render an interface component.
+   * 
+   * @returns {this | Promise<any>}
    */
   update() {
     return this;

packages/core/src/Param.js

@@ -4,7 +4,7 @@ import { distinct } from './util/distinct.js';
 /**
  * Test if a value is a Param instance.
  * @param {*} x The value to test.
- * @returns {boolean} True if the input is a Param, false otherwise.
+ * @returns {x is Param} True if the input is a Param, false otherwise.
  */
 export function isParam(x) {
   return x instanceof Param;
@@ -43,7 +43,9 @@ export class Param extends AsyncDispatch {
   static array(values) {
     if (values.some(v => isParam(v))) {
       const p = new Param();
-      const update = () => p.update(values.map(v => isParam(v) ? v.value : v));
+      const update = () => {
+        p.update(values.map(v => isParam(v) ? v.value : v));
+      };
       update();
       values.forEach(v => isParam(v) ? v.addEventListener('value', update) : 0);
       return p;

packages/core/src/QueryConsolidator.js

@@ -5,6 +5,7 @@ function wait(callback) {
   const method = typeof requestAnimationFrame !== 'undefined'
     ? requestAnimationFrame
     : typeof setImmediate !== 'undefined' ? setImmediate : setTimeout;
+  // @ts-ignore
   return method(callback);
 }
 
@@ -82,7 +83,9 @@ function consolidationKey(query, cache) {
   const sql = `${query}`;
   if (query instanceof Query && !cache.get(sql)) {
     if (
+      // @ts-ignore
       query.orderby().length || query.where().length ||
+      // @ts-ignore
       query.qualify().length || query.having().length
     ) {
       // do not try to analyze if query includes clauses
@@ -97,9 +100,12 @@ function consolidationKey(query, cache) {
     // queries may refer to *derived* columns as group by criteria
     // we resolve these against the true grouping expressions
     const groupby = query.groupby();
+    // @ts-ignore
     if (groupby.length) {
       const map = {}; // expression map (as -> expr)
+      // @ts-ignore
       query.select().forEach(({ as, expr }) => map[as] = expr);
+      // @ts-ignore
       q.$groupby(groupby.map(e => (e instanceof Ref && map[e.column]) || e));
     }
 

packages/core/src/Selection.js

@@ -4,7 +4,7 @@ import { Param } from './Param.js';
 /**
  * Test if a value is a Selection instance.
  * @param {*} x The value to test.
- * @returns {boolean} True if the input is a Selection, false otherwise.
+ * @returns {x is Selection} True if the input is a Selection, false otherwise.
  */
 export function isSelection(x) {
   return x instanceof Selection;
@@ -76,7 +76,7 @@ export class Selection extends Param {
 
   /**
    * Create a cloned copy of this Selection instance.
-   * @returns {this} A clone of this selection.
+   * @returns {Selection} A clone of this selection.
    */
   clone() {
     const s = new Selection(this._resolver);
@@ -88,7 +88,7 @@ export class Selection extends Param {
    * Create a clone of this Selection with clauses corresponding
    * to the provided source removed.
    * @param {*} source The clause source to remove.
-   * @returns {this} A cloned and updated Selection.
+   * @returns {Selection} A cloned and updated Selection.
    */
   remove(source) {
     const s = this.clone();
@@ -168,9 +168,9 @@ export class Selection extends Param {
    * Upon value-typed updates, returns a dispatch queue filter function.
    * The return value depends on the selection resolution strategy.
    * @param {string} type The event type.
-   * @param {*} value The input event value.
-   * @returns {*} For value-typed events, returns a dispatch queue filter
-   *  function. Otherwise returns null.
+   * @param {*} value The new event value that will be enqueued.
+   * @returns {(value: *) => boolean|null} For value-typed events,
+   *  returns a dispatch queue filter function. Otherwise returns null.
    */
   emitQueueFilter(type, value) {
     return type === 'value'
@@ -285,5 +285,6 @@ export class SelectionResolver {
       const source = value.active?.source;
       return clauses => clauses.active?.source !== source;
     }
+    return null;
   }
 }

packages/core/src/connectors/wasm.js

@@ -22,7 +22,7 @@ export function wasmConnector(options = {}) {
   /**
    * Get the backing DuckDB-WASM instance.
    * Will lazily initialize DuckDB-WASM if not already loaded.
-   * @returns {duckdb.AsyncDuckDB} The DuckDB-WASM instance.
+   * @returns {Promise<duckdb.AsyncDuckDB>} The DuckDB-WASM instance.
    */
   async function getDuckDB() {
     if (!db) await load();
@@ -32,7 +32,7 @@ export function wasmConnector(options = {}) {
   /**
    * Get the backing DuckDB-WASM connection.
    * Will lazily initialize DuckDB-WASM if not already loaded.
-   * @returns {duckdb.AsyncDuckDBConnection} The DuckDB-WASM connection.
+   * @returns {Promise<duckdb.AsyncDuckDBConnection>} The DuckDB-WASM connection.
    */
   async function getConnection() {
     if (!con) await load();

packages/core/src/util/AsyncDispatch.js

@@ -16,7 +16,7 @@ export class AsyncDispatch {
   /**
    * Add an event listener callback for the provided event type.
    * @param {string} type The event type.
-   * @param {(value: *) => Promise?} callback The event handler
+   * @param {(value: *) => void | Promise} callback The event handler
    *  callback function to add. If the callback has already been
    *  added for the event type, this method has no effect.
    */
@@ -35,7 +35,7 @@ export class AsyncDispatch {
   /**
    * Remove an event listener callback for the provided event type.
    * @param {string} type The event type.
-   * @param {(value: *) => Promise?} callback The event handler
+   * @param {(value: *) => void | Promise} callback The event handler
    *  callback function to remove.
    */
   removeEventListener(type, callback) {
@@ -64,11 +64,12 @@ export class AsyncDispatch {
    * This default implementation simply returns null, indicating that
    * any other unemitted event values should be dropped (that is, all
    * queued events are filtered)
+   * @param {string} type The event type.
    * @param {*} value The new event value that will be enqueued.
    * @returns {(value: *) => boolean|null} A dispatch queue filter
    *  function, or null if all unemitted event values should be filtered.
    */
-  emitQueueFilter() {
+  emitQueueFilter(type, value) { // eslint-disable-line no-unused-vars
     // removes all pending items
     return null;
   }

packages/core/src/util/convert-arrow.js

@@ -5,7 +5,7 @@ import { DataType } from 'apache-arrow';
  * As sometimes multiple Arrow versions may be used simultaneously,
  * we use a "duck typing" approach and check for a getChild function.
  * @param {*} values The value to test
- * @returns true if the value duck types as Apache Arrow data
+ * @returns {values is import('apache-arrow').Table} true if the value duck types as Apache Arrow data
  */
 export function isArrowTable(values) {
   return typeof values?.getChild === 'function';
@@ -28,7 +28,7 @@ export function convertArrowArrayType(type) {
  * Large integers (BigInt) are converted to Float64 numbers.
  * Fixed-point decimal values are convert to Float64 numbers.
  * Otherwise, the default Arrow values are used.
- * @param {*} type an Apache Arrow column type
+ * @param {DataType} type an Apache Arrow column type
  * @returns a value conversion function
  */
 export function convertArrowValue(type) {
@@ -112,10 +112,10 @@ const BASE32 = Array.from(
 /**
  * Convert a fixed point decimal value to a double precision number.
  * Note: if the value is sufficiently large the conversion may be lossy!
- * @param {Uint32Array} v a fixed decimal value
+ * @param {Uint32Array & { signed: boolean }} v a fixed decimal value
  * @param {number} scale a scale factor, corresponding to the
  *  number of fractional decimal digits in the fixed point value
- * @returns the resulting number
+ * @returns {number} the resulting number
  */
 function decimalToNumber(v, scale) {
   const n = v.length;

packages/core/src/util/query-result.js

@@ -2,7 +2,8 @@ export function queryResult() {
   let resolve;
   let reject;
   const p = new Promise((r, e) => { resolve = r; reject = e; });
-  p.fulfill = value => (resolve(value), p);
-  p.reject = err => (reject(err), p);
-  return p;
+  return Object.assign(p, {
+    fulfill: value => (resolve(value), p),
+    reject: err => (reject(err), p)
+  });
 }

packages/inputs/src/Menu.js

@@ -9,6 +9,10 @@ const isObject = v => {
 export const menu = options => input(Menu, options);
 
 export class Menu extends MosaicClient {
+  /**
+   * Create a new Menu instance.
+   * @param {object} options Options object
+   */
   constructor({
     element,
     filterBy,

packages/inputs/src/Search.js

@@ -10,6 +10,10 @@ let _id = 0;
 export const search = options => input(Search, options);
 
 export class Search extends MosaicClient {
+  /**
+   * Create a new Search instance.
+   * @param {object} options Options object
+   */
   constructor({
     element,
     filterBy,

packages/inputs/src/Slider.js

@@ -7,6 +7,10 @@ let _id = 0;
 export const slider = options => input(Slider, options);
 
 export class Slider extends MosaicClient {
+  /**
+   * Create a new Slider instance.
+   * @param {object} options Options object
+   */
   constructor({
     element,
     filterBy,
@@ -80,7 +84,7 @@ export class Slider extends MosaicClient {
     const { min, max } = Array.from(data)[0];
     if (this.min == null) this.slider.setAttribute('min', min);
     if (this.max == null) this.slider.setAttribute('max', max);
-    if (this.step == null) this.slider.setAttribute('step', (max - min) / 500);
+    if (this.step == null) this.slider.setAttribute('step', String((max - min) / 500));
     return this;
   }