@uwdata/mosaic-sql 0.16.2 → 0.18.0

package/src/util/ast.ts

@@ -0,0 +1,104 @@
+import type { ColumnRefNode } from '../ast/column-ref.js';
+import type { TableRefNode } from '../ast/table-ref.js';
+import { ExprNode, type SQLNode } from '../ast/node.js';
+import { ParamNode } from '../ast/param.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.
+ */
+export function asNode(value: unknown): ExprNode {
+  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.
+ */
+export function asVerbatim(value: unknown): ExprNode {
+  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.
+ */
+export function asLiteral(value: unknown): ExprNode {
+  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 value The value to interpret as a table reference AST node.
+ */
+export function asTableRef(value?: string | string[] | TableRefNode): TableRefNode | undefined {
+  return getTableRef(value);
+}
+
+/**
+ * Try to 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 value The value to interpret as a table reference.
+ */
+export function maybeTableRef(value: string | string[] | SQLNode): SQLNode {
+  return getTableRef(value)!;
+}
+
+function getTableRef<T>(value?: string | string[] | T): TableRefNode | T | undefined {
+  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 ref The column reference string.
+ */
+export function parseColumnRef(ref: string): ColumnRefNode {
+  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 ref The table reference string.
+ */
+export function parseTableRef(ref: string): TableRefNode {
+  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.
+ */
+export function over() {
+  return new WindowDefNode();
+}

package/src/util/{function.js → function.ts}

@@ -1,7 +1,5 @@
-/**
- * @import { SQLNode } from '../ast/node.js'
- * @import { WindowFunctionName } from '../types.js'
- */
+import type { ExprNode, SQLNode } from '../ast/node.js';
+import type { WindowFunctionName } from '../types.js';
 import { AggregateNode } from '../ast/aggregate.js';
 import { FunctionNode } from '../ast/function.js';
 import { WindowFunctionNode, WindowNode } from '../ast/window.js';
@@ -9,31 +7,31 @@ import { asNode } from './ast.js';
 
 /**
  * Test if an AST node is a specific function call.
- * @param {SQLNode} node The SQL AST node to test.
- * @param {string} name The function name.
- * @returns {node is FunctionNode}
+ * @param node The SQL AST node to test.
+ * @param name The function name.
  */
-export function isFunctionCall(node, name) {
+export function isFunctionCall(
+  node: SQLNode,
+  name: string
+): node is FunctionNode {
   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}
+ * @param name The function name.
+ * @param args The function arguments.
  */
-export function fn(name, ...args) {
+export function fn(name: string, ...args: unknown[]): FunctionNode {
   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}
+ * @param name The function name.
+ * @param args The function arguments.
  */
-export function aggFn(name, ...args) {
+export function aggFn(name: string, ...args: unknown[]): AggregateNode {
   return new AggregateNode(name, argsList(args).map(asNode));
 }
 
@@ -41,40 +39,51 @@ export function aggFn(name, ...args) {
  * 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 {WindowFunctionName} name The function name.
- * @param  {...any} args The function arguments.
- * @returns {WindowNode}
+ * @param name The function name.
+ * @param args The function arguments.
  */
-export function winFn(name, ...args) {
+export function winFn(
+  name: WindowFunctionName,
+  ...args: unknown[]
+): WindowNode {
   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 to a SQL AST node.
+ * @param list The list of expression inputs.
+ * @param 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.
+ */
+export function exprList<T>(
+  list: unknown[],
+  cast: ((x: unknown) => T)
+): T[] {
+  return list.flat().filter(x => x != null).map(x => cast(x));
+}
+
 /**
  * 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>[]}
+ * @param list The list of expression inputs.
  */
-export function exprList(list, cast = asNode) {
-  return list.flat().filter(x => x != null).map(x => cast(x));
+export function nodeList(list: unknown[]): ExprNode[] {
+  return exprList(list, asNode);
 }
 
 /**
  * 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.
+ * @param list The input function arguments.
  */
-export function argsList(list) {
+export function argsList<T>(list: T[]): T[] {
   const n = list.length;
   let i = n;
   for (; i > 0 && list[i - 1] === undefined; --i);

package/src/util/identity.ts

@@ -0,0 +1,7 @@
+/**
+ * Identity function.
+ * @param x
+ */
+export function identity<T>(x: T) {
+  return x;
+}

package/src/util/{string.js → string.ts}

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

package/src/util/type-check.ts

@@ -0,0 +1,31 @@
+import type { ParamLike } from '../types.js';
+
+/**
+ * Check if a value is a string.
+ * @param value The value to check.
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+/**
+ * Check if a value is an array.
+ * @param value The value to check.
+ */
+export function isArray(value: unknown): value is Array<unknown> {
+  return Array.isArray(value);
+}
+
+/**
+ * Check if a value is a dynamic parameter.
+ * @param value The value to check.
+ */
+export function isParamLike(value: unknown): value is ParamLike {
+  if (value) {
+    const v = value as Record<string,unknown>;
+    return typeof v?.addEventListener === 'function'
+      && v.dynamic !== false
+      && 'value' in v;
+  }
+  return false;
+}

package/src/visit/clone.ts

@@ -0,0 +1,53 @@
+import { isNode } from '../ast/node.js';
+import { recurse } from './recurse.js';
+
+/**
+ * Create a deep clone of the given SQL AST node and all children nodes.
+ * @param node The node to deeply clone.
+ * @returns The cloned node.
+ */
+export function deepClone<T>(node: T): T {
+  const clone = shallowClone(node);
+
+  if (isNode(node)) {
+    const props = recurse[node.type];
+    const n = props?.length ?? 0;
+    for (let i = 0; i < n; ++i) {
+      const key = props[i];
+      // @ts-expect-error allow assignment
+      const value = node[key];
+      // @ts-expect-error allow assignment
+      clone[key] = Array.isArray(value)
+        ? value.map(v => deepClone(v))
+        : deepClone(value);
+    }
+  }
+
+  return clone;
+}
+
+/**
+ * Create a shallow clone of the given SQL AST node.
+ * @param node The node to clone.
+ * @returns The cloned node.
+ */
+function shallowClone<T>(node: T): T {
+  /** @type {T} */
+  let clone;
+
+  if (!node || typeof node !== 'object') {
+    return node;
+  } else if (isNode(node)) {
+    clone = node.clone();
+  } else if (node instanceof Date) {
+    // @ts-expect-error node is known to be Date
+    return new Date(+node);
+  } else if (Array.isArray(node)) {
+    // @ts-expect-error allow slice
+    return node.slice();
+  } else {
+    return { ...node };
+  }
+
+  return clone;
+}

package/src/visit/{recurse.js → recurse.ts}

@@ -4,6 +4,7 @@ import {
   BINARY_OPERATOR,
   CASE,
   CAST,
+  COLLATE,
   COLUMN_PARAM,
   COLUMN_REF,
   DESCRIBE_QUERY,
@@ -16,23 +17,29 @@ import {
   NOT_BETWEEN_OPERATOR,
   ORDER_BY,
   PARAM,
+  SCALAR_SUBQUERY,
   SELECT_CLAUSE,
   SELECT_QUERY,
   SET_OPERATION,
   UNARY_OPERATOR,
+  UNARY_POSTFIX_OPERATOR,
   WHEN,
   WINDOW,
   WINDOW_CLAUSE,
   WINDOW_DEF,
-  WINDOW_FRAME
+  WINDOW_EXTENT_EXPR,
+  WINDOW_FRAME,
+  WINDOW_FUNCTION,
+  WITH_CLAUSE
 } from '../constants.js';
 
-export const recurse = {
-  [AGGREGATE]: ['args', 'filter'],
+export const recurse: Record<string, string[]> = {
+  [AGGREGATE]: ['args', 'order', 'filter'],
   [BETWEEN_OPERATOR]: ['expr', 'extent'],
   [BINARY_OPERATOR]: ['left', 'right'],
   [CASE]: ['expr', '_when', '_else'],
   [CAST]: ['expr'],
+  [COLLATE]: ['expr'],
   [COLUMN_PARAM]: ['param', 'table'],
   [COLUMN_REF]: ['table'],
   [DESCRIBE_QUERY]: ['query'],
@@ -45,13 +52,18 @@ export const recurse = {
   [NOT_BETWEEN_OPERATOR]: ['expr', 'extent'],
   [ORDER_BY]: ['expr'],
   [PARAM]: ['value'],
+  [SCALAR_SUBQUERY]: ['subquery'],
   [SELECT_CLAUSE]: ['expr'],
   [SELECT_QUERY]: ['_with', '_select', '_from', '_where', '_sample', '_groupby', '_having', '_window', '_qualify', '_orderby'],
-  [SET_OPERATION]: ['subqueries', '_orderby'],
+  [SET_OPERATION]: ['queries', '_orderby'],
   [UNARY_OPERATOR]: ['expr'],
+  [UNARY_POSTFIX_OPERATOR]: ['expr'],
   [WHEN]: ['when', 'then'],
   [WINDOW]: ['func', 'def'],
   [WINDOW_CLAUSE]: ['def'],
-  [WINDOW_DEF]: ['partition', 'order', 'frame'],
-  [WINDOW_FRAME]: ['extent']
+  [WINDOW_DEF]: ['partition', 'order', 'framedef'],
+  [WINDOW_EXTENT_EXPR]: ['expr'],
+  [WINDOW_FRAME]: ['extent'],
+  [WINDOW_FUNCTION]: ['args'],
+  [WITH_CLAUSE]: ['query']
 };

package/src/visit/{rewrite.js → rewrite.ts}

@@ -1,32 +1,33 @@
-/** @import { ExprNode } from '../ast/node.js' */
-import { isNode } from '../ast/node.js';
+import { type 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 copies nodes as needed; it does not modify the input node.
- * @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}
+ * @param node The root AST node of the expression.
+ * @param map The rewrite map. When encountered, key nodes are replaced by value nodes.
  */
-export function rewrite(node, map) {
+export function rewrite(node: ExprNode, map: Map<ExprNode, ExprNode>) {
   if (map.has(node)) {
     return map.get(node);
   } else if (isNode(node)) {
     const props = recurse[node.type];
     const n = props?.length ?? 0;
     if (n > 0) {
-      node = cloneNode(node);
+      node = node.clone();
       for (let i = 0; i < n; ++i) {
         const prop = props[i];
+        // @ts-expect-error lookup valid property
         const child = node[prop];
         if (Array.isArray(child)) {
+          // @ts-expect-error rewrite known property
+          const a = (node[prop] = child.slice());
           const m = child.length;
           for (let j = 0; j < m; ++j) {
-            child[j] = rewrite(child[j], map);
+            a[j] = rewrite(child[j], map);
           }
         } else if (child) {
+          // @ts-expect-error rewrite known property
           node[prop] = rewrite(child, map);
         }
       }
@@ -34,12 +35,3 @@ export function rewrite(node, map) {
   }
   return node;
 }
-
-// TODO: consider typed node.clone() methods
-function cloneNode(node) {
-  const clone = new node.constructor();
-  for (const key in node) {
-    clone[key] = node[key];
-  }
-  return clone;
-}

package/src/visit/{visitors.js → visitors.ts}

@@ -1,12 +1,9 @@
-/**
- * @import { AggregateNode } from '../ast/aggregate.js'
- * @import { ColumnRefNode } from '../ast/column-ref.js'
- * @import { SQLNode } from '../ast/node.js'
- * @import { ParamNode } from '../ast/param.js'
- * @import { ParamLike } from '../types.js'
- */
+import { type AggregateNode, aggregateNames } from '../ast/aggregate.js';
+import type { ColumnRefNode } from '../ast/column-ref.js';
+import type { SQLNode } from '../ast/node.js';
+import type { ParamNode } from '../ast/param.js';
+import type { ParamLike } from '../types.js';
 import { AGGREGATE, COLUMN_PARAM, COLUMN_REF, FRAGMENT, PARAM, VERBATIM, WINDOW } from '../constants.js';
-import { aggregateNames } from '../ast/aggregate.js';
 import { walk } from './walk.js';
 
 // regexp to match valid aggregate function names
@@ -17,7 +14,7 @@ const aggrRegExp = new RegExp(`^(${aggregateNames.join('|')})$`);
 // function call tokens will have a pattern like "name(".
 const funcRegExp = /(\\'|\\"|"(?:\\"|[^"])*"|'(?:\\'|[^'])*'|\w+\()/g;
 
-function hasVerbatimAggregate(s) {
+function hasVerbatimAggregate(s: string) {
   return s
     .split(funcRegExp)
     .some(tok => tok.endsWith('(') && aggrRegExp.test(tok.slice(0, -1)));
@@ -27,12 +24,12 @@ function hasVerbatimAggregate(s) {
  * 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.
+ * @param root The root of the AST to search.
+ * @returns 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) {
+export function isAggregateExpression(root: SQLNode) {
   let agg = 0;
   walk(root, (node) => {
     switch (node.type) {
@@ -64,14 +61,13 @@ export function isAggregateExpression(root) {
 
 /**
  * Collect all aggregate function nodes.
- * @param {SQLNode} root The root of the AST to search.
- * @returns {AggregateNode[]}
+ * @param root The root of the AST to search.
  */
-export function collectAggregates(root) {
-  const aggs = new Set();
+export function collectAggregates(root: SQLNode) {
+  const aggs = new Set<AggregateNode>();
   walk(root, (node) => {
     if (node.type === AGGREGATE) {
-      aggs.add(node);
+      aggs.add(node as AggregateNode);
     }
   });
   return Array.from(aggs);
@@ -81,14 +77,14 @@ export function collectAggregates(root) {
  * 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[]}
+ * @param root The root of the AST to search.
  */
-export function collectColumns(root) {
-  const cols = {};
+export function collectColumns(root: SQLNode) {
+  const cols: Record<string, ColumnRefNode> = {};
   walk(root, (node) => {
     if (node.type === COLUMN_REF || node.type === COLUMN_PARAM) {
-      cols[node] = node; // key on string-coerced node
+       // key on string-coerced node
+      cols[`${node}`] = (node as ColumnRefNode);
     }
   });
   return Object.values(cols);
@@ -96,17 +92,13 @@ export function collectColumns(root) {
 
 /**
  * Collect all unique dynamic parameter instances.
- * @param {SQLNode} root The root of the AST to search.
- * @returns {ParamLike[]}
+ * @param root The root of the AST to search.
  */
-export function collectParams(root) {
-  const params = new Set;
+export function collectParams(root: SQLNode) {
+  const params = new Set<ParamLike>;
   walk(root, (node) => {
     if (node.type === PARAM) {
-      params.add(
-        /** @type {ParamNode} */
-        (node).param
-      );
+      params.add((node as ParamNode).param);
     }
   });
   return Array.from(params);

package/src/visit/walk.ts

@@ -0,0 +1,46 @@
+import type { SQLNode } from '../ast/node.js';
+import { isNode } from '../ast/node.js';
+import { recurse } from './recurse.js';
+
+/**
+ * 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;
+
+/**
+ * Perform a traversal of a SQL expression AST.
+ * @param node Root node for AST traversal.
+ * @param visit Visitor callback function.
+ */
+export function walk(node: unknown, visit: VisitorCallback): VisitorResult {
+  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) {
+    // @ts-expect-error lookup of valid property
+    const value = node[props[i]];
+    if (Array.isArray(value)) {
+      const m = value.length;
+      for (let j = 0; j < m; ++j) {
+        if (value[j] && Number(walk(value[j], visit)) < 0) {
+          return result;
+        }
+      }
+    } else if (value && Number(walk(value, visit)) < 0) {
+      return -1;
+    }
+  }
+}

package/dist/types/ast/aggregate.d.ts

@@ -1,71 +0,0 @@
-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: string, args: ExprNode[], distinct?: boolean, filter?: ExprNode);
-    /**
-     * The aggregate function name.
-     * @type {string}
-     * @readonly
-     */
-    readonly name: string;
-    /**
-     * The aggregate function arguments.
-     * @type {ExprNode[]}
-     * @readonly
-     */
-    readonly args: ExprNode[];
-    /**
-     * The distinct flag.
-     * @type {boolean}
-     * @readonly
-     */
-    readonly isDistinct: boolean;
-    /**
-     * Filter criteria.
-     * @type {ExprNode}
-     * @readonly
-     */
-    readonly filter: ExprNode;
-    /**
-     * Return a new derived aggregate over distinct values.
-     * @param {boolean} [isDistinct=true] The distinct flag.
-     * @returns {AggregateNode} A new aggregate node.
-     */
-    distinct(isDistinct?: boolean): AggregateNode;
-    /**
-     * Return a new derived aggregate function that filters values.
-     * @param {ExprNode | string} filter The filter expression.
-     * @returns {AggregateNode} A new aggregate node.
-     */
-    where(filter: ExprNode | string): AggregateNode;
-    /**
-     * Return a new window function over this aggregate.
-     * @returns {WindowNode} A new window node.
-     */
-    window(): WindowNode;
-    /**
-     * Return a new window function over this aggregate with the given partitions.
-     * @param {...ExprVarArgs} expr The partition by criteria.
-     * @returns {WindowNode} A new window node.
-     */
-    partitionby(...expr: ExprVarArgs[]): WindowNode;
-    /**
-     * Return a new window function over this aggregate with the given ordering.
-     * @param {...ExprVarArgs} expr The order by criteria.
-     * @returns {WindowNode} A new window node.
-     */
-    orderby(...expr: ExprVarArgs[]): WindowNode;
-}
-/**
- * An array of known aggregate function names.
- * From https://duckdb.org/docs/sql/functions/aggregates.html.
- */
-export const aggregateNames: string[];
-import { ExprNode } from './node.js';
-import { WindowNode } from './window.js';
-import type { ExprVarArgs } from '../types.js';