@uwdata/mosaic-sql 0.17.0 → 0.19.0

package/src/transforms/util/{time-interval.js → time-interval.ts}

@@ -1,6 +1,18 @@
-/** @import { TimeUnit } from '../../types.js' */
 import { binStep } from './bin-step.js';
 
+export type DateTimeValue = Date | number;
+
+export type TimeUnit =
+  | 'year'
+  | 'quarter'
+  | 'month'
+  | 'day'
+  | 'hour'
+  | 'minute'
+  | 'second'
+  | 'millisecond'
+  | 'microsecond';
+
 const YEAR = 'year';
 const MONTH = 'month';
 const DAY = 'day';
@@ -18,10 +30,7 @@ const durationWeek = durationDay * 7;
 const durationMonth = durationDay * 30;
 const durationYear = durationDay * 365;
 
-/**
- * @type {Array<{unit: TimeUnit, step: number, dt: number}>}
- */
-const units = [
+const units: {unit: TimeUnit, step: number, dt: number}[] = [
   { unit: SECOND, step:  1, dt: durationSecond },
   { unit: SECOND, step:  5, dt: durationSecond * 5 },
   { unit: SECOND, step: 15, dt: durationSecond * 15 },
@@ -44,18 +53,21 @@ const units = [
 /**
  * Determine a time interval for binning based on provided min
  * and max timestamps and approximate step count.
- * @param {Date|number} min The minimum timestamp value.
- * @param {Date|number} max The maximum timestamp value.
- * @param {number} steps The approximate number of bins desired.
- * @returns {{ unit: TimeUnit, step: number }}
+ * @param min The minimum timestamp value.
+ * @param max The maximum timestamp value.
+ * @param steps The approximate number of bins desired.
  */
-export function timeInterval(min, max, steps) {
+export function timeInterval(
+  min: DateTimeValue,
+  max: DateTimeValue,
+  steps: number
+): ({ unit: TimeUnit, step: number }) {
   const span = +max - +min;
   const t = span / steps; // target step size duration
   const i = bisect(units, t, v => v.dt);
-  /** @type {TimeUnit} */
-  let unit;
-  let step;
+
+  let unit: TimeUnit;
+  let step: number;
 
   if (i === units.length) {
     unit = YEAR;
@@ -72,15 +84,14 @@ export function timeInterval(min, max, steps) {
 
 /**
  * Perform a binary search.
- * @template I, T
- * @param {I[]} a The array to search.
- * @param {T} x The target value
- * @param {(item: I) => T} value A value accessor
- * @returns {number} The search result array index.
+ * @param a The array to search.
+ * @param x The target value.
+ * @param value A value accessor.
+ * @returns The search result array index.
  */
-function bisect(a, x, value) {
-  const compare1 = (a, b) => a - b;
-  const compare2 = (d, x) => compare1(value(d), x);
+function bisect<I, T>(a: I[], x: T, value: (item: I) => T) {
+  const compare1 = (a: T, b: T) => Number(a) - Number(b);
+  const compare2 = (d: I, x: T) => compare1(value(d), x);
 
   let lo = 0;
   let hi = a.length;

package/src/types.ts

@@ -9,7 +9,7 @@ import { WithClauseNode } from './ast/with.js';
  */
 export interface ParamLike {
   /** The current parameter value. */
-  value: any;
+  value: unknown;
   /** Add an event listener callback. */
   addEventListener(type: string, callback: EventCallback): void;
   /** Remove an event listener callback. */
@@ -19,7 +19,7 @@ export interface ParamLike {
 /**
  * Expression value input to SQL builder method.
  */
-export type ExprValue = ExprNode | ParamLike | string | number | boolean | Date;
+export type ExprValue = ExprNode | ParamLike | string | number | boolean | Date | null;
 
 /**
  * Expression values that may be nested in arrays.
@@ -39,22 +39,7 @@ export type NumberValue = ExprNode | ParamLike | number;
 /**
  * Event listener callback function.
  */
-export type EventCallback = <T>(value: any) => Promise<T> | undefined;
-
-/**
- * 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;
+export type EventCallback = <T>(value: unknown) => Promise<T> | undefined;
 
 /** Valid window function names. */
 export type WindowFunctionName =
@@ -74,6 +59,7 @@ export type WindowFunctionName =
 export type MaybeArray<T> = T | T[];
 
 export type SelectEntry =
+  | null
   | string
   | ColumnRefNode
   | [string, ExprNode]
@@ -96,26 +82,6 @@ export type FromEntry =
 
 export type FromExpr = MaybeArray<FromEntry>;
 
-export type FilterExpr = MaybeArray<string | ExprNode>;
+export type FilterExpr = MaybeArray<string | boolean | ExprNode>;
 export type GroupByExpr = MaybeArray<string | ExprNode>;
 export type OrderByExpr = MaybeArray<string | ExprNode>;
-
-export type TimeUnit =
-  | 'year'
-  | 'quarter'
-  | 'month'
-  | 'day'
-  | 'hour'
-  | 'minute'
-  | 'second'
-  | 'millisecond'
-  | 'microsecond';
-
-export type FrameValue =  ExprNode | number | null;
-
-export type FrameExtent = [FrameValue, FrameValue] | ParamLike;
-
-export type FrameScope =
-  | 'PRECEDING'
-  | 'FOLLOWING'
-  | 'CURRENT ROW';

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}

@@ -23,6 +23,7 @@ import {
   SET_OPERATION,
   UNARY_OPERATOR,
   UNARY_POSTFIX_OPERATOR,
+  UNNEST,
   WHEN,
   WINDOW,
   WINDOW_CLAUSE,
@@ -33,7 +34,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'],
@@ -58,6 +59,7 @@ export const recurse = {
   [SET_OPERATION]: ['queries', '_orderby'],
   [UNARY_OPERATOR]: ['expr'],
   [UNARY_POSTFIX_OPERATOR]: ['expr'],
+  [UNNEST]: ['expr'],
   [WHEN]: ['when', 'then'],
   [WINDOW]: ['func', 'def'],
   [WINDOW_CLAUSE]: ['def'],

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);