@uwdata/mosaic-sql 0.12.2 → 0.14.0

package/README.md

@@ -2,6 +2,6 @@
 
 [![npm version](https://img.shields.io/npm/v/@uwdata/mosaic-sql.svg)](https://www.npmjs.com/package/@uwdata/mosaic-sql)
 
-An API for convenient construction and analysis of SQL queries. Query objects then coerce to SQL query strings.
+An API for convenient construction and analysis of SQL queries. Constructed `Query` objects coerce to SQL query strings.
 
 Many `mosaic-sql` utilities are included as part of the [vgplot](https://github.com/uwdata/mosaic/tree/main/packages/vgplot) API.

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

@@ -50,16 +50,16 @@ export class AggregateNode extends ExprNode {
     window(): WindowNode;
     /**
      * Return a new window function over this aggregate with the given partitions.
-     * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+     * @param {...ExprVarArgs} expr The partition by criteria.
      * @returns {WindowNode} A new window node.
      */
-    partitionby(...expr: import("../types.js").ExprVarArgs[]): WindowNode;
+    partitionby(...expr: ExprVarArgs[]): WindowNode;
     /**
      * Return a new window function over this aggregate with the given ordering.
-     * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+     * @param {...ExprVarArgs} expr The order by criteria.
      * @returns {WindowNode} A new window node.
      */
-    orderby(...expr: import("../types.js").ExprVarArgs[]): WindowNode;
+    orderby(...expr: ExprVarArgs[]): WindowNode;
 }
 /**
  * An array of known aggregate function names.
@@ -68,3 +68,4 @@ export class AggregateNode extends ExprNode {
 export const aggregateNames: string[];
 import { ExprNode } from './node.js';
 import { WindowNode } from './window.js';
+import type { ExprVarArgs } from '../types.js';

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

@@ -30,19 +30,17 @@ export class CaseNode extends ExprNode {
     /**
      * Return a new case node with the given conditional added as
      * the last WHEN / THEN pair.
-     * @param {import('../types.js').ExprValue} cond
-     *  The WHEN condition expression.
-     * @param {import('../types.js').ExprValue} value
-     *  The THEN value expression.
+     * @param {ExprValue} cond The WHEN condition expression.
+     * @param {ExprValue} value The THEN value expression.
      * @returns {CaseNode}
      */
-    when(cond: import("../types.js").ExprValue, value: import("../types.js").ExprValue): CaseNode;
+    when(cond: ExprValue, value: ExprValue): CaseNode;
     /**
      * Return a new case node with the given ELSE expression.
-     * @param {import('../types.js').ExprValue} expr The ELSE expression.
+     * @param {ExprValue} expr The ELSE expression.
      * @returns {CaseNode}
      */
-    else(expr: import("../types.js").ExprValue): CaseNode;
+    else(expr: ExprValue): CaseNode;
 }
 export class WhenNode extends SQLNode {
     /**
@@ -65,4 +63,5 @@ export class WhenNode extends SQLNode {
     readonly then: ExprNode;
 }
 import { ExprNode } from './node.js';
+import type { ExprValue } from '../types.js';
 import { SQLNode } from './node.js';

package/dist/types/ast/column-param.d.ts

@@ -7,17 +7,17 @@ export function isColumnParam(value: any): value is ColumnParamNode;
 export class ColumnParamNode extends ColumnRefNode {
     /**
      * Instantiate a column param node.
-     * @param {import('./param.js').ParamNode} param The column name as a
-     *  parameter node.
-     * @param {import('./table-ref.js').TableRefNode} [table] The table
-     *  reference.
+     * @param {ParamNode} param The column name as a parameter node.
+     * @param {TableRefNode} [table] The table reference.
      */
-    constructor(param: import("./param.js").ParamNode, table?: import("./table-ref.js").TableRefNode);
+    constructor(param: ParamNode, table?: TableRefNode);
     /**
      * The column name as a parameter node.
-     * @type {import('./param.js').ParamNode}
+     * @type {ParamNode}
      * @readonly
      */
-    readonly param: import("./param.js").ParamNode;
+    readonly param: ParamNode;
 }
 import { ColumnRefNode } from './column-ref.js';
+import type { ParamNode } from './param.js';
+import type { TableRefNode } from './table-ref.js';

package/dist/types/ast/column-ref.d.ts

@@ -7,15 +7,15 @@ export function isColumnRef(value: any): value is ColumnRefNode;
 export class ColumnRefNode extends ExprNode {
     /**
      * Instantiate a column reference node.
-     * @param {import('./table-ref.js').TableRefNode} [table] The table reference.
+     * @param {TableRefNode} [table] The table reference.
      */
-    constructor(type: any, table?: import("./table-ref.js").TableRefNode);
+    constructor(type: any, table?: TableRefNode);
     /**
      * The table reference.
-     * @type {import('./table-ref.js').TableRefNode}
+     * @type {TableRefNode}
      * @readonly
      */
-    readonly table: import("./table-ref.js").TableRefNode;
+    readonly table: TableRefNode;
     /**
      * Returns the column name.
      * @returns {string}
@@ -26,9 +26,9 @@ export class ColumnNameRefNode extends ColumnRefNode {
     /**
      * Instantiate a column reference node.
      * @param {string} name The column name.
-     * @param {import('./table-ref.js').TableRefNode} [table] The table reference.
+     * @param {TableRefNode} [table] The table reference.
      */
-    constructor(name: string, table?: import("./table-ref.js").TableRefNode);
+    constructor(name: string, table?: TableRefNode);
     /**
      * The column name.
      * @type {string}
@@ -37,3 +37,4 @@ export class ColumnNameRefNode extends ColumnRefNode {
     readonly name: string;
 }
 import { ExprNode } from './node.js';
+import type { TableRefNode } from './table-ref.js';

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

@@ -1,15 +1,15 @@
 export class ParamNode extends ExprNode {
     /**
      * Instantiate a param node with a dynamic parameter.
-     * @param {import('../types.js').ParamLike} param The dynamic parameter.
+     * @param {ParamLike} param The dynamic parameter.
      */
-    constructor(param: import("../types.js").ParamLike);
+    constructor(param: ParamLike);
     /**
      * The dynamic parameter.
-     * @type {import('../types.js').ParamLike}
+     * @type {ParamLike}
      * @readonly
      */
-    readonly param: import("../types.js").ParamLike;
+    readonly param: ParamLike;
     /**
      * Returns the current parameter value.
      * @returns {*}
@@ -17,3 +17,4 @@ export class ParamNode extends ExprNode {
     get value(): any;
 }
 import { ExprNode } from './node.js';
+import type { ParamLike } from '../types.js';

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

@@ -18,23 +18,23 @@ export function isSelectQuery(value: any): value is SelectQuery;
 export function isDescribeQuery(value: any): value is DescribeQuery;
 export class Query extends ExprNode {
     /**
-     * Create a new select query with the given SELECT expressions.
-     * @param {...import('../types.js').SelectExpr} expr The SELECT expressions.
-     * @returns {SelectQuery}
+     * Create a new WITH clause with the given CTE queries.
+     * @param {...WithExpr} expr The WITH CTE queries.
+     * @returns {WithClause}
      */
-    static select(...expr: import("../types.js").SelectExpr[]): SelectQuery;
+    static with(...expr: WithExpr[]): WithClause;
     /**
-     * Create a new select query with the given FROM expressions.
-     * @param {...import('../types.js').FromExpr} expr The FROM expressions.
+     * Create a new select query with the given SELECT expressions.
+     * @param {...SelectExpr} expr The SELECT expressions.
      * @returns {SelectQuery}
      */
-    static from(...expr: import("../types.js").FromExpr[]): SelectQuery;
+    static select(...expr: SelectExpr[]): SelectQuery;
     /**
-     * Create a new select query with the given WITH CTE queries.
-     * @param {...import('../types.js').WithExpr} expr The WITH CTE queries.
+     * Create a new select query with the given FROM expressions.
+     * @param {...FromExpr} expr The FROM expressions.
      * @returns {SelectQuery}
      */
-    static with(...expr: import("../types.js").WithExpr[]): SelectQuery;
+    static from(...expr: FromExpr[]): SelectQuery;
     /**
      * Create a new UNION set operation over the given queries.
      * @param {...Query} queries The queries.
@@ -69,6 +69,8 @@ export class Query extends ExprNode {
      * Instantiate a new query.
      */
     constructor(type: any);
+    /** @type {WithClauseNode[]} */
+    _with: WithClauseNode[];
     /** @type {ExprNode[]} */
     _orderby: ExprNode[];
     /** @type {number} */
@@ -87,12 +89,18 @@ export class Query extends ExprNode {
      * @returns {Query}
      */
     clone(): Query;
+    /**
+     * Add WITH common table expressions (CTEs).
+     * @param  {...WithExpr} expr Expressions to add.
+     * @returns {this}
+     */
+    with(...expr: WithExpr[]): this;
     /**
      * Add ORDER BY expressions.
-     * @param  {...import('../types.js').OrderByExpr} expr Expressions to add.
+     * @param  {...OrderByExpr} expr Expressions to add.
      * @returns
      */
-    orderby(...expr: import("../types.js").OrderByExpr[]): this;
+    orderby(...expr: OrderByExpr[]): this;
     /**
      * Set the query result LIMIT.
      * @param {number} value The limit value.
@@ -111,8 +119,6 @@ export class SelectQuery extends Query {
      * Instantiate a new select query.
      */
     constructor();
-    /** @type {WithClauseNode[]} */
-    _with: WithClauseNode[];
     /** @type {SelectClauseNode[]} */
     _select: SelectClauseNode[];
     /** @type {FromClauseNode[]} */
@@ -134,24 +140,18 @@ export class SelectQuery extends Query {
      * @returns {SelectQuery}
      */
     clone(): SelectQuery;
-    /**
-     * Add WITH common table expressions (CTEs).
-     * @param  {...import('../types.js').WithExpr} expr Expressions to add.
-     * @returns {this}
-     */
-    with(...expr: import("../types.js").WithExpr[]): this;
     /**
      * Add SELECT expressions.
-     * @param {...import('../types.js').SelectExpr} expr Expressions to add.
+     * @param {...SelectExpr} expr Expressions to add.
      * @returns {this}
      */
-    select(...expr: import("../types.js").SelectExpr[]): this;
+    select(...expr: SelectExpr[]): this;
     /**
      * Set SELECT expressions, replacing any prior expressions.
-     * @param {...import('../types.js').SelectExpr} expr Expressions to add.
+     * @param {...SelectExpr} expr Expressions to add.
      * @returns {this}
      */
-    setSelect(...expr: import("../types.js").SelectExpr[]): this;
+    setSelect(...expr: SelectExpr[]): this;
     /**
      * Indicate if this query should retrieve distinct values only.
      * @param {boolean} value The distinct flag
@@ -161,56 +161,56 @@ export class SelectQuery extends Query {
     _distinct: boolean;
     /**
      * Add table FROM expressions.
-     * @param  {...import('../types.js').FromExpr} expr Expressions to add.
+     * @param  {...FromExpr} expr Expressions to add.
      * @returns {this}
      */
-    from(...expr: import("../types.js").FromExpr[]): this;
+    from(...expr: FromExpr[]): this;
     /**
      * Set FROM expressions, replacing any prior expressions.
-     * @param {...import('../types.js').FromExpr} expr Expressions to add.
+     * @param {...FromExpr} expr Expressions to add.
      * @returns {this}
      */
-    setFrom(...expr: import("../types.js").FromExpr[]): this;
+    setFrom(...expr: FromExpr[]): this;
     /**
      * Set SAMPLE settings.
      * @param {number | SampleClauseNode} value Either a sample clause node
      *  or the sample size as either a row count or percentage.
-     * @param {import('./sample.js').SampleMethod} [method] The sampling method
+     * @param {SampleMethod} [method] The sampling method
      *  to use.
      * @param {number} [seed] The random seed.
      * @returns {this}
      */
-    sample(value: number | SampleClauseNode, method?: import("./sample.js").SampleMethod, seed?: number): this;
+    sample(value: number | SampleClauseNode, method?: SampleMethod, seed?: number): this;
     /**
      * Add WHERE expressions.
-     * @param  {...import('../types.js').FilterExpr} expr Expressions to add.
+     * @param  {...FilterExpr} expr Expressions to add.
      * @returns {this}
      */
-    where(...expr: import("../types.js").FilterExpr[]): this;
+    where(...expr: FilterExpr[]): this;
     /**
      * Set WHERE expressions, replacing any prior expressions.
-     * @param {...import('../types.js').FilterExpr} expr Expressions to add.
+     * @param {...FilterExpr} expr Expressions to add.
      * @returns {this}
      */
-    setWhere(...expr: import("../types.js").FilterExpr[]): this;
+    setWhere(...expr: FilterExpr[]): this;
     /**
      * Add GROUP BY expressions.
-     * @param  {...import('../types.js').GroupByExpr} expr Expressions to add.
+     * @param  {...GroupByExpr} expr Expressions to add.
      * @returns {this}
      */
-    groupby(...expr: import("../types.js").GroupByExpr[]): this;
+    groupby(...expr: GroupByExpr[]): this;
     /**
      * Set GROUP BY expressions, replacing any prior expressions.
-     * @param {...import('../types.js').GroupByExpr} expr Expressions to add.
+     * @param {...GroupByExpr} expr Expressions to add.
      * @returns {this}
      */
-    setGroupby(...expr: import("../types.js").GroupByExpr[]): this;
+    setGroupby(...expr: GroupByExpr[]): this;
     /**
      * Add HAVING expressions.
-     * @param {...import('../types.js').FilterExpr} expr Expressions to add.
+     * @param {...FilterExpr} expr Expressions to add.
      * @returns {this}
      */
-    having(...expr: import("../types.js").FilterExpr[]): this;
+    having(...expr: FilterExpr[]): this;
     /**
      * Add WINDOW definitions.
      * @param  {...any} expr Expressions to add.
@@ -219,10 +219,10 @@ export class SelectQuery extends Query {
     window(...expr: any[]): this;
     /**
      * Add QUALIFY expressions.
-     * @param {...import('../types.js').FilterExpr} expr Expressions to add.
+     * @param {...FilterExpr} expr Expressions to add.
      * @returns {this}
      */
-    qualify(...expr: import("../types.js").FilterExpr[]): this;
+    qualify(...expr: FilterExpr[]): this;
 }
 export class DescribeQuery extends SQLNode {
     /**
@@ -261,8 +261,60 @@ export class SetOperation extends Query {
 }
 import { ExprNode } from './node.js';
 import { WithClauseNode } from './with.js';
+import type { WithExpr } from '../types.js';
+import type { OrderByExpr } from '../types.js';
+declare class WithClause {
+    /**
+     * Instantiate a new WITH clause instance.
+     * @param {...WithExpr} expr The WITH CTE queries.
+     */
+    constructor(...expr: WithExpr[]);
+    _with: WithExpr[];
+    /**
+     * Create a new select query with the given SELECT expressions.
+     * @param {...SelectExpr} expr The SELECT expressions.
+     * @returns {SelectQuery}
+     */
+    select(...expr: SelectExpr[]): SelectQuery;
+    /**
+     * Create a new select query with the given FROM expressions.
+     * @param {...FromExpr} expr The FROM expressions.
+     * @returns {SelectQuery}
+     */
+    from(...expr: FromExpr[]): SelectQuery;
+    /**
+     * Create a new UNION set operation over the given queries.
+     * @param {...Query} queries The queries.
+     * @returns {SetOperation}
+     */
+    union(...queries: Query[]): SetOperation;
+    /**
+     * Create a new UNION ALL set operation over the given queries.
+     * @param {...Query} queries The queries.
+     * @returns {SetOperation}
+     */
+    unionAll(...queries: Query[]): SetOperation;
+    /**
+     * Create a new INTERSECT set operation over the given queries.
+     * @param {...Query} queries The queries.
+     * @returns {SetOperation}
+     */
+    intersect(...queries: Query[]): SetOperation;
+    /**
+     * Create a new EXCEPT set operation over the given queries.
+     * @param {...Query} queries The queries.
+     * @returns {SetOperation}
+     */
+    except(...queries: Query[]): SetOperation;
+}
+import type { SelectExpr } from '../types.js';
+import type { FromExpr } from '../types.js';
 import { SelectClauseNode } from './select.js';
 import { FromClauseNode } from './from.js';
 import { SampleClauseNode } from './sample.js';
 import { WindowClauseNode } from './window.js';
+import type { SampleMethod } from './sample.js';
+import type { FilterExpr } from '../types.js';
+import type { GroupByExpr } from '../types.js';
 import { SQLNode } from './node.js';
+export {};

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

@@ -1,5 +1,5 @@
 /**
- * @typedef {[any, any] | import('../types.js').ParamLike} FrameExtent
+ * @typedef {[any, any] | ParamLike} FrameExtent
  */
 export class WindowClauseNode extends SQLNode {
     /**
@@ -46,16 +46,16 @@ export class WindowNode extends ExprNode {
     over(name: string): WindowNode;
     /**
      * Return an updated window with the given partitions.
-     * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+     * @param {...ExprVarArgs} expr The partition by criteria.
      * @returns {WindowNode} A new window node.
      */
-    partitionby(...expr: import("../types.js").ExprVarArgs[]): WindowNode;
+    partitionby(...expr: ExprVarArgs[]): WindowNode;
     /**
      * Return an updated window with the given ordering.
-     * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+     * @param {...ExprVarArgs} expr The order by criteria.
      * @returns {WindowNode} A new window node.
      */
-    orderby(...expr: import("../types.js").ExprVarArgs[]): WindowNode;
+    orderby(...expr: ExprVarArgs[]): WindowNode;
     /**
      * Return an updated window with the given rows frame.
      * @param {FrameExtent} extent The row-based window frame extent.
@@ -72,10 +72,10 @@ export class WindowNode extends ExprNode {
 export class WindowFunctionNode extends FunctionNode {
     /**
      * Instantiate a window function call node.
-     * @param {import('../types.js').WindowFunctionName} name The function name.
+     * @param {WindowFunctionName} name The function name.
      * @param {ExprNode[]} [args=[]] The function arguments.
      */
-    constructor(name: import("../types.js").WindowFunctionName, args?: ExprNode[]);
+    constructor(name: WindowFunctionName, args?: ExprNode[]);
 }
 export class WindowDefNode extends SQLNode {
     /**
@@ -118,16 +118,16 @@ export class WindowDefNode extends SQLNode {
     over(name: string): WindowDefNode;
     /**
      * Return an updated window definition with the given partitions.
-     * @param {...import('../types.js').ExprVarArgs} expr The partition by criteria.
+     * @param {...ExprVarArgs} expr The partition by criteria.
      * @returns {WindowDefNode} A new window definition node.
      */
-    partitionby(...expr: import("../types.js").ExprVarArgs[]): WindowDefNode;
+    partitionby(...expr: ExprVarArgs[]): WindowDefNode;
     /**
      * Return an updated window definition with the given ordering.
-     * @param {...import('../types.js').ExprVarArgs} expr The order by criteria.
+     * @param {...ExprVarArgs} expr The order by criteria.
      * @returns {WindowDefNode} A new window definition node.
      */
-    orderby(...expr: import("../types.js").ExprVarArgs[]): WindowDefNode;
+    orderby(...expr: ExprVarArgs[]): WindowDefNode;
     /**
      * Return an updated window definition with the given rows frame.
      * @param {FrameExtent} extent The row-based window frame extent.
@@ -169,9 +169,12 @@ export class WindowFrameNode extends SQLNode {
      */
     readonly exclude: ExprNode;
 }
-export type FrameExtent = [any, any] | import("../types.js").ParamLike;
+export type FrameExtent = [any, any] | ParamLike;
 import { SQLNode } from './node.js';
 import { ExprNode } from './node.js';
 import { AggregateNode } from './aggregate.js';
+import type { ExprVarArgs } from '../types.js';
 import { FunctionNode } from './function.js';
+import type { WindowFunctionName } from '../types.js';
 import { ParamNode } from './param.js';
+import type { ParamLike } from '../types.js';

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

@@ -3,8 +3,12 @@ export class WithClauseNode extends SQLNode {
      * 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)
+     *  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: string, query: Query);
+    constructor(name: string, query: Query, materialized?: boolean | null);
     /**
      * The common table expression (CTE) name.
      * @type {string}
@@ -17,6 +21,12 @@ export class WithClauseNode extends SQLNode {
      * @readonly
      */
     readonly query: Query;
+    /**
+     * The common table expression (CTE) materialization flag.
+     * @type {boolean | null}
+     * @readonly
+     */
+    readonly materialized: boolean | null;
 }
 import { SQLNode } from './node.js';
 import { Query } from './query.js';