@uwdata/mosaic-sql 0.17.0 → 0.18.0

package/src/transforms/{bin-linear-2d.js → bin-linear-2d.ts}

@@ -1,22 +1,12 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprNode } from '../ast/node.js';
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
 import { Query } from '../ast/query.js';
 import { sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
 import { floor } from '../functions/numeric.js';
 import { add, mul, neq, sub } from '../functions/operators.js';
-
-/**
- * Identity function.
- * @template T
- * @param {T} x
- * @returns {T}
- */
-function identity(x) {
-  return x;
-}
+import { identity } from '../util/identity.js';
 
 /**
  * Compute densities over a 2D domain using linear binning. The weight of
@@ -24,30 +14,28 @@ function identity(x) {
  * a better base for subsequent kernel density estimation. This method takes
  * expressions for the (non-truncated) x and y bin values; these expressions
  * should be in units of grid indices, but can contain fractional components.
- * @param {SelectQuery} q The input query. The FROM and WHERE clauses should
+ * @param q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, before this method is invoked.
- * @param {ExprValue} xp The x grid bin expression
- * @param {ExprValue} yp The y grid bin expression
- * @param {ExprValue | undefined} weight Point weights.
- * @param {number} xn The number of x grid bins.
- * @param {string[]} [groupby] Group by expressions.
- * @returns {SelectQuery} A linear binning query for bin `index` and
- *  aggregate `density` columns, in addition to any group by expressions.
+ * @param xp The x grid bin expression
+ * @param yp The y grid bin expression
+ * @param weight Point weights.
+ * @param xn The number of x grid bins.
+ * @param groupby Group by expressions.
+ * @returns A linear binning query for bin `index` and aggregate `density`
+ *  columns, in addition to any group by expressions.
  */
-export function binLinear2d(q, xp, yp, weight, xn, groupby = []) {
-
-  const w = weight ? x => mul(x, weight) : identity;
+export function binLinear2d(
+  q: SelectQuery,
+  xp: ExprValue,
+  yp: ExprValue,
+  weight: ExprValue | undefined,
+  xn: number,
+  groupby: string[] = []
+) {
+  const w = weight ? (x: ExprNode) => mul(x, weight) : identity;
 
-  /**
-   * @param {ExprValue} i
-   * @param {ExprValue} w
-   */
-  const subq = (i, w) => q.clone().select({ xp, yp, i, w });
-  /**
-   * @param {ExprValue} x
-   * @param {ExprValue} y
-   */
-  const index = (x, y) => add(x, mul(y, xn));
+  const subq = (i: ExprValue, w: ExprValue) => q.clone().select({ xp, yp, i, w });
+  const index = (x: ExprValue, y: ExprValue) => add(x, mul(y, xn));
 
   const xu = int32(floor(xp));
   const yu = int32(floor(yp));

package/src/transforms/{filter-query.js → filter-query.ts}

@@ -1,22 +1,18 @@
-/**
- * @import { Query } from '../ast/query.js'
- * @import { TableRefNode } from '../ast/table-ref.js'
- * @import { FilterExpr } from '../types.js'
- */
-import { isSelectQuery } from '../ast/query.js';
-import { isTableRef } from '../ast/table-ref.js';
+import type { FilterExpr } from '../types.js';
+import { isSelectQuery, type Query } from '../ast/query.js';
+import { isTableRef, type TableRefNode } from '../ast/table-ref.js';
 import { deepClone } from '../visit/clone.js';
 import { walk } from '../visit/walk.js';
 
 /**
  * Returns a generator function that clones the given query and adds
  * a WHERE clause for the specified table reference.
- * @param {Query} query The query to clone and extend.
- * @param {TableRefNode} tableRef The table to filter.
- * @returns {(filter: FilterExpr) => Query} The generator function.
+ * @param query The query to clone and extend.
+ * @param tableRef The table to filter.
+ * @returns The generator function.
  */
-export function filterQuery(query, tableRef) {
-  return (filter) => {
+export function filterQuery(query: Query, tableRef: TableRefNode) {
+  return (filter: FilterExpr) => {
     const clone = deepClone(query);
     walk(clone, (node) => {
       if (
@@ -32,12 +28,12 @@ export function filterQuery(query, tableRef) {
   };
 }
 
-function arrayEquals(a, b) {
+function arrayEquals(a: unknown[], b: unknown[]) {
   if (a === b) return true;
   if (a == null || b == null) return false;
   if (a.length !== b.length) return false;
 
-  for (var i = 0; i < a.length; ++i) {
+  for (let i = 0; i < a.length; ++i) {
     if (a[i] !== b[i]) return false;
   }
   return true;

package/src/transforms/{line-density.js → line-density.ts}

@@ -1,8 +1,5 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
-import { Query } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
+import { Query, type SelectQuery } from '../ast/query.js';
 import { count, max, sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
 import { abs, floor, greatest, round, sign } from '../functions/numeric.js';
@@ -18,24 +15,29 @@ import { over } from '../util/ast.js';
  * pairs, perform line rasterization in-database, normalize arc lengths,
  * and then sum results for all line series to produce a density map.
  * Based on Moritz and Fisher's work: https://arxiv.org/abs/1808.06019
- * @param {SelectQuery} q The base query over the data.
- * @param {ExprValue} x Bin expression for x dimension.
+ * @param q The base query over the data.
+ * @param x Bin expression for x dimension.
  *  Provides gridded x coordinates, potentially with a fractional component.
- * @param {ExprValue} y Bin expression for x dimension.
+ * @param y Bin expression for x dimension.
  *  Provides gridded y coordinates, potentially with a fractional component.
- * @param {string[]} z Group by columns that segment data into individual line
+ * @param z Group by columns that segment data into individual line
  *  series. An empty array indicates there is only a single line series.
- * @param {number} xn The number of grid bins for the x dimension.
- * @param {number} yn The number of grid bins for the y dimension.
- * @param {string[]} [groupby] Additional group by expressions. Separate
+ * @param xn The number of grid bins for the x dimension.
+ * @param yn The number of grid bins for the y dimension.
+ * @param groupby Additional group by expressions. Separate
  *  line density maps are created for each of these groups.
- * @param {boolean} [normalize=true] Flag toggling approximate arc-length
- *  normalization to improve accuracy and reduce artifacts (default `true`).
- * @returns {SelectQuery}
+ * @param normalize Flag toggling approximate arc-length normalization to
+ *  improve accuracy and reduce artifacts (default `true`).
  */
 export function lineDensity(
-  q, x, y, z, xn, yn,
-  groupby = [], normalize = true
+  q: SelectQuery,
+  x: ExprValue,
+  y: ExprValue,
+  z: string[],
+  xn: number,
+  yn: number,
+  groupby: string[] = [],
+  normalize: boolean = true
 ) {
   // select x, y points binned to the grid
   q.select({

package/src/transforms/{m4.js → m4.ts}

@@ -1,7 +1,5 @@
-/**
- * @import { ExprNode } from '../ast/node.js'
- * @import { ExprValue, FromExpr } from '../types.js'
- */
+import type { ExprValue, FromExpr, SelectExpr } from '../types.js';
+import type { ColumnRefNode } from '../ast/column-ref.js';
 import { Query, isQuery } from '../ast/query.js';
 import { argmax, argmin, max, min } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
@@ -15,16 +13,21 @@ import { floor } from '../functions/numeric.js';
  * argmin and argmax, following https://arxiv.org/pdf/2306.03714.pdf.
  * This method can bin along either the *x* or *y* dimension, as determined
  * by the caller-provided *bin* expression.
- * @param {FromExpr} input The base query or table.
- * @param {ExprValue} bin An expression that maps
+ * @param input The base query or table.
+ * @param bin An expression that maps
  *  time-series values to fractional pixel positions.
- * @param {string} x The x dimension column name.
- * @param {string} y The y dimension column name.
- * @param {ExprNode[]} [groups] Additional
- *  groupby columns, for example for faceted charts.
- * @returns {Query} The resulting M4 query.
+ * @param x The x dimension column name.
+ * @param y The y dimension column name.
+ * @param groups Additional groupby columns, for example for faceted charts.
+ * @returns The resulting M4 query.
  */
-export function m4(input, bin, x, y, groups = []) {
+export function m4(
+  input: FromExpr,
+  bin: ExprValue,
+  x: string,
+  y: string,
+  groups: ColumnRefNode[] = []
+) {
   const pixel = int32(floor(bin));
 
   // Below, we treat input as a CTE when it is a query. In this case,
@@ -32,10 +35,10 @@ export function m4(input, bin, x, y, groups = []) {
   const useCTE = isQuery(input);
   const from = useCTE ? 'input' : input;
   const query = useCTE
-    ? Query.with(cte(/** @type {string} */(from), input, true))
+    ? Query.with(cte(String(from), input, true))
     : Query;
 
-  const q = (sel) => Query
+  const q = (sel: SelectExpr) => Query
     .from(from)
     .select(sel)
     .groupby(pixel, groups);

package/src/transforms/{scales.js → scales.ts}

@@ -1,13 +1,55 @@
+import type { ExprValue } from '../types.js';
 import { LiteralNode } from '../ast/literal.js';
+import { ExprNode } from '../ast/node.js';
 import { epoch_ms } from '../functions/datetime.js';
 import { literal } from '../functions/literal.js';
 import { abs, exp, ln, log, sign, sqrt } from '../functions/numeric.js';
 import { add, div, mul, pow, sub } from '../functions/operators.js';
 import { asNode } from '../util/ast.js';
+import { identity } from '../util/identity.js';
+import { DateTimeValue } from './util/time-interval.js';
 
-const identity = x => x;
+export interface ScaleTransform<T> {
+  apply: (value: T) => number;
+  invert: (value: number) => T;
+  sqlApply: (value: ExprValue) => ExprNode;
+  sqlInvert: (value: ExprNode) => ExprNode;
+}
+
+export type ScaleType =
+  | 'identity'
+  | 'linear'
+  | 'log'
+  | 'symlog'
+  | 'sqrt'
+  | 'pow'
+  | 'time'
+  | 'utc'
+  ;
+
+export type ScaleDomain = [number, number] | [Date, Date];
+
+export interface ScaleOptions {
+  /** The scale type, such as `'linear'`, `'log'`, etc. */
+  type: ScaleType;
+  /** The scale domain, as an array of start and end data values. */
+  domain?: ScaleDomain;
+  /**
+   * The scale range, as an array of start and end screen pixels.
+   * The range may be omitted for *identity* scales.
+   */
+  range?: [number, number];
+  /** The base of the logarithm. For `'log'` scales only. */
+  base?: number;
+  /** The constant parameter. For `'symlog'` scales only. */
+  constant?: number;
+  /** The exponent parameter. For `'pow'` scales only. */
+  exponent?: number;
+}
+
+export type Scale<T> = ScaleTransform<T> & ScaleOptions;
 
-function scaleLinear() {
+function scaleLinear(): ScaleTransform<number> {
   return {
     apply: identity,
     invert: identity,
@@ -16,7 +58,7 @@ function scaleLinear() {
   };
 }
 
-function scaleLog({ base = null } = {}) {
+function scaleLog({ base = null }: {base?: number | null} = { }): ScaleTransform<number> {
   if (base == null || base === Math.E) {
     return {
       apply: Math.log,
@@ -42,7 +84,7 @@ function scaleLog({ base = null } = {}) {
   }
 }
 
-function scaleSymlog({ constant = 1 } = {}) {
+function scaleSymlog({ constant = 1 } = {}): ScaleTransform<number> {
   const _ = +constant;
   return {
     apply: x => Math.sign(x) * Math.log1p(Math.abs(x)),
@@ -52,7 +94,7 @@ function scaleSymlog({ constant = 1 } = {}) {
   };
 }
 
-function scaleSqrt() {
+function scaleSqrt(): ScaleTransform<number> {
   return {
     apply: x => Math.sign(x) * Math.sqrt(Math.abs(x)),
     invert: x => Math.sign(x) * x * x,
@@ -61,7 +103,7 @@ function scaleSqrt() {
   };
 }
 
-function scalePow({ exponent = 1 } = {}) {
+function scalePow({ exponent = 1 } = {}): ScaleTransform<number> {
   const e = +exponent;
   return {
     apply: x => Math.sign(x) * Math.pow(Math.abs(x), e),
@@ -71,12 +113,12 @@ function scalePow({ exponent = 1 } = {}) {
   };
 }
 
-function scaleTime() {
+function scaleTime(): ScaleTransform<DateTimeValue> {
   return {
-    apply: x => +x,
+    apply: x => Number(x),
     invert: x => new Date(x),
     sqlApply: c => c instanceof Date ? literal(+c)
-      : isDateLiteral(c) ? literal(+c.value)
+      : isDateLiteral(c) ? literal(Number(c.value))
       : epoch_ms(c),
     sqlInvert: identity
   };
@@ -93,16 +135,17 @@ const scales = {
   utc: scaleTime
 };
 
-export function scaleTransform(options) {
+export function scaleTransform<T>(options: ScaleOptions): Scale<T> {
   const scale = scales[options.type];
-  return scale ? { ...options, ...scale(options) } : null;
+  if (!scale) throw new Error(`Unrecognized scale type: ${options.type}`);
+  // @ts-expect-error suppress error, revisit later?
+  return { ...options, ...scale(options) };
 }
 
 /**
  * Check if a value is a date-valued literal SQL AST node.
- * @param {*} x The value to test.
- * @returns {x is LiteralNode}
+ * @param x The value to test.
  */
-function isDateLiteral(x) {
+function isDateLiteral(x: unknown): x is LiteralNode {
   return x instanceof LiteralNode && x.value instanceof Date;
 }

package/src/transforms/util/bin-step.ts

@@ -0,0 +1,100 @@
+/** Numerical binning options. */
+export interface BinOptions {
+  /**
+   * An exact binning step to use.
+   */
+  step?: number;
+  /**
+   * The desired number of binning steps. This value is a hint,
+   * it does not guarantee an exact number of steps.
+   */
+  steps?: number;
+  /**
+   * A minimum binning step value.
+   * No generated step can be less than this value.
+   */
+  minstep?: number;
+  /**
+   * A boolean flag (default true) indicating if bin extents should be snapped
+   * to "nice" numbers such as multiples of 5 or 10.
+   */
+  nice?: boolean;
+  /**
+   * A number indicating the the logarithm base to use for automatic step size
+   * determination. Defaults to base 10.
+   */
+  base?: number;
+}
+
+/**
+ * Generate a numeric binning scheme suitable for a histogram.
+ * @param min The minimum value of the extent to bin.
+ * @param max The maximum value of the extent to bin.
+ * @param options Binning scheme options.
+ */
+export function binSpec(min: number, max: number, options: BinOptions) {
+  let {
+    step,
+    steps = 25,
+  } = options;
+  const {
+    minstep = 0,
+    nice = true,
+    base
+  } = options;
+
+  if (nice !== false) {
+    // use span to determine step size
+    const span = max - min;
+    const logb = base ? Math.log(base) : Math.LN10;
+    step = step || binStep(span, steps, minstep, logb);
+
+    // adjust min/max relative to step
+    let v = Math.log(step);
+    const precision = v >= 0 ? 0 : ~~(-v / logb) + 1;
+    const eps = Math.pow(10, -precision - 1);
+    v = Math.floor(min / step + eps) * step;
+    min = min < v ? v - step : v;
+    max = Math.ceil(max / step) * step;
+    steps = Math.round((max - min) / step);
+  }
+
+  return { min, max, steps };
+}
+
+/**
+ * Determine a bin step interval.
+ * @param span The span from maximum to minimum value.
+ * @param steps The approximate number of desired bins.
+ * @param minstep The minimum acceptable bin step size.
+ * @param logb The log base for determining orders of magnitude for step
+ *  sizes. Defaults to log base 10 (`Math.LN10`). For example to use log
+ *  base 2, provide the argument `Math.LN2` instead.
+ * @returns The bin step interval (bin size).
+ */
+export function binStep(
+  span: number,
+  steps: number,
+  minstep: number = 0,
+  logb: number = Math.LN10
+) {
+  let v;
+
+  const level = Math.ceil(Math.log(steps) / logb);
+  let step = Math.max(
+    minstep,
+    Math.pow(10, Math.round(Math.log(span) / logb) - level)
+  );
+
+  // increase step size if too many bins
+  while (Math.ceil(span / step) > steps) { step *= 10; }
+
+  // decrease step size if allowed
+  const div = [5, 2];
+  for (let i = 0, n = div.length; i < n; ++i) {
+    v = step / div[i];
+    if (v >= minstep && span / v <= steps) step = v;
+  }
+
+  return step;
+}

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