@uwdata/mosaic-sql 0.17.0 → 0.18.0

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

@@ -5,19 +5,17 @@ import { VerbatimNode } from '../ast/verbatim.js';
  * Return a SQL AST node for a literal value. The supported types are
  * null, string, number, boolean, Date, and RegExp. Otherwise, the
  * input value will be directly coerced to a string.
- * @param {*} value The literal value.
- * @returns {LiteralNode}
+ * @param value The literal value.
  */
-export function literal(value) {
+export function literal(value: unknown) {
   return new LiteralNode(value);
 }
 
 /**
  * Return a SQL AST node for verbatim string content.
- * @param {string} value The verbatim value.
- * @param {string} [hint] A type hint for analyzing verbatim content.
- * @returns {VerbatimNode}
+ * @param value The verbatim value.
+ * @param hint A type hint for analyzing verbatim content.
  */
-export function verbatim(value, hint) {
+export function verbatim(value: string, hint?: string) {
   return new VerbatimNode(value, hint);
 }

package/src/functions/numeric.ts

@@ -0,0 +1,125 @@
+import type { ExprValue } from '../types.js';
+import { fn } from '../util/function.js';
+
+/**
+ * Return true if the floating point value is not a number, false otherwise.
+ * @param expr The input number.
+ */
+export function isNaN(expr: ExprValue) {
+  return fn('isnan', expr);
+}
+
+/**
+ * Return true if the floating point value is finite, false otherwise.
+ * @param expr The input number.
+ */
+export function isFinite(expr: ExprValue) {
+  return fn('isfinite', expr);
+}
+
+/**
+ * Return true if the floating point value is infinite, false otherwise.
+ * @param expr The input number.
+ */
+export function isInfinite(expr: ExprValue) {
+  return fn('isinf', expr);
+}
+
+/**
+ * Selects the largest value.
+ * @param expr The input expressions.
+ */
+export function greatest(...expr: ExprValue[]) {
+  return fn('greatest', ...expr);
+}
+
+/**
+ * Selects the smallest value.
+ * @param expr The input expressions.
+ */
+export function least(...expr: ExprValue[]) {
+  return fn('least', ...expr);
+}
+
+/**
+ * Compute the exponentional function `e ** expr`.
+ * @param expr The input number.
+ */
+export function exp(expr: ExprValue) {
+  return fn('exp', expr);
+}
+
+/**
+ * Compute a base 10 logarithm.
+ * @param expr The input number.
+ */
+export function log(expr: ExprValue) {
+  return fn('log', expr);
+}
+
+/**
+ * Compute a natural logarithm.
+ * @param expr The input number.
+ */
+export function ln(expr: ExprValue) {
+  return fn('ln', expr);
+}
+
+/**
+ * Compute the sign of a number.
+ * @param expr The input number.
+ */
+export function sign(expr: ExprValue) {
+  return fn('sign', expr);
+}
+
+/**
+ * Compute the absolute value of a number.
+ * @param expr The input number.
+ */
+export function abs(expr: ExprValue) {
+  return fn('abs', expr);
+}
+
+/**
+ * Compute the square root of a number.
+ * @param expr The input number.
+ */
+export function sqrt(expr: ExprValue) {
+  return fn('sqrt', expr);
+}
+
+/**
+ * Rounds the number up.
+ * @param expr The input number.
+ */
+export function ceil(expr: ExprValue) {
+  return fn('ceil', expr);
+}
+
+/**
+ * Rounds the number down.
+ * @param expr The input number.
+ */
+export function floor(expr: ExprValue) {
+  return fn('floor', expr);
+}
+
+/**
+ * Round to the given decimal places.
+ * @param expr The input number.
+ * @param places The decimal places.
+ *  Negative values are allowed, to round to tens, hundreds, etc.
+ *  If unspecified, defaults to zero.
+ */
+export function round(expr: ExprValue, places?: ExprValue) {
+  return fn('round', expr, places);
+}
+
+/**
+ * Truncates the number.
+ * @param expr The input number.
+ */
+export function trunc(expr: ExprValue) {
+  return fn('trunc', expr);
+}

package/src/functions/operators.ts

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

package/src/functions/order-by.ts

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

package/src/functions/spatial.ts

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

package/src/functions/{sql-template-tag.js → sql-template-tag.ts}

@@ -1,7 +1,5 @@
-/**
- * @import { ExprNode } from '../ast/node.js'
- * @import { ParamLike } from '../types.js'
- */
+import type { ExprNode } from '../ast/node.js';
+import type { ParamLike } from '../types.js';
 import { FragmentNode } from '../ast/fragment.js';
 import { isNode } from '../ast/node.js';
 import { ParamNode } from '../ast/param.js';
@@ -9,23 +7,28 @@ import { VerbatimNode } from '../ast/verbatim.js';
 import { isParamLike, isString } from '../util/type-check.js';
 import { literal } from './literal.js';
 
-/**
- * @typedef { ExprNode | ParamLike | string | number | boolean | Date } TemplateValue
- */
+export type TemplateValue =
+  | ExprNode
+  | ParamLike
+  | string
+  | number
+  | boolean
+  | Date
+  ;
 
 /**
  * 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.
+ * @param strings Template string constants.
+ * @param exprs Template expression values.
  */
-export function sql(strings, ...exprs) {
+export function sql(strings: TemplateStringsArray, ...exprs: TemplateValue[]) {
   return new FragmentNode(parseSQL(strings, exprs));
 }
 
-function parseSQL(strings, exprs) {
-  const spans = [strings[0]];
+function parseSQL(strings: TemplateStringsArray, exprs: TemplateValue[]) {
+  const spans: (string | ExprNode)[] = [strings[0]];
   const n = exprs.length;
   for (let i = 0, k = 0; i < n;) {
     const e = exprs[i];
@@ -34,7 +37,7 @@ function parseSQL(strings, exprs) {
     } else if (isParamLike(e)) {
       spans[++k] = new ParamNode(e);
     } else {
-      spans[k] += isString(e) ? e : literal(e);
+      spans[k] += isString(e) ? e : `${literal(e)}`;
     }
     const s = strings[++i];
     if (isNode(spans[k])) {

package/src/functions/string.ts

@@ -0,0 +1,79 @@
+import type { ExprValue, StringValue } from '../types.js';
+import { asLiteral } from '../util/ast.js';
+import { argsList, fn } from '../util/function.js';
+
+function strFn(name: string, expr: ExprValue, ...args: unknown[]) {
+  return fn(name, expr, ...(argsList(args).map(asLiteral)));
+}
+
+/**
+ * Function that returns true if a string contains a regexp pattern,
+ * false otherwise.
+ * @param string The string match against.
+ * @param pattern The regular expression pattern to match.
+ * @param 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
+ */
+export function regexp_matches(
+  string: ExprValue,
+  pattern: StringValue,
+  options?: StringValue
+) {
+  return strFn('regexp_matches', string, pattern, options);
+}
+
+/**
+ * Function that returns true if search_string is found within string.
+ * @param string The string to match against.
+ * @param search_string The substring to search for.
+ */
+export function contains(string: ExprValue, search_string: StringValue) {
+  return strFn('contains', string, search_string);
+}
+
+/**
+ * Function that returns true if string begins with search_string.
+ * @param string The string to match against.
+ * @param search_string The substring to search for.
+ */
+export function prefix(string: ExprValue, search_string: StringValue) {
+  return strFn('starts_with', string, search_string);
+}
+
+/**
+ * Function that returns true if string ends with search_string.
+ * @param string The string to match against.
+ * @param search_string The substring to search for.
+ */
+export function suffix(string: ExprValue, search_string: StringValue) {
+  return strFn('ends_with', string, search_string);
+}
+
+/**
+ * Function that converts string to lower case.
+ * @param string The string to convert.
+ */
+export function lower(string: ExprValue) {
+  return strFn('lower', string);
+}
+
+/**
+ * Function that converts string to upper case.
+ * @param string The string to convert.
+ */
+export function upper(string: ExprValue) {
+  return strFn('upper', string);
+}
+
+/**
+ * Function that returns the number of characters in string.
+ * @param value The string to measure.
+ */
+export function length(value: ExprValue) {
+  return strFn('length', value);
+}

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

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

package/src/functions/util.ts

@@ -0,0 +1,10 @@
+import type { ExprValue } from '../types.js';
+import { fn } from '../util/function.js';
+
+/**
+ * Returns the first non-null argument.
+ * @param expr The input expressions.
+ */
+export function coalesce(...expr: ExprValue[]) {
+  return fn('coalesce', ...expr);
+}