@uwdata/mosaic-spec 0.5.0

package/src/config/components.js

@@ -0,0 +1,28 @@
+import { parseHConcat } from '../ast/HConcatNode.js';
+import { parseHSpace } from '../ast/HSpaceNode.js';
+import { parseInput } from '../ast/InputNode.js';
+import { parseLegend } from '../ast/PlotLegendNode.js';
+import { parsePlot, parseTopLevelMark } from '../ast/PlotNode.js';
+import { parseVConcat } from '../ast/VConcatNode.js';
+import { parseVSpace } from '../ast/VSpaceNode.js';
+
+import {
+  HCONCAT, HSPACE, INPUT, LEGEND, MARK, PLOT, VCONCAT, VSPACE
+} from '../constants.js';
+
+/**
+ * Map of specification keys to component parsers.
+ */
+export function componentMap(overrides = []) {
+  return new Map([
+    [ PLOT, parsePlot ],
+    [ MARK, parseTopLevelMark ],
+    [ LEGEND, parseLegend ],
+    [ INPUT, parseInput ],
+    [ HCONCAT, parseHConcat ],
+    [ VCONCAT, parseVConcat ],
+    [ HSPACE, parseHSpace ],
+    [ VSPACE, parseVSpace ],
+    ...overrides
+  ]);
+}

package/src/config/extensions.js

@@ -0,0 +1,23 @@
+import { SPATIAL_DATA } from '../ast/DataNode.js';
+import { SpecNode } from '../ast/SpecNode.js';
+import { toArray } from '../util.js';
+
+/**
+ * Construct a set of database extensions to load.
+ * Automatically adds the spatial extension if a
+ * dataset with format "spatial" is loaded.
+ * @param {SpecNode} ast Mosaic AST root node.
+ * @returns {Set<string>} A set of extension names.
+ */
+export function resolveExtensions(ast) {
+  const spec = ast.config?.extensions;
+  const exts = new Set(spec ? toArray(spec) : []);
+
+  for (const def of Object.values(ast.data)) {
+    if (def.format === SPATIAL_DATA) {
+      exts.add('spatial');
+    }
+  }
+
+  return exts;
+}

package/src/config/inputs.js

@@ -0,0 +1,12 @@
+/**
+ * Set of input widget type names.
+ */
+export function inputNames(overrides = []) {
+  return new Set([
+    'menu',
+    'search',
+    'slider',
+    'table',
+    ...overrides
+  ]);
+}

package/src/config/plots.js

@@ -0,0 +1,58 @@
+import {
+  attributeDirectives,
+  interactorDirectives,
+  legendDirectives,
+  markDirectives
+} from '@uwdata/vgplot';
+
+/**
+ * Generate an object of lookup maps for vgplot components.
+ */
+export function plotNames({
+  attributes = plotAttributeNames(),
+  interactors = plotInteractorNames(),
+  legends = plotLegendNames(),
+  marks = plotMarkNames()
+} = {}) {
+  return { attributes, interactors, legends, marks };
+}
+
+/**
+ * Names of attribute directive functions.
+ */
+export function plotAttributeNames(overrides = []) {
+  return new Set([
+    ...Object.keys(attributeDirectives),
+    ...overrides
+  ]);
+}
+
+/**
+ * Names interactor directive functions.
+ */
+export function plotInteractorNames(overrides = []) {
+  return new Set([
+    ...Object.keys(interactorDirectives),
+    ...overrides
+  ]);
+}
+
+/**
+ * Names of legend directive functions.
+ */
+export function plotLegendNames(overrides = []) {
+  return new Set([
+    ...Object.keys(legendDirectives),
+    ...overrides
+  ]);
+}
+
+/**
+ * Names of mark directive functions.
+ */
+export function plotMarkNames(overrides = []) {
+  return new Set([
+    ...Object.keys(markDirectives),
+    ...overrides
+  ]);
+}

package/src/config/transforms.js

@@ -0,0 +1,35 @@
+/**
+ * Valid transform method names.
+ */
+export function transformNames(overrides = []) {
+  return new Set([
+    'avg',
+    'bin',
+    'centroid',
+    'centroidX',
+    'centroidY',
+    'count',
+    'dateMonth',
+    'dateMonthDay',
+    'dateDay',
+    'geojson',
+    'max',
+    'median',
+    'min',
+    'mode',
+    'quantile',
+    'sum',
+    'row_number',
+    'rank',
+    'dense_rank',
+    'percent_rank',
+    'cume_dist',
+    'ntile',
+    'lag',
+    'lead',
+    'first_value',
+    'last_value',
+    'nth_value',
+    ...overrides
+  ]);
+}

package/src/constants.js

@@ -0,0 +1,51 @@
+// top-level spec
+export const SPEC = 'spec';
+
+// literal values
+export const LITERAL = 'literal';
+
+// dataset identifier
+export const DATAREF = 'dataref';
+
+// options object
+export const OPTIONS = 'options';
+
+// params and selections
+export const SELECTION = 'selection';
+export const PARAMREF = 'paramref';
+export const PARAM = 'param';
+
+// param and selection types
+export const SELECT = 'select';
+export const VALUE = 'value';
+export const CROSSFILTER = 'crossfilter';
+export const INTERSECT = 'intersect';
+export const UNION = 'union';
+export const SINGLE = 'single';
+
+// data definitions
+export const DATA = 'data';
+
+// sql expressions
+export const EXPRESSION = 'expression';
+export const SQL = 'sql';
+export const AGG = 'agg';
+
+// inputs
+export const INPUT = 'input';
+
+// layout
+export const HCONCAT = 'hconcat';
+export const VCONCAT = 'vconcat';
+export const HSPACE = 'hspace';
+export const VSPACE = 'vspace';
+
+// vgplot
+export const MARK = 'mark';
+export const FROM = 'from';
+export const PLOT = 'plot';
+export const LEGEND = 'legend';
+export const ATTRIBUTE = 'attribute';
+export const TRANSFORM = 'transform';
+export const INTERACTOR = 'interactor';
+export const FIXED = 'Fixed';

package/src/index.js

@@ -0,0 +1,36 @@
+export { astToDOM, InstantiateContext } from './ast-to-dom.js';
+export { astToESM, CodegenContext } from './ast-to-esm.js';
+export { parseSpec } from './parse-spec.js';
+
+export * from './constants.js';
+export { ASTNode } from './ast/ASTNode.js';
+export {
+  DataNode,
+  QueryDataNode,
+  TableDataNode,
+  FileDataNode,
+  CSVDataNode,
+  JSONDataNode,
+  ParquetDataNode,
+  SpatialDataNode,
+  LiteralJSONDataNode
+} from './ast/DataNode.js';
+export { ExpressionNode } from './ast/ExpressionNode.js';
+export { HConcatNode } from './ast/HConcatNode.js';
+export { HSpaceNode } from './ast/HSpaceNode.js';
+export { InputNode } from './ast/InputNode.js';
+export { LiteralNode } from './ast/LiteralNode.js';
+export { OptionsNode } from './ast/OptionsNode.js';
+export { ParamNode } from './ast/ParamNode.js';
+export { ParamRefNode } from './ast/ParamRefNode.js';
+export { PlotAttributeNode, PlotFixedNode } from './ast/PlotAttributeNode.js';
+export { PlotFromNode } from './ast/PlotFromNode.js';
+export { PlotInteractorNode } from './ast/PlotInteractorNode.js';
+export { PlotLegendNode } from './ast/PlotLegendNode.js';
+export { PlotMarkNode } from './ast/PlotMarkNode.js';
+export { PlotNode } from './ast/PlotNode.js';
+export { SelectionNode } from './ast/SelectionNode.js';
+export { SpecNode } from './ast/SpecNode.js';
+export { TransformNode } from './ast/TransformNode.js';
+export { VConcatNode } from './ast/VConcatNode.js';
+export { VSpaceNode } from './ast/VSpaceNode.js';

package/src/parse-spec.js

@@ -0,0 +1,111 @@
+import { parseData } from './ast/DataNode.js'
+import { LiteralNode } from './ast/LiteralNode.js';
+import { parseParam, ParamNode } from './ast/ParamNode.js';
+import { ParamRefNode } from './ast/ParamRefNode.js';
+import { parseAttribute } from './ast/PlotAttributeNode.js';
+import { SelectionNode } from './ast/SelectionNode.js';
+import { SpecNode } from './ast/SpecNode.js';
+
+import { componentMap } from './config/components.js';
+import { inputNames } from './config/inputs.js';
+import { plotNames } from './config/plots.js';
+import { transformNames } from './config/transforms.js';
+
+import { error, isString, paramRef } from './util.js';
+
+/**
+ * Parse a Mosaic specification to an AST (abstract syntax tree).
+ * @param {object|string} spec The input specification as an object
+ *  or JSON string.
+ * @param {object} [options] Optional parse options object.
+ * @returns {SpecNode} The top-level AST spec node.
+ */
+export function parseSpec(spec, options) {
+  spec = isString(spec) ? JSON.parse(spec) : spec;
+  return new ParseContext(options).parse(spec);
+}
+
+export class ParseContext {
+  constructor({
+    components = componentMap(),
+    transforms = transformNames(),
+    inputs = inputNames(),
+    plot = plotNames(),
+    params = [],
+    datasets = []
+  } = {}) {
+    this.components = components;
+    this.transforms = transforms;
+    this.inputs = inputs;
+    this.plot = plot;
+    this.params = new Map(params);
+    this.datasets = new Map(datasets);
+  }
+
+  parse(spec) {
+    // eslint-disable-next-line no-unused-vars
+    const {
+      meta,
+      config,
+      data = {},
+      params,
+      plotDefaults = {},
+      ...root
+    } = spec;
+
+    // parse data definitions
+    for (const name in data) {
+      this.datasets.set(name, parseData(name, data[name], this));
+    }
+
+    // parse default attributes
+    this.plotDefaults = Object.entries(plotDefaults)
+      .map(([key, value]) => parseAttribute(key, value, this));
+
+    // parse param/selection definitions
+    for (const name in params) {
+      this.params.set(name, parseParam(params[name], this));
+    }
+
+    return new SpecNode(
+      this.parseComponent(root),
+      meta ? { ...meta } : undefined,
+      config ? { ...config } : undefined,
+      Object.fromEntries(this.datasets),
+      Object.fromEntries(this.params),
+      this.plotDefaults
+    );
+  }
+
+  parseComponent(spec) {
+    for (const [key, parse] of this.components) {
+      const value = spec[key];
+      if (value != null) {
+        return parse(spec, this);
+      }
+    }
+    this.error(`Invalid specification.`, spec);
+  }
+
+  maybeParam(value, makeNode = () => new ParamNode) {
+    const { params } = this;
+    const name = paramRef(value);
+
+    if (name) {
+      if (!params.has(name)) {
+        const p = makeNode();
+        params.set(name, p);
+      }
+      return new ParamRefNode(name);
+    }
+    return new LiteralNode(value);
+  }
+
+  maybeSelection(value) {
+    return this.maybeParam(value, () => new SelectionNode);
+  }
+
+  error(message, data) {
+    error(message, data);
+  }
+}

package/src/util.js

@@ -0,0 +1,47 @@
+export function paramRef(value) {
+  const type = typeof value;
+  return type === 'object' ? value?.param
+    : type === 'string' ? paramStr(value)
+    : null;
+}
+
+export function paramStr(value) {
+  return value?.[0] === '$' ? value.slice(1) : null;
+}
+
+export function toParamRef(name) {
+  return `$${name}`;
+}
+
+export function toArray(value) {
+  return [value].flat();
+}
+
+export function isArray(value) {
+  return Array.isArray(value);
+}
+
+export function isObject(value) {
+  return value !== null && typeof value === 'object' && !isArray(value);
+}
+
+export function isNumber(value) {
+  return typeof value === 'number';
+}
+
+export function isNumberOrString(value) {
+  const t = typeof value;
+  return t === 'number' || t === 'string';
+}
+
+export function isString(value) {
+  return typeof value === 'string';
+}
+
+export function isFunction(value) {
+  return typeof value === 'function';
+}
+
+export function error(message, data) {
+  throw Object.assign(Error(message), { data });
+}