@uwdata/mosaic-sql 0.16.2 → 0.18.0

package/src/ast/sample.ts

@@ -0,0 +1,47 @@
+import { SAMPLE_CLAUSE } from '../constants.js';
+import { SQLNode } from './node.js';
+
+export type SampleMethod = 'reservoir' | 'bernoulli' | 'system';
+
+export class SampleClauseNode extends SQLNode {
+  /** The sample size as either a row count or percentage. */
+  readonly size: number;
+  /** Flag if the sampling unit is rows (`false`) or percentage (`true`). */
+  readonly perc: boolean;
+  /** The sampling method. */
+  readonly method?: SampleMethod;
+  /** The random seed. */
+  readonly seed?: number;
+
+  /**
+   * Instantiate a sample clause node.
+   * @param size The sample size as either a row count or percentage.
+   * @param perc Flag indicating if the sampling unit is
+   *   rows (`false`) or a percentage (`true`).
+   * @param method The sampling method. If unspecified,
+   *   a default method is applied based on the sampling unit.
+   * @param seed The random seed.
+   */
+  constructor(
+    size: number,
+    perc: boolean = false,
+    method?: SampleMethod,
+    seed?: number
+  ) {
+    super(SAMPLE_CLAUSE);
+    this.size = size;
+    this.perc = perc;
+    this.method = method;
+    this.seed = seed;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  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/{select.js → select.ts}

@@ -1,34 +1,28 @@
-/** @import { ExprNode } from './node.js' */
+import type { ExprNode } from './node.js';
 import { SELECT_CLAUSE } from '../constants.js';
 import { quoteIdentifier } from '../util/string.js';
 import { ColumnRefNode } from './column-ref.js';
 import { SQLNode } from './node.js';
 
 export class SelectClauseNode extends SQLNode {
+  /** The select expression. */
+  readonly expr: ExprNode;
+  /** The output name. */
+  readonly alias: string;
+
   /**
    * Instantiate a select node.
-   * @param {ExprNode} expr The select expression.
-   * @param {string} alias The output name.
+   * @param expr The select expression.
+   * @param alias The output name.
    */
-  constructor(expr, alias) {
+  constructor(expr: ExprNode, alias: string) {
     super(SELECT_CLAUSE);
-    /**
-     * The select expression.
-     * @type {ExprNode}
-     * @readonly
-     */
     this.expr = expr;
-    /**
-     * The output name.
-     * @type {string}
-     * @readonly
-     */
     this.alias = alias;
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     const { expr, alias } = this;
@@ -38,7 +32,7 @@ export class SelectClauseNode extends SQLNode {
   }
 }
 
-function isColumnRefFor(expr, name) {
+function isColumnRefFor(expr: unknown, name: string): expr is ColumnRefNode {
   return expr instanceof ColumnRefNode
     && expr.table == null
     && expr.column === name;

package/src/ast/subquery.ts

@@ -0,0 +1,24 @@
+import type { Query } from './query.js';
+import { SCALAR_SUBQUERY } from '../constants.js';
+import { ExprNode } from './node.js';
+
+export class ScalarSubqueryNode extends ExprNode {
+  /** The scalar subquery. */
+  readonly subquery: Query;
+
+  /**
+   * Instantiate a scalar subquery node.
+   * @param subquery The scalar subquery.
+   */
+  constructor(subquery: Query) {
+    super(SCALAR_SUBQUERY);
+    this.subquery = subquery;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    return `(${this.subquery})`;
+  }
+}

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

@@ -4,31 +4,27 @@ import { ExprNode } from './node.js';
 
 /**
  * Check if a value is a table reference node.
- * @param {*} value The value to check.
- * @returns {value is TableRefNode}
+ * @param value The value to check.
  */
-export function isTableRef(value) {
+export function isTableRef(value: unknown): value is TableRefNode {
   return value instanceof TableRefNode;
 }
 
 export class TableRefNode extends ExprNode {
+  /** The table name, including namespaces. */
+  readonly table: string[];
+
   /**
    * Instantiate a table reference node.
-   * @param {string | string[]} table The table name.
+   * @param table The table name.
    */
-  constructor(table) {
+  constructor(table: string | string[]) {
     super(TABLE_REF);
-    /**
-     * The table name, including namespaces.
-     * @type {string[]}
-     * @readonly
-     */
     this.table = [table].flat();
   }
 
   /**
    * The table name without database or schema namespaces.
-   * @returns {string}
    */
   get name() {
     return this.table[this.table.length - 1];
@@ -36,7 +32,6 @@ export class TableRefNode extends ExprNode {
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return this.table.map(t => quoteIdentifier(t)).join('.');

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

@@ -2,25 +2,20 @@ import { UNARY_OPERATOR, UNARY_POSTFIX_OPERATOR } from '../constants.js';
 import { ExprNode } from './node.js';
 
 class AbstractUnaryOpNode extends ExprNode {
+  /** The operator type. */
+  readonly op: string;
+  /** The input expression. */
+  readonly expr: ExprNode;
+
   /**
    * Instantiate an abstract unary operator node.
-   * @param {string} type The node type.
-   * @param {string} op The operator type.
-   * @param {ExprNode} expr The input expression.
+   * @param type The node type.
+   * @param op The operator type.
+   * @param expr The input expression.
    */
-  constructor(type, op, expr) {
+  constructor(type: string, op: string, expr: ExprNode) {
     super(type);
-    /**
-     * The operator type.
-     * @type {string}
-     * @readonly
-     */
     this.op = op;
-    /**
-     * The input expression.
-     * @type {ExprNode}
-     * @readonly
-     */
     this.expr = expr;
   }
 }
@@ -28,35 +23,33 @@ class AbstractUnaryOpNode extends ExprNode {
 export class UnaryOpNode extends AbstractUnaryOpNode {
   /**
    * Instantiate a unary operator node.
-   * @param {string} op The operator type.
-   * @param {ExprNode} expr The input expression.
+   * @param op The operator type.
+   * @param expr The input expression.
    */
-  constructor(op, expr) {
+  constructor(op: string, expr: ExprNode) {
     super(UNARY_OPERATOR, op, expr);
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return `(${this.op} ${this.expr})`;
   }
 }
 
-export class UnaryPosftixOpNode extends AbstractUnaryOpNode {
+export class UnaryPostfixOpNode extends AbstractUnaryOpNode {
   /**
    * Instantiate a unary operator node.
-   * @param {string} op The operator type.
-   * @param {ExprNode} expr The input expression.
+   * @param op The operator type.
+   * @param expr The input expression.
    */
-  constructor(op, expr) {
+  constructor(op: string, expr: ExprNode) {
     super(UNARY_POSTFIX_OPERATOR, op, expr);
   }
 
   /**
    * Generate a SQL query string for this node.
-   * @returns {string}
    */
   toString() {
     return `(${this.expr} ${this.op})`;

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

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

package/src/ast/window-frame.ts

@@ -0,0 +1,97 @@
+import { WINDOW_EXTENT_EXPR, WINDOW_FRAME } from '../constants.js';
+import { type ParamLike } from '../types.js';
+import { isParamLike } from '../util/type-check.js';
+import { type ExprNode, isNode, SQLNode } from './node.js';
+import { ParamNode } from './param.js';
+
+export type FrameValue =  ExprNode | number | null;
+export type FrameExtent = [FrameValue, FrameValue] | ParamLike;
+export type FrameScope = 'PRECEDING' | 'FOLLOWING' | 'CURRENT ROW';
+export type FrameType = 'ROWS' | 'RANGE' | 'GROUPS';
+export type FrameExclude = 'NO OTHERS' | 'CURRENT ROW' | 'TIES' | 'GROUP';
+
+export const ROWS = 'ROWS';
+export const RANGE = 'RANGE';
+export const GROUPS = 'GROUPS';
+export const PRECEDING = 'PRECEDING';
+export const FOLLOWING = 'FOLLOWING';
+export const CURRENT_ROW = 'CURRENT ROW';
+export const UNBOUNDED = 'UNBOUNDED';
+
+export class WindowFrameNode extends SQLNode {
+  /** The frame type, one of ROWS, RANGE, or GROUPS. */
+  readonly frameType: FrameType;
+  /** The window frame extent. */
+  readonly extent: [unknown, unknown] | ParamNode;
+  /** The window frame exclusion criteria. */
+  readonly exclude?: FrameExclude;
+
+  /**
+   * Instantiate a window frame definition node.
+   * @param frameType The frame type, one of ROWS, RANGE, or GROUPS.
+   * @param extent The window frame extent.
+   * @param exclude The window frame exclusion criteria.
+   */
+  constructor(
+    frameType: FrameType,
+    extent: FrameExtent,
+    exclude?: FrameExclude
+  ) {
+    super(WINDOW_FRAME);
+    this.frameType = frameType;
+    this.extent = isParamLike(extent) ? new ParamNode(extent) : extent;
+    this.exclude = exclude;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    const { frameType, exclude, extent } = this;
+    const [prev, next] = isNode(extent)
+      ? extent.value as [unknown, unknown]
+      : extent;
+    const a = asFrameExpr(prev, PRECEDING);
+    const b = asFrameExpr(next, FOLLOWING);
+    return `${frameType} BETWEEN ${a} AND ${b}${exclude ? ` ${exclude}` : ''}`;
+  }
+}
+
+function asFrameExpr(value: unknown, scope: string) {
+  return value instanceof WindowFrameExprNode ? value
+    : value != null && typeof value !== 'number' ? `${value} ${scope}`
+    : value === 0 ? CURRENT_ROW
+    : !(value && Number.isFinite(value)) ? `${UNBOUNDED} ${scope}`
+    : `${Math.abs(value)} ${scope}`;
+}
+
+export class WindowFrameExprNode extends SQLNode {
+  /** The window frame extent. */
+  readonly scope: FrameScope;
+  /**
+   * The window frame extent expression. This value should be null
+   * in the case of current row or unbounded extent values.
+   */
+  readonly expr: FrameValue | null;
+
+  /**
+   * Instantiate a window frame definition node.
+   * @param scope The frame scope, one of PRECEDING, FOLLOWING, or CURRENT ROW.
+   * @param expr The window frame extent expression.
+   */
+  constructor(scope: FrameScope, expr: FrameValue | null = null) {
+    super(WINDOW_EXTENT_EXPR);
+    this.scope = scope;
+    this.expr = expr;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    const { scope, expr } = this;
+    return scope === CURRENT_ROW
+      ? scope
+      : `${expr ?? UNBOUNDED} ${scope}`;
+  }
+}

package/src/ast/window.ts

@@ -0,0 +1,246 @@
+import type { ExprVarArgs, OrderByExpr, WindowFunctionName } from '../types.js';
+import type { AggregateNode } from './aggregate.js';
+import type { WindowFrameNode } from './window-frame.js';
+import { WINDOW, WINDOW_CLAUSE, WINDOW_DEF, WINDOW_FUNCTION } from '../constants.js';
+import { nodeList } from '../util/function.js';
+import { quoteIdentifier } from '../util/string.js';
+import { ExprNode, SQLNode } from './node.js';
+
+export class WindowClauseNode extends SQLNode {
+   /** The window name. */
+   readonly name: string;
+   /** The window definition. */
+   readonly def: WindowDefNode;
+
+  /**
+   * Instantiate a window clause node.
+   * @param name The window name.
+   * @param def The window definition.
+   */
+  constructor(name: string, def: WindowDefNode) {
+    super(WINDOW_CLAUSE);
+    this.name = name;
+    this.def = def;
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    return `${quoteIdentifier(this.name)} AS ${this.def}`;
+  }
+}
+
+export class WindowNode extends ExprNode {
+  readonly func: WindowFunctionNode | AggregateNode;
+  readonly def: WindowDefNode
+
+  /**
+   * Instantiate a window node.
+   * @param func The window function call.
+   * @param over The window definition or name.
+   */
+  constructor(
+    func: WindowFunctionNode | AggregateNode,
+    over: WindowDefNode = new WindowDefNode()
+  ) {
+    super(WINDOW);
+    this.func = func;
+    this.def = over;
+  }
+
+  /**
+   * Return an updated window over a named window definition.
+   * @param name The window definition name.
+   * @returns A new window node.
+   */
+  over(name: string) {
+    return new WindowNode(this.func, this.def.over(name));
+  }
+
+  /**
+   * Return an updated window with the given partitions.
+   * @param expr The partition by criteria.
+   * @returns A new window node.
+   */
+  partitionby(...expr: ExprVarArgs[]) {
+    return new WindowNode(this.func, this.def.partitionby(...expr));
+  }
+
+  /**
+   * Return an updated window with the given ordering.
+   * @param expr The order by criteria.
+   * @returns A new window node.
+   */
+  orderby(...expr: ExprVarArgs[]) {
+    return new WindowNode(this.func, this.def.orderby(...expr));
+  }
+
+  /**
+   * Return an updated window with the given frame definition.
+   * @param framedef The frame definition.
+   * @returns A new window node.
+   */
+  frame(framedef: WindowFrameNode) {
+    return new WindowNode(this.func, this.def.frame(framedef));
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  toString() {
+    return `${this.func} OVER ${this.def}`;
+  }
+}
+
+export class WindowFunctionNode extends ExprNode {
+  /** The window function name. */
+  readonly name: string;
+  /** The window function arguments. */
+  readonly args: ExprNode[];
+  /** Flag to ignore null values. */
+  readonly ignoreNulls: boolean;
+  /** Order by expression for window arguments. */
+  readonly order: ExprNode[];
+
+  /**
+   * Instantiate a window function call node.
+   * @param name The window function name.
+   * @param args The window function arguments.
+   * @param ignoreNulls Flag to ignore null values.
+   * @param argOrder Order expressions for window arguments.
+   *  Note that this argument ordering is distinct from the window ordering.
+   */
+  constructor(
+    name: WindowFunctionName,
+    args: ExprNode[] = [],
+    ignoreNulls: boolean = false,
+    argOrder: OrderByExpr = []
+  ) {
+    super(WINDOW_FUNCTION);
+    this.name = name;
+    this.args = args;
+    this.ignoreNulls = ignoreNulls;
+    this.order = nodeList([argOrder]);
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  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 {
+  /** The base window definition name. */
+  readonly name?: string;
+  /** The partition by criteria. */
+  readonly partition?: ExprNode[];
+  /** The order by criteria. */
+  readonly order?: ExprNode[];
+  /** The window frame definition. */
+  readonly framedef?: WindowFrameNode;
+
+  /**
+   * Instantiate a window definition node.
+   * @param name The base window definition name.
+   * @param partition The partition by criteria.
+   * @param order The order by criteria.
+   * @param framedef The window frame definition.
+   */
+  constructor(
+    name?: string,
+    partition?: ExprNode[],
+    order?: ExprNode[],
+    framedef?: WindowFrameNode
+  ) {
+    super(WINDOW_DEF);
+    this.name = name;
+    this.partition = partition;
+    this.order = order;
+    this.framedef = framedef;
+  }
+
+  /**
+   * Return an updated window definition with the given base name.
+   * @param name The base window definition name.
+   * @returns A new window definition node.
+   */
+  over(name: string) {
+    return deriveDef(this, { name });
+  }
+
+  /**
+   * Return an updated window definition with the given partitions.
+   * @param expr The partition by criteria.
+   * @returns A new window definition node.
+   */
+  partitionby(...expr: ExprVarArgs[]) {
+    return deriveDef(this, { partition: nodeList(expr) });
+  }
+
+  /**
+   * Return an updated window definition with the given ordering.
+   * @param expr The order by criteria.
+   * @returns A new window definition node.
+   */
+  orderby(...expr: ExprVarArgs[]) {
+    return deriveDef(this, { order: nodeList(expr) });
+  }
+
+  /**
+   * Return an updated window definition with the given frame definition.
+   * @param framedef The frame definition.
+   * @return A new window definition node.
+   */
+  frame(framedef: WindowFrameNode) {
+    return deriveDef(this, { framedef });
+  }
+
+  /**
+   * Generate a SQL query string for this node.
+   */
+  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(' ')})`;
+  }
+}
+
+interface DeriveDefOptions {
+  /** The base window definition name. */
+  name?: string;
+  /** The partition by criteria. */
+  partition?: ExprNode[];
+  /** The order by criteria. */
+  order?: ExprNode[];
+  /** The window frame definition. */
+  framedef?: WindowFrameNode;
+}
+
+/**
+ * Derive a new window definition node from an existing one.
+ * @param def The existing window definition.
+ * @param options An options object with new definition properties.
+ */
+function deriveDef(def: WindowDefNode, options: DeriveDefOptions) {
+  return new WindowDefNode(
+    options.name ?? def.name,
+    options.partition ?? def.partition,
+    options.order ?? def.order,
+    options.framedef ?? def.framedef
+  );
+}

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

@@ -1,39 +1,38 @@
-/** @import { Query } from './query.js' */
+import type { Query } from './query.js';
 import { WITH_CLAUSE } from '../constants.js';
 import { SQLNode } from './node.js';
 
 export class WithClauseNode extends SQLNode {
+  /** The common table expression (CTE) name. */
+  readonly name: string;
+  /** The common table expression (CTE) query. */
+  readonly query: Query;
+  /** The common table expression (CTE) materialization flag. */
+  readonly materialized: boolean | null;
+
   /**
    * Instantiate a with clause node for a common table expression (CTE).
-   * @param {string} name The common table expression (CTE) name.
-   * @param {Query} query The common table expression (CTE) query.
-   * @param {boolean | null} [materialized] The common table expression (CTE)
+   * @param name The common table expression (CTE) name.
+   * @param query The common table expression (CTE) query.
+   * @param materialized The common table expression (CTE)
    *  materialization flag. If `true`, forces materialization of the CTE.
    *  If `false`, materialization is not performed. Otherwise (for example, if
    *  `undefined` or `null`), materialization is decided by the database.
    */
-  constructor(name, query, materialized = undefined) {
+  constructor(
+    name: string,
+    query: Query,
+    materialized: boolean | null = null
+  ) {
     super(WITH_CLAUSE);
-    /**
-     * The common table expression (CTE) name.
-     * @type {string}
-     * @readonly
-     */
     this.name = name;
-    /**
-     * The common table expression (CTE) query.
-     * @type {Query}
-     * @readonly
-     */
     this.query = query;
-    /**
-     * The common table expression (CTE) materialization flag.
-     * @type {boolean | null}
-     * @readonly
-     */
     this.materialized = materialized;
   }
 
+  /**
+   * Generate a SQL query string for this node.
+   */
   toString() {
     const flag = this.materialized;
     const mat = flag === true ? ' MATERIALIZED'