@uwdata/mosaic-sql 0.17.0 → 0.18.0

package/src/ast/{with.js → with.ts}

@@ -1,39 +1,38 @@
-/** @import { Query } from './query.js' */
+import type { Query } from './query.js';
 import { WITH_CLAUSE } from '../constants.js';
 import { SQLNode } from './node.js';
 
 export class WithClauseNode extends SQLNode {
+  /** The common table expression (CTE) name. */
+  readonly name: string;
+  /** The common table expression (CTE) query. */
+  readonly query: Query;
+  /** The common table expression (CTE) materialization flag. */
+  readonly materialized: boolean | null;
+
   /**
    * Instantiate a with clause node for a common table expression (CTE).
-   * @param {string} name The common table expression (CTE) name.
-   * @param {Query} query The common table expression (CTE) query.
-   * @param {boolean | null} [materialized] The common table expression (CTE)
+   * @param name The common table expression (CTE) name.
+   * @param query The common table expression (CTE) query.
+   * @param materialized The common table expression (CTE)
    *  materialization flag. If `true`, forces materialization of the CTE.
    *  If `false`, materialization is not performed. Otherwise (for example, if
    *  `undefined` or `null`), materialization is decided by the database.
    */
-  constructor(name, query, materialized = undefined) {
+  constructor(
+    name: string,
+    query: Query,
+    materialized: boolean | null = null
+  ) {
     super(WITH_CLAUSE);
-    /**
-     * The common table expression (CTE) name.
-     * @type {string}
-     * @readonly
-     */
     this.name = name;
-    /**
-     * The common table expression (CTE) query.
-     * @type {Query}
-     * @readonly
-     */
     this.query = query;
-    /**
-     * The common table expression (CTE) materialization flag.
-     * @type {boolean | null}
-     * @readonly
-     */
     this.materialized = materialized;
   }
 
+  /**
+   * Generate a SQL query string for this node.
+   */
   toString() {
     const flag = this.materialized;
     const mat = flag === true ? ' MATERIALIZED'

package/src/functions/aggregate.ts

@@ -0,0 +1,344 @@
+import type { ExprValue } from '../types.js';
+import { aggFn } from '../util/function.js';
+
+/**
+ * Compute an arg_max aggregate.
+ * @param y The argument to return.
+ * @param x The expression to maximize.
+ * @returns A SQL aggregate function call.
+ */
+export function argmax(y: ExprValue, x: ExprValue) {
+  return aggFn('arg_max', y, x);
+}
+
+/**
+ * Compute an arg_min aggregate.
+ * @param y The argument to return.
+ * @param x The expression to minimize.
+ * @returns A SQL aggregate function call.
+ */
+export function argmin(y: ExprValue, x: ExprValue) {
+  return aggFn('arg_min', y, x);
+}
+
+/**
+ * Compute an array aggregation.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function arrayAgg(expr: ExprValue) {
+  return aggFn('array_agg', expr);
+}
+
+/**
+ * Compute an average aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function avg(expr: ExprValue) {
+  return aggFn('avg', expr);
+}
+
+/**
+ * Compute a correlation aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function corr(x: ExprValue, y: ExprValue) {
+  return aggFn('corr', x, y);
+}
+
+/**
+ * Compute a count aggregate.
+ * @param [expr] An optional expression
+ *  to count. If specified, only non-null expression values are counted.
+ *  If omitted, all rows within a group are counted.
+ * @returns A SQL aggregate function call.
+ */
+export function count(expr?: ExprValue) {
+  return aggFn('count', expr);
+}
+
+/**
+ * Compute a sample covariance aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function covariance(x: ExprValue, y: ExprValue) {
+  return aggFn('covar_samp', x, y);
+}
+
+/**
+ * Compute a population covariance aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function covarPop(x: ExprValue, y: ExprValue) {
+  return aggFn('covar_pop', x, y);
+}
+
+/**
+ * Compute an entropy aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function entropy(expr: ExprValue) {
+  return aggFn('entropy', expr);
+}
+
+/**
+ * Compute a first aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function first(expr: ExprValue) {
+  return aggFn('first', expr);
+}
+
+/**
+ * Compute a geomean aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function geomean(expr: ExprValue) {
+  return aggFn('geomean', expr);
+}
+
+/**
+ * Compute a sample kurtosis aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function kurtosis(expr: ExprValue) {
+  return aggFn('kurtosis', expr);
+}
+
+/**
+ * Compute a median absolute deviation (MAD) aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function mad(expr: ExprValue) {
+  return aggFn('mad', expr);
+}
+
+/**
+ * Compute a maximum aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function max(expr: ExprValue) {
+  return aggFn('max', expr);
+}
+
+/**
+ * Compute a median aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function median(expr: ExprValue) {
+  return aggFn('median', expr);
+}
+
+/**
+ * Compute a minimum aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function min(expr: ExprValue) {
+  return aggFn('min', expr);
+}
+
+/**
+ * Compute a mode aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function mode(expr: ExprValue) {
+  return aggFn('mode', expr);
+}
+
+/**
+ * Compute a last aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function last(expr: ExprValue) {
+  return aggFn('last', expr);
+}
+
+/**
+ * Compute a product aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function product(expr: ExprValue) {
+  return aggFn('product', expr);
+}
+
+/**
+ * Compute a quantile aggregate.
+ * @param expr The expression to aggregate.
+ * @param p The quantile value.
+ * @returns A SQL aggregate function call.
+ */
+export function quantile(expr: ExprValue, p: ExprValue) {
+  return aggFn('quantile', expr, p);
+}
+
+/**
+ * Compute a linear regression reg_avgX aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrAvgX(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_avgx', x, y);
+}
+
+/**
+ * Compute a linear regression reg_avgY aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrAvgY(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_avgy', x, y);
+}
+
+/**
+ * Compute a linear regression count aggregate.
+ * This returns the count of rows where both x and y are non-null.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrCount(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_count', x, y);
+}
+
+/**
+ * Compute a linear regression intercept aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrIntercept(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_intercept', x, y);
+}
+
+/**
+ * Compute a linear regression R^2 aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrR2(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_r2', x, y);
+}
+
+/**
+ * Compute a linear regression regr_sxx aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSXX(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_sxx', x, y);
+}
+
+/**
+ * Compute a linear regression regr_sxy aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSXY(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_sxy', x, y);
+}
+
+/**
+ * Compute a linear regression regr_syy aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSYY(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_syy', x, y);
+}
+
+/**
+ * Compute a linear regression slope aggregate.
+ * @param x The x expression to aggregate.
+ * @param y The y expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function regrSlope(x: ExprValue, y: ExprValue) {
+  return aggFn('regr_slope', x, y);
+}
+
+/**
+ * Compute a skewness aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function skewness(expr: ExprValue) {
+  return aggFn('skewness', expr);
+}
+
+/**
+ * Compute a sample standard deviation aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function stddev(expr: ExprValue) {
+  return aggFn('stddev', expr);
+}
+
+/**
+ * Compute a population standard deviation aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function stddevPop(expr: ExprValue) {
+  return aggFn('stddev_pop', expr);
+}
+
+/**
+ * Compute a string aggregation.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function stringAgg(expr: ExprValue) {
+  return aggFn('string_agg', expr);
+}
+
+/**
+ * Compute a sum aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function sum(expr: ExprValue) {
+  return aggFn('sum', expr);
+}
+
+/**
+ * Compute a sample variance aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function variance(expr: ExprValue) {
+  return aggFn('var_samp', expr);
+}
+
+/**
+ * Compute a population variance aggregate.
+ * @param expr The expression to aggregate.
+ * @returns A SQL aggregate function call.
+ */
+export function varPop(expr: ExprValue) {
+  return aggFn('var_pop', expr);
+}

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

@@ -1,6 +1,4 @@
-/**
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprValue } from '../types.js';
 import { CaseNode, WhenNode } from '../ast/case.js';
 import { asNode } from '../util/ast.js';
 
@@ -9,12 +7,11 @@ import { asNode } from '../util/ast.js';
  * acts like a ternary conditional (if, then, else). If no arguments are
  * provided, the chained `when` and `else` methods can be used to to complete
  * a conditional statement with WHEN/THEN and ELSE expressions.
- * @param {ExprValue} [when] A conditional WHEN expression.
- * @param {ExprValue} [then] A THEN value expression.
- * @param {ExprValue} [other] An ELSE expression.
- * @returns {CaseNode}
+ * @param when A conditional WHEN expression.
+ * @param then A THEN value expression.
+ * @param other An ELSE expression.
  */
-export function cond(when, then, other) {
+export function cond(when?: ExprValue, then?: ExprValue, other?: ExprValue) {
   return when
     ? new CaseNode(undefined, [new WhenNode(asNode(when), asNode(then))], asNode(other))
     : new CaseNode();

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

@@ -3,37 +3,33 @@ import { asNode } from '../util/ast.js';
 
 /**
  * Perform a type cast.
- * @param {*} expr The expression to type cast.
- * @param {string} type The type to cast to.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
+ * @param type The type to cast to.
  */
-export function cast(expr, type) {
+export function cast(expr: unknown, type: string) {
   return new CastNode(asNode(expr), type);
 }
 
 /**
  * Cast an expression to a 32-bit integer type.
- * @param {*} expr The expression to type cast.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
  */
-export function int32(expr) {
+export function int32(expr: unknown) {
   return cast(expr, 'INTEGER');
 }
 
 /**
  * Cast an expression to a 32-bit floating point number type.
- * @param {*} expr The expression to type cast.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
  */
-export function float32(expr) {
+export function float32(expr: unknown) {
   return cast(expr, 'FLOAT');
 }
 
 /**
  * Cast an expression to a 64-bit floating point number type.
- * @param {*} expr The expression to type cast.
- * @returns {CastNode}
+ * @param expr The expression to type cast.
  */
-export function float64(expr) {
+export function float64(expr: unknown) {
   return cast(expr, 'DOUBLE');
 }

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

@@ -1,16 +1,13 @@
-/**
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprValue } from '../types.js';
 import { CollateNode } from '../ast/collate.js';
 import { asNode } from '../util/ast.js';
 
 /**
  * Indicate ascending sort order for an expression.
- * @param {ExprValue} expr The expression to collate.
- * @param {string} collation The collation type, such as
+ * @param expr The expression to collate.
+ * @param collation The collation type, such as
  *  'NOCASE', 'NOACCENT', 'NFC', or locale-specific collations.
- * @returns {CollateNode}
  */
-export function collate(expr, collation) {
+export function collate(expr: ExprValue, collation: string) {
   return new CollateNode(asNode(expr), collation);
 }

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

@@ -1,8 +1,6 @@
-/**
- * @import { ColumnRefNode } from '../ast/column-ref.js'
- * @import { TableRefNode } from '../ast/table-ref.js'
- * @import { ParamLike } from '../types.js'
- */
+import type { ColumnRefNode } from '../ast/column-ref.js';
+import type { TableRefNode } from '../ast/table-ref.js';
+import type { ParamLike } from '../types.js';
 import { ColumnParamNode } from '../ast/column-param.js';
 import { ColumnNameRefNode } from '../ast/column-ref.js';
 import { ParamNode } from '../ast/param.js';
@@ -11,12 +9,13 @@ import { isParamLike } from '../util/type-check.js';
 
 /**
  * Create a column reference.
- * @param {string | ParamLike} name The column name,
- *  as a string or as a dynamic parameter.
- * @param {string | string[] | TableRefNode} [table] The table reference.
- * @returns {ColumnRefNode}
+ * @param name The column name, as a string or as a dynamic parameter.
+ * @param table The table reference.
  */
-export function column(name, table) {
+export function column(
+  name: string | ParamLike,
+  table?: string | string[] | TableRefNode
+): ColumnRefNode {
   const tref = asTableRef(table);
   return isParamLike(name)
     ? new ColumnParamNode(new ParamNode(name), tref)

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

@@ -1,16 +1,19 @@
-/** @import { Query } from '../ast/query.js' */
+import type { Query } from '../ast/query.js';
 import { WithClauseNode } from '../ast/with.js';
 
 /**
  * Create a common table expression (CTE) to include within a WITH clause.
- * @param {string} name The common table expression (CTE) name.
- * @param {Query} query The common table expression (CTE) query.
- * @param {boolean | null} [materialized] The common table expression (CTE)
+ * @param name The common table expression (CTE) name.
+ * @param query The common table expression (CTE) query.
+ * @param materialized The common table expression (CTE)
  *  materialization flag. If `true`, forces materialization of the CTE.
  *  If `false`, materialization is not performed. Otherwise (for example, if
  *  `undefined` or `null`), materialization is decided by the database.
- * @returns {WithClauseNode}
  */
-export function cte(name, query, materialized) {
+export function cte(
+  name: string,
+  query: Query,
+  materialized: boolean | null = null
+) {
   return new WithClauseNode(name, query, materialized);
 }

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

@@ -1,7 +1,4 @@
-/**
- * @import { FunctionNode } from '../ast/function.js'
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprValue } from '../types.js';
 import { asNode } from '../util/ast.js';
 import { fn } from '../util/function.js';
 import { interval } from './interval.js';
@@ -9,40 +6,36 @@ import { interval } from './interval.js';
 /**
  * Given a date/time value, return the milliseconds since the UNIX epoch.
  * @param {ExprValue} expr The date/time expression.
- * @returns {FunctionNode}
  */
-export function epoch_ms(expr) {
+export function epoch_ms(expr: ExprValue) {
   return fn('epoch_ms', expr);
 }
 
 /**
  * Perform data binning according to the provided interval unit and steps.
- * @param {ExprValue} expr The date/time expression to bin.
- * @param {string} unit The datetime interval unit to bin by.
- * @param {number} [steps=1] The number of interval steps.
- * @returns {FunctionNode}
+ * @param expr The date/time expression to bin.
+ * @param unit The datetime interval unit to bin by.
+ * @param steps The number of interval steps.
  */
-export function dateBin(expr, unit, steps = 1) {
+export function dateBin(expr: ExprValue, unit: string, steps: number = 1) {
   return fn('time_bucket', interval(unit, steps), expr);
 }
 
 /**
  * Map date/times to a month value, all within the same year for comparison.
  * The resulting value is still date-typed.
- * @param {ExprValue} expr The date/time expression.
- * @returns {FunctionNode}
+ * @param expr The date/time expression.
  */
-export function dateMonth(expr) {
+export function dateMonth(expr: ExprValue) {
   return fn('make_date', 2012, fn('month', expr), 1);
 }
 
 /**
  * Map date/times to a month and day value, all within the same year for
  * comparison. The resulting value is still date-typed.
- * @param {ExprValue} expr The date/time expression.
- * @returns {FunctionNode}
+ * @param expr The date/time expression.
  */
-export function dateMonthDay(expr) {
+export function dateMonthDay(expr: ExprValue) {
   const d = asNode(expr);
   return fn('make_date', 2012, fn('month', d), fn('day', d));
 }
@@ -50,9 +43,8 @@ export function dateMonthDay(expr) {
 /**
  * Map date/times to a day of the month value, all within the same year and month
  * for comparison. The resulting value is still date-typed.
- * @param {ExprValue} expr The date/time expression.
- * @returns {FunctionNode}
+ * @param expr The date/time expression.
  */
-export function dateDay(expr) {
+export function dateDay(expr: ExprValue) {
   return fn('make_date', 2012, 1, fn('day', expr));
 }

package/src/functions/interval.ts

@@ -0,0 +1,74 @@
+import { IntervalNode } from '../ast/interval.js';
+
+/**
+ * Create a new interval.
+ * @param unit The interval unit, such as day or year.
+ * @param steps The number of interval unit steps.
+ */
+export function interval(unit: string, steps: number) {
+  return new IntervalNode(unit, steps);
+}
+
+/**
+ * Create a new years interval.
+ * @param steps The number of years.
+ */
+export function years(steps: number) {
+  return interval('YEARS', steps);
+}
+
+/**
+ * Create a new months interval.
+ * @param steps The number of months.
+ */
+export function months(steps: number) {
+  return interval('MONTHS', steps);
+}
+
+/**
+ * Create a new days interval.
+ * @param steps The number of days.
+ */
+export function days(steps: number) {
+  return interval('DAYS', steps);
+}
+
+/**
+ * Create a new hours interval.
+ * @param steps The number of hours.
+ */
+export function hours(steps: number) {
+  return interval('HOURS', steps);
+}
+
+/**
+ * Create a new minutes interval.
+ * @param steps The number of minutes.
+ */
+export function minutes(steps: number) {
+  return interval('MINUTES', steps);
+}
+
+/**
+ * Create a new seconds interval.
+ * @param steps The number of seconds.
+ */
+export function seconds(steps: number) {
+  return interval('SECONDS', steps);
+}
+
+/**
+ * Create a new milliseconds interval.
+ * @param steps The number of milliseconds.
+ */
+export function milliseconds(steps: number) {
+  return interval('MILLISECONDS', steps);
+}
+
+/**
+ * Create a new microseconds interval.
+ * @param steps The number of microseconds.
+ */
+export function microseconds(steps: number) {
+  return interval('MICROSECONDS', steps);
+}