@uwdata/mosaic-sql 0.13.0 → 0.14.1

package/src/functions/window.js

@@ -1,4 +1,7 @@
-import { WindowNode } from '../ast/window.js';
+/**
+ * @import { WindowNode } from '../ast/window.js'
+ * @import { ExprValue, NumberValue } from '../types.js'
+ */
 import { winFn } from '../util/function.js';
 
 /**
@@ -49,7 +52,7 @@ export function cume_dist() {
 /**
  * Create a window function that returns an integer ranging from 1 to the
  * argument value, dividing the partition as equally as possible.
- * @param {import('../types.js').NumberValue} num_buckets The number of
+ * @param {NumberValue} num_buckets The number of
  *  quantile buckets.
  * @returns {WindowNode}
  */
@@ -63,8 +66,8 @@ export function ntile(num_buckets) {
  * If there is no such row, instead return default (which must be of the same
  * type as the expression). Both offset and default are evaluated with respect
  * to the current row. If omitted, offset defaults to 1 and default to null.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
- * @param {import('../types.js').NumberValue} [offset] The row offset
+ * @param {ExprValue} expr The expression to evaluate.
+ * @param {NumberValue} [offset] The row offset
  *  (default `1`).
  * @param {*} [defaultValue] The default value (default `null`).
  * @returns {WindowNode}
@@ -79,8 +82,8 @@ export function lag(expr, offset, defaultValue){
  * If there is no such row, instead return default (which must be of the same
  * type as the expression). Both offset and default are evaluated with respect
  * to the current row. If omitted, offset defaults to 1 and default to null.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
- * @param {import('../types.js').NumberValue} [offset] The row offset
+ * @param {ExprValue} expr The expression to evaluate.
+ * @param {NumberValue} [offset] The row offset
  *  (default `1`).
  * @param {*} [defaultValue] The default value (default `null`).
  * @returns {WindowNode}
@@ -92,7 +95,7 @@ export function lead(expr, offset, defaultValue){
 /**
  * Create a window function that returns the expression evaluated at the row
  * that is the first row of the window frame.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {ExprValue} expr The expression to evaluate.
  * @returns {WindowNode}
  */
 export function first_value(expr) {
@@ -102,7 +105,7 @@ export function first_value(expr) {
 /**
  * Create a window function that returns the expression evaluated at the row
  * that is the last row of the window frame.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {ExprValue} expr The expression to evaluate.
  * @returns {WindowNode}
  */
 export function last_value(expr) {
@@ -112,8 +115,8 @@ export function last_value(expr) {
 /**
  * Create a window function that returns the expression evaluated at the
  * nth row of the window frame (counting from 1), or null if no such row.
- * @param {import('../types.js').ExprValue} expr The expression to evaluate.
- * @param {import('../types.js').NumberValue} nth The 1-based window frame index.
+ * @param {ExprValue} expr The expression to evaluate.
+ * @param {NumberValue} nth The 1-based window frame index.
  * @returns {WindowNode}
  */
 export function nth_value(expr, nth) {

package/src/index.js

@@ -37,6 +37,7 @@ export { asc, desc } from './functions/order-by.js';
 export { geojson, x, y, centroid, centroidX, centroidY } from './functions/spatial.js';
 export { sql } from './functions/sql-template-tag.js';
 export { regexp_matches, contains, prefix, suffix, lower, upper, length } from './functions/string.js';
+export { coalesce } from './functions/util.js';
 export { cume_dist, dense_rank, first_value, lag, last_value, lead, nth_value, ntile, percent_rank, rank, row_number } from './functions/window.js';
 
 export { rewrite } from './visit/rewrite.js';
@@ -49,6 +50,8 @@ export { loadCSV, loadJSON, loadObjects, loadParquet, loadSpatial } from './load
 
 export { bin1d } from './transforms/bin-1d.js';
 export { bin2d } from './transforms/bin-2d.js';
+export { binDate } from './transforms/bin-date.js';
+export { binHistogram } from './transforms/bin-histogram.js';
 export { binLinear1d } from './transforms/bin-linear-1d.js';
 export { binLinear2d } from './transforms/bin-linear-2d.js';
 export { lineDensity } from './transforms/line-density.js';
@@ -57,3 +60,6 @@ export { scaleTransform } from './transforms/scales.js';
 
 export { asLiteral, asNode, asTableRef, asVerbatim, over } from './util/ast.js';
 export { isParamLike } from './util/type-check.js';
+
+export { binSpec, binStep } from './transforms/util/bin-step.js';
+export { timeInterval } from './transforms/util/time-interval.js';

package/src/transforms/bin-1d.js

@@ -1,9 +1,12 @@
+/**
+ * @import { ExprValue } from '../types.js'
+ */
 import { float64 } from '../functions/cast.js';
 import { mul, sub } from '../functions/operators.js';
 
 /**
  * Compute binned values over a one-dimensional extent.
- * @param {import('../types.js').ExprValue} x The expression to bin.
+ * @param {ExprValue} x The expression to bin.
  *  The expression must return numeric values. For example, to bin
  *  datetime values, the input expression might map them to numeric
  *  values such as milliseconds since the epoch.

package/src/transforms/bin-2d.js

@@ -1,4 +1,7 @@
-import { SelectQuery } from '../ast/query.js';
+/**
+ * @import { SelectQuery } from '../ast/query.js'
+ * @import { ExprValue } from '../types.js'
+ */
 import { int32 } from '../functions/cast.js';
 import { floor } from '../functions/numeric.js';
 import { add, mul } from '../functions/operators.js';
@@ -11,9 +14,9 @@ import { add, mul } from '../functions/operators.js';
  * and uses a 2D integer bin index of the form (xbin + num_xbins * ybin).
  * @param {SelectQuery} q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, either before or after this method.
- * @param {import('../types.js').ExprValue} xp The x bin expression.
- * @param {import('../types.js').ExprValue} yp The y bin expression.
- * @param {Record<string, import('../types.js').ExprValue>} aggs Named
+ * @param {ExprValue} xp The x bin expression.
+ * @param {ExprValue} yp The y bin expression.
+ * @param {Record<string, ExprValue>} aggs Named
  *  aggregate expressions over bins.
  * @param {number} xn The number of bins along the x dimension
  * @param {string[]} groupby Group by expressions.

package/src/transforms/bin-date.js

@@ -0,0 +1,37 @@
+/**
+ * @import { ExprNode } from '../ast/node.js'
+ * @import { ExprValue, TimeUnit } from '../types.js'
+ */
+import { dateBin, interval } from '../functions/datetime.js';
+import { add } from '../functions/operators.js';
+import { timeInterval } from './util/time-interval.js';
+
+/**
+ * @typedef {object} BinDateOptions
+ * @property {TimeUnit} [interval] A string indicating a time interval
+ *  unit, such as 'year', 'day', or 'hour'.
+ * @property {number} [step] The number of time interval steps to
+ *  take, such as 2 years or 3 months.
+ * @property {number} [offset] The number of bin steps (default 0) by
+ *  which to offset the result.
+ * @property {number} [steps] The desired number of binning steps.
+ *  This value is a hint, it does not guarantee an exact number of steps.
+ */
+
+/**
+ * Return a SQL expression for date/time bins.
+ * @param {ExprValue} field The column or expression to bin.
+ * @param {[Date|number, Date|number]} extent The min/max extent over which to bin.
+ * @param {BinDateOptions} [options] Datetime binning options.
+ * @returns {ExprNode}
+ */
+export function binDate(field, extent, options = {}) {
+  const { offset = 0 } = options;
+
+  // use interval if provided, otherwise determine from extent
+  const { unit, step = 1 } = options.interval
+    ? { unit: options.interval, step: options.step }
+    : timeInterval(extent[0], extent[1], options.steps || 40);
+  const bin = dateBin(field, unit, step);
+  return offset ? add(bin, interval(unit, offset * step)) : bin;
+}

package/src/transforms/bin-histogram.js

@@ -0,0 +1,52 @@
+/**
+ * @import { ExprNode } from '../ast/node.js'
+ * @import { ExprValue } from '../types.js'
+ */
+import { float64 } from '../functions/cast.js';
+import { floor } from '../functions/numeric.js';
+import { add, div, mul, sub } from '../functions/operators.js';
+import { binSpec } from './util/bin-step.js';
+import { scaleTransform } from './scales.js';
+
+/**
+ * @typedef {object} BinHistogramOptions
+ * @property {number} [step] An exact binning step to use.
+ * @property {number} [steps] The desired number of binning steps.
+ *  This value is a hint, it does not guarantee an exact number of steps.
+ * @property {number} [minstep] A minimum binning step value. No generated
+ *  step can be less than this value.
+ * @property {boolean} [nice] A boolean flag (default true) indicating if bin
+ *  extents should be snapped to "nice" numbers such as multiples of 5 or 10.
+ * @property {number} [offset] The number of bin steps (default 0) by
+ *  which to offset the result.
+ */
+
+/**
+ * Return a SQL expression for histogram bins.
+ * @param {ExprValue} field The column or expression to bin.
+ * @param {[number, number]} extent The min/max extent over which to bin.
+ * @param {BinHistogramOptions} [options] Binning options.
+ * @param {ReturnType<typeof scaleTransform>} [transform] Scale transforms to
+ *  apply to create (potentially non-linear) binning intervals.
+ * @returns {ExprNode} The resulting SQL expression
+ */
+export function binHistogram(
+  field,
+  extent,
+  options = {},
+  transform = scaleTransform({ type: 'linear' })
+) {
+  const [min, max] = extent;
+  const { offset = 0 } = options;
+  const { apply, sqlApply, sqlInvert } = transform;
+  const b = binSpec(apply(min), apply(max), options);
+  const col = sqlApply(field);
+  const alpha = (b.max - b.min) / b.steps;
+
+  let expr = b.min === 0 ? col : sub(col, b.min);
+  if (alpha !== 1) expr = div(expr, float64(alpha));
+  expr = floor(offset ? add(offset, expr) : expr);
+  if (alpha !== 1) expr = mul(alpha, expr);
+  if (b.min !== 0) expr = add(b.min, expr);
+  return sqlInvert(expr);
+}

package/src/transforms/bin-linear-1d.js

@@ -1,3 +1,7 @@
+/**
+ * @import { SelectQuery } from '../ast/query.js'
+ * @import { ExprValue } from '../types.js'
+ */
 import { Query } from '../ast/query.js';
 import { sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
@@ -6,9 +10,9 @@ import { add, mul, neq, sub } from '../functions/operators.js';
 
 /**
  * Perform linear binning in one dimension.
- * @param {import('../ast/query.js').SelectQuery} query The base query to bin.
- * @param {import('../types.js').ExprValue} x The expression to bin.
- * @param {import('../types.js').ExprValue} [weight] The expression to weight by.
+ * @param {SelectQuery} query The base query to bin.
+ * @param {ExprValue} x The expression to bin.
+ * @param {ExprValue} [weight] The expression to weight by.
  * @param {string[]} [groupby] Group by expressions.
  * @returns {Query}
  */

package/src/transforms/bin-linear-2d.js

@@ -1,4 +1,8 @@
-import { Query, SelectQuery } from '../ast/query.js';
+/**
+ * @import { SelectQuery } from '../ast/query.js'
+ * @import { ExprValue } from '../types.js'
+ */
+import { Query } from '../ast/query.js';
 import { sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
 import { floor } from '../functions/numeric.js';
@@ -22,9 +26,9 @@ function identity(x) {
  * should be in units of grid indices, but can contain fractional components.
  * @param {SelectQuery} q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, before this method is invoked.
- * @param {import('../types.js').ExprValue} xp The x grid bin expression
- * @param {import('../types.js').ExprValue} yp The y grid bin expression
- * @param {import('../types.js').ExprValue | undefined} weight Point weights.
+ * @param {ExprValue} xp The x grid bin expression
+ * @param {ExprValue} yp The y grid bin expression
+ * @param {ExprValue | undefined} weight Point weights.
  * @param {number} xn The number of x grid bins.
  * @param {string[]} [groupby] Group by expressions.
  * @returns {SelectQuery} A linear binning query for bin `index` and
@@ -35,13 +39,13 @@ export function binLinear2d(q, xp, yp, weight, xn, groupby = []) {
   const w = weight ? x => mul(x, weight) : identity;
 
   /**
-   * @param {import('../types.js').ExprValue} i
-   * @param {import('../types.js').ExprValue} w
+   * @param {ExprValue} i
+   * @param {ExprValue} w
    */
   const subq = (i, w) => q.clone().select({ xp, yp, i, w });
   /**
-   * @param {import('../types.js').ExprValue} x
-   * @param {import('../types.js').ExprValue} y
+   * @param {ExprValue} x
+   * @param {ExprValue} y
    */
   const index = (x, y) => add(x, mul(y, xn));
 

package/src/transforms/line-density.js

@@ -1,4 +1,8 @@
-import { Query, SelectQuery } from '../ast/query.js';
+/**
+ * @import { SelectQuery } from '../ast/query.js'
+ * @import { ExprValue } from '../types.js'
+ */
+import { Query } from '../ast/query.js';
 import { count, max, sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
 import { abs, floor, greatest, round, sign } from '../functions/numeric.js';
@@ -15,9 +19,9 @@ import { over } from '../util/ast.js';
  * and then sum results for all line series to produce a density map.
  * Based on Moritz and Fisher's work: https://arxiv.org/abs/1808.06019
  * @param {SelectQuery} q The base query over the data.
- * @param {import('../types.js').ExprValue} x Bin expression for x dimension.
+ * @param {ExprValue} x Bin expression for x dimension.
  *  Provides gridded x coordinates, potentially with a fractional component.
- * @param {import('../types.js').ExprValue} y Bin expression for x dimension.
+ * @param {ExprValue} y Bin expression for x dimension.
  *  Provides gridded y coordinates, potentially with a fractional component.
  * @param {string[]} z Group by columns that segment data into individual line
  *  series. An empty array indicates there is only a single line series.

package/src/transforms/m4.js

@@ -1,3 +1,7 @@
+/**
+ * @import { ExprNode } from '../ast/node.js'
+ * @import { ExprValue, FromExpr } from '../types.js'
+ */
 import { Query, isQuery } from '../ast/query.js';
 import { argmax, argmin, max, min } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
@@ -11,12 +15,12 @@ import { floor } from '../functions/numeric.js';
  * argmin and argmax, following https://arxiv.org/pdf/2306.03714.pdf.
  * This method can bin along either the *x* or *y* dimension, as determined
  * by the caller-provided *bin* expression.
- * @param {import('../types.js').FromExpr} input The base query or table.
- * @param {import('../types.js').ExprValue} bin An expression that maps
+ * @param {FromExpr} input The base query or table.
+ * @param {ExprValue} bin An expression that maps
  *  time-series values to fractional pixel positions.
  * @param {string} x The x dimension column name.
  * @param {string} y The y dimension column name.
- * @param {import('../ast/node.js').ExprNode[]} [groups] Additional
+ * @param {ExprNode[]} [groups] Additional
  *  groupby columns, for example for faceted charts.
  * @returns {Query} The resulting M4 query.
  */

package/src/transforms/util/bin-step.js

@@ -0,0 +1,79 @@
+/**
+ * @typedef {object} BinOptions
+ * @property {number} [step] An exact binning step to use.
+ * @property {number} [steps] The desired number of binning steps.
+ *  This value is a hint, it does not guarantee an exact number of steps.
+ * @property {number} [minstep] A minimum binning step value. No generated
+ *  step can be less than this value.
+ * @property {boolean} [nice] A boolean flag (default true) indicating if bin
+ *  extents should be snapped to "nice" numbers such as multiples of 5 or 10.
+ * @property {number} [base] A number indicating the the logarithm base to
+ *  use for automatic step size determination. Defaults to base 10.
+ */
+
+/**
+ * Generate a numeric binning scheme suitable for a histogram.
+ * @param {number} min The minimum value of the extent to bin.
+ * @param {number} max The maximum value of the extent to bin.
+ * @param {BinOptions} options Binning scheme options.
+ */
+export function binSpec(min, max, options) {
+  let {
+    step,
+    steps = 25,
+    minstep = 0,
+    nice = true,
+    base
+  } = options;
+
+  if (nice !== false) {
+    // use span to determine step size
+    const span = max - min;
+    const logb = base ? Math.log(base) : Math.LN10;
+    step = step || binStep(span, steps, minstep, logb);
+
+    // adjust min/max relative to step
+    let v = Math.log(step);
+    const precision = v >= 0 ? 0 : ~~(-v / logb) + 1;
+    const eps = Math.pow(10, -precision - 1);
+    v = Math.floor(min / step + eps) * step;
+    min = min < v ? v - step : v;
+    max = Math.ceil(max / step) * step;
+    steps = Math.round((max - min) / step);
+  }
+
+  return { min, max, steps };
+}
+
+/**
+ * Determine a bin step interval.
+ * @param {number} span The span from maximum to minimum value.
+ * @param {number} steps The approximate number of desired bins.
+ * @param {number} [minstep=0] The minimum acceptable bin step size.
+ * @param {number} [logb=Math.LN10] The log base for determining
+ *  orders of magnitude for step sizes. Defaults to log base 10
+ *  (`Math.LN10`). For example to use log base 2, provide the
+ *  argument `Math.LN2` instead.
+ * @returns {number} The bin step interval (bin size).
+ */
+export function binStep(span, steps, minstep = 0, logb = Math.LN10) {
+  let v;
+
+  const level = Math.ceil(Math.log(steps) / logb);
+  let step = Math.max(
+    minstep,
+    Math.pow(10, Math.round(Math.log(span) / logb) - level)
+  );
+
+  // increase step size if too many bins
+  while (Math.ceil(span / step) > steps) { step *= 10; }
+
+  // decrease step size if allowed
+  const div = [5, 2];
+  for (let i = 0, n = div.length; i < n; ++i) {
+    v = step / div[i];
+    if (v >= minstep && span / v <= steps) step = v;
+  }
+
+  return step;
+}

package/src/transforms/util/time-interval.js

@@ -0,0 +1,97 @@
+/** @import { TimeUnit } from '../../types.js' */
+import { binStep } from './bin-step.js';
+
+const YEAR = 'year';
+const MONTH = 'month';
+const DAY = 'day';
+const HOUR = 'hour';
+const MINUTE = 'minute';
+const SECOND = 'second';
+const MILLISECOND = 'millisecond';
+const MICROSECOND = 'microsecond';
+
+const durationSecond = 1000;
+const durationMinute = durationSecond * 60;
+const durationHour = durationMinute * 60;
+const durationDay = durationHour * 24;
+const durationWeek = durationDay * 7;
+const durationMonth = durationDay * 30;
+const durationYear = durationDay * 365;
+
+/**
+ * @type {Array<{unit: TimeUnit, step: number, dt: number}>}
+ */
+const units = [
+  { unit: SECOND, step:  1, dt: durationSecond },
+  { unit: SECOND, step:  5, dt: durationSecond * 5 },
+  { unit: SECOND, step: 15, dt: durationSecond * 15 },
+  { unit: SECOND, step: 30, dt: durationSecond * 30 },
+  { unit: MINUTE, step:  1, dt: durationMinute },
+  { unit: MINUTE, step:  5, dt: durationMinute * 5 },
+  { unit: MINUTE, step: 15, dt: durationMinute * 15 },
+  { unit: MINUTE, step: 30, dt: durationMinute * 30 },
+  { unit: HOUR,   step:  1, dt: durationHour },
+  { unit: HOUR,   step:  3, dt: durationHour * 3 },
+  { unit: HOUR,   step:  6, dt: durationHour * 6 },
+  { unit: HOUR,   step: 12, dt: durationHour * 12 },
+  { unit: DAY,    step:  1, dt: durationDay },
+  { unit: DAY,    step:  7, dt: durationWeek },
+  { unit: MONTH,  step:  1, dt: durationMonth },
+  { unit: MONTH,  step:  3, dt: durationMonth * 3 },
+  { unit: YEAR,   step:  1, dt: durationYear }
+];
+
+/**
+ * Determine a time interval for binning based on provided min
+ * and max timestamps and approximate step count.
+ * @param {Date|number} min The minimum timestamp value.
+ * @param {Date|number} max The maximum timestamp value.
+ * @param {number} steps The approximate number of bins desired.
+ * @returns {{ unit: TimeUnit, step: number }}
+ */
+export function timeInterval(min, max, steps) {
+  const span = +max - +min;
+  const t = span / steps; // target step size duration
+  const i = bisect(units, t, v => v.dt);
+  /** @type {TimeUnit} */
+  let unit;
+  let step;
+
+  if (i === units.length) {
+    unit = YEAR;
+    step = binStep(span / durationYear, steps);
+  } else if (i) {
+    ({ unit, step } = units[t / units[i-1].dt < units[i].dt / t ? i-1 : i]);
+  } else {
+    step = binStep(span, steps);
+    unit = step >= 1 ? MILLISECOND : MICROSECOND;
+    step = step >= 1 ? step : step * 1000;
+  }
+  return { unit, step };
+}
+
+/**
+ * Perform a binary search.
+ * @template I, T
+ * @param {I[]} a The array to search.
+ * @param {T} x The target value
+ * @param {(item: I) => T} value A value accessor
+ * @returns {number} The search result array index.
+ */
+function bisect(a, x, value) {
+  const compare1 = (a, b) => a - b;
+  const compare2 = (d, x) => compare1(value(d), x);
+
+  let lo = 0;
+  let hi = a.length;
+
+  if (lo < hi) {
+    if (compare1(x, x) !== 0) return hi;
+    do {
+      const mid = (lo + hi) >>> 1;
+      if (compare2(a[mid], x) <= 0) lo = mid + 1;
+      else hi = mid;
+    } while (lo < hi);
+  }
+  return lo;
+}

package/src/types.ts

@@ -99,3 +99,14 @@ export type FromExpr = MaybeArray<FromEntry>;
 export type FilterExpr = MaybeArray<string | ExprNode>;
 export type GroupByExpr = MaybeArray<string | ExprNode>;
 export type OrderByExpr = MaybeArray<string | ExprNode>;
+
+export type TimeUnit =
+  | 'year'
+  | 'quarter'
+  | 'month'
+  | 'day'
+  | 'hour'
+  | 'minute'
+  | 'second'
+  | 'millisecond'
+  | 'microsecond';

package/src/util/ast.js

@@ -1,6 +1,9 @@
+/**
+ * @import { ColumnRefNode } from '../ast/column-ref.js'
+ * @import { TableRefNode } from '../ast/table-ref.js'
+ */
 import { ExprNode } from '../ast/node.js';
 import { ParamNode } from '../ast/param.js';
-import { TableRefNode } from '../ast/table-ref.js';
 import { WindowDefNode } from '../ast/window.js';
 import { column } from '../functions/column.js';
 import { literal, verbatim } from '../functions/literal.js';
@@ -68,7 +71,7 @@ export function asTableRef(value) {
  * Parse a string as a column reference, potentially with
  * dot ('.') delimited table, schema, and database references.
  * @param {string} ref The column reference string.
- * @returns {import('../ast/column-ref.js').ColumnRefNode}
+ * @returns {ColumnRefNode}
  */
 export function parseColumnRef(ref) {
   const ids = parseIdentifier(ref);
@@ -79,7 +82,7 @@ export function parseColumnRef(ref) {
  * Parse a string as a table reference, potentially with
  * dot ('.') delimited schema and database references.
  * @param {string} ref The table reference string.
- * @returns {import('../ast/table-ref.js').TableRefNode}
+ * @returns {TableRefNode}
  */
 export function parseTableRef(ref) {
   return tableRef(parseIdentifier(ref));

package/src/util/function.js

@@ -1,3 +1,7 @@
+/**
+ * @import { SQLNode } from '../ast/node.js'
+ * @import { WindowFunctionName } from '../types.js'
+ */
 import { AggregateNode } from '../ast/aggregate.js';
 import { FunctionNode } from '../ast/function.js';
 import { WindowFunctionNode, WindowNode } from '../ast/window.js';
@@ -5,7 +9,7 @@ import { asNode } from './ast.js';
 
 /**
  * Test if an AST node is a specific function call.
- * @param {import('../ast/node.js').SQLNode} node The SQL AST node to test.
+ * @param {SQLNode} node The SQL AST node to test.
  * @param {string} name The function name.
  * @returns {node is FunctionNode}
  */
@@ -37,7 +41,7 @@ export function aggFn(name, ...args) {
  * Create a new window AST node. The output node has an empty window
  * definition. Use chained calls such as `partitionby` and `orderby`
  * to specify the window settings.
- * @param {import('../types.js').WindowFunctionName} name The function name.
+ * @param {WindowFunctionName} name The function name.
  * @param  {...any} args The function arguments.
  * @returns {WindowNode}
  */

package/src/util/type-check.js

@@ -1,3 +1,7 @@
+/**
+ * @import { ParamLike } from '../types.js'
+ */
+
 /**
  * Check if a value is a string.
  * @param {*} value The value to check.
@@ -19,7 +23,7 @@ export function isArray(value) {
 /**
  * Check if a value is a dynamic parameter.
  * @param {*} value The value to check.
- * @returns {value is import('../types.js').ParamLike}
+ * @returns {value is ParamLike}
  */
 export function isParamLike(value) {
   return value

package/src/visit/visitors.js

@@ -1,3 +1,7 @@
+/**
+ * @import { ParamNode } from '../ast/param.js'
+ * @import { ParamLike } from '../types.js'
+ */
 import { AGGREGATE, COLUMN_PARAM, COLUMN_REF, FRAGMENT, PARAM, VERBATIM, WINDOW } from '../constants.js';
 import { aggregateNames, AggregateNode } from '../ast/aggregate.js';
 import { ColumnRefNode } from '../ast/column-ref.js';
@@ -92,14 +96,14 @@ export function collectColumns(root) {
 /**
  * Collect all unique dynamic parameter instances.
  * @param {SQLNode} root The root of the AST to search.
- * @returns {import('../types.js').ParamLike[]}
+ * @returns {ParamLike[]}
  */
 export function collectParams(root) {
   const params = new Set;
   walk(root, (node) => {
     if (node.type === PARAM) {
       params.add(
-        /** @type {import('../ast/param.js').ParamNode} */
+        /** @type {ParamNode} */
         (node).param
       );
     }

package/src/visit/walk.js

@@ -1,11 +1,16 @@
+/**
+ * @import { SQLNode } from '../ast/node.js'
+ * @import { VisitorCallback, VisitorResult } from '../types.js'
+
+ */
 import { isNode } from '../ast/node.js';
 import { recurse } from './recurse.js';
 
 /**
  * Perform a traversal of a SQL expression AST.
- * @param {import('../ast/node.js').SQLNode} node Root node for AST traversal.
- * @param {import('../types.js').VisitorCallback} visit Visitor callback function.
- * @return {import('../types.js').VisitorResult}
+ * @param {SQLNode} node Root node for AST traversal.
+ * @param {VisitorCallback} visit Visitor callback function.
+ * @return {VisitorResult}
  */
 export function walk(node, visit) {
   if (!isNode(node)) return;