@uwdata/mosaic-sql 0.17.0 → 0.19.0

package/src/functions/interval.ts

@@ -0,0 +1,74 @@
+import { IntervalNode } from '../ast/interval.js';
+
+/**
+ * Create a new interval.
+ * @param unit The interval unit, such as day or year.
+ * @param steps The number of interval unit steps.
+ */
+export function interval(unit: string, steps: number) {
+  return new IntervalNode(unit, steps);
+}
+
+/**
+ * Create a new years interval.
+ * @param steps The number of years.
+ */
+export function years(steps: number) {
+  return interval('YEARS', steps);
+}
+
+/**
+ * Create a new months interval.
+ * @param steps The number of months.
+ */
+export function months(steps: number) {
+  return interval('MONTHS', steps);
+}
+
+/**
+ * Create a new days interval.
+ * @param steps The number of days.
+ */
+export function days(steps: number) {
+  return interval('DAYS', steps);
+}
+
+/**
+ * Create a new hours interval.
+ * @param steps The number of hours.
+ */
+export function hours(steps: number) {
+  return interval('HOURS', steps);
+}
+
+/**
+ * Create a new minutes interval.
+ * @param steps The number of minutes.
+ */
+export function minutes(steps: number) {
+  return interval('MINUTES', steps);
+}
+
+/**
+ * Create a new seconds interval.
+ * @param steps The number of seconds.
+ */
+export function seconds(steps: number) {
+  return interval('SECONDS', steps);
+}
+
+/**
+ * Create a new milliseconds interval.
+ * @param steps The number of milliseconds.
+ */
+export function milliseconds(steps: number) {
+  return interval('MILLISECONDS', steps);
+}
+
+/**
+ * Create a new microseconds interval.
+ * @param steps The number of microseconds.
+ */
+export function microseconds(steps: number) {
+  return interval('MICROSECONDS', steps);
+}

package/src/functions/list.ts

@@ -0,0 +1,63 @@
+import type { ExprValue } from "../types.js";
+import { asLiteral, asNode } from "../util/ast.js";
+import { argsList, fn } from "../util/function.js";
+import { ListNode } from "../ast/list.js";
+
+/**
+ * Create a List containing the argument values.
+ * @param values
+ */
+export function list(values: ExprValue[]) {
+  return new ListNode(argsList(values).map(asLiteral));
+}
+
+/**
+ * Convert a single value or an array of values to either a ListNode if the input
+ * is an array, or a single ExprNode if it is a single value. A single string will
+ * be interpreted as a column reference.
+ * @param values
+ */
+function asList(values: ExprValue | ExprValue[]) {
+  return Array.isArray(values) ? list(values) : asNode(values);
+}
+
+/**
+ * Function that returns true if the list contains the element,
+ * false otherwise. If the first argument is a string, it is
+ * interpreted as a column reference, otherwise it is coerced
+ * to a list.
+ * @param list1
+ * @param element
+ */
+export function listContains(
+  list1: ExprValue | ExprValue[],
+  element: ExprValue,
+) {
+  return fn("list_contains", asList(list1), asLiteral(element));
+}
+
+/**
+ * Function that returns true if all elements of list2 exist in list1,
+ * false otherwise.
+ * @param list1
+ * @param list2
+ */
+export function listHasAll(
+  list1: ExprValue | ExprValue[],
+  list2: ExprValue | ExprValue[],
+) {
+  return fn("list_has_all", asList(list1), asList(list2));
+}
+
+/**
+ * Function that returns true if any elements exist in both lists,
+ * false otherwise.
+ * @param list1
+ * @param list2
+ */
+export function listHasAny(
+  list1: ExprValue | ExprValue[],
+  list2: ExprValue | ExprValue[],
+) {
+  return fn("list_has_any", asList(list1), asList(list2));
+}

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])) {