@uwdata/mosaic-sql 0.16.2 → 0.18.0

package/src/ast/window.js

@@ -1,294 +0,0 @@
-/**
- * @import { AggregateNode } from './aggregate.js'
- * @import { ExprVarArgs, WindowFunctionName } from '../types.js'
- * @import { ParamLike } from '../types.js'
- */
-import { WINDOW, WINDOW_CLAUSE, WINDOW_DEF, WINDOW_FRAME } from '../constants.js';
-import { exprList } from '../util/function.js';
-import { quoteIdentifier } from '../util/string.js';
-import { isParamLike } from '../util/type-check.js';
-import { FunctionNode } from './function.js';
-import { ExprNode, isNode, SQLNode } from './node.js';
-import { ParamNode } from './param.js';
-
-/**
- * @typedef {[any, any] | ParamLike} FrameExtent
- */
-
-export class WindowClauseNode extends SQLNode {
-  /**
-   * Instantiate a window clause node.
-   * @param {string} name The window name.
-   * @param {WindowDefNode} def The window definition.
-   */
-  constructor(name, def) {
-    super(WINDOW_CLAUSE);
-    /**
-     * The window name.
-     * @type {string}
-     * @readonly
-     */
-    this.name = name;
-    /**
-     * The window definition.
-     * @type {WindowDefNode}
-     * @readonly
-     */
-    this.def = def;
-  }
-
-  toString() {
-    return `${quoteIdentifier(this.name)} AS ${this.def}`;
-  }
-}
-
-export class WindowNode extends ExprNode {
-  /**
-   * Instantiate a window node.
-   * @param {WindowFunctionNode | AggregateNode} func The window function call.
-   * @param {WindowDefNode} [over] The window definition or name.
-   */
-  constructor(func, over = new WindowDefNode()) {
-    super(WINDOW);
-    /**
-     * @type {WindowFunctionNode | AggregateNode}
-     * @readonly
-     */
-    this.func = func;
-    /**
-     * @type {WindowDefNode}
-     * @readonly
-     */
-    this.def = over;
-  }
-
-  /**
-   * Return an updated window over a named window definition.
-   * @param {string} name The window definition name.
-   * @returns {WindowNode} A new window node.
-   */
-  over(name) {
-    return new WindowNode(this.func, this.def.over(name));
-  }
-
-  /**
-   * Return an updated window with the given partitions.
-   * @param {...ExprVarArgs} expr The partition by criteria.
-   * @returns {WindowNode} A new window node.
-   */
-  partitionby(...expr) {
-    return new WindowNode(this.func, this.def.partitionby(...expr));
-  }
-
-  /**
-   * Return an updated window with the given ordering.
-   * @param {...ExprVarArgs} expr The order by criteria.
-   * @returns {WindowNode} A new window node.
-   */
-  orderby(...expr) {
-    return new WindowNode(this.func, this.def.orderby(...expr));
-  }
-
-  /**
-   * Return an updated window with the given rows frame.
-   * @param {FrameExtent} extent The row-based window frame extent.
-   * @returns {WindowNode} A new window node.
-   */
-  rows(extent) {
-    return new WindowNode(this.func, this.def.rows(extent));
-  }
-
-  /**
-   * Return an updated window with the given range frame.
-   * @param {FrameExtent} extent The range-based window frame extent.
-   * @returns {WindowNode} A new window node.
-   */
-  range(extent) {
-    return new WindowNode(this.func, this.def.range(extent));
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    return `${this.func} OVER ${this.def}`;
-  }
-}
-
-export class WindowFunctionNode extends FunctionNode {
-  /**
-   * Instantiate a window function call node.
-   * @param {WindowFunctionName} name The function name.
-   * @param {ExprNode[]} [args=[]] The function arguments.
-   */
-  constructor(name, args) {
-    super(name, args);
-  }
-}
-
-export class WindowDefNode extends SQLNode {
-  /**
-   * Instantiate a window definition node.
-   * @param {string} [name] The base window definition name.
-   * @param {ExprNode[]} [partition] The partition by criteria.
-   * @param {ExprNode[]} [order] The order by criteria.
-   * @param {WindowFrameNode} [frame] The window frame definition.
-   */
-  constructor(name, partition, order, frame) {
-    super(WINDOW_DEF);
-    /**
-     * The base window definition name.
-     * @type {string}
-     * @readonly
-     */
-    this.name = name;
-    /**
-     * The partition by criteria.
-     * @type {ExprNode[]}
-     * @readonly
-     */
-    this.partition = partition;
-    /**
-     * The order by criteria.
-     * @type {ExprNode[]}
-     * @readonly
-     */
-    this.order = order;
-    /**
-     * The window frame definition.
-     * @type {WindowFrameNode}
-     * @readonly
-     */
-    this.frame = frame;
-  }
-
-  /**
-   * Return an updated window definition with the given base name.
-   * @param {string} name The base window definition name.
-   * @returns {WindowDefNode} A new window definition node.
-   */
-  over(name) {
-    return deriveDef(this, { name });
-  }
-
-  /**
-   * Return an updated window definition with the given partitions.
-   * @param {...ExprVarArgs} expr The partition by criteria.
-   * @returns {WindowDefNode} A new window definition node.
-   */
-  partitionby(...expr) {
-    return deriveDef(this, { partition: exprList(expr) });
-  }
-
-  /**
-   * Return an updated window definition with the given ordering.
-   * @param {...ExprVarArgs} expr The order by criteria.
-   * @returns {WindowDefNode} A new window definition node.
-   */
-  orderby(...expr) {
-    return deriveDef(this, { order: exprList(expr) });
-  }
-
-  /**
-   * Return an updated window definition with the given rows frame.
-   * @param {FrameExtent} extent The row-based window frame extent.
-   * @returns {WindowDefNode} A new window definition node.
-   */
-  rows(extent) {
-    return deriveDef(this, { frame: new WindowFrameNode(extent) });
-  }
-
-  /**
-   * Return an updated window definition with the given range frame.
-   * @param {FrameExtent} extent The range-based window frame extent.
-   * @returns {WindowDefNode} A new window definition node.
-   */
-  range(extent) {
-    return deriveDef(this, { frame: new WindowFrameNode(extent, true) });
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    const { name, partition, order, frame } = this;
-    const base = name && quoteIdentifier(name);
-    const def = [
-      base,
-      partition?.length && `PARTITION BY ${partition.join(', ')}`,
-      order?.length && `ORDER BY ${order.join(', ')}`,
-      frame
-    ].filter(x => x);
-    return base && def.length < 2 ? base : `(${def.join(' ')})`;
-  }
-}
-
-export class WindowFrameNode extends SQLNode {
-  /**
-   * Instantiate a window frame definition node.
-   * @param {FrameExtent} extent The frame extent as [preceding, following]
-   *  row or interval offsets.
-   * @param {boolean} [range] The frame type: `true` for range, otherwise rows.
-   * @param {ExprNode} [exclude] The window exclusion criteria.
-   */
-  constructor(extent, range = false, exclude = undefined) {
-    super(WINDOW_FRAME);
-    /**
-     * The frame extent as [preceding, following] row or interval offsets.
-     * @type {ParamNode | [any, any]}
-     * @readonly
-     */
-    this.extent = isParamLike(extent) ? new ParamNode(extent) : extent;
-    /**
-     * The frame type: `true` for range, otherwise rows.
-     * @type {boolean}
-     * @readonly
-     */
-    this.range = range;
-    /**
-     * The window exclusion criteria.
-     * @type {ExprNode}
-     * @readonly
-     */
-    this.exclude = exclude;
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    const { range, exclude, extent  } = this;
-    const type = range ? 'RANGE' : 'ROWS';
-    const [prev, next] = isNode(extent) ? extent.value : extent;
-    const a = frameValue(prev, 'PRECEDING');
-    const b = frameValue(next, 'FOLLOWING');
-    return `${type} BETWEEN ${a} AND ${b}${exclude ? ` ${exclude}` : ''}`;
-  }
-}
-
-/**
- * Derive a new window definition node from an existing one.
- * @param {WindowDefNode} def The existing window definition.
- * @param {object} options An options object with new definition properties.
- * @param {string} [options.name] The base window definition name.
- * @param {ExprNode[]} [options.partition] The partition by criteria.
- * @param {ExprNode[]} [options.order] The order by criteria.
- * @param {WindowFrameNode} [options.frame] The window frame definition.
- */
-function deriveDef(def, options) {
-  return new WindowDefNode(
-    options.name ?? def.name,
-    options.partition ?? def.partition,
-    options.order ?? def.order,
-    options.frame ?? def.frame
-  );
-}
-
-function frameValue(value, order) {
-  return value === 0 ? 'CURRENT ROW'
-    : Number.isFinite(value) ? `${Math.abs(value)} ${order}`
-    : `UNBOUNDED ${order}`;
-}

package/src/functions/aggregate.js

@@ -1,347 +0,0 @@
-/**
- * @import { AggregateNode } from '../ast/aggregate.js'
- * @import { ExprValue } from '../types.js'
- */
-import { aggFn } from '../util/function.js';
-
-/**
- * Compute an arg_max aggregate.
- * @param {ExprValue} y The argument to return.
- * @param {ExprValue} x The expression to maximize.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function argmax(y, x) {
-  return aggFn('arg_max', y, x);
-}
-
-/**
- * Compute an arg_min aggregate.
- * @param {ExprValue} y The argument to return.
- * @param {ExprValue} x The expression to minimize.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function argmin(y, x) {
-  return aggFn('arg_min', y, x);
-}
-
-/**
- * Compute an array aggregation.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function arrayAgg(expr) {
-  return aggFn('array_agg', expr);
-}
-
-/**
- * Compute an average aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function avg(expr) {
-  return aggFn('avg', expr);
-}
-
-/**
- * Compute a correlation aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function corr(x, y) {
-  return aggFn('corr', x, y);
-}
-
-/**
- * Compute a count aggregate.
- * @param {ExprValue} [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 {AggregateNode} A SQL aggregate function call.
- */
-export function count(expr) {
-  return aggFn('count', expr);
-}
-
-/**
- * Compute a sample covariance aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function covariance(x, y) {
-  return aggFn('covar_samp', x, y);
-}
-
-/**
- * Compute a population covariance aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function covarPop(x, y) {
-  return aggFn('covar_pop', x, y);
-}
-
-/**
- * Compute an entropy aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function entropy(expr) {
-  return aggFn('entropy', expr);
-}
-
-/**
- * Compute a first aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function first(expr) {
-  return aggFn('first', expr);
-}
-
-/**
- * Compute a geomean aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function geomean(expr) {
-  return aggFn('geomean', expr);
-}
-
-/**
- * Compute a sample kurtosis aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function kurtosis(expr) {
-  return aggFn('kurtosis', expr);
-}
-
-/**
- * Compute a median absolute deviation (MAD) aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function mad(expr) {
-  return aggFn('mad', expr);
-}
-
-/**
- * Compute a maximum aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function max(expr) {
-  return aggFn('max', expr);
-}
-
-/**
- * Compute a median aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function median(expr) {
-  return aggFn('median', expr);
-}
-
-/**
- * Compute a minimum aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function min(expr) {
-  return aggFn('min', expr);
-}
-
-/**
- * Compute a mode aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function mode(expr) {
-  return aggFn('mode', expr);
-}
-
-/**
- * Compute a last aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function last(expr) {
-  return aggFn('last', expr);
-}
-
-/**
- * Compute a product aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function product(expr) {
-  return aggFn('product', expr);
-}
-
-/**
- * Compute a quantile aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @param {ExprValue} p The quantile value.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function quantile(expr, p) {
-  return aggFn('quantile', expr, p);
-}
-
-/**
- * Compute a linear regression reg_avgX aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrAvgX(x, y) {
-  return aggFn('regr_avgx', x, y);
-}
-
-/**
- * Compute a linear regression reg_avgY aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrAvgY(x, y) {
-  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 {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrCount(x, y) {
-  return aggFn('regr_count', x, y);
-}
-
-/**
- * Compute a linear regression intercept aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrIntercept(x, y) {
-  return aggFn('regr_intercept', x, y);
-}
-
-/**
- * Compute a linear regression R^2 aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrR2(x, y) {
-  return aggFn('regr_r2', x, y);
-}
-
-/**
- * Compute a linear regression regr_sxx aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrSXX(x, y) {
-  return aggFn('regr_sxx', x, y);
-}
-
-/**
- * Compute a linear regression regr_sxy aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrSXY(x, y) {
-  return aggFn('regr_sxy', x, y);
-}
-
-/**
- * Compute a linear regression regr_syy aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrSYY(x, y) {
-  return aggFn('regr_syy', x, y);
-}
-
-/**
- * Compute a linear regression slope aggregate.
- * @param {ExprValue} x The x expression to aggregate.
- * @param {ExprValue} y The y expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function regrSlope(x, y) {
-  return aggFn('regr_slope', x, y);
-}
-
-/**
- * Compute a skewness aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function skewness(expr) {
-  return aggFn('skewness', expr);
-}
-
-/**
- * Compute a sample standard deviation aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function stddev(expr) {
-  return aggFn('stddev', expr);
-}
-
-/**
- * Compute a population standard deviation aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function stddevPop(expr) {
-  return aggFn('stddev_pop', expr);
-}
-
-/**
- * Compute a string aggregation.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function stringAgg(expr) {
-  return aggFn('string_agg', expr);
-}
-
-/**
- * Compute a sum aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function sum(expr) {
-  return aggFn('sum', expr);
-}
-
-/**
- * Compute a sample variance aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function variance(expr) {
-  return aggFn('var_samp', expr);
-}
-
-/**
- * Compute a population variance aggregate.
- * @param {ExprValue} expr The expression to aggregate.
- * @returns {AggregateNode} A SQL aggregate function call.
- */
-export function varPop(expr) {
-  return aggFn('var_pop', expr);
-}

package/src/functions/datetime.js

@@ -1,68 +0,0 @@
-/**
- * @import { FunctionNode } from '../ast/function.js'
- * @import { ExprValue } from '../types.js'
- */
-import { IntervalNode } from '../ast/interval.js';
-import { asNode } from '../util/ast.js';
-import { fn } from '../util/function.js';
-
-/**
- * Create a new interval.
- * @param {string} unit The interval unit, such as day or year.
- * @param {number} steps The number interval unit steps.
- * @returns {IntervalNode}
- */
-export function interval(unit, steps) {
-  return new IntervalNode(unit, steps);
-}
-
-/**
- * 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) {
-  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}
- */
-export function dateBin(expr, unit, steps = 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}
- */
-export function dateMonth(expr) {
-  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}
- */
-export function dateMonthDay(expr) {
-  const d = asNode(expr);
-  return fn('make_date', 2012, fn('month', d), fn('day', d));
-}
-
-/**
- * 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}
- */
-export function dateDay(expr) {
-  return fn('make_date', 2012, 1, fn('day', expr));
-}