@uwdata/mosaic-sql 0.10.0 → 0.12.0

package/src/aggregates.js

@@ -1,185 +0,0 @@
-import { SQLExpression, parseSQL, sql } from './expression.js';
-import { asColumn } from './ref.js';
-import { repeat } from './repeat.js';
-import { literalToSQL } from './to-sql.js';
-import { WindowFunction } from './windows.js';
-
-/**
- * Tag function for SQL aggregate expressions. Interpolated values
- * may be strings, other SQL expression objects (such as column
- * references), or parameterized values.
- */
-export function agg(strings, ...exprs) {
-  return sql(strings, ...exprs).annotate({ aggregate: true });
-}
-
-/**
- * Base class for individual aggregate functions.
- * Most callers should use a dedicated aggregate function
- * rather than instantiate this class.
- */
-export class AggregateFunction extends SQLExpression {
-  /**
-   * Create a new AggregateFunction instance.
-   * @param {*} op The aggregate operation.
-   * @param {*} [args] The aggregate function arguments.
-   * @param {*} [type] The SQL data type to cast to.
-   * @param {boolean} [isDistinct] Flag indicating if this is a distinct value aggregate.
-   * @param {*} [filter] Filtering expression to apply prior to aggregation.
-   */
-  constructor(op, args, type, isDistinct, filter) {
-    args = (args || []).map(asColumn);
-    const { strings, exprs } = aggExpr(op, args, type, isDistinct, filter);
-    const { spans, cols } = parseSQL(strings, exprs);
-    super(spans, cols);
-    this.aggregate = op;
-    this.args = args;
-    this.type = type;
-    this.isDistinct = isDistinct;
-    this.filter = filter;
-  }
-
-  get basis() {
-    return this.column;
-  }
-
-  get label() {
-    const { aggregate: op, args, isDistinct } = this;
-    const dist = isDistinct ? 'DISTINCT' + (args.length ? ' ' : '') : '';
-    const tail = args.length ? `(${dist}${args.map(unquoted).join(', ')})` : '';
-    return `${op.toLowerCase()}${tail}`;
-  }
-
-  /**
-   * Return a new derived aggregate function over distinct values.
-   * @returns {AggregateFunction} A new aggregate function.
-   */
-  distinct() {
-    const { aggregate: op, args, type, filter } = this;
-    return new AggregateFunction(op, args, type, true, filter);
-  }
-
-  /**
-   * Return a new derived aggregate function that filters values.
-   * @param {*} filter The filter expresion.
-   * @returns {AggregateFunction} A new aggregate function.
-   */
-  where(filter) {
-    const { aggregate: op, args, type, isDistinct } = this;
-    return new AggregateFunction(op, args, type, isDistinct, filter);
-  }
-
-  /**
-   * Return a new window function over this aggregate.
-   * @returns {WindowFunction} A new aggregate function.
-   */
-  window() {
-    const { aggregate: op, args, type, isDistinct } = this;
-    const func = new AggregateFunction(op, args, null, isDistinct);
-    return new WindowFunction(op, func, type);
-  }
-
-  /**
-   * Return a window function over this aggregate with the given partitioning.
-   * @param {*} expr The grouping (partition by) criteria for the window function.
-   * @returns {WindowFunction} A new window function.
-   */
-  partitionby(...expr) {
-    return this.window().partitionby(...expr);
-  }
-
-  /**
-   * Return a window function over this aggregate with the given ordering.
-   * @param {*} expr The sorting (order by) criteria for the window function.
-   * @returns {WindowFunction} A new window function.
-   */
-  orderby(...expr) {
-    return this.window().orderby(...expr);
-  }
-
-  /**
-   * Return a window function over this aggregate with the given row frame.
-   * @param {(number|null)[] | import('./expression.js').ParamLike} frame The row-based window frame.
-   * @returns {WindowFunction} A new window function.
-   */
-  rows(frame) {
-    return this.window().rows(frame);
-  }
-
-  /**
-   * Return a window function over this aggregate with the given range frame.
-   * @param {(number|null)[] | import('./expression.js').ParamLike} frame The range-based window frame.
-   * @returns {WindowFunction} A new window function.
-   */
-  range(frame) {
-    return this.window().range(frame);
-  }
-}
-
-function aggExpr(op, args, type, isDistinct, filter) {
-  const close = `)${type ? `::${type}` : ''}`;
-  let strings = [`${op}(${isDistinct ? 'DISTINCT ' :''}`];
-  let exprs = [];
-  if (args.length) {
-    strings = strings.concat([
-      ...repeat(args.length - 1, ', '),
-      `${close}${filter ? ' FILTER (WHERE ' : ''}`,
-      ...(filter ? [')'] : [])
-    ]);
-    exprs = [...args, ...(filter ? [filter] : [])];
-  } else {
-    strings[0] += '*' + close;
-  }
-  return { exprs, strings };
-}
-
-function unquoted(value) {
-  const s = literalToSQL(value);
-  return s && s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1) : s
-}
-
-function aggf(op, type) {
-  return (...args) => new AggregateFunction(op, args, type);
-}
-
-export const count = aggf('COUNT', 'INTEGER');
-export const avg = aggf('AVG');
-export const mean = aggf('AVG');
-export const mad = aggf('MAD');
-export const max = aggf('MAX');
-export const min = aggf('MIN');
-export const sum = aggf('SUM', 'DOUBLE');
-export const product = aggf('PRODUCT');
-export const median = aggf('MEDIAN');
-export const quantile = aggf('QUANTILE');
-export const mode = aggf('MODE');
-
-export const variance = aggf('VARIANCE');
-export const stddev = aggf('STDDEV');
-export const skewness = aggf('SKEWNESS');
-export const kurtosis = aggf('KURTOSIS');
-export const entropy = aggf('ENTROPY');
-export const varPop = aggf('VAR_POP');
-export const stddevPop = aggf('STDDEV_POP');
-
-export const corr = aggf('CORR');
-export const covariance = aggf('COVAR_SAMP');
-export const covarPop = aggf('COVAR_POP');
-export const regrIntercept = aggf('REGR_INTERCEPT');
-export const regrSlope = aggf('REGR_SLOPE');
-export const regrCount = aggf('REGR_COUNT');
-export const regrR2 = aggf('REGR_R2');
-export const regrSYY = aggf('REGR_SYY');
-export const regrSXX = aggf('REGR_SXX');
-export const regrSXY = aggf('REGR_SXY');
-export const regrAvgX = aggf('REGR_AVGX');
-export const regrAvgY = aggf('REGR_AVGY');
-
-export const first = aggf('FIRST');
-export const last = aggf('LAST');
-
-export const argmin = aggf('ARG_MIN');
-export const argmax = aggf('ARG_MAX');
-
-export const stringAgg = aggf('STRING_AGG');
-export const arrayAgg = aggf('ARRAY_AGG');

package/src/cast.js

@@ -1,19 +0,0 @@
-import { sql } from './expression.js';
-import { asColumn } from './ref.js';
-
-export function cast(expr, type) {
-  const arg = asColumn(expr);
-  const e = sql`CAST(${arg} AS ${type})`;
-  Object.defineProperty(e, 'label', {
-    enumerable: true,
-    get() { return expr.label; }
-  });
-  Object.defineProperty(e, 'aggregate', {
-    enumerable: true,
-    get() { return expr.aggregate || false; }
-  });
-  return e;
-}
-
-export const castDouble = expr => cast(expr, 'DOUBLE');
-export const castInteger = expr => cast(expr, 'INTEGER');

package/src/datetime.js

@@ -1,31 +0,0 @@
-import { sql } from './expression.js';
-import { asColumn } from './ref.js';
-
-export const epoch_ms = expr => {
-  return sql`epoch_ms(${asColumn(expr)})`;
-};
-
-export function dateBin(expr, interval, steps = 1) {
-  const i = `INTERVAL ${steps} ${interval}`;
-  const d = asColumn(expr);
-  return sql`TIME_BUCKET(${i}, ${d})`
-    .annotate({ label: interval });
-}
-
-export const dateMonth = expr => {
-  const d = asColumn(expr);
-  return sql`MAKE_DATE(2012, MONTH(${d}), 1)`
-    .annotate({ label: 'month' });
-};
-
-export const dateMonthDay = expr => {
-  const d = asColumn(expr);
-  return sql`MAKE_DATE(2012, MONTH(${d}), DAY(${d}))`
-    .annotate({ label: 'date' });
-};
-
-export const dateDay = expr => {
-  const d = asColumn(expr);
-  return sql`MAKE_DATE(2012, 1, DAY(${d}))`
-    .annotate({ label: 'date' });
-};

package/src/desc.js

@@ -1,13 +0,0 @@
-import { sql } from './expression.js';
-import { asColumn } from './ref.js';
-
-/**
- * Annotate an expression to indicate descending sort order.
- * Null values are ordered last.
- * @param {import('./expression.js').SQLExpression|string} expr A SQL expression or column name string.
- * @returns {import('./expression.js').SQLExpression} An expression with descending order.
- */
-export function desc(expr) {
-  const e = asColumn(expr);
-  return sql`${e} DESC NULLS LAST`.annotate({ label: e?.label, desc: true });
-}

package/src/expression.js

@@ -1,170 +0,0 @@
-import { literalToSQL } from './to-sql.js';
-
-/**
- * @typedef {{
- *   value: any;
- *   addEventListener(type: string, callback: Function): any;
- *   column?: string,
- *   columns?: string[]
- * }} ParamLike
- */
-
-/**
- * Test if a value is parameter-like. Parameters have addEventListener methods.
- * @param {*} value The value to test.
- * @returns {value is ParamLike} True if the value is param-like, false otherwise.
- */
-export const isParamLike = value => typeof value?.addEventListener === 'function';
-
-/**
- * Test if a value is a SQL expression instance.
- * @param {*} value The value to test.
- * @returns {value is SQLExpression} True if value is a SQL expression, false otherwise.
- */
-export function isSQLExpression(value) {
-  return value instanceof SQLExpression;
-}
-
-/**
- * Base class for all SQL expressions. Most callers should use the `sql`
- * template tag rather than instantiate this class.
- */
-export class SQLExpression {
-
-  /**
-   * Create a new SQL expression instance.
-   * @param {(string | ParamLike | SQLExpression | import('./ref.js').Ref)[]} parts The parts of the expression.
-   * @param {string[]} [columns=[]] The column dependencies
-   * @param {object} [props] Additional properties for this expression.
-   */
-  constructor(parts, columns, props) {
-    this._expr = Array.isArray(parts) ? parts : [parts];
-    this._deps = columns || [];
-    this.annotate(props);
-
-    const params = this._expr.filter(part => isParamLike(part));
-    if (params.length > 0) {
-      /** @type {ParamLike[]} */
-      // @ts-ignore
-      this._params = Array.from(new Set(params));
-      this._params.forEach(param => {
-        param.addEventListener('value', () => update(this, this.map?.get('value')));
-      });
-    } else {
-      // do not support event listeners if not needed
-      // this causes the expression instance to NOT be param-like
-      this.addEventListener = undefined;
-    }
-  }
-
-  /**
-   * A reference to this expression.
-   * Provides compatibility with param-like objects.
-   */
-  get value() {
-    return this;
-  }
-
-  /**
-   * The column dependencies of this expression.
-   * @returns {string[]} The columns dependencies.
-   */
-  get columns() {
-    const { _params, _deps } = this;
-    if (_params) {
-      // pull latest dependencies, as they may change across updates
-      const pset = new Set(_params.flatMap(p => {
-        const cols = p.value?.columns;
-        return Array.isArray(cols) ? cols : [];
-      }));
-      if (pset.size) {
-        const set = new Set(_deps);
-        pset.forEach(col => set.add(col));
-        return Array.from(set);
-      }
-    }
-    // if no params, return fixed dependencies
-    return _deps;
-  }
-
-  /**
-   * The first column dependency in this expression, or undefined if none.
-   * @returns {string} The first column dependency.
-   */
-  get column() {
-    return this._deps.length ? this._deps[0] : this.columns[0];
-  }
-
-  /**
-   * Annotate this expression instance with additional properties.
-   * @param {object[]} [props] One or more objects with properties to add.
-   * @returns This SQL expression.
-   */
-  annotate(...props) {
-    return Object.assign(this, ...props);
-  }
-
-  /**
-   * Generate a SQL code string corresponding to this expression.
-   * @returns {string} A SQL code string.
-   */
-  toString() {
-    return this._expr
-      .map(p => isParamLike(p) && !isSQLExpression(p) ? literalToSQL(p.value) : p)
-      .join('');
-  }
-
-  /**
-   * Add an event listener callback for the provided event type.
-   * @param {string} type The event type to listen for (for example, "value").
-   * @param {(a: SQLExpression) => Promise?} callback The callback function to
-   *  invoke upon updates. A callback may optionally return a Promise that
-   *  upstream listeners may await before proceeding.
-   */
-  addEventListener(type, callback) {
-    const map = this.map || (this.map = new Map());
-    const set = map.get(type) || (map.set(type, new Set), map.get(type));
-    set.add(callback);
-  }
-}
-
-function update(expr, callbacks) {
-  if (callbacks?.size) {
-    return Promise.allSettled(Array.from(callbacks, fn => fn(expr)));
-  }
-}
-
-export function parseSQL(strings, exprs) {
-  const spans = [strings[0]];
-  const cols = new Set;
-  const n = exprs.length;
-  for (let i = 0, k = 0; i < n;) {
-    const e = exprs[i];
-    if (isParamLike(e)) {
-      spans[++k] = e;
-    } else {
-      if (Array.isArray(e?.columns)) {
-        e.columns.forEach(col => cols.add(col));
-      }
-      spans[k] += typeof e === 'string' ? e : literalToSQL(e);
-    }
-    const s = strings[++i];
-    if (isParamLike(spans[k])) {
-      spans[++k] = s;
-    } else {
-      spans[k] += s;
-    }
-  }
-
-  return { spans, cols: Array.from(cols) };
-}
-
-/**
- * Tag function for SQL expressions. Interpolated values
- * may be strings, other SQL expression objects (such as column
- * references), or parameterized values.
- */
-export function sql(strings, ...exprs) {
-  const { spans, cols } = parseSQL(strings, exprs);
-  return new SQLExpression(spans, cols);
-}

package/src/functions.js

@@ -1,25 +0,0 @@
-import { sql } from './expression.js';
-import { asColumn } from './ref.js';
-import { repeat } from './repeat.js';
-
-export function functionCall(op, type) {
-  return (...values) => {
-    const args = values.map(asColumn);
-    const cast = type ? `::${type}` : '';
-    const expr = args.length
-      ? sql([`${op}(`, ...repeat(args.length - 1, ', '), `)${cast}`], ...args)
-      : sql`${op}()${cast}`;
-    return expr.annotate({ func: op, args });
-  }
-}
-
-export const regexp_matches = functionCall('REGEXP_MATCHES');
-export const contains = functionCall('CONTAINS');
-export const prefix = functionCall('PREFIX');
-export const suffix = functionCall('SUFFIX');
-export const lower = functionCall('LOWER');
-export const upper = functionCall('UPPER');
-export const length = functionCall('LENGTH');
-export const isNaN = functionCall('ISNAN');
-export const isFinite = functionCall('ISFINITE');
-export const isInfinite = functionCall('ISINF');

package/src/literal.js

@@ -1,6 +0,0 @@
-import { literalToSQL } from './to-sql.js';
-
-export const literal = value => ({
-  value,
-  toString: () => literalToSQL(value)
-});

package/src/operators.js

@@ -1,54 +0,0 @@
-import { sql } from './expression.js';
-import { asColumn } from './ref.js';
-
-function visit(callback) {
-  callback(this.op, this);
-  this.children?.forEach(v => v.visit(callback));
-}
-
-function logical(op, clauses) {
-  const children = clauses.filter(x => x != null).map(asColumn);
-  const strings = children.map((c, i) => i ? ` ${op} ` : '');
-  if (children.length === 1) {
-    strings.push('')
-  } else if (children.length > 1) {
-    strings[0] = '(';
-    strings.push(')');
-  }
-  return sql(strings, ...children).annotate({ op, children, visit });
-}
-
-export const and = (...clauses) => logical('AND', clauses.flat());
-export const or = (...clauses) => logical('OR', clauses.flat());
-
-const unaryOp = op => a => sql`(${op} ${asColumn(a)})`.annotate({ op, a, visit });
-
-export const not = unaryOp('NOT');
-
-const unaryPostOp = op => a => sql`(${asColumn(a)} ${op})`.annotate({ op, a, visit });
-
-export const isNull = unaryPostOp('IS NULL');
-export const isNotNull = unaryPostOp('IS NOT NULL');
-
-const binaryOp = op => (a, b) => sql`(${asColumn(a)} ${op} ${asColumn(b)})`.annotate({ op, a, b, visit });
-
-export const eq = binaryOp('=');
-export const neq = binaryOp('<>');
-export const lt = binaryOp('<');
-export const gt = binaryOp('>');
-export const lte = binaryOp('<=');
-export const gte = binaryOp('>=');
-export const isDistinct = binaryOp('IS DISTINCT FROM');
-export const isNotDistinct = binaryOp('IS NOT DISTINCT FROM');
-
-function rangeOp(op, a, range, exclusive) {
-  a = asColumn(a);
-  const prefix = op.startsWith('NOT ') ? 'NOT ' : '';
-  const expr = !range ? sql``
-    : exclusive ? sql`${prefix}(${range[0]} <= ${a} AND ${a} < ${range[1]})`
-    : sql`(${a} ${op} ${range[0]} AND ${range[1]})`;
-  return expr.annotate({ op, visit, field: a, range });
-}
-
-export const isBetween = (a, range, exclusive) => rangeOp('BETWEEN', a, range, exclusive);
-export const isNotBetween = (a, range, exclusive) => rangeOp('NOT BETWEEN', a, range, exclusive);

package/src/ref.js

@@ -1,109 +0,0 @@
-/**
- * Class representing a table and/or column reference.
- */
-export class Ref {
-  /**
-   * Create a new Ref instance.
-   * @param {string|Ref|null} table The table name.
-   * @param {string|null} [column] The column name.
-   */
-  constructor(table, column) {
-    if (table) this.table = String(table);
-    if (column) this.column = column;
-  }
-
-  /**
-   * Get the list of referenced columns. Either a single element array
-   * if column is non-null, otherwise an empty array.
-   */
-  get columns() {
-    return this.column ? [this.column] : [];
-  }
-
-  /**
-   * Generate a SQL string for this reference.
-   * @returns {string} The SQL string.
-   */
-  toString() {
-    const { table, column } = this;
-    if (column) {
-      const col = column.startsWith('*') ? column : `"${column}"`;
-      return `${table ? `${quoteTableName(table)}.` : ''}${col}`;
-    } else {
-      return table ? quoteTableName(table) : 'NULL';
-    }
-  }
-}
-
-/**
- * Quote a table name. For example, `foo.bar` becomes `"foo"."bar".
- * @param {string} table the name of the table which may contain a database reference
- * @returns The quoted table name.
- */
-function quoteTableName(table) {
-  const pieces = table.split('.');
-  return pieces.map(p => `"${p}"`).join('.');
-}
-
-/**
- * Test is a reference refers to a given column name.
- * @param {*} ref The reference to test.
- * @param {string} name The column name to check for.
- * @returns {boolean} True if ref is a Ref instance that refers to
- *  the given column name. False otherwise.
- */
-export function isColumnRefFor(ref, name) {
-  return ref instanceof Ref && ref.column === name;
-}
-
-/**
- * Interpret a value, defaulting to a column reference.
- * @param {*} value The value to interpret. If string-typed,
- *  a new column reference will be returned.
- * @returns {*} A column reference or the input value.
- */
-export function asColumn(value) {
-  return typeof value === 'string' ? column(value) : value;
-}
-
-/**
- * Interpret a value, defaulting to a table (relation) reference.
- * @param {*} value The value to interpret. If string-typed,
- *  a new table (relation) reference will be returned.
- * @returns {*} A table reference or the input value.
- */
-export function asRelation(value) {
-  return typeof value === 'string' ? relation(value) : value;
-}
-
-/**
- * Create a table (relation) reference.
- * @param {string} name The table (relation) name.
- * @returns {Ref} The generated table reference.
- */
-export function relation(name) {
-  return new Ref(name);
-}
-
-/**
- * Create a column reference.
- * @param {string} table The table name (optional).
- * @param {string} [column] The column name.
- * @returns {Ref} The generated column reference.
- */
-export function column(table, column = null) {
-  if (arguments.length === 1) {
-    column = table;
-    table = null;
-  }
-  return new Ref(table, column);
-}
-
-/**
- * Create a reference to all columns in a table (relation).
- * @param {string} table The table name.
- * @returns {Ref} The generated reference.
- */
-export function all(table) {
-  return new Ref(table, '*');
-}

package/src/repeat.js

@@ -1,3 +0,0 @@
-export function repeat(length, str) {
-  return Array.from({ length }, () => str);
-}

package/src/spatial.js

@@ -1,10 +0,0 @@
-import { functionCall } from './functions.js';
-
-export const geojson = functionCall('ST_AsGeoJSON');
-
-export const x = functionCall('ST_X');
-export const y = functionCall('ST_Y');
-
-export const centroid = functionCall('ST_CENTROID');
-export const centroidX = geom => x(centroid(geom));
-export const centroidY = geom => y(centroid(geom));

package/src/to-sql.js

@@ -1,52 +0,0 @@
-/**
- * Convert a value to a corresponding SQL string.
- * Input string values are assumed to be column references,
- * otherwise the logic of literalToSQL applies.
- * @param {*} value The value to convert to SQL.
- * @returns {string} A SQL string.
- */
-export function toSQL(value) {
-  return typeof value === 'string'
-    ? `"${value}"` // strings as column refs
-    : literalToSQL(value);
-}
-
-/**
- * Convert a literal value to a corresponding SQL string.
- * The values null, undefined, Infinity, NaN, and invalid
- * dates are converted to SQL NULL values.
- * UTC dates map to the SQL Date type, otherwise JavaScript
- * date values map to the SQL Timestamp type.
- * Values that are not JavaScript Date, RegExp, or primitive types
- * are coerced to strings, relying on a defined toString method.
- * @param {*} value The literal value.
- * @returns {string} A SQL string.
- */
-export function literalToSQL(value) {
-  switch (typeof value) {
-    case 'boolean':
-      return value ? 'TRUE' : 'FALSE';
-    case 'string':
-      return `'${value.replace(`'`, `''`)}'`;
-    case 'number':
-      return Number.isFinite(value) ? String(value) : 'NULL';
-    default:
-      if (value == null) {
-        return 'NULL';
-      } else if (value instanceof Date) {
-        const ts = +value;
-        if (Number.isNaN(ts)) return 'NULL';
-        const y = value.getUTCFullYear();
-        const m = value.getUTCMonth();
-        const d = value.getUTCDate();
-        return ts === Date.UTC(y, m, d)
-          ? `MAKE_DATE(${y}, ${m+1}, ${d})` // utc date
-          : `EPOCH_MS(${ts})`; // timestamp
-      } else if (value instanceof RegExp) {
-        return `'${value.source}'`;
-      } else {
-        // otherwise rely on string coercion
-        return String(value);
-      }
-  }
-}