@uwdata/mosaic-spec 0.16.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-spec",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Declarative specification of Mosaic-powered applications.",
   "keywords": [
     "mosaic",
@@ -13,7 +13,7 @@
   "author": "Jeffrey Heer (https://idl.uw.edu)",
   "type": "module",
   "exports": {
-    "types": "./dist/types/index.d.ts",
+    "types": "./dist/src/index.d.ts",
     "default": "./src/index.js"
   },
   "repository": {
@@ -22,21 +22,17 @@
   },
   "scripts": {
     "prebuild": "rimraf dist && mkdir dist",
-    "build": "npm run types",
+    "build": "tsc && npm run schema",
     "lint": "eslint src test",
-    "types": "tsc && npm run schema",
     "schema": "ts-json-schema-generator -f tsconfig.json -p src/spec/Spec.ts -t Spec --no-type-check --no-ref-encode --functions hide > dist/mosaic-schema.json",
-    "pretest": "npm run prebuild && npm run types",
-    "test": "vitest run && npm run tsc",
-    "tsc": "tsc -p jsconfig.json",
+    "test": "vitest run && tsc",
     "version": "cd ../.. && npm run docs:schema",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
   "dependencies": {
-    "@uwdata/mosaic-core": "^0.16.2",
-    "@uwdata/mosaic-sql": "^0.16.2",
-    "@uwdata/vgplot": "^0.16.2",
+    "@uwdata/mosaic-core": "^0.17.0",
+    "@uwdata/mosaic-sql": "^0.17.0",
+    "@uwdata/vgplot": "^0.17.0",
     "ts-json-schema-generator": "^2.3.0"
-  },
-  "gitHead": "26d2719f4bcab471d2831145e1f03f39f3509869"
+  }
 }

package/src/ast/TransformNode.js

@@ -1,6 +1,7 @@
 import { ASTNode } from './ASTNode.js';
 import { TRANSFORM } from '../constants.js';
 import { parseOptions } from './OptionsNode.js';
+import { parseWindowFrame } from './WindowFrameNode.js';
 
 function toArray(value, ctx) {
   return value == null
@@ -30,8 +31,7 @@ export function parseTransform(spec, ctx) {
       distinct: spec.distinct,
       orderby: toArray(spec.orderby, ctx),
       partitionby: toArray(spec.partitionby, ctx),
-      rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
-      range: spec.range ? ctx.maybeParam(spec.range) : null
+      frame: parseWindowFrame(spec, ctx)
     };
     return new TransformNode(name, args, options);
   }
@@ -47,7 +47,7 @@ export class TransformNode extends ASTNode {
 
   instantiate(ctx) {
     const { name, args, options } = this;
-    const { distinct, orderby, partitionby, rows, range } = options;
+    const { distinct, orderby, partitionby, frame } = options;
 
     let expr = ctx.api[name](...args.map(a => a.instantiate(ctx)));
     if (distinct) {
@@ -59,17 +59,15 @@ export class TransformNode extends ASTNode {
     if (partitionby.length) {
       expr = expr.partitionby(partitionby.map(v => v.instantiate(ctx)));
     }
-    if (rows != null) {
-      expr = expr.rows(rows.instantiate(ctx));
-    } else if (range != null) {
-      expr = expr.range(range.instantiate(ctx));
+    if (frame) {
+      expr = expr.frame(frame.instantiate(ctx));
     }
     return expr;
   }
 
   codegen(ctx) {
     const { name, args, options } = this;
-    const { distinct, orderby, partitionby, rows, range } = options;
+    const { distinct, orderby, partitionby, frame } = options;
 
     let str = `${ctx.ns()}${name}(`
       + args.map(v => v.codegen(ctx)).join(', ')
@@ -86,10 +84,8 @@ export class TransformNode extends ASTNode {
       const p = partitionby.map(v => v.codegen(ctx));
       str += `.partitionby(${p.join(', ')})`;
     }
-    if (rows) {
-      str += `.rows(${rows.codegen(ctx)})`;
-    } else if (range) {
-      str += `.range(${range.codegen(ctx)})`;
+    if (frame) {
+      str += `.frame(${frame.codegen(ctx)})`;
     }
 
     return str;
@@ -97,7 +93,7 @@ export class TransformNode extends ASTNode {
 
   toJSON() {
     const { name, args, options } = this;
-    const { distinct, orderby, partitionby, rows, range } = options;
+    const { distinct, orderby, partitionby, frame } = options;
 
     const json = { [name]: simplify(args.map(v => v.toJSON())) };
 
@@ -110,10 +106,8 @@ export class TransformNode extends ASTNode {
     if (partitionby.length) {
       json.partitionby = simplify(partitionby.map(v => v.toJSON()));
     }
-    if (rows) {
-      json.rows = rows.toJSON();
-    } else if (range) {
-      json.range = range.toJSON();
+    if (frame) {
+      Object.assign(json, frame.toJSON());
     }
 
     return json;

package/src/ast/WindowFrameNode.js

@@ -0,0 +1,61 @@
+import { LiteralNode, WindowFrameNode as WindowFrame } from '@uwdata/mosaic-sql';
+import { WINDOW_FRAME } from '../constants.js';
+import { isObject, paramRef } from '../util.js';
+import { ASTNode } from './ASTNode.js';
+import { parseTransform } from './TransformNode.js';
+
+export function parseWindowFrame(spec, ctx) {
+  const type = spec.rows ? 'ROWS'
+    : spec.range ? 'RANGE'
+    : spec.groups ? 'GROUPS'
+    : null;
+
+  if (!type) return null;
+
+  const value = spec[type.toLowerCase()];
+  const name = paramRef(value);
+  const extent = name
+    ? ctx.paramRef(name)
+    : value.map(v => isObject(v)
+        ? parseTransform(v, ctx)
+        : new LiteralNode(v)
+      );
+
+  return new WindowFrameNode(type, extent, spec.exclude);
+}
+
+export class WindowFrameNode extends ASTNode {
+  constructor(type, extent, exclude) {
+    super(WINDOW_FRAME);
+    this.type = type;
+    this.extent = extent;
+    this.exclude = exclude?.toUpperCase();
+  }
+
+  instantiate(ctx) {
+    const { type, extent, exclude } = this;
+    const ex = Array.isArray(extent)
+      ? extent.map(v => v.instantiate(ctx))
+      : extent.instantiate(ctx);
+    return new WindowFrame(type, ex, exclude?.toUpperCase());
+  }
+
+  codegen(ctx) {
+    const { type, extent, exclude } = this;
+    const fn = `frame${type[0].toUpperCase()}${type.slice(1).toLowerCase()}`;
+    const ex = Array.isArray(extent)
+      ? `[${extent.map(v => v.codegen(ctx)).join(', ')}]`
+      : extent.codegen(ctx);
+    const cl = exclude ? `, '${exclude.toUpperCase()}'` : '';
+    return `${ctx.ns()}${fn}(${ex}${cl})`;
+  }
+
+  toJSON() {
+    const { type, extent, exclude } = this;
+    const key = type.toLowerCase();
+    const ex = Array.isArray(extent)
+      ? extent.map(v => v.toJSON())
+      : extent.toJSON();
+    return { [key]: ex, exclude };
+  }
+}

package/src/config/transforms.js

@@ -43,6 +43,14 @@ export function transformNames(overrides = []) {
     'first_value',
     'last_value',
     'nth_value',
+    'years',
+    'months',
+    'days',
+    'hours',
+    'minutes',
+    'seconds',
+    'milliseconds',
+    'microseconds',
     ...overrides
   ]);
 }

package/src/constants.js

@@ -48,5 +48,6 @@ export const PLOT = 'plot';
 export const LEGEND = 'legend';
 export const ATTRIBUTE = 'attribute';
 export const TRANSFORM = 'transform';
+export const WINDOW_FRAME = 'windowframe';
 export const INTERACTOR = 'interactor';
 export const FIXED = 'Fixed';

package/src/spec/Interval.ts

@@ -0,0 +1,75 @@
+/** Date/time interval. */
+export type IntervalTransform =
+  | Years
+  | Months
+  | Days
+  | Hours
+  | Minutes
+  | Seconds
+  | Milliseconds
+  | Microseconds
+  ;
+
+/** A date/time interval in units of years. */
+export interface Years {
+  /**
+   * A date/time interval in units of years.
+   */
+  years: number;
+}
+
+/** A date/time interval in units of months. */
+export interface Months {
+  /**
+   * A date/time interval in units of months.
+   */
+  months: number;
+}
+
+/** A date/time interval in units of days. */
+export interface Days {
+  /**
+   * A date/time interval in units of days.
+   */
+  days: number;
+}
+
+/** A date/time interval in units of hours. */
+export interface Hours {
+  /**
+   * A date/time interval in units of hours.
+   */
+  hours: number;
+}
+
+/** A date/time interval in units of minutes. */
+export interface Minutes {
+  /**
+   * A date/time interval in units of minutes.
+   */
+  minutes: number;
+}
+
+/** A date/time interval in units of seconds. */
+export interface Seconds {
+  /**
+   * A date/time interval in units of seconds.
+   */
+  seconds: number;
+}
+
+/** A date/time interval in units of milliseconds. */
+export interface Milliseconds {
+  /**
+   * A date/time interval in units of milliseconds.
+   */
+  milliseconds: number;
+}
+
+/** A date/time interval in units of microseconds. */
+export interface Microseconds {
+  /**
+   * A date/time interval in units of microseconds.
+   */
+  microseconds: number;
+}

package/src/spec/Transform.ts

@@ -1,14 +1,21 @@
+import { IntervalTransform } from './Interval.js';
 import { ParamRef } from './Param.js';
 
 /** A field argument to a data transform. */
 export type TransformField = string | ParamRef;
 
+export type FrameExclude = 'CURRENT ROW' | 'GROUP' | 'TIES' | 'NO OTHERS';
+
+export type FrameValue = number | IntervalTransform | null;
+
 /** Window transform options. */
 export interface WindowOptions {
   orderby?: TransformField | TransformField[];
   partitionby?: TransformField | TransformField[];
-  rows?: (number | null)[] | ParamRef;
-  range?: (number | null)[] | ParamRef;
+  rows?: [FrameValue, FrameValue] | ParamRef;
+  range?: [FrameValue, FrameValue] | ParamRef;
+  groups?: [FrameValue, FrameValue] | ParamRef;
+  exclude?: Uppercase<FrameExclude> | Lowercase<FrameExclude>;
 }
 
 /** Aggregate transform options. */
@@ -53,7 +60,7 @@ export type BinInterval =
   | 'month'
   | 'year';
 
-/* A bin transform. */
+/** A bin transform. */
 export interface Bin {
   /**
    * Bin a continuous variable into discrete intervals. The bin argument
@@ -102,7 +109,7 @@ export interface Bin {
   offset?: number;
 }
 
-/* A column transform. */
+/** A column transform. */
 export interface Column {
   /**
    * Intpret a string or param-value as a column reference.
@@ -110,7 +117,7 @@ export interface Column {
   column: Arg1;
 }
 
-/* A dateMonth transform. */
+/** A dateMonth transform. */
 export interface DateMonth {
   /**
    * Transform a Date value to a month boundary for cyclic comparison.
@@ -119,7 +126,7 @@ export interface DateMonth {
   dateMonth: Arg1;
 }
 
-/* A dateMonthDay transform. */
+/** A dateMonthDay transform. */
 export interface DateMonthDay {
   /**
    * Transform a Date value to a month and day boundary for cyclic comparison.
@@ -128,7 +135,7 @@ export interface DateMonthDay {
   dateMonthDay: Arg1;
 }
 
-/* A dateDay transform. */
+/** A dateDay transform. */
 export interface DateDay {
   /**
    * Transform a Date value to a day of the month for cyclic comparison.
@@ -137,7 +144,7 @@ export interface DateDay {
   dateDay: Arg1;
 }
 
-/* A centroid transform. */
+/** A centroid transform. */
 export interface Centroid {
   /**
    * Compute the 2D centroid of geometry-typed data.
@@ -146,7 +153,7 @@ export interface Centroid {
   centroid: Arg1;
 }
 
-/* A centroidX transform. */
+/** A centroidX transform. */
 export interface CentroidX {
   /**
    * Compute the centroid x-coordinate of geometry-typed data.
@@ -155,7 +162,7 @@ export interface CentroidX {
   centroidX: Arg1;
 }
 
-/* A centroidY transform. */
+/** A centroidY transform. */
 export interface CentroidY {
   /**
    * Compute the centroid y-coordinate of geometry-typed data.
@@ -164,7 +171,7 @@ export interface CentroidY {
   centroidY: Arg1;
 }
 
-/* A geojson transform. */
+/** A geojson transform. */
 export interface GeoJSON {
   /**
    * Compute a GeoJSON-formatted string from geometry-typed data.
@@ -173,7 +180,7 @@ export interface GeoJSON {
   geojson: Arg1;
 }
 
-/* An argmax aggregate transform. */
+/** An argmax aggregate transform. */
 export interface Argmax extends AggregateOptions, WindowOptions {
   /**
    * Find a value of the first column that maximizes the second column.
@@ -181,7 +188,7 @@ export interface Argmax extends AggregateOptions, WindowOptions {
   argmax: Arg2;
 }
 
-/* An argmin aggregate transform. */
+/** An argmin aggregate transform. */
 export interface Argmin extends AggregateOptions, WindowOptions {
   /**
    * Find a value of the first column that minimizes the second column.
@@ -189,7 +196,7 @@ export interface Argmin extends AggregateOptions, WindowOptions {
   argmin: Arg2;
 }
 
-/* An avg (average, or mean) aggregate transform. */
+/** An avg (average, or mean) aggregate transform. */
 export interface Avg extends AggregateOptions, WindowOptions {
   /**
    * Compute the average (mean) value of the given column.
@@ -197,7 +204,7 @@ export interface Avg extends AggregateOptions, WindowOptions {
   avg: Arg1;
 }
 
-/* A count aggregate transform. */
+/** A count aggregate transform. */
 export interface Count extends AggregateOptions, WindowOptions {
   /**
    * Compute the count of records in an aggregation group.
@@ -205,7 +212,7 @@ export interface Count extends AggregateOptions, WindowOptions {
   count: Arg0 | Arg1;
 }
 
-/* A sample covariance aggregate transform. */
+/** A sample covariance aggregate transform. */
 export interface Covariance extends AggregateOptions, WindowOptions {
   /**
    * Compute the sample covariance of between the given columns.
@@ -213,7 +220,7 @@ export interface Covariance extends AggregateOptions, WindowOptions {
   covariance: Arg2;
 }
 
-/* A population covariance aggregate transform. */
+/** A population covariance aggregate transform. */
 export interface CovarPop extends AggregateOptions, WindowOptions {
   /**
    * Compute the population covariance of between the given columns.
@@ -221,7 +228,7 @@ export interface CovarPop extends AggregateOptions, WindowOptions {
   covarPop: Arg2;
 }
 
-/* A first aggregate transform. */
+/** A first aggregate transform. */
 export interface First extends AggregateOptions, WindowOptions {
   /**
    * Return the first column value found in an aggregation group.
@@ -229,7 +236,7 @@ export interface First extends AggregateOptions, WindowOptions {
   first: Arg1;
 }
 
-/* A geometric mean aggregate transform. */
+/** A geometric mean aggregate transform. */
 export interface Geomean extends AggregateOptions, WindowOptions {
   /**
    * Compute the geometric mean value of the given column.
@@ -237,7 +244,7 @@ export interface Geomean extends AggregateOptions, WindowOptions {
   geomean: Arg1;
 }
 
-/* A last aggregate transform. */
+/** A last aggregate transform. */
 export interface Last extends AggregateOptions, WindowOptions {
   /**
    * Return the last column value found in an aggregation group.
@@ -245,7 +252,7 @@ export interface Last extends AggregateOptions, WindowOptions {
   last: Arg1;
 }
 
-/* A max aggregate transform. */
+/** A max aggregate transform. */
 export interface Max extends AggregateOptions, WindowOptions {
   /**
    * Compute the maximum value of the given column.
@@ -253,7 +260,7 @@ export interface Max extends AggregateOptions, WindowOptions {
   max: Arg1;
 }
 
-/* A min aggregate transform. */
+/** A min aggregate transform. */
 export interface Min extends AggregateOptions, WindowOptions {
   /**
    * Compute the minimum value of the given column.
@@ -261,7 +268,7 @@ export interface Min extends AggregateOptions, WindowOptions {
   min: Arg1;
 }
 
-/* A median aggregate transform. */
+/** A median aggregate transform. */
 export interface Median extends AggregateOptions, WindowOptions {
   /**
    * Compute the median value of the given column.
@@ -269,7 +276,7 @@ export interface Median extends AggregateOptions, WindowOptions {
   median: Arg1;
 }
 
-/* A mode aggregate transform. */
+/** A mode aggregate transform. */
 export interface Mode extends AggregateOptions, WindowOptions {
   /**
    * Compute the mode value of the given column.
@@ -277,7 +284,7 @@ export interface Mode extends AggregateOptions, WindowOptions {
   mode: Arg1;
 }
 
-/* A product aggregate transform. */
+/** A product aggregate transform. */
 export interface Product extends AggregateOptions, WindowOptions {
   /**
    * Compute the product of the given column.
@@ -285,7 +292,7 @@ export interface Product extends AggregateOptions, WindowOptions {
   product: Arg1;
 }
 
-/* A quantile aggregate transform. */
+/** A quantile aggregate transform. */
 export interface Quantile extends AggregateOptions, WindowOptions {
   /**
    * Compute the quantile value of the given column at the provided
@@ -294,7 +301,7 @@ export interface Quantile extends AggregateOptions, WindowOptions {
   quantile: Arg2;
 }
 
-/* A sample standard deviation aggregate transform. */
+/** A sample standard deviation aggregate transform. */
 export interface Stddev extends AggregateOptions, WindowOptions {
   /**
    * Compute the sum of the given column.
@@ -302,7 +309,7 @@ export interface Stddev extends AggregateOptions, WindowOptions {
   stddev: Arg1;
 }
 
-/* A population standard deviation aggregate transform. */
+/** A population standard deviation aggregate transform. */
 export interface StddevPop extends AggregateOptions, WindowOptions {
   /**
    * Compute the sum of the given column.
@@ -310,7 +317,7 @@ export interface StddevPop extends AggregateOptions, WindowOptions {
   stddevPop: Arg1;
 }
 
-/* A sum aggregate transform. */
+/** A sum aggregate transform. */
 export interface Sum extends AggregateOptions, WindowOptions {
   /**
    * Compute the sum of the given column.
@@ -318,7 +325,7 @@ export interface Sum extends AggregateOptions, WindowOptions {
   sum: Arg1;
 }
 
-/* A sample variance aggregate transform. */
+/** A sample variance aggregate transform. */
 export interface Variance extends AggregateOptions, WindowOptions {
   /**
    * Compute the sample variance of the given column.
@@ -326,7 +333,7 @@ export interface Variance extends AggregateOptions, WindowOptions {
   variance: Arg1;
 }
 
-/* A population variance aggregate transform. */
+/** A population variance aggregate transform. */
 export interface VarPop extends AggregateOptions, WindowOptions {
   /**
    * Compute the population variance of the given column.
@@ -334,7 +341,7 @@ export interface VarPop extends AggregateOptions, WindowOptions {
   varPop: Arg1;
 }
 
-/* A row_number window transform. */
+/** A row_number window transform. */
 export interface RowNumber extends WindowOptions {
   /**
    * Compute the 1-based row number over an ordered window partition.
@@ -342,7 +349,7 @@ export interface RowNumber extends WindowOptions {
   row_number: Arg0;
 }
 
-/* A rank window transform. */
+/** A rank window transform. */
 export interface Rank extends WindowOptions {
   /**
    * Compute the row rank over an ordered window partition.
@@ -351,7 +358,7 @@ export interface Rank extends WindowOptions {
   rank: Arg0;
 }
 
-/* A dense_rank window transform. */
+/** A dense_rank window transform. */
 export interface DenseRank extends WindowOptions {
   /**
    * Compute the dense row rank (no gaps) over an ordered window partition.
@@ -360,7 +367,7 @@ export interface DenseRank extends WindowOptions {
   dense_rank: Arg0;
 }
 
-/* A percent_rank window transform. */
+/** A percent_rank window transform. */
 export interface PercentRank extends WindowOptions {
   /**
    * Compute the percetange rank over an ordered window partition.
@@ -368,7 +375,7 @@ export interface PercentRank extends WindowOptions {
   percent_rank: Arg0;
 }
 
-/* A cume_dist window transform. */
+/** A cume_dist window transform. */
 export interface CumeDist extends WindowOptions {
   /**
    * Compute the cumulative distribution value over an ordered window
@@ -378,7 +385,7 @@ export interface CumeDist extends WindowOptions {
   cume_dist: Arg0;
 }
 
-/* An ntile window transform. */
+/** An ntile window transform. */
 export interface NTile extends WindowOptions {
   /**
    * Compute an n-tile integer ranging from 1 to the provided argument
@@ -387,7 +394,7 @@ export interface NTile extends WindowOptions {
   ntile: Arg1;
 }
 
-/* A lag window transform. */
+/** A lag window transform. */
 export interface Lag extends WindowOptions {
   /**
    * Compute lagging values in a column. Returns the value at the row that is
@@ -399,7 +406,7 @@ export interface Lag extends WindowOptions {
   lag: Arg3Opt;
 }
 
-/* A lead window transform. */
+/** A lead window transform. */
 export interface Lead extends WindowOptions {
   /**
    * Compute leading values in a column. Returns the value at the row that is
@@ -411,7 +418,7 @@ export interface Lead extends WindowOptions {
   lag: Arg3Opt;
 }
 
-/* A first_value window transform. */
+/** A first_value window transform. */
 export interface FirstValue extends WindowOptions {
   /**
    * Get the first value of the given column in the current window frame.
@@ -419,7 +426,7 @@ export interface FirstValue extends WindowOptions {
   first_value: Arg1;
 }
 
-/* A last_value window transform. */
+/** A last_value window transform. */
 export interface LastValue extends WindowOptions {
   /**
    * Get the last value of the given column in the current window frame.
@@ -427,7 +434,7 @@ export interface LastValue extends WindowOptions {
   last_value: Arg1;
 }
 
-/* An nth_value window transform. */
+/** An nth_value window transform. */
 export interface NthValue extends WindowOptions {
   /**
    * Get the nth value of the given column in the current window frame,
@@ -468,9 +475,10 @@ export type AggregateTransform =
   | StddevPop
   | Sum
   | Variance
-  | VarPop;
+  | VarPop
+  ;
 
-/* A window transform that operates over a sorted domain. */
+/** A window transform that operates over a sorted domain. */
 export type WindowTransform =
   | RowNumber
   | Rank
@@ -483,10 +491,12 @@ export type WindowTransform =
   | Lead
   | FirstValue
   | LastValue
-  | NthValue;
+  | NthValue
+  ;
 
 /** A data transform. */
 export type Transform =
   | ColumnTransform
   | AggregateTransform
-  | WindowTransform;
+  | WindowTransform
+  ;