@uwdata/mosaic-sql 0.11.0 → 0.12.1

package/dist/types/visit/recurse.d.ts

@@ -0,0 +1,28 @@
+export namespace recurse {
+    let AGGREGATE: string[];
+    let BETWEEN: string[];
+    let BINARY: string[];
+    let CASE: string[];
+    let CAST: string[];
+    let COLUMN_PARAM: string[];
+    let COLUMN_REF: string[];
+    let DESCRIBE_QUERY: string[];
+    let EXPRESSION: string[];
+    let FRAGMENT: string[];
+    let FROM_CLAUSE: string[];
+    let FUNCTION: string[];
+    let IN: string[];
+    let LOGICAL_OPERATOR: string[];
+    let NOT_BETWEEN: string[];
+    let ORDER_BY: string[];
+    let PARAM: string[];
+    let SELECT_CLAUSE: string[];
+    let SELECT_QUERY: string[];
+    let SET_OPERATION: string[];
+    let UNARY: string[];
+    let WHEN: string[];
+    let WINDOW: string[];
+    let WINDOW_CLAUSE: string[];
+    let WINDOW_DEF: string[];
+    let WINDOW_FRAME: string[];
+}

package/dist/types/visit/rewrite.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rewrite a SQL expression, based on a map of nodes to replace.
+ * This method updates the expression in place.
+ * @param {ExprNode} node The root AST node of the expression.
+ * @param {Map<ExprNode, ExprNode>} map The rewrite map.
+ *  When encountered, key nodes are replaced by value nodes.
+ * @returns {ExprNode}
+ */
+export function rewrite(node: ExprNode, map: Map<ExprNode, ExprNode>): ExprNode;
+import { ExprNode } from '../ast/node.js';

package/dist/types/visit/visitors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Indicate if the input AST contains an aggregate expression.
+ * The string content of verbatim nodes is analyzed to try to identify
+ * unparsed aggregate functions calls within SQL strings.
+ * @param {SQLNode} root The root of the AST to search.
+ * @returns {number} Return 0 if no aggregate functions are found.
+ *  Sets bit 1 if an AggregateFunction instance is found.
+ *  Sets bit 2 if an aggregate embedded in verbatim text is found.
+ */
+export function isAggregateExpression(root: SQLNode): number;
+/**
+ * Collect all aggregate function nodes.
+ * @param {SQLNode} root The root of the AST to search.
+ * @returns {AggregateNode[]}
+ */
+export function collectAggregates(root: SQLNode): AggregateNode[];
+/**
+ * Collect all unique column references.
+ * Multiple references to the same column are de-duplicated, even if
+ * they are not object-equal node instances.
+ * @param {SQLNode} root The root of the AST to search.
+ * @returns {ColumnRefNode[]}
+ */
+export function collectColumns(root: SQLNode): ColumnRefNode[];
+/**
+ * Collect all unique dynamic parameter instances.
+ * @param {SQLNode} root The root of the AST to search.
+ * @returns {import('../types.js').ParamLike[]}
+ */
+export function collectParams(root: SQLNode): import("../types.js").ParamLike[];
+import { SQLNode } from '../ast/node.js';
+import { AggregateNode } from '../ast/aggregate.js';
+import { ColumnRefNode } from '../ast/column-ref.js';

package/dist/types/visit/walk.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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}
+ */
+export function walk(node: import("../ast/node.js").SQLNode, visit: import("../types.js").VisitorCallback): import("../types.js").VisitorResult;

package/jsconfig.json

@@ -0,0 +1,11 @@
+{
+  "include": ["src/**/*"],
+  "compilerOptions": {
+    "checkJs": true,
+    "noEmit": true,
+    "noImplicitAny": false,
+    "module": "node16",
+    "skipLibCheck": true,
+    "types": []
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-sql",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "SQL query construction and analysis.",
   "keywords": [
     "sql",
@@ -14,16 +14,18 @@
   "module": "src/index.js",
   "jsdelivr": "dist/mosaic-sql.min.js",
   "unpkg": "dist/mosaic-sql.min.js",
+  "types": "dist/types/index-types.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/uwdata/mosaic.git"
   },
   "scripts": {
     "prebuild": "rimraf dist && mkdir dist",
-    "build": "node ../../esbuild.js mosaic-sql",
+    "build": "npm run types && node ../../esbuild.js mosaic-sql",
+    "types": "tsc",
     "lint": "eslint src test",
-    "test": "vitest run",
+    "test": "vitest run && tsc -p jsconfig.json",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
-  "gitHead": "861d616f39926a1d2aee83b59dbdd70b0b3caf12"
+  "gitHead": "fe3a7c34352da54ec36a1ebf557846f46a649782"
 }

package/src/ast/aggregate.js

@@ -0,0 +1,164 @@
+import { AGGREGATE } from '../constants.js';
+import { asVerbatim } from '../util/ast.js';
+import { isString } from '../util/type-check.js';
+import { ExprNode } from './node.js';
+import { WindowNode } from './window.js';
+
+export class AggregateNode extends ExprNode {
+  /**
+   * Instantiate an aggregate function node.
+   * @param {string} name The aggregate function name.
+   * @param {ExprNode[]} args The aggregate function arguments.
+   * @param {boolean} [distinct] The distinct flag.
+   * @param {ExprNode} [filter] Filter expression.
+   */
+  constructor(name, args, distinct, filter) {
+    super(AGGREGATE);
+    /**
+     * The aggregate function name.
+     * @type {string}
+     * @readonly
+     */
+    this.name = name;
+    /**
+     * The aggregate function arguments.
+     * @type {ExprNode[]}
+     * @readonly
+     */
+    this.args = args;
+    /**
+     * The distinct flag.
+     * @type {boolean}
+     * @readonly
+     */
+    this.isDistinct = distinct;
+    /**
+     * Filter criteria.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.filter = filter;
+  }
+
+  /**
+   * Return a new derived aggregate over distinct values.
+   * @param {boolean} [isDistinct=true] The distinct flag.
+   * @returns {AggregateNode} A new aggregate node.
+   */
+  distinct(isDistinct = true) {
+    return new AggregateNode(this.name, this.args, isDistinct, this.filter);
+  }
+
+  /**
+   * Return a new derived aggregate function that filters values.
+   * @param {ExprNode | string} filter The filter expression.
+   * @returns {AggregateNode} A new aggregate node.
+   */
+  where(filter) {
+    if (isString(filter)) filter = asVerbatim(filter);
+    return new AggregateNode(this.name, this.args, this.isDistinct, filter);
+  }
+
+  /**
+   * Return a new window function over this aggregate.
+   * @returns {WindowNode} A new window node.
+   */
+  window() {
+    return new WindowNode(this);
+  }
+
+  /**
+   * Return a new window function over this aggregate with the given partitions.
+   * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+   * @returns {WindowNode} A new window node.
+   */
+  partitionby(...expr) {
+    return this.window().partitionby(...expr);
+  }
+
+  /**
+   * Return a new window function over this aggregate with the given ordering.
+   * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+   * @returns {WindowNode} A new window node.
+   */
+  orderby(...expr) {
+    return this.window().orderby(...expr);
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    const { name, args, isDistinct, filter } = this;
+    const dist = isDistinct ? 'DISTINCT ' : '';
+    const arg = args?.length ? args.join(', ') : '*';
+    const filt = filter ? ` FILTER (WHERE ${filter})` : '';
+    return `${name}(${dist}${arg})${filt}`;
+  }
+}
+
+/**
+ * An array of known aggregate function names.
+ * From https://duckdb.org/docs/sql/functions/aggregates.html.
+ */
+export const aggregateNames = [
+  'any_value',
+  'approx_count_distinct',
+  'approx_quantile',
+  'arbitrary',
+  'arg_max',
+  'arg_max_null',
+  'arg_min',
+  'arg_min_null',
+  'array_agg',
+  'avg',
+  'bit_and',
+  'bit_or',
+  'bit_xor',
+  'bitstring_agg',
+  'bool_and',
+  'bool_or',
+  'corr',
+  'count',
+  'covar_pop',
+  'covar_samp',
+  'entropy',
+  'favg',
+  'first',
+  'fsum',
+  'geomean',
+  'kurtosis_pop',
+  'kurtosis',
+  'last',
+  'mad',
+  'max',
+  'max_by',
+  'median',
+  'min',
+  'min_by',
+  'mode',
+  'product',
+  'quantile',
+  'quantile_cont',
+  'quantile_disc',
+  'regr_avgx',
+  'regr_avgy',
+  'regr_count',
+  'regr_intercept',
+  'regr_r2',
+  'regr_sxx',
+  'regr_sxy',
+  'regr_syy',
+  'regr_slope',
+  'reservoir_quantile',
+  'skewness',
+  'stddev',
+  'stddev_pop',
+  'stddev_samp',
+  'string_agg',
+  'sum',
+  'variance',
+  'var_pop',
+  'var_samp'
+];

package/src/ast/between-op.js

@@ -0,0 +1,75 @@
+import { BETWEEN_OPERATOR, NOT_BETWEEN_OPERATOR } from '../constants.js';
+import { ExprNode } from './node.js';
+
+class AbstractBetweenOpNode extends ExprNode {
+  /**
+   * Instantiate an abstract between operator node.
+   * @param {string} type The node type.
+   * @param {ExprNode} expr The input expression.
+   * @param {[ExprNode, ExprNode]} extent The range extent.
+   */
+  constructor(type, expr, extent) {
+    super(type);
+    /**
+     * The input expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.expr = expr;
+    /**
+     * The range extent.
+     * @type {[ExprNode, ExprNode]}
+     * @readonly
+     */
+    this.extent = extent;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toSQL(op) {
+    const { extent: r, expr } = this;
+    return r ? `(${expr} ${op} ${r[0]} AND ${r[1]})` : '';
+  }
+}
+
+export class BetweenOpNode extends AbstractBetweenOpNode {
+  /**
+   * Instantiate a between operator node.
+   * @param {ExprNode} expr The input expression.
+   * @param {[ExprNode, ExprNode]} extent
+   *  The range extent.
+   */
+  constructor(expr, extent) {
+    super(BETWEEN_OPERATOR, expr, extent);
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return super.toSQL('BETWEEN');
+  }
+}
+
+export class NotBetweenOpNode extends AbstractBetweenOpNode {
+  /**
+   * Instantiate a not between operator node.
+   * @param {ExprNode} expr The input expression.
+   * @param {[ExprNode, ExprNode]} extent
+   *  The range extent.
+   */
+  constructor(expr, extent) {
+    super(NOT_BETWEEN_OPERATOR, expr, extent);
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return super.toSQL('NOT BETWEEN');
+  }
+}

package/src/ast/binary-op.js

@@ -0,0 +1,40 @@
+import { BINARY_OPERATOR } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class BinaryOpNode extends ExprNode {
+  /**
+   * Instantiate a binary operator node.
+   * @param {string} op The operator type.
+   * @param {ExprNode} left The left input expression.
+   * @param {ExprNode} right The right input expression.
+   */
+  constructor(op, left, right) {
+    super(BINARY_OPERATOR);
+    /**
+     * The operator type.
+     * @type {string}
+     * @readonly
+     */
+    this.op = op;
+    /**
+     * The left input expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.left = left;
+    /**
+     * The right input expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.right = right;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return `(${this.left} ${this.op} ${this.right})`;
+  }
+}

package/src/ast/case.js

@@ -0,0 +1,105 @@
+import { CASE, WHEN } from '../constants.js';
+import { asNode } from '../util/ast.js';
+import { ExprNode, SQLNode } from './node.js';
+
+export class CaseNode extends ExprNode {
+  /**
+   * Instantiate a case node.
+   * @param {ExprNode} [expr] An optional base expression, that comes
+   *  immediately after the CASE keyword. If specified, this case statement
+   *  acts like a switch statement, with WHEN expressions as values to
+   *  match against the switch value rather than boolean conditions.
+   * @param {WhenNode[]} [when] An array of WHEN/THEN expression nodes.
+   * @param {ExprNode} [elseExpr] An ELSE expression.
+   */
+  constructor(expr = undefined, when = [], elseExpr = undefined) {
+    super(CASE);
+    /**
+     * The optional base expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.expr = expr;
+    /**
+     * An array of WHEN/THEN expression nodes.
+     * @type {WhenNode[]}
+     * @readonly
+     */
+    this._when = when;
+    /**
+     * An ELSE expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this._else = elseExpr;
+  }
+
+  /**
+   * Return a new case node with the given conditional added as
+   * the last WHEN / THEN pair.
+   * @param {import('../types.js').ExprValue} cond
+   *  The WHEN condition expression.
+   * @param {import('../types.js').ExprValue} value
+   *  The THEN value expression.
+   * @returns {CaseNode}
+   */
+  when(cond, value) {
+    return new CaseNode(
+      this.expr,
+      this._when.concat(new WhenNode(asNode(cond), asNode(value))),
+      this._else
+    );
+  }
+
+  /**
+   * Return a new case node with the given ELSE expression.
+   * @param {import('../types.js').ExprValue} expr The ELSE expression.
+   * @returns {CaseNode}
+   */
+  else(expr) {
+    return new CaseNode(this.expr, this._when, asNode(expr));
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return 'CASE '
+      + (this.expr ? `${this.expr} ` : '')
+      + this._when.join(' ')
+      + (this._else ? ` ELSE ${this._else}` : '')
+      + ' END';
+  }
+}
+
+export class WhenNode extends SQLNode {
+  /**
+   * Instantiate a case node.
+   * @param {ExprNode} when The WHEN condition expression.
+   * @param {ExprNode} then The THEN value expression.
+   */
+  constructor(when, then) {
+    super(WHEN);
+    /**
+     * The condition expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.when = when;
+    /**
+     * The value expression.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.then = then;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return `WHEN ${this.when} THEN ${this.then}`;
+  }
+}

package/src/ast/cast.js

@@ -0,0 +1,34 @@
+import { CAST } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class CastNode extends ExprNode {
+  /**
+   * Instantiate a cast node.
+   * @param {ExprNode} expr The expression to type cast.
+   * @param {string} type The type to cast to.
+   */
+  constructor(expr, type) {
+    super(CAST);
+    /**
+     * The expression to type cast.
+     * @type {ExprNode}
+     * @readonly
+     */
+    this.expr = expr;
+    /**
+     * The type to cast to.
+     * @type {string}
+     * @readonly
+     */
+    this.cast = type;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    // TODO? could include check to see if parens are necessary
+    return `(${this.expr})::${this.cast}`;
+  }
+}

package/src/ast/column-param.js

@@ -0,0 +1,29 @@
+import { COLUMN_PARAM } from '../constants.js';
+import { ColumnRefNode } from './column-ref.js';
+
+export class ColumnParamNode extends ColumnRefNode {
+  /**
+   * Instantiate a column param node.
+   * @param {import('./param.js').ParamNode} param The column name as a
+   *  parameter node.
+   * @param {import('./table-ref.js').TableRefNode} [table] The table
+   *  reference.
+   */
+  constructor(param, table) {
+    super(COLUMN_PARAM, table);
+    /**
+     * The column name as a parameter node.
+     * @type {import('./param.js').ParamNode}
+     * @readonly
+     */
+    this.param = param;
+  }
+
+  /**
+   * Returns the column name.
+   * @returns {string}
+   */
+  get column() {
+    return `${this.param.value}`;
+  }
+}

package/src/ast/column-ref.js

@@ -0,0 +1,72 @@
+import { COLUMN_REF } from '../constants.js';
+import { quoteIdentifier } from '../util/string.js';
+import { ExprNode } from './node.js';
+
+/**
+ * Check if a value is a column reference node.
+ * @param {*} value The value to check.
+ * @returns {value is ColumnRefNode}
+ */
+export function isColumnRef(value) {
+  return value instanceof ColumnRefNode;
+}
+
+export class ColumnRefNode extends ExprNode {
+  /**
+   * Instantiate a column reference node.
+   * @param {import('./table-ref.js').TableRefNode} [table] The table reference.
+   */
+  constructor(type, table) {
+    super(type);
+    /**
+     * The table reference.
+     * @type {import('./table-ref.js').TableRefNode}
+     * @readonly
+     */
+    this.table = table;
+  }
+
+  /**
+   * Returns the column name.
+   * @returns {string}
+   */
+  get column() {
+    return null; // subclasses to override
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    const { column, table } = this;
+    const tref = `${table ?? ''}`;
+    const id = column === '*' ? '*' : quoteIdentifier(column);
+    return (tref ? (tref + '.') : '') + id;
+  }
+}
+
+export class ColumnNameRefNode extends ColumnRefNode {
+  /**
+   * Instantiate a column reference node.
+   * @param {string} name The column name.
+   * @param {import('./table-ref.js').TableRefNode} [table] The table reference.
+   */
+  constructor(name, table) {
+    super(COLUMN_REF, table);
+    /**
+     * The column name.
+     * @type {string}
+     * @readonly
+     */
+    this.name = name;
+  }
+
+  /**
+   * Returns the column name.
+   * @returns {string}
+   */
+  get column() {
+    return this.name;
+  }
+}

package/src/ast/fragment.js

@@ -0,0 +1,26 @@
+import { FRAGMENT } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class FragmentNode extends ExprNode {
+  /**
+   * Instantiate a fragment node with arbitrary content.
+   * @param {ExprNode[]} spans The consecutive parts making up the fragment.
+   */
+  constructor(spans) {
+    super(FRAGMENT);
+    /**
+     * The consecutive parts making up the fragment.
+     * @type {ExprNode[]}
+     * @readonly
+     */
+    this.spans = spans;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   * @returns {string}
+   */
+  toString() {
+    return this.spans.join('');
+  }
+}