feat: add jsdoc comments and type definitions for field info

packages/core/src/MosaicClient.js

@@ -1,5 +1,15 @@
 import { throttle } from './util/throttle.js';
 
+/**
+ * @typedef {import('./util/field-info.js').Stat} Stat
+ * 
+ * @typedef {{
+ *   table: string | import('@uwdata/mosaic-sql').TableRefNode,
+*    column: string | import('@uwdata/mosaic-sql').ColumnRefNode,
+ *   stats?: Stat[] | Set<Stat>
+ * }} MosaicClientField
+ */
+
 /**
  * Base class for Mosaic clients.
  */
@@ -49,15 +59,15 @@ export class MosaicClient {
 
   /**
    * Return an array of fields queried by this client.
-   * @returns {object[]|null} The fields to retrieve info for.
+   * @returns {MosaicClientField[] | 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.
+   * @param {import('./util/field-info.js').FieldInfo[]} info The field info result.
    * @returns {this}
    */
   fieldInfo(info) { // eslint-disable-line no-unused-vars

packages/core/src/util/field-info.js

@@ -9,7 +9,11 @@ export const Distinct = 'distinct';
 export const Stats = { Count, Nulls, Max, Min, Distinct };
 
 /**
- * @type {Record<string, (column: string) => AggregateNode>}
+ * @typedef {Count | Distinct | Max | Min | Nulls} Stat
+ */
+
+/**
+ * @type {Record<Stat, (column: string) => AggregateNode>}
  */
 const statMap = {
   [Count]: count,
@@ -20,10 +24,10 @@ const statMap = {
 };
 
 /**
- *
- * @param {string} table
- * @param {string} column
- * @param {string[]|Set<string>} stats
+ * Get summary stats of the given column
+ * @param {string | import('@uwdata/mosaic-sql').TableRefNode} table
+ * @param {string | import('@uwdata/mosaic-sql').ColumnRefNode} column
+ * @param {Stat[] | Set<Stat>} stats
  * @returns
  */
 function summarize(table, column, stats) {
@@ -32,6 +36,26 @@ function summarize(table, column, stats) {
     .select(Array.from(stats, s => ({[s]: statMap[s](column)})));
 }
 
+/**
+ * @typedef {{
+ *   table: string,
+ *   column: string,
+ *   sqlType: string,
+ *   type: ReturnType<typeof jsType>,
+ *   nullable: boolean,
+ * } & Record<Stat, number>} FieldInfo
+ */
+
+/**
+ * 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} coordinator A Mosaic coordinator.
+ * @param {import('../MosaicClient.js').MosaicClientField[]} fields 
+ * @returns {Promise<FieldInfo[]>}
+ */
 export async function queryFieldInfo(mc, fields) {
   if (fields.length === 1 && fields[0].column === '*') {
     return getTableInfo(mc, fields[0].table);
@@ -42,6 +66,12 @@ export async function queryFieldInfo(mc, fields) {
   }
 }
 
+/**
+ * Get information about a single field of a table.
+ * @param {import('../Coordinator.js').Coordinator} coordinator A Mosaic coordinator.
+ * @param {import('../MosaicClient.js').MosaicClientField} field 
+ * @returns {Promise<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
@@ -71,6 +101,12 @@ 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} coordinator A Mosaic coordinator.
+ * @param {string | import('@uwdata/mosaic-sql').TableRefNode} table the table name or reference 
+ * @returns {Promise<FieldInfo[]>}
+ */
 async function getTableInfo(mc, table) {
   const result = await mc.query(`DESCRIBE ${asTableRef(table)}`);
   return Array.from(result).map(desc => ({