@uwdata/mosaic-sql 0.11.0 → 0.12.1

package/src/functions/operators.js

@@ -0,0 +1,298 @@
+import { BetweenOpNode, NotBetweenOpNode } from '../ast/between-op.js';
+import { BinaryOpNode } from '../ast/binary-op.js';
+import { InOpNode } from '../ast/in-op.js';
+import { AndNode, OrNode } from '../ast/logical-op.js';
+import { UnaryOpNode, UnaryPosftixOpNode } from '../ast/unary-op.js';
+import { asNode } from '../util/ast.js';
+import { exprList } from '../util/function.js';
+
+function unaryOp(op, expr) {
+  return new UnaryOpNode(op, asNode(expr));
+}
+
+function unaryPostfixOp(op, expr) {
+  return new UnaryPosftixOpNode(op, asNode(expr));
+}
+
+function binaryOp(op, left, right) {
+  return new BinaryOpNode(op, asNode(left), asNode(right));
+}
+
+function betweenOp(expr, extent, negate = false) {
+  const Op = negate ? NotBetweenOpNode : BetweenOpNode;
+  return new Op(asNode(expr), extent?.map(asNode));
+}
+
+/**
+ * Logical and (AND) operator.
+ * @param {...import('../types.js').ExprVarArgs} clauses The input expressions.
+ * @returns {AndNode}
+ */
+export function and(...clauses) {
+  return new AndNode(exprList(clauses));
+}
+
+/**
+ * Logical or (OR) operator.
+ * @param {...import('../types.js').ExprVarArgs} clauses The input expressions.
+ * @returns {OrNode}
+ */
+export function or(...clauses) {
+  return new OrNode(exprList(clauses));
+}
+
+/**
+ * Logical not (NOT) operator.
+ * @param {import('../types.js').ExprValue} expr The expression to negate.
+ * @returns {UnaryOpNode}
+ */
+export function not(expr) {
+  return unaryOp('NOT', expr);
+}
+
+/**
+ * Null check (IS NULL) operator.
+ * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @returns {UnaryPosftixOpNode}
+ */
+export function isNull(expr) {
+  return unaryPostfixOp('IS NULL', expr);
+}
+
+/**
+ * Non-null check (IS NOT NULL) operator.
+ * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @returns {UnaryPosftixOpNode}
+ */
+export function isNotNull(expr) {
+  return unaryPostfixOp('IS NOT NULL', expr);
+}
+
+/**
+ * Bitwise not (~) operator.
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {UnaryOpNode}
+ */
+export function bitNot(expr) {
+  return unaryOp('~', expr);
+}
+
+/**
+ * Bitwise and (&) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function bitAnd(left, right) {
+  return binaryOp('&', left, right);
+}
+
+/**
+ * Bitwise or (|) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function bitOr(left, right) {
+  return binaryOp('|', left, right);
+}
+
+/**
+ * Bit shift left (<<) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function bitLeft(left, right) {
+  return binaryOp('<<', left, right);
+}
+
+/**
+ * Bit shift right (>>) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function bitRight(left, right) {
+  return binaryOp('>>', left, right);
+}
+
+/**
+ * Addition (+) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function add(left, right) {
+  return binaryOp('+', left, right);
+}
+
+/**
+ * Subtraction (-) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function sub(left, right) {
+  return binaryOp('-', left, right);
+}
+
+/**
+ * Multiplication (*) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function mul(left, right) {
+  return binaryOp('*', left, right);
+}
+
+/**
+ * Division (/) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function div(left, right) {
+  return binaryOp('/', left, right);
+}
+
+/**
+ * Integer division (//) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function idiv(left, right) {
+  return binaryOp('//', left, right);
+}
+
+/**
+ * Modulo (%) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function mod(left, right) {
+  return binaryOp('%', left, right);
+}
+
+/**
+ * Exponentiation (**) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function pow(left, right) {
+  return binaryOp('**', left, right);
+}
+
+/**
+ * Equality comparision (=) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function eq(left, right) {
+  return binaryOp('=', left, right);
+}
+
+/**
+ * Non-equality comparision (<>) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function neq(left, right) {
+  return binaryOp('<>', left, right);
+}
+
+/**
+ * Less-than comparision (<) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function lt(left, right) {
+  return binaryOp('<', left, right);
+}
+
+/**
+ * Greater-than comparision (>) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function gt(left, right) {
+  return binaryOp('>', left, right);
+}
+
+/**
+ * Less-than or equal comparision (<=) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function lte(left, right) {
+  return binaryOp('<=', left, right);
+}
+
+/**
+ * Greater-than or equal comparision (>=) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function gte(left, right) {
+  return binaryOp('>=', left, right);
+}
+
+/**
+ * Null-inclusive non-equality (IS DISTINCT FROM) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function isDistinct(left, right) {
+  return binaryOp('IS DISTINCT FROM', left, right);
+}
+
+/**
+ * Null-inclusive equality (IS NOT DISTINCT FROM) operator.
+ * @param {import('../types.js').ExprValue} left The left argument.
+ * @param {import('../types.js').ExprValue} right The right argument.
+ * @returns {BinaryOpNode}
+ */
+export function isNotDistinct(left, right) {
+  return binaryOp('IS NOT DISTINCT FROM', left, right);
+}
+
+/**
+ * Range inclusion (BETWEEN) operator.
+ * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @param {import('../types.js').ExprValue[]} extent The range extent.
+ * @returns {BetweenOpNode}
+ */
+export function isBetween(expr, extent) {
+  return betweenOp(expr, extent, false);
+}
+
+/**
+ * Range exclusion (NOT BETWEEN) operator.
+ * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @param {import('../types.js').ExprValue[]} extent The range extent.
+ * @returns {NotBetweenOpNode}
+ */
+export function isNotBetween(expr, extent) {
+  return betweenOp(expr, extent, true);
+}
+
+/**
+ * Set inclusion (IN) operator.
+ * @param {import('../types.js').ExprValue} expr The expression to test.
+ * @param {import('../types.js').ExprValue[]} values The included values.
+ * @returns {InOpNode}
+ */
+export function isIn(expr, values) {
+  return new InOpNode(asNode(expr), values.map(asNode));
+}

package/src/functions/order-by.js

@@ -0,0 +1,24 @@
+import { OrderByNode } from '../ast/order-by.js';
+import { asNode } from '../util/ast.js';
+
+/**
+ * Indicate ascending sort order for an expression.
+ * @param {import('../types.js').ExprValue} expr An expression to order by.
+ * @param {boolean | undefined} [nullsFirst] Flag indicating if null values
+ *  should be sorted first.
+ * @returns {OrderByNode}
+ */
+export function asc(expr, nullsFirst) {
+  return new OrderByNode(asNode(expr), false, nullsFirst);
+}
+
+/**
+ * Indicate descending sort order for an expression.
+ * @param {import('../types.js').ExprValue} expr An expression to order by.
+ * @param {boolean | undefined} [nullsFirst] Flag indicating if null values
+ *  should be sorted first.
+ * @returns {OrderByNode}
+ */
+export function desc(expr, nullsFirst) {
+  return new OrderByNode(asNode(expr), true, nullsFirst);
+}

package/src/functions/spatial.js

@@ -0,0 +1,56 @@
+import { FunctionNode } from '../ast/function.js';
+import { fn } from '../util/function.js';
+
+/**
+ * Function that converts geometry data to GeoJSON format.
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {FunctionNode}
+ */
+export function geojson(expr) {
+  return fn('st_asgeojson', expr);
+}
+
+/**
+ * Function that returns a spatial x position (using ST_X).
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {FunctionNode}
+ */
+export function x(expr) {
+  return fn('st_x', expr);
+}
+
+/**
+ * Function that returns a spatial y position (using ST_Y).
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {FunctionNode}
+ */
+export function y(expr) {
+  return fn('st_y', expr);
+}
+
+/**
+ * Function that returns the centroid point for geometry data.
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {FunctionNode}
+ */
+export function centroid(expr) {
+  return fn('st_centroid', expr);
+}
+
+/**
+ * Function that returns the centroid x-coordinate for geometry data.
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {FunctionNode}
+ */
+export function centroidX(expr) {
+  return x(centroid(expr));
+}
+
+/**
+ * Function that returns yhe centroid y-coordinate for geometry data.
+ * @param {import('../types.js').ExprValue} expr The input expression.
+ * @returns {FunctionNode}
+ */
+export function centroidY(expr) {
+  return y(centroid(expr));
+}

package/src/functions/sql-template-tag.js

@@ -0,0 +1,51 @@
+/* eslint-disable jsdoc/no-undefined-types */
+import { FragmentNode } from '../ast/fragment.js';
+import { isNode } from '../ast/node.js';
+import { ParamNode } from '../ast/param.js';
+import { VerbatimNode } from '../ast/verbatim.js';
+import { isParamLike, isString } from '../util/type-check.js';
+import { literal } from './literal.js';
+
+/**
+ * @typedef {import('../ast/node.js').ExprNode
+ *  | import('../types.js').ParamLike
+ *  | string | number | boolean | Date
+ * } TemplateValue
+ */
+
+/**
+ * Template tag function for SQL fragments. Interpolated values
+ * may be strings, other SQL expression objects (such as column
+ * references), primitive values, or dynamic parameters.
+ * @param {TemplateStringsArray} strings Template string constants.
+ * @param {...TemplateValue} exprs Template expression values.
+ */
+export function sql(strings, ...exprs) {
+  return new FragmentNode(parseSQL(strings, exprs));
+}
+
+function parseSQL(strings, exprs) {
+  const spans = [strings[0]];
+  const n = exprs.length;
+  for (let i = 0, k = 0; i < n;) {
+    const e = exprs[i];
+    if (isNode(e)) {
+      spans[++k] = e;
+    } else if (isParamLike(e)) {
+      spans[++k] = new ParamNode(e);
+    } else {
+      spans[k] += isString(e) ? e : literal(e);
+    }
+    const s = strings[++i];
+    if (isNode(spans[k])) {
+      spans[++k] = s;
+    } else {
+      spans[k] += s;
+    }
+  }
+
+   // remove empty strings and preserve verbatim content
+  return spans
+    .filter(s => s)
+    .map(s => isString(s) ? new VerbatimNode(s) : s);
+}

package/src/functions/string.js

@@ -0,0 +1,82 @@
+import { FunctionNode } from '../ast/function.js';
+import { asLiteral } from '../util/ast.js';
+import { argsList, fn } from '../util/function.js';
+
+function strFn(name, expr, ...args) {
+  return fn(name, expr, ...(argsList(args).map(asLiteral)));
+}
+
+/**
+ * Function that returns true if a string contains a regexp pattern,
+ * false otherwise.
+ * @param {import('../types.js').ExprValue} string The string match against.
+ * @param {import('../types.js').StringValue} pattern The regular expression pattern to match.
+ * @param {import('../types.js').StringValue} [options] Regular expression options:
+ *  'c': case-sensitive matching
+ *  'i': case-insensitive matching
+ *  'l': match literals instead of regular expression tokens
+ *  'm', 'n', 'p': newline sensitive matching
+ *  'g': global replace, only available for regexp_replace
+ *  's': non-newline sensitive matching
+ * @returns {FunctionNode}
+ */
+export function regexp_matches(string, pattern, options) {
+  return strFn('regexp_matches', string, pattern, options);
+}
+
+/**
+ * Function that returns true if search_string is found within string.
+ * @param {import('../types.js').ExprValue} string The string to match against.
+ * @param {import('../types.js').StringValue} search_string The substring to search for.
+ * @returns {FunctionNode}
+ */
+export function contains(string, search_string) {
+  return strFn('contains', string, search_string);
+}
+
+/**
+ * Function that returns true if string begins with search_string.
+ * @param {import('../types.js').ExprValue} string The string to match against.
+ * @param {import('../types.js').StringValue} search_string The substring to search for.
+ * @returns {FunctionNode}
+ */
+export function prefix(string, search_string) {
+  return strFn('starts_with', string, search_string);
+}
+
+/**
+ * Function that returns true if string ends with search_string.
+ * @param {import('../types.js').ExprValue} string The string to match against.
+ * @param {import('../types.js').StringValue} search_string The substring to search for.
+ * @returns {FunctionNode}
+ */
+export function suffix(string, search_string) {
+  return strFn('ends_with', string, search_string);
+}
+
+/**
+ * Function that converts string to lower case.
+ * @param {import('../types.js').ExprValue} string The string to convert.
+ * @returns {FunctionNode}
+ */
+export function lower(string) {
+  return strFn('lower', string);
+}
+
+/**
+ * Function that converts string to upper case.
+ * @param {import('../types.js').ExprValue} string The string to convert.
+ * @returns {FunctionNode}
+ */
+export function upper(string) {
+  return strFn('upper', string);
+}
+
+/**
+ * Function that returns the number of characters in string.
+ * @param {import('../types.js').ExprValue} value The string to measure.
+ * @returns {FunctionNode}
+ */
+export function length(value) {
+  return strFn('length', value);
+}

package/src/functions/table-ref.js

@@ -0,0 +1,14 @@
+import { TableRefNode } from '../ast/table-ref.js';
+import { exprList } from '../util/function.js';
+
+/**
+ * Returns a named table or view reference.
+ * @param {...(string | string[])} ids Table and namespace identifiers.
+ *  For example 'name' or ['schema', 'name'].
+ * @returns {TableRefNode | undefined} A table reference, or undefined
+ *  if the input identifier list is empty.
+ */
+export function tableRef(...ids) {
+  const args = exprList(ids, String);
+  return args?.length ? new TableRefNode(args) : undefined;
+}

package/src/functions/window.js

@@ -0,0 +1,121 @@
+import { WindowNode } from '../ast/window.js';
+import { winFn } from '../util/function.js';
+
+/**
+ * Create a window function that returns the number of the current row
+ * within the partition, counting from 1.
+ * @returns {WindowNode}
+ */
+export function row_number() {
+  return winFn('row_number');
+}
+
+/**
+ * Create a window function that returns the rank of the current row with gaps.
+ * This is the same as the row_number of its first peer.
+ * @returns {WindowNode}
+ */
+export function rank() {
+  return winFn('rank');
+}
+
+/**
+ * Create a window function that returns the rank of the current row without
+ * gaps. The function counts peer groups.
+ * @returns {WindowNode}
+ */
+export function dense_rank() {
+  return winFn('dense_rank');
+}
+
+/**
+ * Create a window function that returns the relative rank of the current row.
+ * Computed as (rank() - 1) / (total partition rows - 1).
+ * @returns {WindowNode}
+ */
+export function percent_rank() {
+  return winFn('percent_rank');
+}
+
+/**
+ * Create a window function that returns the cumulative distribution. Computed
+ * as (number of preceding or peer partition rows) / total partition rows.
+ * @returns {WindowNode}
+ */
+export function cume_dist() {
+  return winFn('cume_dist');
+}
+
+/**
+ * Create a window function that returns an integer ranging from 1 to the
+ * argument value, dividing the partition as equally as possible.
+ * @param {import('../types.js').NumberValue} num_buckets The number of
+ *  quantile buckets.
+ * @returns {WindowNode}
+ */
+export function ntile(num_buckets) {
+  return winFn('ntile', num_buckets);
+}
+
+/**
+ * Create a window function that returns the expression evaluated at the row
+ * that is offset rows before the current row within the partition.
+ * If there is no such row, instead return default (which must be of the same
+ * type as the expression). Both offset and default are evaluated with respect
+ * to the current row. If omitted, offset defaults to 1 and default to null.
+ * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {import('../types.js').NumberValue} [offset] The row offset
+ *  (default `1`).
+ * @param {*} [defaultValue] The default value (default `null`).
+ * @returns {WindowNode}
+ */
+export function lag(expr, offset, defaultValue){
+  return winFn('lag', expr, offset, defaultValue);
+}
+
+/**
+ * Create a window function that returns the expression evaluated at the row
+ * that is offset rows after the current row within the partition.
+ * If there is no such row, instead return default (which must be of the same
+ * type as the expression). Both offset and default are evaluated with respect
+ * to the current row. If omitted, offset defaults to 1 and default to null.
+ * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {import('../types.js').NumberValue} [offset] The row offset
+ *  (default `1`).
+ * @param {*} [defaultValue] The default value (default `null`).
+ * @returns {WindowNode}
+ */
+export function lead(expr, offset, defaultValue){
+  return winFn('lead', expr, offset, defaultValue);
+}
+
+/**
+ * Create a window function that returns the expression evaluated at the row
+ * that is the first row of the window frame.
+ * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @returns {WindowNode}
+ */
+export function first_value(expr) {
+  return winFn('first_value', expr);
+}
+
+/**
+ * Create a window function that returns the expression evaluated at the row
+ * that is the last row of the window frame.
+ * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @returns {WindowNode}
+ */
+export function last_value(expr) {
+  return winFn('last_value', expr);
+}
+
+/**
+ * Create a window function that returns the expression evaluated at the
+ * nth row of the window frame (counting from 1), or null if no such row.
+ * @param {import('../types.js').ExprValue} expr The expression to evaluate.
+ * @param {import('../types.js').NumberValue} nth The 1-based window frame index.
+ * @returns {WindowNode}
+ */
+export function nth_value(expr, nth) {
+  return winFn('nth_value', expr, nth);
+}

package/src/index-types.ts

@@ -0,0 +1,2 @@
+export * from './index.js';
+export * from './types.js';