@uwdata/mosaic-sql 0.17.0 → 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.js → clone.ts}

@@ -3,11 +3,10 @@ import { recurse } from './recurse.js';
 
 /**
  * Create a deep clone of the given SQL AST node and all children nodes.
- * @template T
- * @param {T} node The node to deeply clone.
- * @returns {T} The cloned node.
+ * @param node The node to deeply clone.
+ * @returns The cloned node.
  */
-export function deepClone(node) {
+export function deepClone<T>(node: T): T {
   const clone = shallowClone(node);
 
   if (isNode(node)) {
@@ -15,7 +14,9 @@ export function deepClone(node) {
     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);
@@ -27,11 +28,10 @@ export function deepClone(node) {
 
 /**
  * Create a shallow clone of the given SQL AST node.
- * @template T
- * @param {T} node The node to clone.
- * @returns {T} The cloned node.
+ * @param node The node to clone.
+ * @returns The cloned node.
  */
-function shallowClone(node) {
+function shallowClone<T>(node: T): T {
   /** @type {T} */
   let clone;
 
@@ -40,10 +40,10 @@ function shallowClone(node) {
   } else if (isNode(node)) {
     clone = node.clone();
   } else if (node instanceof Date) {
-    // @ts-expect-error
+    // @ts-expect-error node is known to be Date
     return new Date(+node);
   } else if (Array.isArray(node)) {
-    // @ts-expect-error
+    // @ts-expect-error allow slice
     return node.slice();
   } else {
     return { ...node };

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

@@ -33,7 +33,7 @@ import {
   WITH_CLAUSE
 } from '../constants.js';
 
-export const recurse = {
+export const recurse: Record<string, string[]> = {
   [AGGREGATE]: ['args', 'order', 'filter'],
   [BETWEEN_OPERATOR]: ['expr', 'extent'],
   [BINARY_OPERATOR]: ['left', 'right'],

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

@@ -1,16 +1,13 @@
-/** @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)) {
@@ -20,14 +17,17 @@ export function rewrite(node, map) {
       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) {
             a[j] = rewrite(child[j], map);
           }
         } else if (child) {
+          // @ts-expect-error rewrite known property
           node[prop] = rewrite(child, map);
         }
       }

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/src/ast/binary-op.js

@@ -1,40 +0,0 @@
-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/column-param.js

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

package/src/ast/fragment.js

@@ -1,26 +0,0 @@
-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('');
-  }
-}