@finos/legend-cube-builder 0.0.0-stage → 0.0.2

package/src/stores/editors/CubeFilterDraft.ts

@@ -0,0 +1,241 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  changeFilterColumn,
+  changeFilterOperator,
+  ColumnComparisonFilter,
+  CompositeFilter,
+  CompositeFilterOperator,
+  encodeFilterRule,
+  type Filter,
+  type FilterOperator,
+  type FilterRule,
+  type FilterValue,
+  negateFilter,
+  normalizeFilter,
+  NotFilter,
+  type Schema,
+  unwrapFilter,
+} from '@finos/legend-cube';
+import { action, makeObservable, observable } from 'mobx';
+import { CubeNodeDraft } from './CubeNodeDraft.js';
+
+/** A condition with no column picked and no value: what Add puts in a group */
+export const isBlankFilterRow = (rule: FilterRule): boolean =>
+  rule instanceof ColumnComparisonFilter &&
+  rule.columnName === '' &&
+  rule.value === undefined;
+
+/**
+ * The rule without its blank conditions, and without the groups and
+ * negations left empty by that; `undefined` when nothing else is left
+ */
+export const pruneBlankFilterRows = (
+  rule: FilterRule,
+): FilterRule | undefined => {
+  if (isBlankFilterRow(rule)) {
+    return undefined;
+  }
+  if (rule instanceof CompositeFilter) {
+    const rules = rule.rules
+      .map(pruneBlankFilterRows)
+      .filter((child): child is FilterRule => child !== undefined);
+    if (!rules.length) {
+      return undefined;
+    }
+    return rules.length === rule.rules.length &&
+      rules.every((child, index) => child === rule.rules[index])
+      ? rule
+      : rule.withRules(rules);
+  }
+  if (rule instanceof NotFilter) {
+    const inner = pruneBlankFilterRows(rule.rule);
+    return inner === undefined
+      ? undefined
+      : inner === rule.rule
+        ? rule
+        : rule.withRule(inner);
+  }
+  return rule;
+};
+
+/**
+ * The tree with the rule of `key` replaced by what `replace` gives, or
+ * removed when it gives `undefined`; a negation whose rule is removed goes
+ * too. Rules that don't change stay the same objects.
+ */
+const replaceRule = (
+  rule: FilterRule,
+  key: number,
+  replace: (found: FilterRule) => FilterRule | undefined,
+): FilterRule | undefined => {
+  if (rule.key === key) {
+    return replace(rule);
+  }
+  if (rule instanceof CompositeFilter) {
+    const rules = rule.rules
+      .map((child) => replaceRule(child, key, replace))
+      .filter((child): child is FilterRule => child !== undefined);
+    return rules.length === rule.rules.length &&
+      rules.every((child, index) => child === rule.rules[index])
+      ? rule
+      : rule.withRules(rules);
+  }
+  if (rule instanceof NotFilter) {
+    const inner = replaceRule(rule.rule, key, replace);
+    return inner === undefined
+      ? undefined
+      : inner === rule.rule
+        ? rule
+        : rule.withRule(inner);
+  }
+  return rule;
+};
+
+const blankRow = (): ColumnComparisonFilter => new ColumnComparisonFilter('');
+
+/**
+ * The Filter editor's draft (spec §8.5, §17.6): the filter as a tree that
+ * always has an And/Or group at its top, so rows can be added to it. Each
+ * rule keeps its key across edits, so the editor's rows keep theirs.
+ *
+ * When built, blank conditions are left out, and a tree of nothing else
+ * stores no filter at all (user's choice, 2026-10-07): an Apply with an
+ * untouched blank row changes nothing. Rules this version can't read are
+ * kept as they were.
+ */
+export class CubeFilterDraft extends CubeNodeDraft<Filter> {
+  tree: CompositeFilter;
+  /** Anything was changed; until then, `build()` gives the original back */
+  private touched = false;
+
+  constructor(original: Filter) {
+    super(original);
+    makeObservable<CubeFilterDraft, 'touched'>(this, {
+      tree: observable.ref,
+      touched: observable,
+      setGroupOperator: action,
+      addCondition: action,
+      addGroup: action,
+      removeRule: action,
+      toggleNegation: action,
+      setColumn: action,
+      setOperator: action,
+      setValue: action,
+    });
+    this.tree = normalizeFilter(original.filter);
+  }
+
+  private update(
+    key: number,
+    replace: (rule: FilterRule) => FilterRule | undefined,
+  ): void {
+    const tree = replaceRule(this.tree, key, replace);
+    // the top group stays a group
+    if (tree instanceof CompositeFilter && tree !== this.tree) {
+      this.tree = tree;
+      this.touched = true;
+    }
+  }
+
+  setGroupOperator(groupKey: number, operator: CompositeFilterOperator): void {
+    this.update(groupKey, (rule) =>
+      rule instanceof CompositeFilter ? rule.withOperator(operator) : rule,
+    );
+  }
+
+  /** Adds a blank condition at the end of the group */
+  addCondition(groupKey: number): void {
+    this.update(groupKey, (rule) =>
+      rule instanceof CompositeFilter
+        ? rule.withRules([...rule.rules, blankRow()])
+        : rule,
+    );
+  }
+
+  /** Adds a group holding one blank condition at the end of the group */
+  addGroup(groupKey: number): void {
+    this.update(groupKey, (rule) =>
+      rule instanceof CompositeFilter
+        ? rule.withRules([
+            ...rule.rules,
+            new CompositeFilter(CompositeFilterOperator.AND, [blankRow()]),
+          ])
+        : rule,
+    );
+  }
+
+  /** Removes a rule; the top group stays */
+  removeRule(key: number): void {
+    if (key !== this.tree.key) {
+      this.update(key, () => undefined);
+    }
+  }
+
+  /**
+   * Negates a rule as simply as it can (`negateFilter`): a comparison takes
+   * its negated operator, e.g. `is` and `is not`, a negation gives back its
+   * rule, anything else is wrapped in Not. The top group can't be negated.
+   */
+  toggleNegation(key: number): void {
+    if (key !== this.tree.key) {
+      this.update(key, negateFilter);
+    }
+  }
+
+  /** Changes a condition's column, keeping its operator and value when they still fit */
+  setColumn(key: number, columnName: string, schema: Schema): void {
+    this.update(key, (rule) =>
+      rule instanceof ColumnComparisonFilter
+        ? changeFilterColumn(rule, columnName, schema)
+        : rule,
+    );
+  }
+
+  /** Changes a condition's operator, dropping its value when the operator takes another shape */
+  setOperator(key: number, operator: FilterOperator): void {
+    this.update(key, (rule) =>
+      rule instanceof ColumnComparisonFilter
+        ? changeFilterOperator(rule, operator)
+        : rule,
+    );
+  }
+
+  setValue(key: number, value: FilterValue | undefined): void {
+    this.update(key, (rule) =>
+      rule instanceof ColumnComparisonFilter ? rule.withValue(value) : rule,
+    );
+  }
+
+  build(): Filter {
+    const { original } = this;
+    if (!this.touched) {
+      return original;
+    }
+    const pruned = pruneBlankFilterRows(this.tree);
+    const filter = pruned === undefined ? undefined : unwrapFilter(pruned);
+    // a saved group of one rule comes back as the rule: it saves differently
+    // but means the same, so it is no change
+    const isUnchanged =
+      filter === undefined
+        ? original.filter === undefined
+        : original.filter !== undefined &&
+          JSON.stringify(encodeFilterRule(filter)) ===
+            JSON.stringify(encodeFilterRule(unwrapFilter(original.filter)));
+    return isUnchanged ? original : original.withFilter(filter);
+  }
+}

package/src/stores/editors/CubeJoinDraft.ts

@@ -0,0 +1,197 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  getSameNamedJoinKeys,
+  Join,
+  JoinType,
+  type Query,
+  RelationalTableSource,
+  type SchemaInferenceResult,
+} from '@finos/legend-cube';
+import { action, makeObservable, observable } from 'mobx';
+import type { CubeModelOutline } from '../../graph-manager/CubeEngine.js';
+import { CubeNodeDraft } from './CubeNodeDraft.js';
+
+/** One pair of key columns, matched by position; `''` until a column is picked */
+export interface CubeJoinKeyPair {
+  /** Identifies the row in the editor */
+  readonly key: number;
+  readonly left: string;
+  readonly right: string;
+}
+
+let nextPairKey = 1;
+
+const isSameList = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((name, index) => name === b[index]);
+
+/** The key lists pairs build: a pair with no column picked is left out */
+const toKeyLists = (
+  pairs: readonly CubeJoinKeyPair[],
+): [string[], string[]] => {
+  const kept = pairs.filter((pair) => pair.left || pair.right);
+  return [kept.map((pair) => pair.left), kept.map((pair) => pair.right)];
+};
+
+/**
+ * The Join editor's draft (spec §17.6): the join type and the key column
+ * pairs. A pair with no column picked on either side is left out when built,
+ * as a Filter's blank rows are (user's choice, 2026-10-07).
+ */
+export class CubeJoinDraft extends CubeNodeDraft<Join> {
+  joinType: JoinType;
+  pairs: CubeJoinKeyPair[];
+  /** Anything was changed; until then, `build()` gives the original back */
+  private touched = false;
+  /**
+   * The key lists the pairs built before any edit, so edits undone by hand
+   * give the original back, even for saved lists of unequal length
+   */
+  private readonly initialKeyLists: [string[], string[]];
+
+  constructor(original: Join) {
+    super(original);
+    makeObservable<CubeJoinDraft, 'touched'>(this, {
+      joinType: observable,
+      pairs: observable.ref,
+      touched: observable,
+      setJoinType: action,
+      addPair: action,
+      removePair: action,
+      setLeftColumn: action,
+      setRightColumn: action,
+    });
+    this.joinType = original.joinType;
+    this.pairs = Array.from(
+      {
+        length: Math.max(
+          original.leftColumns.length,
+          original.rightColumns.length,
+        ),
+      },
+      (_, index) => ({
+        key: nextPairKey++,
+        left: original.leftColumns[index] ?? '',
+        right: original.rightColumns[index] ?? '',
+      }),
+    );
+    this.initialKeyLists = toKeyLists(this.pairs);
+  }
+
+  setJoinType(joinType: JoinType): void {
+    this.joinType = joinType;
+    this.touched = true;
+  }
+
+  addPair(): void {
+    this.pairs = [...this.pairs, { key: nextPairKey++, left: '', right: '' }];
+    this.touched = true;
+  }
+
+  removePair(key: number): void {
+    this.pairs = this.pairs.filter((pair) => pair.key !== key);
+    this.touched = true;
+  }
+
+  setLeftColumn(key: number, left: string): void {
+    this.pairs = this.pairs.map((pair) =>
+      pair.key === key ? { ...pair, left } : pair,
+    );
+    this.touched = true;
+  }
+
+  setRightColumn(key: number, right: string): void {
+    this.pairs = this.pairs.map((pair) =>
+      pair.key === key ? { ...pair, right } : pair,
+    );
+    this.touched = true;
+  }
+
+  build(): Join {
+    const [leftColumns, rightColumns] = toKeyLists(this.pairs);
+    const [initialLeft, initialRight] = this.initialKeyLists;
+    const { original } = this;
+    return !this.touched ||
+      (this.joinType === original.joinType &&
+        isSameList(leftColumns, initialLeft) &&
+        isSameList(rightColumns, initialRight))
+      ? original
+      : original.withSettings({
+          joinType: this.joinType,
+          leftColumns,
+          rightColumns,
+        });
+  }
+}
+
+/**
+ * The table sources a column of a node's output comes from: followed back
+ * through the inputs whose output has the column. A join key of the same name
+ * on both sides comes from the side the join keeps (the left for INNER and
+ * LEFT OUTER, the right for RIGHT OUTER), and from both for FULL OUTER, which
+ * merges them.
+ */
+export const findColumnSources = (
+  query: Query,
+  analysis: SchemaInferenceResult,
+  nodeId: string,
+  columnName: string,
+): RelationalTableSource[] => {
+  const node = query.getNode(nodeId);
+  if (node instanceof RelationalTableSource) {
+    return node.resolution.kind === 'resolved' &&
+      node.resolution.schema.lookup(columnName)
+      ? [node]
+      : [];
+  }
+  const inputIds = query.getInputIds(nodeId);
+  const [leftId, rightId] = inputIds;
+  const followed =
+    node instanceof Join &&
+    node.joinType !== JoinType.FULL_OUTER &&
+    getSameNamedJoinKeys(node.leftColumns, node.rightColumns).includes(
+      columnName,
+    )
+      ? [node.joinType === JoinType.RIGHT_OUTER ? rightId : leftId]
+      : inputIds;
+  return followed.flatMap((inputId) =>
+    inputId !== undefined && analysis.schemas.get(inputId)?.lookup(columnName)
+      ? findColumnSources(query, analysis, inputId, columnName)
+      : [],
+  );
+};
+
+/**
+ * Whether the column of the node's output comes from a table column whose
+ * type Cube can't read (OTHER or ARRAY), so it was typed as a bare String
+ * (PLAN §8.7). Unknown until the model's outline has loaded.
+ */
+export const isUntypedColumn = (
+  outline: CubeModelOutline | undefined,
+  query: Query,
+  analysis: SchemaInferenceResult,
+  nodeId: string,
+  columnName: string,
+): boolean =>
+  outline !== undefined &&
+  findColumnSources(query, analysis, nodeId, columnName).some((source) =>
+    outline.databases
+      .find((database) => database.path === source.database)
+      ?.schemas.find((schema) => schema.name === source.schema)
+      ?.tables.find((table) => table.name === source.table)
+      ?.untypedColumns.includes(columnName),
+  );

package/src/stores/editors/CubeNodeDraft.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { QueryNode } from '@finos/legend-cube';
+
+/**
+ * The edits of one node in the side panel, kept until Apply (PLAN §7.4,
+ * spec §17.5). A node type's editor edits its draft, never the document:
+ * only the panel's Apply stores `build()`, as one undo step. A draft is
+ * made once each time the panel opens on a node, and again after an Apply.
+ */
+export abstract class CubeNodeDraft<N extends QueryNode = QueryNode> {
+  /** The node the draft was made from */
+  readonly original: N;
+
+  constructor(original: N) {
+    this.original = original;
+  }
+
+  /**
+   * The node Apply would store. Return `original` itself while nothing was
+   * edited; the panel also treats a node that saves the same as `original`
+   * as no change.
+   */
+  abstract build(): N;
+}
+
+/** A node with nothing to edit in the panel, such as a source or an Unknown node */
+export class CubeReadOnlyNodeDraft extends CubeNodeDraft {
+  build(): QueryNode {
+    return this.original;
+  }
+}

package/src/stores/editors/CubeNodeDraftRegistry.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Filter, Join, type QueryNode } from '@finos/legend-cube';
+import { guaranteeType } from '@finos/legend-shared';
+import type { CubeEditorState } from '../CubeEditorState.js';
+import { CubeFilterDraft } from './CubeFilterDraft.js';
+import { CubeJoinDraft } from './CubeJoinDraft.js';
+import { type CubeNodeDraft, CubeReadOnlyNodeDraft } from './CubeNodeDraft.js';
+
+/** Makes the draft of a node of one type */
+export type CubeNodeDraftFactory = (
+  node: QueryNode,
+  editorState: CubeEditorState,
+) => CubeNodeDraft;
+
+/**
+ * The draft of each node type the panel edits, by type (PLAN §7.4). A
+ * transform with an editor in `CUBE_NODE_EDITORS` has its factory here; a
+ * source, which has nothing to edit, has none, and so no Apply or Cancel.
+ */
+export const CUBE_NODE_DRAFT_FACTORIES: ReadonlyMap<
+  string,
+  CubeNodeDraftFactory
+> = new Map<string, CubeNodeDraftFactory>([
+  [Filter.TYPE, (node) => new CubeFilterDraft(guaranteeType(node, Filter))],
+  [Join.TYPE, (node) => new CubeJoinDraft(guaranteeType(node, Join))],
+]);
+
+/** The node's draft; a node with nothing to edit gets a read-only one */
+export const createCubeNodeDraft = (
+  node: QueryNode,
+  editorState: CubeEditorState,
+): CubeNodeDraft =>
+  CUBE_NODE_DRAFT_FACTORIES.get(node.type)?.(node, editorState) ??
+  new CubeReadOnlyNodeDraft(node);