@uwdata/mosaic-sql 0.17.0 → 0.19.0

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('');
-  }
-}

package/src/ast/logical-op.js

@@ -1,67 +0,0 @@
-import { LOGICAL_OPERATOR } from '../constants.js';
-import { ExprNode } from './node.js';
-
-/**
- * @template {ExprNode} T
- */
-export class LogicalOpNode extends ExprNode {
-  /**
-   * Instantiate a logical operator node.
-   * @param {string} op The logical operation.
-   * @param {T[]} clauses The input clause expressions.
-   */
-  constructor(op, clauses) {
-    super(LOGICAL_OPERATOR);
-    /**
-     * The logical operator.
-     * @type {string}
-     * @readonly
-     */
-    this.op = op;
-    /**
-     * The input clause expressions.
-     * @type {T[]}
-     * @readonly
-     */
-    this.clauses = clauses;
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    const c = this.clauses;
-    return c.length === 0 ? ''
-      : c.length === 1 ? `${c[0]}`
-      : `(${c.join(` ${this.op} `)})`;
-  }
-}
-
-/**
- * @template {ExprNode} T
- * @extends {LogicalOpNode<T>}
- */
-export class AndNode extends LogicalOpNode {
-  /**
-   * Instantiate a logical AND operator node.
-   * @param {T[]} clauses The input clause expressions.
-   */
-  constructor(clauses) {
-    super('AND', clauses);
-  }
-}
-
-/**
- * @template {ExprNode} T
- * @extends {LogicalOpNode<T>}
- */
-export class OrNode extends LogicalOpNode {
-  /**
-   * Instantiate a logical OR operator node.
-   * @param {T[]} clauses The input clause expressions.
-   */
-  constructor(clauses) {
-    super('OR', clauses);
-  }
-}

package/src/ast/order-by.js

@@ -1,48 +0,0 @@
-import { ORDER_BY } from '../constants.js';
-import { ExprNode } from './node.js';
-
-export class OrderByNode extends ExprNode {
-  /**
-   * Instantiate an order by entry node.
-   * @param {ExprNode} expr The expression to order by.
-   * @param {boolean | undefined} [desc] Flag indicating descending order.
-   * @param {boolean | undefined} [nullsFirst] Flag indicating if null
-   *  values should be sorted first.
-   */
-  constructor(expr, desc, nullsFirst) {
-    super(ORDER_BY);
-    /**
-     * The expression to order by.
-     * @type {ExprNode}
-     * @readonly
-     */
-    this.expr = expr;
-    /**
-     * Flag indicating descending order.
-     * @type {boolean | undefined}
-     * @readonly
-     */
-    this.desc = desc;
-    /**
-     * Flag indicating if null values should be sorted first.
-     * @type {boolean | undefined}
-     * @readonly
-     */
-    this.nullsFirst = nullsFirst;
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    const { expr, desc, nullsFirst } = this;
-    const dir = desc ? ' DESC'
-      : desc === false ? ' ASC'
-      : '';
-    const nf = nullsFirst ? ' NULLS FIRST'
-      : nullsFirst === false ? ' NULLS LAST'
-      : '';
-    return `${expr}${dir}${nf}`;
-  }
-}

package/src/ast/sample.js

@@ -1,53 +0,0 @@
-import { SAMPLE_CLAUSE } from '../constants.js';
-import { SQLNode } from './node.js';
-
-/**
- * @typedef {'reservoir' | 'bernoulli' | 'system'} SampleMethod
- */
-
-export class SampleClauseNode extends SQLNode {
-  /**
-   * Instantiate a sample clause node.
-   * @param {number} size The sample size as either a row count or percentage.
-   * @param {boolean} [perc=false] Flag indicating if the sampling unit is
-   *   rows (`false`) or a percentage (`true`).
-   * @param {SampleMethod} [method] The sampling method. If unspecified,
-   *   a default method is applied based on the sampling unit.
-   * @param {number} [seed] The random seed.
-   */
-  constructor(size, perc = false, method = undefined, seed = undefined) {
-    super(SAMPLE_CLAUSE);
-    /**
-     * The sample size as either a row count or percentage.
-     * @type {number}
-     * @readonly
-     */
-    this.size = size;
-    /**
-     * Flag indicating if the sampling unit is rows (`false`) or a
-     * percentage (`true`).
-     * @type {boolean}
-     * @readonly
-     */
-    this.perc = perc;
-    /**
-     * The sampling method.
-     * @type {SampleMethod}
-     * @readonly
-     */
-    this.method = method;
-    /**
-     * The random seed.
-     * @type {number}
-     * @readonly
-     */
-    this.seed = seed;
-  }
-
-  toString() {
-    const { size, perc, method, seed } = this;
-    const m = method ? `${method} ` : '';
-    const s = seed != null ? ` REPEATABLE (${seed})` : '';
-    return `${m}(${size}${perc ? '%' : ' ROWS'})${s}`;
-  }
-}

package/src/ast/verbatim.js

@@ -1,33 +0,0 @@
-import { VERBATIM } from '../constants.js';
-import { ExprNode } from './node.js';
-
-export class VerbatimNode extends ExprNode {
-  /**
-   * Instantiate a raw node with verbatim content.
-   * @param {string} value The verbatim content to include.
-   * @param {string} [hint] A type hint for analyzing verbatim content.
-   */
-  constructor(value, hint) {
-    super(VERBATIM);
-    /**
-     * The verbatim content to include.
-     * @type {string}
-     * @readonly
-     */
-    this.value = value;
-    /**
-     * A type hint for analyzing verbatim content.
-     * @type {string}
-     * @readonly
-     */
-    this.hint = hint;
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    return this.value;
-  }
-}

package/src/ast/window.js

@@ -1,260 +0,0 @@
-/**
- * @import { ExprVarArgs, OrderByExpr, WindowFunctionName } from '../types.js'
- * @import { AggregateNode } from './aggregate.js'
- * @import { WindowFrameNode } from './window-frame.js'
- */
-import { WINDOW, WINDOW_CLAUSE, WINDOW_DEF, WINDOW_FUNCTION } from '../constants.js';
-import { exprList } from '../util/function.js';
-import { quoteIdentifier } from '../util/string.js';
-import { ExprNode, SQLNode } from './node.js';
-
-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 frame definition.
-   * @param {WindowFrameNode} framedef The frame definition.
-   * @returns {WindowNode} A new window node.
-   */
-  frame(framedef) {
-    return new WindowNode(this.func, this.def.frame(framedef));
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    return `${this.func} OVER ${this.def}`;
-  }
-}
-
-export class WindowFunctionNode extends ExprNode {
-  /**
-   * Instantiate a window function call node.
-   * @param {WindowFunctionName} name The window function name.
-   * @param {ExprNode[]} [args=[]] The window function arguments.
-   * @param {boolean} [ignoreNulls=false] Flag to ignore null values.
-   * @param {OrderByExpr} [argOrder] Order expressions for window arguments.
-   *  Note that this argument ordering is distinct from the window ordering.
-   */
-  constructor(name, args = [], ignoreNulls = false, argOrder = []) {
-    super(WINDOW_FUNCTION);
-    /**
-     * The window function name.
-     * @type {string}
-     * @readonly
-     */
-    this.name = name;
-    /**
-     * The window function arguments.
-     * @type {ExprNode[]}
-     * @readonly
-     */
-    this.args = args;
-    /**
-     * Flag to ignore null values.
-     * @type {boolean}
-     * @readonly
-     */
-    this.ignoreNulls = ignoreNulls;
-    /**
-     * Order by expression for window arguments.
-     * @type {ExprNode[]}
-     * @readonly
-     */
-    this.order = exprList([argOrder]);
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    const { name, args, ignoreNulls, order } = this;
-    const arg = [
-      args.join(', '),
-      order.length ? `ORDER BY ${order.join(', ')}` : '',
-      ignoreNulls ? 'IGNORE NULLS' : ''
-    ].filter(x => x).join(' ');
-    return `${name}(${arg})`;
-  }
-}
-
-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} [framedef] The window frame definition.
-   */
-  constructor(name, partition, order, framedef) {
-    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.framedef = framedef;
-  }
-
-  /**
-   * 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 frame definition.
-   * @param {WindowFrameNode} framedef The frame definition.
-   * @returns {WindowDefNode} A new window definition node.
-   */
-  frame(framedef) {
-    return deriveDef(this, { framedef });
-  }
-
-  /**
-   * Generate a SQL query string for this node.
-   * @returns {string}
-   */
-  toString() {
-    const { name, partition, order, framedef } = this;
-    const base = name && quoteIdentifier(name);
-    const def = [
-      base,
-      partition?.length && `PARTITION BY ${partition.join(', ')}`,
-      order?.length && `ORDER BY ${order.join(', ')}`,
-      framedef
-    ].filter(x => x);
-    return base && def.length < 2 ? base : `(${def.join(' ')})`;
-  }
-}
-
-/**
- * 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.framedef] The window frame definition.
- */
-function deriveDef(def, options) {
-  return new WindowDefNode(
-    options.name ?? def.name,
-    options.partition ?? def.partition,
-    options.order ?? def.order,
-    options.framedef ?? def.framedef
-  );
-}