fix: Improve JSDoc comments and typings. (#125)

src/arrow/arrow-column.js

@@ -10,7 +10,7 @@ const isList = id => id === Type.List || id === Type.FixedSizeList;
 /**
  * Create an Arquero column that proxies access to an Arrow column.
  * @param {object} arrow An Apache Arrow column.
- * @return {import('./column').ColumnType} An Arquero-compatible column.
+ * @return {import('../table/column').ColumnType} An Arquero-compatible column.
  */
 export default function arrowColumn(arrow, nested) {
   if (arrow.dictionary) return arrowDictionary(arrow);

src/arrow/encode/index.js

@@ -1,3 +1,5 @@
+import { Table } from 'apache-arrow'; // eslint-disable-line no-unused-vars
+
 import dataFromObjects from './data-from-objects';
 import dataFromTable from './data-from-table';
 import { scanArray, scanTable } from './scan';

src/format/from-arrow.js

@@ -19,7 +19,7 @@ import ColumnTable from '../table/column-table';
  * Create a new table backed by an Apache Arrow table instance.
  * @param {object} arrow An Apache Arrow data table or byte buffer.
  * @param {ArrowOptions} options Options for Arrow import.
- * @param {ColumnTable} table A new table containing the imported values.
+ * @return {ColumnTable} A new table containing the imported values.
  */
 export default function(arrow, options = {}) {
   arrow = from(arrow);

src/format/from-csv.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import fromTextRows from './from-text-rows';
 import parseDelimited from './parse/parse-delimited';
 
@@ -33,7 +35,7 @@ import parseDelimited from './parse/parse-delimited';
  * of input column values, use the parse option.
  * @param {string} text A string in a delimited-value format.
  * @param {CSVParseOptions} options The formatting options.
- * @param {ColumnTable} table A new table containing the parsed values.
+ * @return {ColumnTable} A new table containing the parsed values.
  */
 export default function(text, options = {}) {
   const next = parseDelimited(text, options);

src/format/from-fixed.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import fromTextRows from './from-text-rows';
 import parseLines from './parse/parse-lines';
 import error from '../util/error';
@@ -32,7 +34,7 @@ import error from '../util/error';
  * parsing of input column values, use the parse option.
  * @param {string} text A string in a fixed-width file format.
  * @param {FixedParseOptions} options The formatting options.
- * @param {import('../table/column-table')} table A new table containing the parsed values.
+ * @return {ColumnTable} A new table containing the parsed values.
  */
 export default function(text, options = {}) {
   const read = parseLines(text, options);

src/format/from-json.js

@@ -29,7 +29,7 @@ import isString from '../util/is-string';
  * metadata such as a "fields" array of ordered column information.
  * @param {string|object} data A string in JSON format, or pre-parsed object.
  * @param {JSONParseOptions} options The formatting options.
- * @param {ColumnTable} table A new table containing the parsed values.
+ * @return {ColumnTable} A new table containing the parsed values.
  */
 export default function(json, options = {}) {
   const autoType = defaultTrue(options.autoType);

src/format/load-file.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import fromArrow from './from-arrow';
 import fromCSV from './from-csv';
 import fromFixed from './from-fixed';
@@ -111,9 +113,4 @@ export function loadJSON(path, options) {
 
 function parseJSON(data, options) {
   return isArray(data) ? from(data) : fromJSON(data, options);
-}
-
-/**
- * An Arquero Column Table
- * @typedef {import('../table/column-table')} ColumnTable
- */
+}

src/format/load-url.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import fromArrow from './from-arrow';
 import fromCSV from './from-csv';
 import fromFixed from './from-fixed';
@@ -86,9 +88,4 @@ export function loadJSON(url, options) {
 
 function parseJSON(data, options) {
   return isArray(data) ? from(data) : fromJSON(data, options);
-}
-
-/**
- * An Arquero Column Table
- * @typedef {import('../table/column-table')} ColumnTable
- */
+}

src/format/to-csv.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import { columns, scan } from './util';
 import { formatUTCDate } from '../util/format-date';
 import isDate from '../util/is-date';

src/format/to-html.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import formatValue from './value';
 import { columns, formats, scan } from './util';
 import isFunction from '../util/is-function';

src/format/to-json.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import { columns } from './util';
 import { formatUTCDate } from '../util/format-date';
 import defaultTrue from '../util/default-true';

src/format/to-markdown.js

@@ -1,3 +1,5 @@
+import ColumnTable from '../table/column-table'; // eslint-disable-line no-unused-vars
+
 import formatValue from './value';
 import { columns, formats, scan } from './util';
 

src/format/util.js

@@ -1,11 +1,8 @@
+import Table from '../table/table'; // eslint-disable-line no-unused-vars
+
 import inferFormat from './infer';
 import isFunction from '../util/is-function';
 
-/**
- * Data table.
- * @typedef {typeof import('../table/table')} Table
- */
-
 /**
  * Column selection function.
  * @typedef {(table: Table) => string[]} ColumnSelectFunction

src/op/op-api.js

@@ -1,10 +1,5 @@
 import functions from './functions';
-import op from './op';
-
-/**
- * Table expression operation.
- * @typedef {import('./op').Op} Op
- */
+import op, { Op } from './op'; // eslint-disable-line no-unused-vars
 
 export const any = (field) => op('any', field);
 export const count = () => op('count');

src/table/table.js

@@ -518,7 +518,7 @@ export default class Table extends Transformable {
 
 /**
  * Proxy type for BitSet class.
- * @typedef {typeof import('./bit-set')} BitSet
+ * @typedef {import('./bit-set').default} BitSet
  */
 
 /**

src/table/transformable.js

@@ -86,7 +86,7 @@ export default class Transformable {
    * The resulting table provides a filtered view over the original data; no
    * data copy is made. To create a table that copies only filtered data to
    * new data structures, call {@link Transformable#reify} on the output table.
-   * @param {TableExpr|string} criteria Filter criteria as a table expression.
+   * @param {TableExpr} criteria Filter criteria as a table expression.
    *  Both aggregate and window functions are permitted, taking into account
    *  {@link Transformable#groupby} or {@link Transformable#orderby} settings.
    * @return {this} A new table with filtered rows.
@@ -741,12 +741,22 @@ export default class Transformable {
 
 /**
  * A function defined over a table row.
- * @typedef {(d?: object, $?: Params) => any} TableExpr
+ * @typedef {(d?: object, $?: Params) => any} TableExprFunc
+ */
+
+/**
+ * A table expression defined over a single table.
+ * @typedef {TableExprFunc|TableExprString} TableExpr
  */
 
 /**
  * A function defined over rows from two tables.
- * @typedef {(a?: object, b?: object, $?: Params) => any} TableExpr2
+ * @typedef {(a?: object, b?: object, $?: Params) => any} TableFunc2
+ */
+
+/**
+ * A table expression defined over two tables.
+ * @typedef {TableExprFunc2|TableExprString} TableExpr2
  */
 
 /**
@@ -775,12 +785,12 @@ export default class Transformable {
 
 /**
  * An object of column name / table expression pairs.
- * @typedef {{ [name: string]: (TableExpr | TableExprString) }} ExprObject
+ * @typedef {{ [name: string]: TableExpr }} ExprObject
  */
 
 /**
  * An object of column name / two-table expression pairs.
- * @typedef {{ [name: string]: (TableExpr2 | TableExprString) }} Expr2Object
+ * @typedef {{ [name: string]: TableExpr2 }} Expr2Object
  */
 
 /**
@@ -820,7 +830,7 @@ export default class Transformable {
 
 /**
  * Column values to use as a join key.
- * @typedef {ColumnRef|TableExpr} JoinKey
+ * @typedef {ColumnRef|TableExprFunc} JoinKey
  */
 
 /**
@@ -830,7 +840,7 @@ export default class Transformable {
 
 /**
  * A predicate specification for joining two tables.
- * @typedef {JoinKeys|TableExpr2|null} JoinPredicate
+ * @typedef {JoinKeys|TableExprFunc2|null} JoinPredicate
  */
 
 /**
@@ -889,7 +899,7 @@ export default class Transformable {
  * @typedef {object} SampleOptions
  * @property {boolean} [replace=false] Flag for sampling with replacement.
  * @property {boolean} [shuffle=true] Flag to ensure randomly ordered rows.
- * @property {string|TableExpr} [weight] Column values to use as weights
+ * @property {string|TableExprFunc} [weight] Column values to use as weights
  *  for sampling. Rows will be sampled with probability proportional to
  *  their relative weight. The input should be a column name string or
  *  a table expression compatible with {@link Transformable#derive}.

src/verbs/helpers/agg.js

@@ -1,9 +1,11 @@
+import Table from '../../table/table'; // eslint-disable-line no-unused-vars
+
 /**
  * Convenience function for computing a single aggregate value for
  * a table. Equivalent to ungrouping a table, applying a rollup verb
  * for a single aggregate, and extracting the resulting value.
- * @param {import('../../table/Table')} table A table instance.
- * @param {import('../../table/Transformable').TableExpr|string} expr An
+ * @param {Table} table A table instance.
+ * @param {import('../../table/Transformable').TableExpr} expr An
  *   aggregate table expression to evaluate.
  * @return {import('../../table/Table').DataValue} The aggregate value.
  * @example agg(table, op.max('colA'))