@uwdata/mosaic-sql 0.11.0 → 0.12.1

package/src/{scales.js → transforms/scales.js}

@@ -1,6 +1,9 @@
-import { epoch_ms } from './datetime.js';
-import { sql } from './expression.js';
-import { asColumn } from './ref.js';
+import { LiteralNode } from '../ast/literal.js';
+import { epoch_ms } from '../functions/datetime.js';
+import { literal } from '../functions/literal.js';
+import { abs, exp, ln, log, sign, sqrt } from '../functions/numeric.js';
+import { add, div, mul, pow, sub } from '../functions/operators.js';
+import { asNode } from '../util/ast.js';
 
 const identity = x => x;
 
@@ -8,7 +11,7 @@ function scaleLinear() {
   return {
     apply: identity,
     invert: identity,
-    sqlApply: asColumn,
+    sqlApply: asNode,
     sqlInvert: identity
   };
 }
@@ -18,23 +21,23 @@ function scaleLog({ base = null } = {}) {
     return {
       apply: Math.log,
       invert: Math.exp,
-      sqlApply: c => sql`LN(${asColumn(c)})`,
-      sqlInvert: c => sql`EXP(${c})`
+      sqlApply: c => ln(c),
+      sqlInvert: c => exp(c)
     };
   } else if (base === 10) {
     return {
       apply: Math.log10,
       invert: x => Math.pow(10, x),
-      sqlApply: c => sql`LOG(${asColumn(c)})`,
-      sqlInvert: c => sql`POW(10, ${c})`
+      sqlApply: c => log(c),
+      sqlInvert: c => pow(10, c)
     };
   } else {
     const b = +base;
     return {
       apply: x => Math.log(x) / Math.log(b),
       invert: x => Math.pow(b, x),
-      sqlApply: c => sql`LN(${asColumn(c)}) / LN(${b})`,
-      sqlInvert: c => sql`POW(${b}, ${c})`
+      sqlApply: c => div(ln(c), ln(b)),
+      sqlInvert: c => pow(b, c)
     };
   }
 }
@@ -44,8 +47,8 @@ function scaleSymlog({ constant = 1 } = {}) {
   return {
     apply: x => Math.sign(x) * Math.log1p(Math.abs(x)),
     invert: x => Math.sign(x) * Math.exp(Math.abs(x) - _),
-    sqlApply: c => (c = asColumn(c), sql`SIGN(${c}) * LN(${_} + ABS(${c}))`),
-    sqlInvert: c => sql`SIGN(${c}) * (EXP(ABS(${c})) - ${_})`
+    sqlApply: c => (c = asNode(c), mul(sign(c), ln(add(_, abs(c))))),
+    sqlInvert: c => mul(sign(c), sub(exp(abs(c)), _))
   };
 }
 
@@ -53,8 +56,8 @@ function scaleSqrt() {
   return {
     apply: x => Math.sign(x) * Math.sqrt(Math.abs(x)),
     invert: x => Math.sign(x) * x * x,
-    sqlApply: c => (c = asColumn(c), sql`SIGN(${c}) * SQRT(ABS(${c}))`),
-    sqlInvert: c => sql`SIGN(${c}) * (${c}) ** 2`
+    sqlApply: c => (c = asNode(c), mul(sign(c), sqrt(abs(c)))),
+    sqlInvert: c => mul(sign(c), pow(c, 2))
   };
 }
 
@@ -63,8 +66,8 @@ function scalePow({ exponent = 1 } = {}) {
   return {
     apply: x => Math.sign(x) * Math.pow(Math.abs(x), e),
     invert: x => Math.sign(x) * Math.pow(Math.abs(x), 1/e),
-    sqlApply: c => (c = asColumn(c), sql`SIGN(${c}) * POW(ABS(${c}), ${e})`),
-    sqlInvert: c => sql`SIGN(${c}) * POW(ABS(${c}), 1/${e})`
+    sqlApply: c => (c = asNode(c), mul(sign(c), pow(abs(c), e))),
+    sqlInvert: c => mul(sign(c), pow(abs(c), div(1, e)))
   };
 }
 
@@ -72,7 +75,9 @@ function scaleTime() {
   return {
     apply: x => +x,
     invert: x => new Date(x),
-    sqlApply: c => c instanceof Date ? +c : epoch_ms(asColumn(c)),
+    sqlApply: c => c instanceof Date ? literal(+c)
+      : isDateLiteral(c) ? literal(+c.value)
+      : epoch_ms(c),
     sqlInvert: identity
   };
 }
@@ -92,3 +97,12 @@ export function scaleTransform(options) {
   const scale = scales[options.type];
   return scale ? { ...options, ...scale(options) } : null;
 }
+
+/**
+ * Check if a value is a date-valued literal SQL AST node.
+ * @param {*} x The value to test.
+ * @returns {x is LiteralNode}
+ */
+function isDateLiteral(x) {
+  return x instanceof LiteralNode && x.value instanceof Date;
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+import { ColumnRefNode } from './ast/column-ref.js';
+import { ExprNode, SQLNode } from './ast/node.js';
+import { TableRefNode } from './ast/table-ref.js';
+import { Query } from './ast/query.js';
+
+/**
+ * Interface representing a dynamic parameter value.
+ */
+export interface ParamLike {
+  /** The current parameter value. */
+  value: any;
+  /** Add an event listener callback. */
+  addEventListener(type: string, callback: EventCallback): void;
+  /** Remove an event listener callback. */
+  removeEventListener(type: string, callback: EventCallback): void;
+}
+
+/**
+ * Expression value input to SQL builder method.
+ */
+export type ExprValue = ExprNode | ParamLike | string | number | boolean | Date;
+
+/**
+ * Expression values that may be nested in arrays.
+ */
+export type ExprVarArgs = MaybeArray<ExprValue>;
+
+/**
+ * String-typed expression value.
+ */
+export type StringValue = ExprNode | ParamLike | string;
+
+/**
+ * Number-typed expression value.
+ */
+export type NumberValue = ExprNode | ParamLike | number;
+
+/**
+ * Event listener callback function.
+ */
+export type EventCallback = <T>(value: any) => Promise<T> | undefined;
+
+/**
+ * SQL AST traversal visitor callback result.
+ * A falsy value (including `undefined`, `null`, `false`, and `0`) indicates
+ * that traversal should continue.
+ * A negative number values indicates that traversal should stop immediately.
+ * Any other truthy value indicates that traversal should not recurse on the
+ * current node, but should otherwise continue.
+ */
+export type VisitorResult = boolean | number | null | undefined | void;
+
+/**
+ * SQL AST traversal callback function.
+ */
+export type VisitorCallback = (node: SQLNode) => VisitorResult;
+
+/** Valid window function names. */
+export type WindowFunctionName =
+  | 'cume_dist'
+  | 'dense_rank'
+  | 'first_value'
+  | 'lag'
+  | 'last_value'
+  | 'lead'
+  | 'nth_value'
+  | 'ntile'
+  | 'percent_rank'
+  | 'rank_dense'
+  | 'rank'
+  | 'row_number';
+
+export type MaybeArray<T> = T | T[];
+
+export type SelectEntry =
+  | string
+  | ColumnRefNode
+  | [string, ExprNode]
+  | Record<string, ExprValue>;
+
+export type SelectExpr = MaybeArray<SelectEntry>;
+
+export type WithExpr = MaybeArray<Record<string, Query>>;
+
+export type FromEntry =
+  | string
+  | TableRefNode
+  | SQLNode
+  | [string, SQLNode]
+  | Record<string, string | SQLNode>;
+
+export type FromExpr = MaybeArray<FromEntry>;
+
+export type FilterExpr = MaybeArray<string | ExprNode>;
+export type GroupByExpr = MaybeArray<string | ExprNode>;
+export type OrderByExpr = MaybeArray<string | ExprNode>;

package/src/util/ast.js

@@ -0,0 +1,96 @@
+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';
+import { tableRef } from '../functions/table-ref.js';
+import { parseIdentifier } from './string.js';
+import { isArray, isParamLike, isString } from './type-check.js';
+
+/**
+ * Interpret a value as a SQL AST node. String values are assumed to be
+ * column references. All other primitive values are interpreted as
+ * SQL literals. Dynamic parameters are interpreted as param AST nodes,
+ * while existing AST nodes are left as-is.
+ * @param {*} value The value to interpret as a SQL AST node.
+ * @returns {ExprNode}
+ */
+export function asNode(value) {
+  return isString(value)
+    ? parseColumnRef(value)
+    : asLiteral(value);
+}
+
+/**
+ * Interpret a value as a verbatim SQL AST node. String values will be
+ * passed through to queries as verbatim text. All other primitive values
+ * are interpreted as SQL literals. Dynamic parameters are interpreted
+ * as param AST nodes, while existing AST nodes are left as-is.
+ * @param {*} value The value to interpret as a verbatim AST node.
+ * @returns {ExprNode}
+ */
+export function asVerbatim(value) {
+  return isString(value)
+    ? verbatim(value)
+    : asLiteral(value);
+}
+
+/**
+ * Interpret a value as a literal AST node. All other primitive values
+ * are interpreted as SQL literals. Dynamic parameters are interpreted
+ * as param AST nodes, while existing AST nodes are left as-is.
+ * @param {*} value The value to interpret as a literal AST node.
+ * @returns {ExprNode}
+ */
+export function asLiteral(value) {
+  return value instanceof ExprNode ? value
+    : isParamLike(value) ? new ParamNode(value)
+    : literal(value);
+}
+
+/**
+ * Interpret a value as a table reference AST node. String values are parsed
+ * assuming dot ('.') delimiters (as in `schema.table`). Array values are
+ * interpreted as pre-parsed name paths (as in `['schema', 'table']`). Any
+ * other values are left as-is.
+ * @param {string | string[] | TableRefNode} value The value to interpret as a
+ *  table reference AST node.
+ * @returns {TableRefNode}
+ */
+export function asTableRef(value) {
+  return isString(value) ? parseTableRef(value)
+    : isArray(value) ? tableRef(value)
+    : 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}
+ */
+export function parseColumnRef(ref) {
+  const ids = parseIdentifier(ref);
+  return column(ids.pop(), tableRef(ids));
+}
+
+/**
+ * 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}
+ */
+export function parseTableRef(ref) {
+  return tableRef(parseIdentifier(ref));
+}
+
+/**
+ * Create a new window definition node. The return value is an empty
+ * window definition. Use chained calls such as `partitionby` and `orderby`
+ * to specify the window settings.
+ * @returns {WindowDefNode}
+ */
+export function over() {
+  return new WindowDefNode();
+}

package/src/util/function.js

@@ -0,0 +1,78 @@
+import { AggregateNode } from '../ast/aggregate.js';
+import { FunctionNode } from '../ast/function.js';
+import { WindowFunctionNode, WindowNode } from '../ast/window.js';
+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 {string} name The function name.
+ * @returns {node is FunctionNode}
+ */
+export function isFunctionCall(node, name) {
+  return node instanceof FunctionNode && node.name === name;
+}
+
+/**
+ * Create a new function call AST node.
+ * @param {string} name The function name.
+ * @param  {...any} args The function arguments.
+ * @returns {FunctionNode}
+ */
+export function fn(name, ...args) {
+  return new FunctionNode(name, argsList(args).map(asNode));
+}
+
+/**
+ * Create a new aggregate function AST node.
+ * @param {string} name The function name.
+ * @param  {...any} args The function arguments.
+ * @returns {AggregateNode}
+ */
+export function aggFn(name, ...args) {
+  return new AggregateNode(name, argsList(args).map(asNode));
+}
+
+/**
+ * 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  {...any} args The function arguments.
+ * @returns {WindowNode}
+ */
+export function winFn(name, ...args) {
+  return new WindowNode(
+    new WindowFunctionNode(name, argsList(args).map(asNode))
+  );
+}
+
+/**
+ * Process a list of expression inputs. Nested arrays are flattened,
+ * null results are removed, and each input is cast (as needed) to
+ * be a proper SQL AST node. By default, strings are assumed to be
+ * column names, while other primitive values map to SQL literals.
+ * Use an alternative *cast* function to change this behavior.
+ * @param {any[]} list The list of expression inputs.
+ * @param {function} [cast] A function that casts an input value
+ *  to a desired type. By default, `asNode` is used to coerce
+ *  inputs to AST nodes as needed.
+ * @returns {ReturnType<cast>[]}
+ */
+export function exprList(list, cast = asNode) {
+  return list.flat().filter(x => x != null).map(x => cast(x));
+}
+
+/**
+ * Process a list of function arguments, stripping any undefined
+ * values from the end of the list.
+ * @template T
+ * @param {T[]} list The input function arguments.
+ * @returns {T[]} The prepared argument list.
+ */
+export function argsList(list) {
+  const n = list.length;
+  let i = n;
+  for (; i > 0 && list[i - 1] === undefined; --i);
+  return i < n ? list.slice(0, i) : list;
+}

package/src/util/string.js

@@ -0,0 +1,16 @@
+// TODO: handle case where identifiers are already quoted?
+export function parseIdentifier(id) {
+  return id.split('.');
+}
+
+export function quoteIdentifier(value) {
+  return `"${value}"`;
+}
+
+export function unquote(s) {
+  return s && isDoubleQuoted(s) ? s.slice(1, -1) : s;
+}
+
+function isDoubleQuoted(s) {
+  return s[0] === '"' && s[s.length-1] === '"';
+}

package/src/util/type-check.js

@@ -0,0 +1,29 @@
+/**
+ * Check if a value is a string.
+ * @param {*} value The value to check.
+ * @returns {value is string}
+ */
+export function isString(value) {
+  return typeof value === 'string';
+}
+
+/**
+ * Check if a value is an array.
+ * @param {*} value The value to check.
+ * @returns {value is Array}
+ */
+export function isArray(value) {
+  return Array.isArray(value);
+}
+
+/**
+ * Check if a value is a dynamic parameter.
+ * @param {*} value The value to check.
+ * @returns {value is import('../types.js').ParamLike}
+ */
+export function isParamLike(value) {
+  return value
+    && typeof value.addEventListener === 'function'
+    && value.dynamic !== false
+    && 'value' in value;
+}

package/src/visit/recurse.js

@@ -0,0 +1,57 @@
+import {
+  AGGREGATE,
+  BETWEEN_OPERATOR,
+  BINARY_OPERATOR,
+  CASE,
+  CAST,
+  COLUMN_PARAM,
+  COLUMN_REF,
+  DESCRIBE_QUERY,
+  EXPRESSION,
+  FRAGMENT,
+  FROM_CLAUSE,
+  FUNCTION,
+  IN_OPERATOR,
+  LOGICAL_OPERATOR,
+  NOT_BETWEEN_OPERATOR,
+  ORDER_BY,
+  PARAM,
+  SELECT_CLAUSE,
+  SELECT_QUERY,
+  SET_OPERATION,
+  UNARY_OPERATOR,
+  WHEN,
+  WINDOW,
+  WINDOW_CLAUSE,
+  WINDOW_DEF,
+  WINDOW_FRAME
+} from '../constants.js';
+
+export const recurse = {
+  [AGGREGATE]: ['args', 'filter'],
+  [BETWEEN_OPERATOR]: ['expr', 'extent'],
+  [BINARY_OPERATOR]: ['left', 'right'],
+  [CASE]: ['expr', '_when', '_else'],
+  [CAST]: ['expr'],
+  [COLUMN_PARAM]: ['param', 'table'],
+  [COLUMN_REF]: ['table'],
+  [DESCRIBE_QUERY]: ['query'],
+  [EXPRESSION]: ['node'],
+  [FRAGMENT]: ['spans'],
+  [FROM_CLAUSE]: ['expr'],
+  [FUNCTION]: ['args'],
+  [IN_OPERATOR]: ['expr', 'values'],
+  [LOGICAL_OPERATOR]: ['clauses'],
+  [NOT_BETWEEN_OPERATOR]: ['expr', 'extent'],
+  [ORDER_BY]: ['expr'],
+  [PARAM]: ['value'],
+  [SELECT_CLAUSE]: ['expr'],
+  [SELECT_QUERY]: ['_with', '_select', '_from', '_where', '_sample', '_groupby', '_having', '_window', '_qualify', '_orderby'],
+  [SET_OPERATION]: ['subqueries', '_orderby'],
+  [UNARY_OPERATOR]: ['expr'],
+  [WHEN]: ['when', 'then'],
+  [WINDOW]: ['func', 'def'],
+  [WINDOW_CLAUSE]: ['def'],
+  [WINDOW_DEF]: ['partition', 'order', 'frame'],
+  [WINDOW_FRAME]: ['extent']
+};

package/src/visit/rewrite.js

@@ -0,0 +1,32 @@
+import { ExprNode, isNode } from '../ast/node.js';
+import { recurse } from './recurse.js';
+
+/**
+ * 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, map) {
+  if (map.has(node)) {
+    return map.get(node);
+  } else if (isNode(node)) {
+    const props = recurse[node.type];
+    const n = props?.length ?? 0;
+    for (let i = 0; i < n; ++i) {
+      const prop = props[i];
+      const child = node[prop];
+      if (Array.isArray(child)) {
+        const m = child.length;
+        for (let j = 0; j < m; ++j) {
+          child[j] = rewrite(child[j], map);
+        }
+      } else if (child) {
+        node[prop] = rewrite(child, map);
+      }
+    }
+  }
+  return node;
+}

package/src/visit/visitors.js

@@ -0,0 +1,108 @@
+import { AGGREGATE, COLUMN_REF, FRAGMENT, PARAM, VERBATIM, WINDOW } from '../constants.js';
+import { aggregateNames, AggregateNode } from '../ast/aggregate.js';
+import { ColumnRefNode } from '../ast/column-ref.js';
+import { SQLNode } from '../ast/node.js';
+import { walk } from './walk.js';
+
+// regexp to match valid aggregate function names
+const aggrRegExp = new RegExp(`^(${aggregateNames.join('|')})$`);
+
+// regexp to tokenize sql text in order to find function calls
+// includes checks to avoid analyzing text within quoted strings
+// function call tokens will have a pattern like "name(".
+const funcRegExp = /(\\'|\\"|"(?:\\"|[^"])*"|'(?:\\'|[^'])*'|\w+\()/g;
+
+function hasVerbatimAggregate(s) {
+  return s
+    .split(funcRegExp)
+    .some(tok => tok.endsWith('(') && aggrRegExp.test(tok.slice(0, -1)));
+}
+
+/**
+ * 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) {
+  let agg = 0;
+  walk(root, (node) => {
+    switch (node.type) {
+      case WINDOW:
+        return -1; // aggs can't include windows
+      case AGGREGATE:
+        agg |= 1;
+        return -1;
+      case FRAGMENT:
+      case VERBATIM: {
+        let s = `${node}`.toLowerCase();
+
+        // strip away scalar subquery content
+        const sub = s.indexOf('(select ');
+        if (sub >= 0) s = s.slice(0, sub);
+
+        // exit if expression includes windowing
+        if (s.includes(') over ')) return -1;
+        if (hasVerbatimAggregate(s)) {
+          agg |= 2;
+          return -1;
+        }
+        return 1; // don't recurse
+      }
+    }
+  });
+  return agg;
+}
+
+/**
+ * Collect all aggregate function nodes.
+ * @param {SQLNode} root The root of the AST to search.
+ * @returns {AggregateNode[]}
+ */
+export function collectAggregates(root) {
+  const aggs = new Set();
+  walk(root, (node) => {
+    if (node.type === AGGREGATE) {
+      aggs.add(node);
+    }
+  });
+  return Array.from(aggs);
+}
+
+/**
+ * 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) {
+  const cols = {};
+  walk(root, (node) => {
+    if (node.type === COLUMN_REF) {
+      cols[node] = node; // key on string-coerced node
+    }
+  });
+  return Object.values(cols);
+}
+
+/**
+ * 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) {
+  const params = new Set;
+  walk(root, (node) => {
+    if (node.type === PARAM) {
+      params.add(
+        /** @type {import('../ast/param.js').ParamNode} */
+        (node).param
+      );
+    }
+  });
+  return Array.from(params);
+}

package/src/visit/walk.js

@@ -0,0 +1,30 @@
+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}
+ */
+export function walk(node, visit) {
+  if (!isNode(node)) return;
+  const result = visit(node);
+  if (result) return result;
+
+  const props = recurse[node.type];
+  const n = props?.length ?? 0;
+  for (let i = 0; i < n; ++i) {
+    const value = node[props[i]];
+    if (Array.isArray(value)) {
+      const m = value.length;
+      for (let j = 0; j < m; ++j) {
+        if (value[j] && +walk(value[j], visit) < 0) {
+          return result;
+        }
+      }
+    } else if (value && +walk(value, visit) < 0) {
+      return -1;
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "include": ["src/index-types.ts"],
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist/types",
+    "module": "node16",
+    "skipLibCheck": true,
+    "types": []
+  }
+}