@uwdata/mosaic-sql 0.16.2 → 0.18.0

package/src/ast/{case.js → case.ts}

@@ -1,50 +1,43 @@
-/**
- * @import { ExprValue } from '../types.js'
- */
+import { ExprValue } from '../types.js';
 import { CASE, WHEN } from '../constants.js';
 import { asNode } from '../util/ast.js';
 import { ExprNode, SQLNode } from './node.js';
 
 export class CaseNode extends ExprNode {
+  /** The optional base expression. */
+  readonly expr?: ExprNode;
+  /** An array of WHEN/THEN expression nodes. */
+  readonly _when: WhenNode[];
+  /** An ELSE expression. */
+  readonly _else?: ExprNode;
+
   /**
    * Instantiate a case node.
-   * @param {ExprNode} [expr] An optional base expression, that comes
+   * @param 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.
+   * @param when An array of WHEN/THEN expression nodes.
+   * @param elseExpr An ELSE expression.
    */
-  constructor(expr = undefined, when = [], elseExpr = undefined) {
+  constructor(
+    expr: ExprNode | undefined = undefined,
+    when: WhenNode[] = [],
+    elseExpr: ExprNode | undefined = 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 {ExprValue} cond The WHEN condition expression.
-   * @param {ExprValue} value The THEN value expression.
-   * @returns {CaseNode}
+   * @param cond The WHEN condition expression.
+   * @param value The THEN value expression.
    */
-  when(cond, value) {
+  when(cond: ExprValue, value: ExprValue) {
     return new CaseNode(
       this.expr,
       this._when.concat(new WhenNode(asNode(cond), asNode(value))),
@@ -54,16 +47,14 @@ export class CaseNode extends ExprNode {
 
   /**
    * Return a new case node with the given ELSE expression.
-   * @param {ExprValue} expr The ELSE expression.
-   * @returns {CaseNode}
+   * @param expr The ELSE expression.
    */
-  else(expr) {
+  else(expr: ExprValue) {
     return new CaseNode(this.expr, this._when, asNode(expr));
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return 'CASE '
@@ -75,30 +66,24 @@ export class CaseNode extends ExprNode {
 }
 
 export class WhenNode extends SQLNode {
+  /** The condition expression. */
+  readonly when: ExprNode;
+  /** The value expression. */
+  readonly then: ExprNode;
+
   /**
    * Instantiate a case node.
-   * @param {ExprNode} when The WHEN condition expression.
-   * @param {ExprNode} then The THEN value expression.
+   * @param when The WHEN condition expression.
+   * @param then The THEN value expression.
    */
-  constructor(when, then) {
+  constructor(when: ExprNode, then: ExprNode) {
     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 → cast.ts}

@@ -2,30 +2,24 @@ import { CAST } from '../constants.js';
 import { ExprNode } from './node.js';
 
 export class CastNode extends ExprNode {
+  /** The expression to type cast. */
+  readonly expr: ExprNode;
+  /** The type to cast to. */
+  readonly cast: string;
+
   /**
    * Instantiate a cast node.
-   * @param {ExprNode} expr The expression to type cast.
-   * @param {string} type The type to cast to.
+   * @param expr The expression to type cast.
+   * @param type The type to cast to.
    */
-  constructor(expr, type) {
+  constructor(expr: ExprNode, type: string) {
     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

package/src/ast/collate.ts

@@ -0,0 +1,27 @@
+import { COLLATE } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class CollateNode extends ExprNode {
+  /** The expression to collate. */
+  readonly expr: ExprNode;
+  /** The collation type. */
+  readonly collation: string;
+
+  /**
+   * Instantiate a collate node.
+   * @param expr The expression to collate.
+   * @param collation The collation type.
+   */
+  constructor(expr: ExprNode, collation: string) {
+    super(COLLATE);
+    this.expr = expr;
+    this.collation = collation;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    return `${this.expr} ${COLLATE} ${this.collation}`;
+  }
+}

package/src/ast/column-param.ts

@@ -0,0 +1,34 @@
+import type { ParamNode } from './param.js';
+import type { 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.
+ */
+export function isColumnParam(value: unknown): value is ColumnParamNode {
+  return value instanceof ColumnParamNode;
+}
+
+export class ColumnParamNode extends ColumnRefNode {
+  /** The column name as a parameter node */
+  readonly param: ParamNode;
+
+  /**
+   * Instantiate a column param node.
+   * @param param The column name as a parameter node.
+   * @param table The table reference.
+   */
+  constructor(param: ParamNode, table?: TableRefNode) {
+    super(COLUMN_PARAM, table);
+    this.param = param;
+  }
+
+  /**
+   * Returns the column name.
+   */
+  get column() {
+    return `${this.param.value}`;
+  }
+}

package/src/ast/{column-ref.js → column-ref.ts}

@@ -1,45 +1,39 @@
-/**
- * @import { TableRefNode } from './table-ref.js'
- */
+import type { TableRefNode } from './table-ref.js';
 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}
+ * @param value The value to check.
  */
-export function isColumnRef(value) {
+export function isColumnRef(value: unknown): value is ColumnRefNode {
   return value instanceof ColumnRefNode;
 }
 
 export class ColumnRefNode extends ExprNode {
+  /** The table reference. */
+  readonly table?: TableRefNode;
+
   /**
    * Instantiate a column reference node.
-   * @param {TableRefNode} [table] The table reference.
+   * @param type The AST node type.
+   * @param table The table reference.
    */
-  constructor(type, table) {
+  constructor(type: string, table?: TableRefNode) {
     super(type);
-    /**
-     * The table reference.
-     * @type {TableRefNode}
-     * @readonly
-     */
     this.table = table;
   }
 
   /**
    * Returns the column name.
-   * @returns {string}
    */
   get column() {
-    return null; // subclasses to override
+    return ''; // subclasses to override
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     const { column, table } = this;
@@ -50,24 +44,21 @@ export class ColumnRefNode extends ExprNode {
 }
 
 export class ColumnNameRefNode extends ColumnRefNode {
+  /** The column name. */
+  readonly name: string;
+
   /**
    * Instantiate a column reference node.
-   * @param {string} name The column name.
-   * @param {TableRefNode} [table] The table reference.
+   * @param name The column name.
+   * @param table The table reference.
    */
-  constructor(name, table) {
+  constructor(name: string, table?: TableRefNode) {
     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.ts

@@ -0,0 +1,28 @@
+import { FRAGMENT } from '../constants.js';
+import { ExprNode } from './node.js';
+
+/**
+ * A SQL AST node made up of disjoint fragments that are combined to form
+ * a coherent expression. Along with verbatim content, this class serves
+ * as an "escape hatch" for handling more unstructured SQL content.
+ */
+export class FragmentNode extends ExprNode {
+  /** The consecutive parts making up the fragment. */
+  readonly spans: ExprNode[];
+
+  /**
+   * Instantiate a fragment node with arbitrary content.
+   * @param spans The consecutive parts making up the fragment.
+   */
+  constructor(spans: ExprNode[]) {
+    super(FRAGMENT);
+    this.spans = spans;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    return this.spans.join('');
+  }
+}

package/src/ast/from.ts

@@ -0,0 +1,40 @@
+import type { SampleClauseNode } from './sample.js';
+import { FROM_CLAUSE } from '../constants.js';
+import { quoteIdentifier } from '../util/string.js';
+import { SQLNode } from './node.js';
+import { isQuery } from './query.js';
+import { isTableRef } from './table-ref.js';
+
+export class FromClauseNode extends SQLNode {
+  /** The from expression. */
+  readonly expr: SQLNode;
+  /** The output name. */
+  readonly alias?: string;
+  /** The table sample. */
+  readonly sample?: SampleClauseNode;
+
+  /**
+   * Instantiate a from node.
+   * @param expr The from expression.
+   * @param alias The output name.
+   * @param sample The table sample.
+   */
+  constructor(expr: SQLNode, alias?: string, sample?: SampleClauseNode) {
+    super(FROM_CLAUSE);
+    this.expr = expr;
+    this.alias = alias;
+    this.sample = sample;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    const { expr, alias, sample } = this;
+    const ref = isQuery(expr) ? `(${expr})` : `${expr}`;
+    const from = alias && !(isTableRef(expr) && expr.table.join('.') === alias)
+      ? `${ref} AS ${quoteIdentifier(alias)}`
+      : `${ref}`;
+    return `${from}${sample ? ` TABLESAMPLE ${sample}` : ''}`;
+  }
+}

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

@@ -2,30 +2,24 @@ import { FUNCTION } from '../constants.js';
 import { ExprNode } from './node.js';
 
 export class FunctionNode extends ExprNode {
+  /** The function name. */
+  readonly name: string;
+  /** The function arguments. */
+  readonly args: ExprNode[];
+
   /**
    * Instantiate a function node.
-   * @param {string} name The function name.
-   * @param {ExprNode[]} [args=[]] The function arguments.
+   * @param name The function name.
+   * @param args The function arguments.
    */
-  constructor(name, args = []) {
+  constructor(name: string, args: ExprNode[] = []) {
     super(FUNCTION);
-    /**
-     * The function name.
-     * @type {string}
-     * @readonly
-     */
     this.name = name;
-    /**
-     * The function arguments.
-     * @type {ExprNode[]}
-     * @readonly
-     */
     this.args = args;
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     const { name, args } = this;

package/src/ast/{in-op.js → in-op.ts}

@@ -2,30 +2,24 @@ import { IN_OPERATOR } from '../constants.js';
 import { ExprNode } from './node.js';
 
 export class InOpNode extends ExprNode {
+  /** The input expression. */
+  readonly expr: ExprNode;
+  /** The value set. */
+  readonly values: ExprNode[];
+
   /**
    * Instantiate an in operator node.
-   * @param {ExprNode} expr The input expression.
-   * @param {ExprNode[]} values The value set.
+   * @param expr The input expression.
+   * @param values The value set.
    */
-  constructor(expr, values) {
+  constructor(expr: ExprNode, values: ExprNode[]) {
     super(IN_OPERATOR);
-    /**
-     * The input expression.
-     * @type {ExprNode}
-     * @readonly
-     */
     this.expr = expr;
-    /**
-     * The value set.
-     * @type {ExprNode[]}
-     * @readonly
-     */
     this.values = values;
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return `(${this.expr} IN (${this.values.join(', ')}))`;

package/src/ast/{interval.js → interval.ts}

@@ -2,30 +2,24 @@ import { INTERVAL } from '../constants.js';
 import { ExprNode } from './node.js';
 
 export class IntervalNode extends ExprNode {
+  /** The interval name. */
+  readonly name: string;
+  /** The interval steps. */
+  readonly steps: number;
+
   /**
    * Instantiate an interval node.
-   * @param {string} name The interval name.
-   * @param {number} [steps=1] The interval steps.
+   * @param name The interval name.
+   * @param steps The interval steps.
    */
-  constructor(name, steps = 1) {
+  constructor(name: string, steps: number = 1) {
     super(INTERVAL);
-    /**
-     * The interval name.
-     * @type {string}
-     * @readonly
-     */
     this.name = name;
-    /**
-     * The interval steps.
-     * @type {number}
-     * @readonly
-     */
     this.steps = steps;
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return `INTERVAL ${this.steps} ${this.name}`;

package/src/ast/{literal.js → literal.ts}

@@ -2,30 +2,27 @@ import { LITERAL } from '../constants.js';
 import { ExprNode } from './node.js';
 
 export class LiteralNode extends ExprNode {
+  /** The literal value. */
+  readonly value: unknown;
+
   /**
    * Instantiate an literal node.
-   * @param {*} value The literal value.
+   * @param value The literal value.
    */
-  constructor(value) {
+  constructor(value: unknown) {
     super(LITERAL);
-    /**
-     * The literal value.
-     * @type {any}
-     * @readonly
-     */
     this.value = value;
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return literalToSQL(this.value);
   }
 }
 
-export function literalToSQL(value) {
+export function literalToSQL(value: unknown) {
   switch (typeof value) {
     case 'number':
       return Number.isFinite(value) ? `${value}` : 'NULL';

package/src/ast/logical-op.ts

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

package/src/ast/node.ts

@@ -0,0 +1,39 @@
+/**
+ * Check if a value is a SQL AST node.
+ * @param value The value to check.
+ */
+export function isNode(value: unknown): value is SQLNode {
+  return value instanceof SQLNode;
+}
+
+export class SQLNode {
+  /** The SQL AST node type. */
+  readonly type: string;
+
+  /**
+   * Instantiate a SQL AST node.
+   * @param type The SQL AST node type.
+   */
+  constructor(type: string) {
+    this.type = type;
+  }
+
+  /**
+   * Create a shallow clone of this SQL AST node.
+   * @returns The shallow clone node.
+   */
+  clone(): this {
+    // @ts-expect-error use constructor
+    const clone = new this.constructor();
+    for (const key in this) {
+      clone[key] = this[key];
+    }
+    return clone;
+  }
+}
+
+/**
+ * AST node corresponding to an individual expression.
+ */
+export class ExprNode extends SQLNode {
+}

package/src/ast/order-by.ts

@@ -0,0 +1,38 @@
+import { ORDER_BY } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class OrderByNode extends ExprNode {
+  /** The expression to order by. */
+  readonly expr: ExprNode;
+  /** Flag indicating descending order. */
+  readonly desc?: boolean;
+  /** Flag indicating if null values should be sorted first. */
+  readonly nullsFirst?: boolean;
+
+  /**
+   * Instantiate an order by entry node.
+   * @param expr The expression to order by.
+   * @param desc Flag indicating descending order.
+   * @param nullsFirst Flag indicating if null values should be sorted first.
+   */
+  constructor(expr: ExprNode, desc?: boolean, nullsFirst?: boolean) {
+    super(ORDER_BY);
+    this.expr = expr;
+    this.desc = desc;
+    this.nullsFirst = nullsFirst;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  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}`;
+  }
+}