@uwdata/mosaic-spec 0.5.0

package/src/ast/PlotInteractorNode.js

@@ -0,0 +1,34 @@
+import { ASTNode } from './ASTNode.js';
+import { INTERACTOR, SELECT } from '../constants.js';
+import { parseOptions } from './OptionsNode.js';
+
+export function parseInteractor(spec, ctx) {
+  const { [SELECT]: name, ...options } = spec;
+  if (!ctx.plot?.interactors?.has(name)) {
+    ctx.error(`Unrecognized interactor type: ${name}`, spec);
+  }
+  return new PlotInteractorNode(name, parseOptions(options, ctx));
+}
+
+export class PlotInteractorNode extends ASTNode {
+  constructor(name, options) {
+    super(INTERACTOR);
+    this.name = name;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const fn = ctx.api[this.name];
+    return fn(this.options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const opt = this.options.codegen(ctx);
+    return `${ctx.tab()}${ctx.ns()}${this.name}(${opt})`;
+  }
+
+  toJSON() {
+    const { name, options } = this;
+    return { [SELECT]: name, ...options.toJSON() };
+  }
+}

package/src/ast/PlotLegendNode.js

@@ -0,0 +1,36 @@
+import { ASTNode } from './ASTNode.js';
+import { LEGEND } from '../constants.js';
+import { parseOptions } from './OptionsNode.js';
+
+export function parseLegend(spec, ctx) {
+  const { [LEGEND]: name, ...options } = spec;
+  const key = `${name}Legend`;
+  if (!ctx.plot?.legends?.has(key)) {
+    ctx.error(`Unrecognized legend type: ${name}`, spec);
+  }
+  return new PlotLegendNode(key, name, parseOptions(options, ctx));
+}
+
+export class PlotLegendNode extends ASTNode {
+  constructor(key, name, options) {
+    super(LEGEND);
+    this.key = key;
+    this.name = name;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const fn = ctx.api[this.key];
+    return fn(this.options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const opt = this.options.codegen(ctx);
+    return `${ctx.tab()}${ctx.ns()}${this.key}(${opt})`;
+  }
+
+  toJSON() {
+    const { type, name, options } = this;
+    return { [type]: name, ...options.toJSON() };
+  }
+}

package/src/ast/PlotMarkNode.js

@@ -0,0 +1,75 @@
+import { AGG, MARK, SQL } from '../constants.js';
+import { isObject } from '../util.js';
+import { ASTNode } from './ASTNode.js';
+import { parseExpression } from './ExpressionNode.js';
+import { OptionsNode } from './OptionsNode.js';
+import { parseMarkData } from './PlotFromNode.js';
+import { parseTransform } from './TransformNode.js';
+
+function maybeTransform(value, ctx) {
+  if (isObject(value)) {
+    return (value[SQL] || value[AGG])
+      ? parseExpression(value, ctx)
+      : parseTransform(value, ctx);
+  }
+}
+
+export function parseMark(spec, ctx) {
+  const { mark, data, ...options } = spec;
+  if (!ctx.plot?.marks?.has(mark)) {
+    ctx.error(`Unrecognized mark type: ${mark}`, spec);
+  }
+
+  const input = parseMarkData(data, ctx);
+
+  const opt = {};
+  for (const key in options) {
+    const value = options[key];
+    opt[key] = maybeTransform(value, ctx) || ctx.maybeParam(value);
+  }
+
+  return new PlotMarkNode(mark, input, new OptionsNode(opt));
+}
+
+export class PlotMarkNode extends ASTNode {
+  constructor(name, data, options) {
+    super(MARK);
+    this.name = name;
+    this.data = data;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { name, data, options } = this;
+    const fn = ctx.api[name];
+    const opt = options.instantiate(ctx);
+    return data ? fn(data.instantiate(ctx), opt) : fn(opt);
+  }
+
+  codegen(ctx) {
+    const { name, data, options } = this;
+    const d = data ? data.codegen(ctx) : '';
+    const o = options.codegen(ctx);
+
+    let arg;
+    if (d && o) {
+      ctx.indent();
+      const opt = options.codegen(ctx);
+      arg = `\n${ctx.tab()}${d},\n${ctx.tab()}${opt}\n`;
+      ctx.undent();
+      arg += ctx.tab();
+    } else {
+      arg = `${d}${o}`;
+    }
+    return `${ctx.tab()}${ctx.ns()}${name}(${arg})`;
+  }
+
+  toJSON() {
+    const { type, name, data, options } = this;
+    return {
+      [type]: name,
+      ...(data ? { data: data.toJSON() } : {}),
+      ...options.toJSON()
+    };
+  }
+}

package/src/ast/PlotNode.js

@@ -0,0 +1,66 @@
+import { isString } from '../util.js';
+import { ASTNode } from './ASTNode.js';
+import { PLOT } from '../constants.js';
+import { parseAttribute } from './PlotAttributeNode.js';
+import { parseInteractor } from './PlotInteractorNode.js';
+import { parseLegend } from './PlotLegendNode.js';
+import { parseMark } from './PlotMarkNode.js';
+
+export function parseTopLevelMark(spec, ctx) {
+  return parsePlot({ plot: [ spec ] }, ctx);
+}
+
+export function parsePlot(spec, ctx) {
+  const { [PLOT]: entries, ...attrs } = spec;
+  const attributes = Object.entries(attrs)
+    .map(([key, value]) => parseAttribute(key, value, ctx));
+
+  const children = entries.map(spec => {
+    return isString(spec.mark) ? parseMark(spec, ctx)
+      : isString(spec.legend) ? parseLegend(spec, ctx)
+      : isString(spec.select) ? parseInteractor(spec, ctx)
+      : ctx.error(`Invalid plot entry.`, spec);
+  });
+
+  return new PlotNode(children, attributes);
+}
+
+export class PlotNode extends ASTNode {
+  constructor(children, attributes) {
+    super(PLOT, children);
+    this.attributes = attributes;
+  }
+
+  instantiate(ctx) {
+    const attrs = [
+      ...(ctx.plotDefaults || []),
+      ...(this.attributes || [])
+    ];
+    return ctx.api[PLOT](
+      this.children.map(c => c.instantiate(ctx)),
+      attrs.map(a => a.instantiate(ctx))
+    );
+  }
+
+  codegen(ctx) {
+    const { type, children, attributes } = this;
+    ctx.indent();
+    const entries = [
+      ...children.map(c => c.codegen(ctx)),
+      ...(ctx.plotDefaults?.length ? [`${ctx.tab()}...defaultAttributes`] : []),
+      ...attributes.map(a => a.codegen(ctx))
+    ].join(',\n');
+    ctx.undent();
+
+    return `${ctx.tab()}${ctx.ns()}${type}(\n${entries}\n${ctx.tab()})`;
+  }
+
+  toJSON() {
+    const { type, children, attributes } = this;
+    const plot = { [type]: children.map(c => c.toJSON()) };
+    for (const a of attributes) {
+      Object.assign(plot, a.toJSON());
+    }
+    return plot;
+  }
+}

package/src/ast/SelectionNode.js

@@ -0,0 +1,26 @@
+import { ASTNode } from './ASTNode.js';
+import { INTERSECT, SELECTION } from '../constants.js';
+
+export class SelectionNode extends ASTNode {
+  constructor(select = INTERSECT, cross) {
+    super(SELECTION);
+    this.select = select;
+    this.cross = cross;
+  }
+
+  instantiate(ctx) {
+    const { select, cross } = this;
+    return ctx.api.Selection[select]({ cross });
+  }
+
+  codegen(ctx) {
+    const { select, cross } = this;
+    const arg = cross != null ? `{ cross: ${cross} }` : '';
+    return `${ctx.ns()}Selection.${select}(${arg})`;
+  }
+
+  toJSON() {
+    const { select, cross } = this;
+    return { select, cross };
+  }
+}

package/src/ast/SpecNode.js

@@ -0,0 +1,47 @@
+import { SPEC } from '../constants.js';
+import { ASTNode } from './ASTNode.js';
+
+export class SpecNode extends ASTNode {
+  constructor(root, meta, config, data, params, plotDefaults) {
+    super(SPEC, [root]);
+    this.root = root;
+    this.meta = meta;
+    this.config = config;
+    this.data = data;
+    this.params = params;
+    this.plotDefaults = plotDefaults;
+  }
+
+  toJSON() {
+    const { root, meta, config, plotDefaults } = this;
+    const dataDefs = new Map(Object.entries(this.data));
+    const paramDefs = new Map(Object.entries(this.params));
+    const spec = {};
+
+    if (meta) spec.meta = { ...meta };
+    if (config) spec.config = { ...config };
+
+    if (dataDefs?.size) {
+      const data = spec.data = {};
+      for (const [name, node] of dataDefs) {
+        data[name] = node.toJSON();
+      }
+    }
+
+    if (paramDefs?.size) {
+      const params = spec.params = {};
+      for (const [name, node] of paramDefs) {
+        params[name] = node.toJSON();
+      }
+    }
+
+    if (plotDefaults?.length) {
+      const defaults = spec.plotDefaults = {};
+      for (const node of plotDefaults) {
+        Object.assign(defaults, node.toJSON());
+      }
+    }
+
+    return Object.assign(spec, root.toJSON());
+  }
+}

package/src/ast/TransformNode.js

@@ -0,0 +1,118 @@
+import { ASTNode } from './ASTNode.js';
+import { TRANSFORM } from '../constants.js';
+
+function toArray(value) {
+  return value == null ? [] : [value].flat();
+}
+
+export function parseTransform(spec, ctx) {
+  let name;
+  for (const key in spec) {
+    if (ctx.transforms.has(key)) {
+      name = key;
+    }
+  }
+
+  if (!name) {
+    return; // return undefined to signal no transform!
+  }
+
+  const args = name === 'count' || name == null ? [] : toArray(spec[name]);
+  const options = {
+    distinct: spec.distinct,
+    orderby: toArray(spec.orderby).map(v => ctx.maybeParam(v)),
+    partitionby: toArray(spec.partitionby).map(v => ctx.maybeParam(v)),
+    rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
+    range: spec.range ? ctx.maybeParam(spec.range) : null
+  };
+
+  return new TransformNode(name, args, options);
+}
+
+export class TransformNode extends ASTNode {
+  constructor(name, args, options) {
+    super(TRANSFORM);
+    this.name = name;
+    this.args = args;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { name, args, options } = this;
+    const { distinct, orderby, partitionby, rows, range } = options;
+
+    const fn = ctx.api[name];
+    let expr = fn(...args);
+    if (distinct) {
+      expr = expr.distinct();
+    }
+    if (orderby.length) {
+      expr = expr.orderby(orderby.map(v => v.instantiate(ctx)));
+    }
+    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));
+    }
+    return expr;
+  }
+
+  codegen(ctx) {
+    const { name, args, options } = this;
+    const { distinct, orderby, partitionby, rows, range } = options;
+
+    let str = `${ctx.ns()}${name}(`
+      + args.map(v => JSON.stringify(v)).join(', ')
+      + ')';
+
+    if (distinct) {
+      str += '.distinct()'
+    }
+    if (orderby.length) {
+      const p = orderby.map(v => v.codegen(ctx));
+      str += `.orderby(${p.join(', ')})`;
+    }
+    if (partitionby.length) {
+      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)})`;
+    }
+
+    return str;
+  }
+
+  toJSON() {
+    const { name, args, options } = this;
+    const { distinct, orderby, partitionby, rows, range } = options;
+
+    const json = { [name]: simplify(args) };
+
+    if (distinct) {
+      json.distinct = true;
+    }
+    if (orderby.length) {
+      json.orderby = simplify(orderby.map(v => v.toJSON()));
+    }
+    if (partitionby.length) {
+      json.partitionby = simplify(partitionby.map(v => v.toJSON()));
+    }
+    if (rows) {
+      json.rows = rows.toJSON();
+    } else if (range) {
+      json.range = range.toJSON();
+    }
+
+    return json;
+  }
+}
+
+function simplify(array) {
+  return array.length === 0 ? '' : array.length === 1 ? array[0] : array;
+}

package/src/ast/VConcatNode.js

@@ -0,0 +1,28 @@
+import { ASTNode } from './ASTNode.js';
+import { VCONCAT } from '../constants.js';
+
+export function parseVConcat(spec, ctx) {
+  const children = spec[VCONCAT].map(s => ctx.parseComponent(s));
+  return new VConcatNode(children);
+}
+
+export class VConcatNode extends ASTNode {
+  constructor(children) {
+    super(VCONCAT, children);
+  }
+
+  instantiate(ctx) {
+    return ctx.api[VCONCAT](this.children.map(c => c.instantiate(ctx)));
+  }
+
+  codegen(ctx) {
+    ctx.indent();
+    const items = this.children.map(c => c.codegen(ctx));
+    ctx.undent();
+    return `${ctx.tab()}${ctx.ns()}${this.type}(\n${items.join(',\n')}\n${ctx.tab()})`;
+  }
+
+  toJSON() {
+    return { [this.type]: this.children.map(c => c.toJSON()) };
+  }
+}

package/src/ast/VSpaceNode.js

@@ -0,0 +1,25 @@
+import { ASTNode } from './ASTNode.js';
+import { VSPACE } from '../constants.js';
+
+export function parseVSpace(spec) {
+  return new VSpaceNode(spec[VSPACE]);
+}
+
+export class VSpaceNode extends ASTNode {
+  constructor(value) {
+    super(VSPACE);
+    this.value = value;
+  }
+
+  instantiate(ctx) {
+    return ctx.api[VSPACE](this.value);
+  }
+
+  codegen(ctx) {
+    return `${ctx.tab()}${ctx.ns()}${this.type}(${this.value})`;
+  }
+
+  toJSON() {
+    return { [this.type]: this.value };
+  }
+}

package/src/ast-to-dom.js

@@ -0,0 +1,64 @@
+import { createAPIContext, loadExtension } from '@uwdata/vgplot';
+import { SpecNode } from './ast/SpecNode.js';
+import { resolveExtensions } from './config/extensions.js';
+import { error } from './util.js';
+
+/**
+ * Generate running web application (DOM content) for a Mosaic spec AST.
+ * @param {SpecNode} ast Mosaic AST root node.
+ * @param {object} [options] Instantiation options.
+ * @param {string} [options.baseURL] The base URL for loading data files.
+ * @returns {object} An object with the resulting DOM element, and
+ *   a map of named parameters (Param and Selection instances).
+ */
+export async function astToDOM(ast, options) {
+  const { data, params, plotDefaults } = ast;
+  const ctx = new InstantiateContext({ plotDefaults, ...options });
+
+  const queries = [];
+
+  // process database extensions
+  const exts = resolveExtensions(ast);
+  queries.push(...Array.from(exts).map(name => loadExtension(name)));
+
+  // process data definitions
+  for (const node of Object.values(data)) {
+    const query = node.instantiate(ctx);
+    if (query) queries.push(query);
+  }
+
+  // perform extension and data loading, if needed
+  if (queries.length > 0) {
+    await ctx.coordinator.exec(queries);
+  }
+
+  // process param/selection definitions
+  for (const [name, node] of Object.entries(params)) {
+    const param = node.instantiate(ctx);
+    ctx.activeParams.set(name, param);
+  }
+
+  return {
+    element: ast.root.instantiate(ctx),
+    params: ctx.activeParams
+  };
+}
+
+export class InstantiateContext {
+  constructor({
+    api = createAPIContext(),
+    plotDefaults = [],
+    activeParams = new Map,
+    baseURL = null
+  } = {}) {
+    this.api = api;
+    this.plotDefaults = plotDefaults;
+    this.activeParams = activeParams;
+    this.baseURL = baseURL;
+    this.coordinator = api.context.coordinator;
+  }
+
+  error(message, data) {
+    error(message, data);
+  }
+}

package/src/ast-to-esm.js

@@ -0,0 +1,178 @@
+import { SpecNode } from './ast/SpecNode.js';
+import { resolveExtensions } from './config/extensions.js';
+import { error, isArray, isObject, isString, toParamRef } from './util.js';
+
+/**
+ * Generate ESM code for a Mosaic spec AST.
+ * @param {SpecNode} ast Mosaic AST root node.
+ * @param {object} [options] Code generation options.
+ * @param {string} [options.namespace='vg'] The vgplot API namespace object.
+ * @param {string} [options.baseURL] The base URL for loading data files.
+ * @param {number} [options.depth=0] The starting indentation depth.
+ * @param {Map<string,string>} [options.imports] A Map of ESM imports to
+ *  include in generated code. Keys are packages (e.g., '@uwdata/vgplot')
+ *  and values indicate what to import (e.g., '* as vg').
+ * @returns {string} Generated ESM code using the vgplot API.
+ */
+export function astToESM(ast, options) {
+  const { root, data, params, plotDefaults } = ast;
+  const ctx = new CodegenContext({ plotDefaults, ...options });
+
+  // generate package imports
+  const importsCode = [];
+  for (const [pkg, methods] of ctx.imports) {
+    importsCode.push(
+      isString(methods)
+        ? `import ${methods} from "${pkg}";`
+        : `import { ${methods.join(', ')} } from "${pkg}";`
+    );
+  }
+
+  // generate database connector code
+  const connectorCode = [];
+  if (ctx.connector) {
+    const con = `${ctx.ns()}${ctx.connector}Connector()`;
+    connectorCode.push(
+      `${ctx.tab()}${ctx.ns()}coordinator().databaseConnector(${con});`
+    );
+  }
+
+  // process extensions and data definitions
+  const queries = [];
+  for (const name of resolveExtensions(ast)) {
+    queries.push(`${ctx.ns()}loadExtension("${name}")`);
+  }
+  for (const node of Object.values(data)) {
+    const load = node.codegen(ctx);
+    if (load) queries.push(load);
+  }
+
+  // perform extension and data loading
+  const dataCode = [];
+  if (queries.length) {
+    dataCode.push(`${ctx.tab()}await ${ctx.ns()}coordinator().exec([`);
+    ctx.indent();
+    dataCode.push(queries.map(q => `${ctx.tab()}${q}`).join(',\n'));
+    ctx.undent();
+    dataCode.push(`${ctx.tab()}]);`);
+  }
+
+  // generate params / selections
+  const paramCode = [];
+  for (const [key, value] of Object.entries(params)) {
+    paramCode.push(`const ${toParamRef(key)} = ${value.codegen(ctx)};`);
+  }
+
+  // generate default attributes
+  let defaultCode = [];
+  const defaultList = plotDefaults;
+  if (defaultList.length) {
+    defaultCode = [
+      'const defaultAttributes = [',
+      defaultList.map(a => '  ' + a.codegen(ctx)).join(',\n'),
+      '];'
+    ];
+  }
+
+  // generate specification tree
+  const specCode = [
+    `export default ${root.codegen(ctx)};`
+  ];
+
+  return [
+    ...importsCode,
+    ...maybeNewline(importsCode),
+    ...connectorCode,
+    ...maybeNewline(connectorCode),
+    ...dataCode,
+    ...maybeNewline(dataCode),
+    ...paramCode,
+    ...maybeNewline(paramCode),
+    ...defaultCode,
+    ...maybeNewline(defaultCode),
+    ...specCode
+  ].join('\n');
+}
+
+export class CodegenContext {
+  constructor({
+    plotDefaults = null,
+    namespace = 'vg',
+    connector = null,
+    imports = new Map([['@uwdata/vgplot', '* as vg']]),
+    baseURL = null,
+    depth = 0
+  } = {}) {
+    this.plotDefaults = plotDefaults;
+    this.namespace = `${namespace}.`;
+    this.connector = connector;
+    this.imports = imports;
+    this.baseURL = baseURL;
+    this.depth = depth;
+  }
+
+  addImport(pkg, method) {
+    if (!this.imports.has(pkg)) {
+      this.imports.set(pkg, []);
+    }
+    this.imports.get(pkg).push(method);
+  }
+
+  setImports(pkg, all) {
+    this.imports.set(pkg, all);
+  }
+
+  ns() {
+    return this.namespace;
+  }
+
+  indent() {
+    this.depth += 1;
+  }
+
+  undent() {
+    this.depth -= 1;
+  }
+
+  tab() {
+    return Array.from({ length: this.depth }, () => '  ').join('');
+  }
+
+  stringify(value) {
+    if (isArray(value)) {
+      const items = value.map(v => this.stringify(v));
+      return `[${this.maybeLineWrap(items)}]`;
+    } else if (isObject(value)) {
+      const props = Object.entries(value)
+        .map(([k, v]) => `${maybeQuote(k)}: ${this.stringify(v)}`);
+      return `{${this.maybeLineWrap(props)}}`;
+    } else {
+      return JSON.stringify(value);
+    }
+  }
+
+  maybeLineWrap(spans) {
+    const limit = 80 - 2 * this.depth;
+    const chars = 2 * spans.length + spans.reduce((a, b) => a + b.length, 0);
+    if (chars > limit) {
+      this.indent();
+      const str = spans.map(s => `\n${this.tab()}${s}`).join(',')
+      this.undent();
+      return str + '\n' + this.tab();
+    } else {
+      return spans.join(', ');
+    }
+  }
+
+  error(message, data) {
+    error(message, data);
+  }
+}
+
+function maybeQuote(str) {
+  return /^[A-Za-z_$]\w*/.test(str) ? str : JSON.stringify(str);
+}
+
+function maybeNewline(entry) {
+  return entry?.length ? [''] : [];
+}