@uwdata/mosaic-sql 0.16.2 → 0.18.0

package/src/functions/{window.js → window.ts}

@@ -1,13 +1,9 @@
-/**
- * @import { WindowNode } from '../ast/window.js'
- * @import { ExprValue, NumberValue } from '../types.js'
- */
+import type { ExprValue, NumberValue } from '../types.js';
 import { winFn } from '../util/function.js';
 
 /**
  * Create a window function that returns the number of the current row
  * within the partition, counting from 1.
- * @returns {WindowNode}
  */
 export function row_number() {
   return winFn('row_number');
@@ -16,7 +12,6 @@ export function row_number() {
 /**
  * Create a window function that returns the rank of the current row with gaps.
  * This is the same as the row_number of its first peer.
- * @returns {WindowNode}
  */
 export function rank() {
   return winFn('rank');
@@ -25,7 +20,6 @@ export function rank() {
 /**
  * Create a window function that returns the rank of the current row without
  * gaps. The function counts peer groups.
- * @returns {WindowNode}
  */
 export function dense_rank() {
   return winFn('dense_rank');
@@ -34,7 +28,6 @@ export function dense_rank() {
 /**
  * Create a window function that returns the relative rank of the current row.
  * Computed as (rank() - 1) / (total partition rows - 1).
- * @returns {WindowNode}
  */
 export function percent_rank() {
   return winFn('percent_rank');
@@ -43,7 +36,6 @@ export function percent_rank() {
 /**
  * Create a window function that returns the cumulative distribution. Computed
  * as (number of preceding or peer partition rows) / total partition rows.
- * @returns {WindowNode}
  */
 export function cume_dist() {
   return winFn('cume_dist');
@@ -52,11 +44,9 @@ 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 {NumberValue} num_buckets The number of
- *  quantile buckets.
- * @returns {WindowNode}
+ * @param num_buckets The number of quantile buckets.
  */
-export function ntile(num_buckets) {
+export function ntile(num_buckets: NumberValue) {
   return winFn('ntile', num_buckets);
 }
 
@@ -66,13 +56,11 @@ 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 {ExprValue} expr The expression to evaluate.
- * @param {NumberValue} [offset] The row offset
- *  (default `1`).
- * @param {*} [defaultValue] The default value (default `null`).
- * @returns {WindowNode}
+ * @param expr The expression to evaluate.
+ * @param offset The row offset (default `1`).
+ * @param defaultValue The default value (default `null`).
  */
-export function lag(expr, offset, defaultValue){
+export function lag(expr: ExprValue, offset?: NumberValue, defaultValue?: unknown) {
   return winFn('lag', expr, offset, defaultValue);
 }
 
@@ -82,43 +70,38 @@ 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 {ExprValue} expr The expression to evaluate.
- * @param {NumberValue} [offset] The row offset
- *  (default `1`).
- * @param {*} [defaultValue] The default value (default `null`).
- * @returns {WindowNode}
+ * @param expr The expression to evaluate.
+ * @param offset The row offset (default `1`).
+ * @param defaultValue The default value (default `null`).
  */
-export function lead(expr, offset, defaultValue){
+export function lead(expr: ExprValue, offset?: NumberValue, defaultValue?: unknown) {
   return winFn('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 {ExprValue} expr The expression to evaluate.
- * @returns {WindowNode}
+ * @param expr The expression to evaluate.
  */
-export function first_value(expr) {
+export function first_value(expr: ExprValue) {
   return winFn('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 {ExprValue} expr The expression to evaluate.
- * @returns {WindowNode}
+ * @param expr The expression to evaluate.
  */
-export function last_value(expr) {
+export function last_value(expr: ExprValue) {
   return winFn('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 {ExprValue} expr The expression to evaluate.
- * @param {NumberValue} nth The 1-based window frame index.
- * @returns {WindowNode}
+ * @param expr The expression to evaluate.
+ * @param nth The 1-based window frame index.
  */
-export function nth_value(expr, nth) {
+export function nth_value(expr: ExprValue, nth: NumberValue) {
   return winFn('nth_value', expr, nth);
 }

package/src/index.ts

@@ -0,0 +1,75 @@
+export { AggregateNode, aggregateNames, isAggregateFunction } from './ast/aggregate.js';
+export { BetweenOpNode, NotBetweenOpNode } from './ast/between-op.js'
+export { BinaryOpNode } from './ast/binary-op.js';
+export { CaseNode, WhenNode } from './ast/case.js';
+export { CastNode } from './ast/cast.js';
+export { CollateNode } from './ast/collate.js';
+export { ColumnParamNode, isColumnParam } from './ast/column-param.js';
+export { ColumnRefNode, ColumnNameRefNode, isColumnRef } from './ast/column-ref.js';
+export { FragmentNode } from './ast/fragment.js';
+export { FromClauseNode } from './ast/from.js';
+export { FunctionNode } from './ast/function.js';
+export { InOpNode } from './ast/in-op.js';
+export { IntervalNode } from './ast/interval.js';
+export { LiteralNode } from './ast/literal.js';
+export { AndNode, OrNode } from './ast/logical-op.js';
+export { SQLNode, ExprNode, isNode } from './ast/node.js';
+export { OrderByNode } from './ast/order-by.js';
+export { ParamNode } from './ast/param.js';
+export { DescribeQuery, Query, SelectQuery, SetOperation, isDescribeQuery, isQuery, isSelectQuery } from './ast/query.js';
+export { SampleClauseNode } from './ast/sample.js';
+export { ScalarSubqueryNode } from './ast/subquery.js';
+export { SelectClauseNode } from './ast/select.js';
+export { TableRefNode, isTableRef } from './ast/table-ref.js';
+export { UnaryOpNode, UnaryPostfixOpNode } from './ast/unary-op.js';
+export { VerbatimNode } from './ast/verbatim.js';
+export { WindowClauseNode, WindowDefNode, WindowFunctionNode, WindowNode } from './ast/window.js';
+export { WindowFrameNode, WindowFrameExprNode, type FrameExclude, type FrameExtent, type FrameScope, type FrameType, type FrameValue } from './ast/window-frame.js';
+export { WithClauseNode } from './ast/with.js';
+
+export { argmax, argmin, arrayAgg, avg, corr, count, covariance, covarPop, entropy, first, geomean, kurtosis, mad, max, median, min, mode, last, product, quantile, regrAvgX, regrAvgY, regrCount, regrIntercept, regrR2, regrSXX, regrSXY, regrSYY, regrSlope, skewness, stddev, stddevPop, stringAgg, sum, variance, varPop } from './functions/aggregate.js';
+export { cond } from './functions/case.js';
+export { cast, float32, float64, int32 } from './functions/cast.js';
+export { collate } from './functions/collate.js';
+export { column } from './functions/column.js';
+export { cte } from './functions/cte.js';
+export { dateBin, dateMonth, dateMonthDay, dateDay, epoch_ms } from './functions/datetime.js';
+export { days, hours, interval, microseconds, minutes, milliseconds, months, seconds, years } from './functions/interval.js';
+export { literal, verbatim } from './functions/literal.js';
+export { abs, ceil, exp, floor, greatest, isFinite, isInfinite, isNaN, least, ln, log, round, sign, sqrt, trunc } from './functions/numeric.js';
+export { and, or, not, isNull, isNotNull, bitNot, bitAnd, bitOr, bitLeft, bitRight, add, sub, mul, div, idiv, mod, pow, eq, neq, lt, gt, lte, gte, isDistinct, isNotDistinct, isBetween, isNotBetween, isIn } from './functions/operators.js';
+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 { currentRow, following, frameGroups, frameRange, frameRows, preceding } from './functions/window-frame.js';
+
+export { deepClone } from './visit/clone.js';
+export { rewrite } from './visit/rewrite.js';
+export { collectAggregates, collectColumns, collectParams, isAggregateExpression } from './visit/visitors.js';
+export { walk, type VisitorCallback, type VisitorResult } from './visit/walk.js';
+
+export { createTable, createSchema } from './load/create.js';
+export { loadExtension } from './load/extension.js';
+export { loadCSV, loadJSON, loadObjects, loadParquet, loadSpatial } from './load/load.js';
+
+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 { filterQuery } from './transforms/filter-query.js';
+export { lineDensity } from './transforms/line-density.js';
+export { m4 } from './transforms/m4.js';
+export { scaleTransform, type Scale, type ScaleDomain, type ScaleOptions, type ScaleTransform, type ScaleType } from './transforms/scales.js';
+
+export { asLiteral, asNode, asTableRef, asVerbatim, over } from './util/ast.js';
+export { isParamLike } from './util/type-check.js';
+
+export { binSpec, binStep, type BinOptions } from './transforms/util/bin-step.js';
+export { timeInterval, type TimeUnit } from './transforms/util/time-interval.js';
+
+export * from './types.js';

package/src/load/{create.js → create.ts}

@@ -1,8 +1,14 @@
-export function createTable(name, query, {
+export interface CreateTableOptions {
+  replace?: boolean;
+  temp?: boolean;
+  view?: boolean;
+}
+
+export function createTable(name: string, query: string, {
   replace = false,
   temp = false,
   view = false
-} = {}) {
+}: CreateTableOptions = {}) {
   return 'CREATE'
     + (replace ? ' OR REPLACE ' : ' ')
     + (temp ? 'TEMP ' : '')
@@ -11,7 +17,7 @@ export function createTable(name, query, {
     + name + ' AS ' + query;
 }
 
-export function createSchema(name, {
+export function createSchema(name: string, {
   strict = false
 } = {}) {
   return 'CREATE SCHEMA '

package/src/load/extension.ts

@@ -0,0 +1,3 @@
+export function loadExtension(name: string) {
+  return `INSTALL ${name}; LOAD ${name}`;
+}

package/src/load/{load.js → load.ts}

@@ -1,7 +1,18 @@
-import { createTable } from './create.js';
+import { createTable, CreateTableOptions } from './create.js';
 import { sqlFrom } from './sql-from.js';
 
-export function load(method, tableName, fileName, options = {}, defaults = {}) {
+type Options =
+  & { select?: string[]; }
+  & CreateTableOptions
+  & Record<string, unknown>;
+
+export function load(
+  method: string,
+  tableName: string,
+  fileName: string,
+  options: Options = {},
+  defaults: Record<string, unknown> = {}
+) {
   const { select = ['*'], where, view, temp, replace, ...file } = options;
   const params = parameters({ ...defaults, ...file });
   const read = `${method}('${fileName}'${params ? ', ' + params : ''})`;
@@ -10,25 +21,25 @@ export function load(method, tableName, fileName, options = {}, defaults = {}) {
   return createTable(tableName, query, { view, temp, replace });
 }
 
-export function loadCSV(tableName, fileName, options) {
+export function loadCSV(tableName: string, fileName: string, options?: Options) {
   return load('read_csv', tableName, fileName, options, { auto_detect: true, sample_size: -1 });
 }
 
-export function loadJSON(tableName, fileName, options) {
+export function loadJSON(tableName: string, fileName: string, options?: Options) {
   return load('read_json', tableName, fileName, options, { auto_detect: true, format: 'auto' });
 }
 
-export function loadParquet(tableName, fileName, options) {
+export function loadParquet(tableName: string, fileName: string, options?: Options) {
   return load('read_parquet', tableName, fileName, options);
 }
 
 /**
  * Load geometry data within a spatial file format.
  * This method requires that the DuckDB spatial extension is loaded.
- * Supports GeoJSON, TopoJSON, and other comomn spatial formats.
+ * Supports GeoJSON, TopoJSON, and other common spatial formats.
  * For TopoJSON, wet the layer option to indicate the feature to extract.
  */
-export function loadSpatial(tableName, fileName, options = {}) {
+export function loadSpatial(tableName: string, fileName: string, options: Options = {}) {
   // nested options map to the open_options argument of st_read
   const { options: opt, ...rest } = options;
   if (opt) {
@@ -45,7 +56,11 @@ export function loadSpatial(tableName, fileName, options = {}) {
   return load('st_read', tableName, fileName, rest);
 }
 
-export function loadObjects(tableName, data, options = {}) {
+export function loadObjects(
+  tableName: string,
+  data: (Record<string,unknown>)[],
+  options: Options = {}
+) {
   const { select = ['*'], ...opt } = options;
   const values = sqlFrom(data);
   const query = select.length === 1 && select[0] === '*'
@@ -54,13 +69,13 @@ export function loadObjects(tableName, data, options = {}) {
   return createTable(tableName, query, opt);
 }
 
-function parameters(options) {
+function parameters(options: Record<string, unknown>) {
   return Object.entries(options)
     .map(([key, value]) => `${key}=${toDuckDBValue(value)}`)
     .join(', ');
 }
 
-function toDuckDBValue(value) {
+function toDuckDBValue(value: unknown): string {
   switch (typeof value) {
     case 'boolean':
       return String(value);
@@ -80,6 +95,6 @@ function toDuckDBValue(value) {
           + '}';
       }
     default:
-      return value;
+      return `${value}`;
   }
 }

package/src/load/{sql-from.js → sql-from.ts}

@@ -1,20 +1,27 @@
 import { asLiteral } from '../util/ast.js';
 
+type SQLFromOptions = {
+  columns?: string[] | Record<string, string>;
+} & Record<string,string>;
+
 /**
  * Create a SQL query that embeds the given data for loading.
- * @param {*} data The dataset as an array of objects.
- * @param {object} [options] Loading options.
+ * @param data The dataset as an array of objects.
+ * @param options Loading options.
  * @param {string[]|object} [options.columns] The columns to include.
  *   If not specified, the keys of the first data object are used.
  * @returns {string} SQL query string to load data.
  */
-export function sqlFrom(data, {
-  columns = Object.keys(data?.[0] || {})
-} = {}) {
-  let keys = [];
+export function sqlFrom(
+  data: (Record<string, unknown>)[],
+  {
+    columns = Object.keys(data?.[0] || {})
+  }: SQLFromOptions = {}
+) {
+  let keys: string[] = [];
   if (Array.isArray(columns)) {
     keys = columns;
-    columns = keys.reduce((m, k) => (m[k] = k, m), {});
+    columns = keys.reduce((m, k) => (m[k] = k, m), {} as Record<string, string>);
   } else if (columns) {
     keys = Object.keys(columns);
   }

package/src/transforms/{bin-1d.js → bin-1d.ts}

@@ -1,23 +1,27 @@
-/**
- * @import { ExprValue } from '../types.js'
- */
+import type { 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 {ExprValue} x The expression to bin.
+ * @param 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.
- * @param {number} lo The low value of the bin extent.
- * @param {number} hi The high value of the bin extent.
- * @param {number} bins The integer number of bins to use within the
+ * @param lo The low value of the bin extent.
+ * @param hi The high value of the bin extent.
+ * @param bins The integer number of bins to use within the
  *  defined binning extent.
- * @param {boolean} [reverse] Flag indicating if bins should be
+ * @param reverse Flag indicating if bins should be
  *  produced in reverse order from *hi* to *lo* (default `false`).
  */
-export function bin1d(x, lo, hi, bins, reverse) {
+export function bin1d(
+  x: ExprValue,
+  lo: number,
+  hi: number,
+  bins: number,
+  reverse: boolean = false
+) {
   const diff = reverse ? sub(hi, float64(x)) : sub(float64(x), lo);
   const scale = hi === lo ? 0 : bins / (hi - lo);
   return scale ? mul(diff, float64(scale)) : diff;

package/src/transforms/{bin-2d.js → bin-2d.ts}

@@ -1,7 +1,5 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
 import { int32 } from '../functions/cast.js';
 import { floor } from '../functions/numeric.js';
 import { add, mul } from '../functions/operators.js';
@@ -12,17 +10,23 @@ import { add, mul } from '../functions/operators.js';
  * in units of grid indices, but can contain fractional components. The
  * resulting query performs grouping and aggregation over the binned domain,
  * 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
+ * @param q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, either before or after this method.
- * @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.
- * @returns {SelectQuery} The input query, with binning expressions added.
+ * @param xp The x bin expression.
+ * @param yp The y bin expression.
+ * @param aggs Named aggregate expressions over bins.
+ * @param {xn The number of bins along the x dimension
+ * @param groupby Group by expressions.
+ * @returns The input query, with binning expressions added.
  */
-export function bin2d(q, xp, yp, aggs, xn, groupby) {
+export function bin2d(
+  q: SelectQuery,
+  xp: ExprValue,
+  yp: ExprValue,
+  aggs: Record<string, ExprValue>,
+  xn: number,
+  groupby: string[]
+) {
   return q
     .select({
       index: add(int32(floor(xp)), mul(int32(floor(yp)), xn)),

package/src/transforms/bin-date.ts

@@ -0,0 +1,48 @@
+import type { ExprNode } from '../ast/node.js';
+import type { ExprValue } from '../types.js';
+import { dateBin } from '../functions/datetime.js';
+import { interval } from '../functions/interval.js';
+import { add } from '../functions/operators.js';
+import { timeInterval, type DateTimeValue, type TimeUnit } from './util/time-interval.js';
+
+export interface BinDateOptions {
+  /**
+   * A string indicating a time interval unit,
+   * such as 'year', 'day', or 'hour'.
+   */
+  interval?: TimeUnit;
+  /**
+   * The number of time interval steps to take, such as 2 years or 3 months.
+   */
+  step?: number;
+  /**
+   * The number of bin steps (default 0) by which to offset the result.
+   */
+  offset?: number;
+  /**
+   * The desired number of binning steps. This value is a hint,
+   * it does not guarantee an exact number of steps.
+   */
+  steps?: number;
+}
+
+/**
+ * Return a SQL expression for date/time bins.
+ * @param field The column or expression to bin.
+ * @param extent The min/max extent over which to bin.
+ * @param options Datetime binning options.
+ */
+export function binDate(
+  field: ExprValue,
+  extent: [DateTimeValue, DateTimeValue],
+  options: BinDateOptions = {}
+): ExprNode {
+  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.ts

@@ -0,0 +1,61 @@
+import type { ExprNode } from '../ast/node.js';
+import type { 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 { Scale, scaleTransform } from './scales.js';
+
+export interface BinHistogramOptions {
+  /** An exact binning step to use. */
+  step?: number;
+  /**
+   * The desired number of binning steps. This value is a hint,
+   * it does not guarantee an exact number of steps.
+   */
+  steps?: number;
+  /**
+   * A minimum binning step value. No generated
+   * step can be less than this value.
+   */
+  minstep?: number;
+  /**
+   * A boolean flag (default true) indicating if bin extents should be
+   * snapped to "nice" numbers such as multiples of 5 or 10.
+   */
+  nice?: boolean;
+  /**
+   * The number of bin steps (default 0) by which to offset the result.
+   */
+  offset?: number;
+}
+
+/**
+ * Return a SQL expression for histogram bins.
+ * @param field The column or expression to bin.
+ * @param extent The min/max extent over which to bin.
+ * @param options Binning options.
+ * @param transform Scale transforms to apply to create
+ *  (potentially non-linear) binning intervals.
+ * @returns The resulting SQL expression
+ */
+export function binHistogram(
+  field: ExprValue,
+  extent: [number, number],
+  options: BinHistogramOptions = {},
+  transform: Scale<number> = scaleTransform({ type: 'linear' })!
+): ExprNode {
+  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 → bin-linear-1d.ts}

@@ -1,7 +1,6 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprNode } from '../ast/node.js';
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
 import { Query } from '../ast/query.js';
 import { sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
@@ -10,14 +9,20 @@ import { add, mul, neq, sub } from '../functions/operators.js';
 
 /**
  * Perform linear binning in one dimension.
- * @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}
+ * @param  query The base query to bin.
+ * @param x The expression to bin.
+ * @param weight The expression to weight by.
+ * @param groupby Group by expressions.
  */
-export function binLinear1d(query, x, weight = undefined, groupby = []) {
-  const w = weight ? (x => mul(x, weight)) : (x => x);
+export function binLinear1d(
+  query: SelectQuery,
+  x: ExprValue,
+  weight: ExprValue | undefined = undefined,
+  groupby: string[] = []
+) {
+  const w = weight
+    ? ((x: ExprNode) => mul(x, weight))
+    : ((x: ExprNode) => x);
   const p0 = floor(x);
   const p1 = add(p0, 1);
   return Query