@uwdata/mosaic-spec 0.5.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@uwdata/mosaic-spec",
+  "version": "0.5.0",
+  "description": "Declarative specification of Mosaic-powered applications.",
+  "keywords": [
+    "mosaic",
+    "visualization",
+    "dashboard",
+    "declarative",
+    "specification"
+  ],
+  "license": "BSD-3-Clause",
+  "author": "Jeffrey Heer (http://idl.cs.washington.edu)",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "jsdelivr": "dist/mosaic-spec.min.js",
+  "unpkg": "dist/mosaic-spec.min.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uwdata/mosaic.git"
+  },
+  "scripts": {
+    "prebuild": "rimraf dist && mkdir dist",
+    "build": "node ../../esbuild.js mosaic-spec",
+    "lint": "eslint src test --ext .js",
+    "test": "mocha 'test/**/*-test.js'",
+    "prepublishOnly": "npm run test && npm run lint && npm run build"
+  },
+  "dependencies": {
+    "@uwdata/mosaic-core": "^0.5.0",
+    "@uwdata/mosaic-sql": "^0.5.0",
+    "@uwdata/vgplot": "^0.5.0",
+    "isoformat": "^0.2.1"
+  },
+  "gitHead": "92886dddfb126c1439924c5a0189e4639c3519a7"
+}

package/src/ast/ASTNode.js

@@ -0,0 +1,18 @@
+export class ASTNode {
+  constructor(type, children = null) {
+    this.type = type;
+    this.children = children;
+  }
+
+  instantiate(/* ctx */) {
+    throw Error('instantiate not implemented');
+  }
+
+  codegen(/* ctx */) {
+    return Error('codegen not implemented');
+  }
+
+  toJSON() {
+    return Error('toJSON not implemented');
+  }
+}

package/src/ast/DataNode.js

@@ -0,0 +1,226 @@
+import { create } from '@uwdata/mosaic-sql';
+import { DATA } from '../constants.js';
+import { isArray, isString } from '../util.js';
+import { ASTNode } from './ASTNode.js';
+import { parseOptions } from './OptionsNode.js';
+
+export const TABLE_DATA = 'table';
+export const PARQUET_DATA = 'parquet';
+export const CSV_DATA = 'csv';
+export const JSON_DATA = 'json';
+export const SPATIAL_DATA = 'spatial';
+
+const dataFormats = new Map([
+  [TABLE_DATA, parseTableData],
+  [PARQUET_DATA, parseParquetData],
+  [CSV_DATA, parseCSVData],
+  [JSON_DATA, parseJSONData],
+  [SPATIAL_DATA, parseSpatialData]
+]);
+
+export function parseData(name, spec, ctx) {
+  spec = resolveDataSpec(spec);
+  if (dataFormats.has(spec.type)) {
+    const parse = dataFormats.get(spec.type);
+    return parse(name, spec, ctx);
+  } else {
+    ctx.error(`Unrecognized data format type.`, spec);
+  }
+}
+
+function parseTableData(name, spec, ctx) {
+  // eslint-disable-next-line no-unused-vars
+  const { query, type, ...options } = spec;
+  return new TableDataNode(name, query, parseOptions(options, ctx));
+}
+
+function parseParquetData(name, spec, ctx) {
+  // eslint-disable-next-line no-unused-vars
+  const { file, type, ...options } = spec;
+  return new ParquetDataNode(name, file, parseOptions(options, ctx));
+}
+
+function parseCSVData(name, spec, ctx) {
+  // eslint-disable-next-line no-unused-vars
+  const { file, type, ...options } = spec;
+  return new CSVDataNode(name, file, parseOptions(options, ctx));
+}
+
+function parseJSONData(name, spec, ctx) {
+  // eslint-disable-next-line no-unused-vars
+  const { data, file, type, ...options } = spec;
+  const opt = parseOptions(options, ctx);
+  return data
+    ? new LiteralJSONDataNode(name, data, opt)
+    : new JSONDataNode(name, file, opt);
+}
+
+function parseSpatialData(name, spec, ctx) {
+  // eslint-disable-next-line no-unused-vars
+  const { file, type, ...options } = spec;
+  return new SpatialDataNode(name, file, parseOptions(options, ctx));
+}
+
+function resolveDataSpec(spec) {
+  if (isArray(spec)) spec = { type: 'json', data: spec };
+  if (isString(spec)) spec = { type: 'table', query: spec };
+  return { ...spec, type: inferType(spec) };
+}
+
+function inferType(spec) {
+  return spec.type
+    || fileExtension(spec.file)
+    || 'table';
+}
+
+function fileExtension(file) {
+  const idx = file?.lastIndexOf('.');
+  return idx > 0 ? file.slice(idx + 1) : null;
+}
+
+function resolveFileURL(file, baseURL) {
+  return baseURL ? new URL(file, baseURL).toString() : file;
+}
+
+function codegenOptions(options, ctx) {
+  const code = options?.codegen(ctx);
+  return code ? `, ${code}` : '';
+}
+
+export class DataNode extends ASTNode {
+  constructor(name, format) {
+    super(DATA);
+    this.name = name;
+    this.format = format;
+  }
+}
+
+export class QueryDataNode extends DataNode {
+  constructor(name, format) {
+    super(name, format);
+  }
+
+  instantiateQuery(ctx) {
+    ctx.error('instantiateQuery not implemented');
+  }
+
+  codegenQuery(ctx) {
+    ctx.error('codegenQuery not implemented');
+  }
+
+  instantiate(ctx) {
+    const query = this.instantiateQuery(ctx);
+    if (query) return query;
+  }
+
+  codegen(ctx) {
+    const query = this.codegenQuery(ctx);
+    if (query) return query;
+  }
+}
+
+export class TableDataNode extends QueryDataNode {
+  constructor(name, query, options) {
+    super(name, TABLE_DATA);
+    this.query = query?.trim();
+    this.options = options;
+  }
+
+  instantiateQuery(ctx) {
+    const { name, query, options } = this;
+    if (query) {
+      return ctx.api.create(name, query, options.instantiate(ctx));
+    }
+  }
+
+  codegenQuery(ctx) {
+    const { name, query, options } = this;
+    if (query) {
+      return `\`${create(name, query, options.instantiate(ctx))}\``;
+    }
+  }
+
+  toJSON() {
+    const { format, query, options } = this;
+    return { type: format, query, ...options.toJSON() };
+  }
+}
+
+export class FileDataNode extends QueryDataNode {
+  constructor(name, format, method, file, options) {
+    super(name, format);
+    this.file = file;
+    this.method = method;
+    this.options = options;
+  }
+
+  instantiateQuery(ctx) {
+    const { name, method, file, options } = this;
+    const url = resolveFileURL(file, ctx.baseURL);
+    const opt = options?.instantiate(ctx)
+    return ctx.api[method](name, url, opt);
+  }
+
+  codegenQuery(ctx) {
+    const { name, method, file, options } = this;
+    const url = resolveFileURL(file, ctx.baseURL);
+    const opt = codegenOptions(options, ctx);
+    return `${ctx.ns()}${method}("${name}", "${url}"${opt})`;
+  }
+
+  toJSON() {
+    const { format, file, options } = this;
+    return { type: format, file, ...options.toJSON() };
+  }
+}
+
+export class SpatialDataNode extends FileDataNode {
+  constructor(name, file, options) {
+    super(name, SPATIAL_DATA, 'loadSpatial', file, options);
+  }
+}
+
+export class ParquetDataNode extends FileDataNode {
+  constructor(name, file, options) {
+    super(name, PARQUET_DATA, 'loadParquet', file, options);
+  }
+}
+
+export class CSVDataNode extends FileDataNode {
+  constructor(name, file, options) {
+    super(name, CSV_DATA, 'loadCSV', file, options);
+  }
+}
+
+export class JSONDataNode extends FileDataNode {
+  constructor(name, file, options) {
+    super(name, JSON_DATA, 'loadJSON', file, options);
+  }
+}
+
+export class LiteralJSONDataNode extends QueryDataNode {
+  constructor(name, data, options) {
+    super(name, JSON_DATA);
+    this.data = data;
+    this.options = options;
+  }
+
+  instantiateQuery(ctx) {
+    const { name, data, options } = this;
+    return ctx.api.loadObjects(name, data, options.instantiate(ctx));
+  }
+
+  codegenQuery(ctx) {
+    const { name, data, options } = this;
+    const opt = options ? ',' + options.codegen(ctx) : '';
+    const d = '[\n    '
+      + data.map(d => JSON.stringify(d)).join(',\n    ')
+      + '\n  ]';
+    return `${ctx.ns()}loadObjects("${name}", ${d}${opt})`;
+  }
+
+  toJSON() {
+    const { format, data, options } = this;
+    return { type: format, data, ...options.toJSON() };
+  }
+}

package/src/ast/ExpressionNode.js

@@ -0,0 +1,65 @@
+import { AGG, EXPRESSION, SQL } from '../constants.js';
+import { ASTNode } from './ASTNode.js';
+
+export function parseExpression(spec, ctx) {
+  const { label } = spec;
+  const key = spec[SQL] ? SQL
+    : spec[AGG] ? AGG
+    : ctx.error('Unrecognized expression type', spec);
+
+  const expr = spec[key];
+  const tokens = expr.split(/(\\'|\\"|"(?:\\"|[^"])*"|'(?:\\'|[^'])*'|\$\w+)/g);
+  const spans = [''];
+  const params = [];
+
+  for (let i = 0, k = 0; i < tokens.length; ++i) {
+    const tok = tokens[i];
+    if (tok.startsWith('$')) {
+      params[k] = ctx.maybeParam(tok);
+      spans[++k] = '';
+    } else {
+      spans[k] += tok;
+    }
+  }
+
+  return new ExpressionNode(expr, spans, params, label, key === AGG);
+}
+
+export class ExpressionNode extends ASTNode {
+  constructor(value, spans, params, label, aggregate) {
+    super(EXPRESSION);
+    this.value = value;
+    this.spans = spans;
+    this.params = params;
+    this.label = label;
+    this.aggregate = aggregate;
+  }
+
+  instantiate(ctx) {
+    const { spans, params, label, aggregate } = this;
+    const tag = ctx.api[aggregate ? AGG : SQL];
+    const args = params.map(e => e.instantiate(ctx));
+    return tag(spans, ...args).annotate({ label });
+  }
+
+  codegen(ctx) {
+    const { spans, params, label, aggregate } = this;
+    const method = aggregate ? AGG : SQL;
+
+    // reconstitute expression string
+    let str = '';
+    const n = params.length;
+    for (let i = 0; i < n; ++i) {
+      str += spans[i] + '${' + params[i].codegen(ctx) + '}';
+    }
+    str += spans[n];
+
+    return `${ctx.ns()}${method}\`${str}\``
+      + (label ? `.annotate({ label: ${JSON.stringify(label)} })` : '');
+  }
+
+  toJSON() {
+    const key = this.aggregate ? AGG : SQL;
+    return { [key]: this.value };
+  }
+}

package/src/ast/HConcatNode.js

@@ -0,0 +1,29 @@
+import { ASTNode } from './ASTNode.js';
+import { HCONCAT } from '../constants.js';
+
+export function parseHConcat(spec, ctx) {
+  const children = spec[HCONCAT].map(s => ctx.parseComponent(s));
+  return new HConcatNode(children);
+}
+
+export class HConcatNode extends ASTNode {
+
+  constructor(children) {
+    super(HCONCAT, children);
+  }
+
+  instantiate(ctx) {
+    return ctx.api[HCONCAT](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/HSpaceNode.js

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

package/src/ast/InputNode.js

@@ -0,0 +1,34 @@
+import { ASTNode } from './ASTNode.js';
+import { INPUT } from '../constants.js';
+import { parseOptions } from './OptionsNode.js';
+
+export function parseInput(spec, ctx) {
+  const { [INPUT]: name, ...options } = spec;
+  if (!ctx.inputs?.has(name)) {
+    ctx.error(`Unrecognized input type: ${name}`, spec);
+  }
+  return new InputNode(name, parseOptions(options, ctx));
+}
+
+export class InputNode extends ASTNode {
+  constructor(name, options) {
+    super(INPUT);
+    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 { type, name, options } = this;
+    return { [type]: name, ...options.toJSON() };
+  }
+}

package/src/ast/LiteralNode.js

@@ -0,0 +1,21 @@
+import { ASTNode } from './ASTNode.js';
+import { LITERAL } from '../constants.js';
+
+export class LiteralNode extends ASTNode {
+  constructor(value) {
+    super(LITERAL);
+    this.value = value;
+  }
+
+  instantiate() {
+    return this.value;
+  }
+
+  codegen(ctx) {
+    return ctx.stringify(this.value);
+  }
+
+  toJSON() {
+    return this.value;
+  }
+}

package/src/ast/OptionsNode.js

@@ -0,0 +1,52 @@
+import { ASTNode } from './ASTNode.js';
+import { OPTIONS } from '../constants.js';
+
+export function parseOptions(spec, ctx) {
+  const options = {};
+  for (const key in spec) {
+    options[key] = ctx.maybeSelection(spec[key]);
+  }
+  return new OptionsNode(options);
+}
+
+export class OptionsNode extends ASTNode {
+  constructor(options) {
+    super(OPTIONS);
+    this.options = options;
+  }
+
+  filter(predicate) {
+    const opt = Object.fromEntries(
+      Object.entries(this.options)
+        .filter(([key, value]) => predicate(key, value))
+    );
+    return new OptionsNode(opt);
+  }
+
+  instantiate(ctx) {
+    const { options } = this;
+    const opt = {};
+    for (const key in options) {
+      opt[key] = options[key].instantiate(ctx);
+    }
+    return opt;
+  }
+
+  codegen(ctx) {
+    const { options } = this;
+    const opt = [];
+    for (const key in options) {
+      opt.push(`${key}: ${options[key].codegen(ctx)}`);
+    }
+    return opt.length ? `{${ctx.maybeLineWrap(opt)}}` : '';
+  }
+
+  toJSON() {
+    const { options } = this;
+    const opt = {};
+    for (const key in options) {
+      opt[key] = options[key].toJSON();
+    }
+    return opt;
+  }
+}

package/src/ast/ParamNode.js

@@ -0,0 +1,55 @@
+import { parse as isoparse } from 'isoformat';
+import { isArray, isObject } from '../util.js';
+import { ASTNode } from './ASTNode.js';
+import { CROSSFILTER, INTERSECT, PARAM, SINGLE, UNION, VALUE } from '../constants.js';
+import { SelectionNode } from './SelectionNode.js';
+
+const paramTypes = new Set([VALUE, SINGLE, CROSSFILTER, INTERSECT, UNION]);
+
+export function parseParam(spec, ctx) {
+  const param = isObject(spec) ? spec : { value: spec };
+  const { select = VALUE, cross, date, value } = param;
+  if (!paramTypes.has(select)) {
+    ctx.error(`Unrecognized param type: ${select}`, param);
+  }
+
+  if (select !== VALUE) {
+    return new SelectionNode(select, cross);
+  } else if (isArray(value)) {
+    return new ParamNode(value.map(v => ctx.maybeParam(v)));
+  } else {
+    return new ParamNode(value, date);
+  }
+}
+
+export class ParamNode extends ASTNode {
+  constructor(value, date) {
+    super(PARAM);
+    this.value = value;
+    this.date = date;
+  }
+
+  instantiate(ctx) {
+    const { date, value } = this;
+    const { Param } = ctx.api;
+    return isArray(value)
+      ? Param.array(value.map(v => v.instantiate(ctx)))
+      : Param.value(isoparse(date, value));
+  }
+
+  codegen(ctx) {
+    const { value, date } = this;
+    const prefix = `${ctx.ns()}Param.`;
+    return isArray(value)
+      ? `${prefix}array([${value.map(v => v.codegen(ctx)).join(', ')}])`
+      : date ? `${prefix}value(new Date(${JSON.stringify(date)}))`
+      : `${prefix}value(${JSON.stringify(value)})`;
+  }
+
+  toJSON() {
+    const { date, value } = this;
+    return isArray(value) ? value.map(v => v.toJSON())
+      : date ? { date }
+      : value;
+  }
+}

package/src/ast/ParamRefNode.js

@@ -0,0 +1,22 @@
+import { ASTNode } from './ASTNode.js';
+import { PARAMREF } from '../constants.js';
+import { toParamRef } from '../util.js';
+
+export class ParamRefNode extends ASTNode {
+  constructor(name) {
+    super(PARAMREF);
+    this.name = name;
+  }
+
+  instantiate(ctx) {
+    return ctx.activeParams?.get(this.name);
+  }
+
+  codegen() {
+    return toParamRef(this.name);
+  }
+
+  toJSON() {
+    return toParamRef(this.name);
+  }
+}

package/src/ast/PlotAttributeNode.js

@@ -0,0 +1,55 @@
+import { ASTNode } from './ASTNode.js';
+import { ATTRIBUTE, FIXED, LITERAL } from '../constants.js';
+
+export function parseAttribute(key, value, ctx) {
+  if (!ctx.plot?.attributes?.has(key)) {
+    ctx.error(`Unrecognized attribute: ${key}`);
+  }
+  return new PlotAttributeNode(
+    key,
+    value === FIXED ? new PlotFixedNode : ctx.maybeParam(value)
+  );
+}
+
+export class PlotAttributeNode extends ASTNode {
+  constructor(name, value) {
+    super(ATTRIBUTE);
+    this.name = name;
+    this.value = value;
+  }
+
+  instantiate(ctx) {
+    const { name, value } = this;
+    const fn = ctx.api[name];
+    return fn(value.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const { name, value } = this;
+    return `${ctx.tab()}${ctx.ns()}${name}(${value.codegen(ctx)})`;
+  }
+
+  toJSON() {
+    const { name, value } = this;
+    return { [name]: value.toJSON() };
+  }
+}
+
+export class PlotFixedNode extends ASTNode {
+  constructor() {
+    super(LITERAL);
+    this.value = FIXED;
+  }
+
+  instantiate(ctx) {
+    return ctx.api[FIXED];
+  }
+
+  codegen(ctx) {
+    return `${ctx.ns()}${FIXED}`;
+  }
+
+  toJSON() {
+    return this.value;
+  }
+}

package/src/ast/PlotFromNode.js

@@ -0,0 +1,44 @@
+import { isArray } from '../util.js';
+import { ASTNode } from './ASTNode.js';
+import { FROM } from '../constants.js';
+import { LiteralNode } from './LiteralNode.js';
+import { parseOptions } from './OptionsNode.js';
+
+export function parseMarkData(spec, ctx) {
+  if (!spec) {
+    // no data, likely a decoration mark
+    return null;
+  }
+
+  if (isArray(spec)) {
+    // data provided directly, treat as JSON literal
+    return new LiteralNode(spec);
+  }
+
+  const { from: table, ...options } = spec;
+  return new PlotFromNode(table, parseOptions(options, ctx));
+}
+
+export class PlotFromNode extends ASTNode {
+  constructor(table, options) {
+    super(FROM);
+    this.table = table;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { table, options } = this;
+    return ctx.api[FROM](table, options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const { type, table, options } = this;
+    const opt = options.codegen(ctx);
+    return `${ctx.ns()}${type}("${table}"${opt ? ', ' + opt : ''})`;
+  }
+
+  toJSON() {
+    const { type, table, options } = this;
+    return { [type]: table, ...options.toJSON() };
+  }
+}