@uwdata/mosaic-spec 0.10.0 → 0.11.0

package/dist/types/ast/ParamNode.d.ts

@@ -1,9 +1,8 @@
-export function parseParam(spec: any, ctx: any): SelectionNode | ParamNode;
+export function parseParam(spec: any, ctx: any): import("./SelectionNode.js").SelectionNode | ParamNode;
 export class ParamNode extends ASTNode {
     value: any;
     date: any;
     instantiate(ctx: any): any;
     codegen(ctx: any): string;
 }
-import { SelectionNode } from './SelectionNode.js';
 import { ASTNode } from './ASTNode.js';

package/dist/types/ast/ParamRefNode.d.ts

@@ -2,7 +2,7 @@ export class ParamRefNode extends ASTNode {
     constructor(name: any);
     name: any;
     instantiate(ctx: any): any;
-    codegen(): string;
+    codegen(ctx: any): string;
     toJSON(): string;
 }
 import { ASTNode } from './ASTNode.js';

package/dist/types/ast/SelectionNode.d.ts

@@ -1,14 +1,24 @@
+export function parseSelection(spec: any, ctx: any): SelectionNode;
 export class SelectionNode extends ASTNode {
-    constructor(select: string, cross: any, empty: any);
+    /**
+     * Create a Selection AST node.
+     * @param {string} select The selection type.
+     * @param {OptionsNode} options Selection options.
+     */
+    constructor(select?: string, options?: OptionsNode);
     select: string;
-    cross: any;
-    empty: any;
+    options: OptionsNode;
     instantiate(ctx: any): any;
     codegen(ctx: any): string;
     toJSON(): {
         select: string;
-        cross: any;
-        empty: any;
     };
 }
+export class IncludeNode extends ASTNode {
+    constructor(refs: any);
+    refs: any;
+    instantiate(ctx: any): any;
+    codegen(ctx: any): string;
+}
 import { ASTNode } from './ASTNode.js';
+import { OptionsNode } from './OptionsNode.js';

package/dist/types/constants.d.ts

@@ -5,6 +5,7 @@ export const OPTIONS: "options";
 export const SELECTION: "selection";
 export const PARAMREF: "paramref";
 export const PARAM: "param";
+export const INCLUDE: "include";
 export const SELECT: "select";
 export const VALUE: "value";
 export const CROSSFILTER: "crossfilter";

package/dist/types/parse-spec.d.ts

@@ -59,15 +59,40 @@ export class ParseContext {
     plotDefaults: import("./ast/PlotAttributeNode.js").PlotAttributeNode[];
     parseComponent(spec: any): any;
     /**
-     * Test if a value is param reference, if so, generate a paramter definition
-     * as needed and return a new ParamRefNode. Otherwise, return a LiteralNode.
+     * Test if a value is a param reference, if so, generates a parameter
+     * definition as needed and returns a new ParamRefNode. Otherwise,
+     * returns a LiteralNode for the given value.
      * @param {*} value The value to test.
-     * @param {() => ParamNode | SelectionNode} [makeNode] A Param of Selection AST
-     *  node constructor.
      * @returns {ParamRefNode|LiteralNode} An AST node for the input value.
      */
-    maybeParam(value: any, makeNode?: () => ParamNode | SelectionNode): ParamRefNode | LiteralNode;
-    maybeSelection(value: any): LiteralNode | ParamRefNode;
+    maybeParam(value: any): ParamRefNode | LiteralNode;
+    /**
+     * Test if a value is a param reference, if so, generates a selection
+     * definition as needed and returns a new ParamRefNode. Otherwise,
+     * returns a LiteralNode for the given value.
+     * @param {*} value The value to test.
+     * @returns {ParamRefNode|LiteralNode} An AST node for the input value.
+     */
+    maybeSelection(value: any): ParamRefNode | LiteralNode;
+    /**
+     * Create a parameter reference. Generates a parameter definition if needed
+     * and returns a new ParamRefNode.
+     * @param {string} name The parameter name.
+     * @param {() => ParamNode | SelectionNode} [makeNode] A Param or Selection AST
+     *  node constructor.
+     * @returns {ParamRefNode|null} A node referring to the param or selection.
+     */
+    paramRef(name: string, makeNode?: () => ParamNode | SelectionNode): ParamRefNode | null;
+    /**
+     * Create a selection reference. Generates a selection definition if needed
+     * and returns a new ParamRefNode. Returns null if a non-selection parameter
+     * with the same name already exists and *strict* is true.
+     * @param {string} name The selection name.
+     * @param {boolean} [strict=false] Indicates if this method may return param
+     *  references (false, default) or only selection references (true).
+     * @returns {ParamRefNode|null} A node referring to the param or selection.
+     */
+    selectionRef(name: string, strict?: boolean): ParamRefNode | null;
     error(message: any, data: any): void;
 }
 /**
@@ -80,7 +105,7 @@ export type PlotNames = {
     marks: Set<string>;
 };
 import { SpecNode } from './ast/SpecNode.js';
-import { ParamNode } from './ast/ParamNode.js';
-import { SelectionNode } from './ast/SelectionNode.js';
 import { ParamRefNode } from './ast/ParamRefNode.js';
 import { LiteralNode } from './ast/LiteralNode.js';
+import { ParamNode } from './ast/ParamNode.js';
+import { SelectionNode } from './ast/SelectionNode.js';

package/dist/types/spec/Param.d.ts

@@ -52,6 +52,12 @@ export interface Selection {
      * false, a selection with no clauses selects all values.
      */
     empty?: boolean;
+    /**
+     * Upstream selections whose clauses should be included as part of this
+     * selection. Any clauses or activations published to the upstream
+     * selections will be relayed to this selection.
+     */
+    include?: ParamRef | ParamRef[];
 }
 /** A Param or Selection definition. */
 export type ParamDefinition = ParamValue | Param | ParamDate | Selection;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-spec",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Declarative specification of Mosaic-powered applications.",
   "keywords": [
     "mosaic",
@@ -28,15 +28,15 @@
     "types": "tsc -p tsconfig.json && 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": "mocha 'test/**/*-test.js' && tsc -p jsconfig.json",
+    "test": "vitest run && tsc -p jsconfig.json",
     "version": "cd ../.. && npm run docs:schema",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
   "dependencies": {
-    "@uwdata/mosaic-core": "^0.10.0",
-    "@uwdata/mosaic-sql": "^0.10.0",
-    "@uwdata/vgplot": "^0.10.0",
+    "@uwdata/mosaic-core": "^0.11.0",
+    "@uwdata/mosaic-sql": "^0.11.0",
+    "@uwdata/vgplot": "^0.11.0",
     "ts-json-schema-generator": "^2.3.0"
   },
-  "gitHead": "94fc4f0d4efc622001f6afd6714d1e9dda745be2"
+  "gitHead": "861d616f39926a1d2aee83b59dbdd70b0b3caf12"
 }

package/src/ast/ParamNode.js

@@ -1,19 +1,18 @@
 import { isArray, isObject, isoparse } from '../util.js';
 import { ASTNode } from './ASTNode.js';
+import { parseSelection } from './SelectionNode.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, empty, date, value } = param;
+  const { select = VALUE, value, date } = param;
   if (!paramTypes.has(select)) {
     ctx.error(`Unrecognized param type: ${select}`, param);
   }
-
   if (select !== VALUE) {
-    return new SelectionNode(select, cross, empty);
+    return parseSelection(spec, ctx);
   } else if (isArray(value)) {
     return new ParamNode(value.map(v => ctx.maybeParam(v)));
   } else {

package/src/ast/ParamRefNode.js

@@ -12,7 +12,7 @@ export class ParamRefNode extends ASTNode {
     return ctx.activeParams?.get(this.name);
   }
 
-  codegen() {
+  codegen(ctx) { // eslint-disable-line no-unused-vars
     return toParamRef(this.name);
   }
 

package/src/ast/SelectionNode.js

@@ -1,30 +1,62 @@
 import { ASTNode } from './ASTNode.js';
-import { INTERSECT, SELECTION } from '../constants.js';
+import { OptionsNode, parseOptions } from './OptionsNode.js';
+import { INCLUDE, INTERSECT, SELECTION } from '../constants.js';
+import { paramRef, toArray } from '../util.js';
+
+export function parseSelection(spec, ctx) {
+  const { select, include, ...options } = spec;
+  const opt = parseOptions(options, ctx);
+  if (include) {
+    opt.options.include = new IncludeNode(
+      toArray(include).map(ref => ctx.selectionRef(paramRef(ref)))
+    );
+  }
+  return new SelectionNode(select, opt);
+}
 
 export class SelectionNode extends ASTNode {
-  constructor(select = INTERSECT, cross, empty) {
+  /**
+   * Create a Selection AST node.
+   * @param {string} select The selection type.
+   * @param {OptionsNode} options Selection options.
+   */
+  constructor(select = INTERSECT, options = new OptionsNode({})) {
     super(SELECTION);
     this.select = select;
-    this.cross = cross;
-    this.empty = empty;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { select, options } = this;
+    return ctx.api.Selection[select](options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const { select, options } = this;
+    return `${ctx.ns()}Selection.${select}(${options.codegen(ctx)})`;
+  }
+
+  toJSON() {
+    const { select, options } = this;
+    return { select, ...options.toJSON() };
+  }
+}
+
+export class IncludeNode extends ASTNode {
+  constructor(refs) {
+    super(INCLUDE);
+    this.refs = refs;
   }
 
   instantiate(ctx) {
-    const { select, cross, empty } = this;
-    return ctx.api.Selection[select]({ cross, empty });
+    return this.refs.map(ref => ref.instantiate(ctx));
   }
 
   codegen(ctx) {
-    const { select, cross, empty } = this;
-    const args = [['cross', cross], ['empty', empty]]
-      .filter(a => a[1] != null)
-      .map(a => `${a[0]}: ${a[1]}`);
-    const arg = args.length ? `{ ${args.join(', ')} }` : '';
-    return `${ctx.ns()}Selection.${select}(${arg})`;
+    return `[${this.refs.map(ref => ref.codegen(ctx)).join(', ')}]`;
   }
 
   toJSON() {
-    const { select, cross, empty } = this;
-    return { select, cross, empty };
+    return this.refs.map(ref => ref.toJSON());
   }
 }

package/src/constants.js

@@ -14,6 +14,7 @@ export const OPTIONS = 'options';
 export const SELECTION = 'selection';
 export const PARAMREF = 'paramref';
 export const PARAM = 'param';
+export const INCLUDE = 'include';
 
 // param and selection types
 export const SELECT = 'select';

package/src/parse-spec.js

@@ -68,7 +68,6 @@ export class ParseContext {
   }
 
   parse(spec) {
-    // eslint-disable-next-line no-unused-vars
     const {
       meta,
       config,
@@ -113,29 +112,67 @@ export class ParseContext {
   }
 
   /**
-   * Test if a value is param reference, if so, generate a paramter definition
-   * as needed and return a new ParamRefNode. Otherwise, return a LiteralNode.
+   * Test if a value is a param reference, if so, generates a parameter
+   * definition as needed and returns a new ParamRefNode. Otherwise,
+   * returns a LiteralNode for the given value.
    * @param {*} value The value to test.
-   * @param {() => ParamNode | SelectionNode} [makeNode] A Param of Selection AST
-   *  node constructor.
    * @returns {ParamRefNode|LiteralNode} An AST node for the input value.
    */
-  maybeParam(value, makeNode = () => new ParamNode) {
-    const { params } = this;
+  maybeParam(value) {
     const name = paramRef(value);
+    return name
+      ? this.paramRef(name)
+      : new LiteralNode(value);
+  }
 
-    if (name) {
-      if (!params.has(name)) {
-        const p = makeNode();
-        params.set(name, p);
-      }
-      return new ParamRefNode(name);
+  /**
+   * Test if a value is a param reference, if so, generates a selection
+   * definition as needed and returns a new ParamRefNode. Otherwise,
+   * returns a LiteralNode for the given value.
+   * @param {*} value The value to test.
+   * @returns {ParamRefNode|LiteralNode} An AST node for the input value.
+   */
+  maybeSelection(value) {
+    const name = paramRef(value);
+    return name
+      ? this.selectionRef(name)
+      : new LiteralNode(value);
+  }
+
+  /**
+   * Create a parameter reference. Generates a parameter definition if needed
+   * and returns a new ParamRefNode.
+   * @param {string} name The parameter name.
+   * @param {() => ParamNode | SelectionNode} [makeNode] A Param or Selection AST
+   *  node constructor.
+   * @returns {ParamRefNode|null} A node referring to the param or selection.
+   */
+  paramRef(name, makeNode = () => new ParamNode) {
+    const { params } = this;
+    if (!name) return null;
+    let p = params.get(name);
+    if (!p) {
+      p = makeNode();
+      params.set(name, p);
     }
-    return new LiteralNode(value);
+    return new ParamRefNode(name);
   }
 
-  maybeSelection(value) {
-    return this.maybeParam(value, () => new SelectionNode);
+  /**
+   * Create a selection reference. Generates a selection definition if needed
+   * and returns a new ParamRefNode. Returns null if a non-selection parameter
+   * with the same name already exists and *strict* is true.
+   * @param {string} name The selection name.
+   * @param {boolean} [strict=false] Indicates if this method may return param
+   *  references (false, default) or only selection references (true).
+   * @returns {ParamRefNode|null} A node referring to the param or selection.
+   */
+  selectionRef(name, strict = false) {
+    const p = this.params.get(name);
+    if (strict && p && !(p instanceof SelectionNode)) {
+      return null;
+    }
+    return this.paramRef(name, () => new SelectionNode);
   }
 
   error(message, data) {

package/src/spec/Param.ts

@@ -65,6 +65,13 @@ export interface Selection {
    * false, a selection with no clauses selects all values.
    */
   empty?: boolean;
+
+  /**
+   * Upstream selections whose clauses should be included as part of this
+   * selection. Any clauses or activations published to the upstream
+   * selections will be relayed to this selection.
+   */
+  include?: ParamRef | ParamRef[];
 }
 
 /** A Param or Selection definition. */

package/src/spec/Spec.ts

@@ -1,5 +1,5 @@
 import { DataDefinition } from './Data.js';
-import { ParamDefinition } from './Param.js';
+import { ParamDefinition, ParamRef } from './Param.js';
 import { HConcat } from './HConcat.js';
 import { VConcat } from './VConcat.js';
 import { HSpace } from './HSpace.js';