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

package/src/stores/CubeExecutionState.ts

@@ -0,0 +1,255 @@
+/**
+ * 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 { isSchemasError, type Query, type Schema } from '@finos/legend-cube';
+import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
+import { action, computed, flow, makeObservable, observable } from 'mobx';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeResult,
+  type CubeResultValue,
+} from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+/** What the grid shows of a run: the rows within the limit, under the schema the run was made with */
+export interface CubeExecutionResult {
+  /** Counts the page's runs: the grid is built anew for each */
+  readonly id: number;
+  /** The query that ran: results are stale once the document holds another */
+  readonly query: Query;
+  /** The capture node's schema when the run started; the grid's columns, by position */
+  readonly schema: Schema;
+  /** At most `rowLimit` rows */
+  readonly rows: readonly (readonly CubeResultValue[])[];
+  readonly rowLimit: number;
+  /** The engine returned more than `rowLimit` rows */
+  readonly limited: boolean;
+  readonly sql: readonly string[];
+  readonly durationMs: number;
+}
+
+/**
+ * The first error found walking up from the capture node, named by its node.
+ * A node that is invalid only because an input is gets passed over for that
+ * input's own error.
+ */
+const findUpstreamError = (
+  query: Query,
+  validity: ReadonlyMap<string, readonly string[]>,
+  captureId: string,
+): string => {
+  const visit = (nodeId: string): string | undefined => {
+    const node = query.getNode(nodeId);
+    if (!node) {
+      return undefined;
+    }
+    for (const inputId of query.getInputIds(nodeId)) {
+      const error = inputId === undefined ? undefined : visit(inputId);
+      if (error) {
+        return error;
+      }
+    }
+    const error = (validity.get(nodeId) ?? []).find(
+      (message) => !isSchemasError(message),
+    );
+    return error === undefined ? undefined : `${node.describe()}: ${error}`;
+  };
+  return (
+    visit(captureId) ?? 'The node to run, or one of its inputs, has errors.'
+  );
+};
+
+/**
+ * Runs the query up to its capture node (PLAN §8.2, §9). Execution is
+ * explicit; while a run is in flight Execute becomes Stop, and only the latest
+ * run's answer is applied (Settled before M1.8).
+ */
+export class CubeExecutionState {
+  readonly editorState: CubeEditorState;
+
+  result: CubeExecutionResult | undefined;
+  error: CubeEngineError | undefined;
+  /** The abort controller of the run in flight, if any */
+  private runController: AbortController | undefined;
+  private runCount = 0;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable<CubeExecutionState, 'runController'>(this, {
+      result: observable.ref,
+      error: observable.ref,
+      runController: observable.ref,
+      isRunning: computed,
+      isStale: computed,
+      disabledReasons: computed,
+      canExecute: computed,
+      execute: flow,
+      clearError: action,
+      stop: action,
+      reset: action,
+    });
+    this.editorState = editorState;
+  }
+
+  get isRunning(): boolean {
+    return this.runController !== undefined;
+  }
+
+  /** The shown result no longer matches the query or the row limit; it is kept until the next run */
+  get isStale(): boolean {
+    return (
+      this.result !== undefined &&
+      !this.isRunning &&
+      (this.result.query !== this.editorState.document.query ||
+        this.result.rowLimit !== this.editorState.rowLimit)
+    );
+  }
+
+  /**
+   * Why Execute is unavailable, if it is: it needs a source, a model and a
+   * runtime, and a valid capture node whose inputs are all valid. Invalid
+   * nodes elsewhere don't matter (PLAN §10.3).
+   */
+  get disabledReasons(): string[] {
+    const { document, emitter, analysis } = this.editorState;
+    const { query, context } = document;
+    if (!query.nodes.length) {
+      return ['Add a table first.'];
+    }
+    const reasons: string[] = [];
+    if (!context) {
+      reasons.push('The cube has no model.');
+    } else if (!context.runtime) {
+      reasons.push('The cube has no runtime.');
+    }
+    const captureId = query.selected;
+    if (captureId === undefined) {
+      reasons.push('Select the node to run.');
+    } else if (!emitter.canEmit(captureId)) {
+      reasons.push(findUpstreamError(query, analysis.validity, captureId));
+    }
+    return reasons;
+  }
+
+  get canExecute(): boolean {
+    return !this.disabledReasons.length;
+  }
+
+  *execute(): GeneratorFn<void> {
+    if (this.isRunning || !this.canExecute) {
+      return;
+    }
+    const { document, emitter, analysis, rowLimit, host } = this.editorState;
+    const { query, context } = document;
+    // checked by canExecute
+    const captureId = query.selected as string;
+    const model = context?.model;
+    const runtime = context?.runtime;
+    const schema = analysis.schemas.get(captureId);
+    if (!model || !runtime || !schema) {
+      return;
+    }
+    const lambda = emitter.emitExecutionLambda({ rowLimit, runtime });
+    const controller = new AbortController();
+    this.runController = controller;
+    this.error = undefined;
+    this.editorState.clearHostIssues();
+    try {
+      const response = (yield host.engine.execute(model, lambda, {
+        abortController: controller,
+      })) as CubeResult;
+      if (this.runController !== controller) {
+        return;
+      }
+      // rows are read by position, so the engine's columns must be the query's
+      if (response.columns.length !== schema.columns.length) {
+        throw new CubeEngineError(
+          CubeEngineErrorKind.EXECUTION,
+          `The engine returned ${response.columns.length} columns, but the query has ${schema.columns.length}`,
+          captureId,
+        );
+      }
+      const misplaced = schema.columns.findIndex(
+        (column, position) => response.columns[position] !== column.name,
+      );
+      if (misplaced !== -1) {
+        throw new CubeEngineError(
+          CubeEngineErrorKind.EXECUTION,
+          `The engine returned the column "${response.columns[misplaced]}" at position ${misplaced + 1}, but the query has "${schema.columns[misplaced]?.name}" there`,
+          captureId,
+        );
+      }
+      const limited = response.rows.length > rowLimit;
+      this.result = {
+        id: ++this.runCount,
+        query,
+        schema,
+        rows: limited ? response.rows.slice(0, rowLimit) : response.rows,
+        rowLimit,
+        limited,
+        sql: response.sql,
+        durationMs: response.durationMs,
+      };
+    } catch (error) {
+      // a stopped or replaced run shows nothing
+      if (this.runController !== controller || controller.signal.aborted) {
+        return;
+      }
+      assertErrorThrown(error);
+      const engineError =
+        error instanceof CubeEngineError
+          ? error
+          : new CubeEngineError(
+              CubeEngineErrorKind.EXECUTION,
+              error.message,
+              captureId,
+            );
+      // the rows of an earlier run are never shown as this run's
+      this.result = undefined;
+      // an error belongs to the query it came from: one that changed while
+      // the run was in flight drops it, as an edit after the run would
+      if (this.editorState.document.query === query) {
+        this.error = engineError;
+        this.editorState.setHostIssue(
+          engineError.nodeId ?? captureId,
+          engineError,
+        );
+      }
+    } finally {
+      if (this.runController === controller) {
+        this.runController = undefined;
+      }
+    }
+  }
+
+  /** Drops the last run's error: it described a query the cube no longer has */
+  clearError(): void {
+    this.error = undefined;
+  }
+
+  /** Cancels the run in flight; it shows no result and no error */
+  stop(): void {
+    this.runController?.abort();
+    this.runController = undefined;
+  }
+
+  /** Stops any run and forgets the last one's rows and error, e.g. when another cube is opened */
+  reset(): void {
+    this.stop();
+    this.result = undefined;
+    this.error = undefined;
+  }
+}

package/src/stores/CubeHost.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { GenericLegendApplicationStore } from '@finos/legend-application';
+import type { CubeEngine } from '../graph-manager/CubeEngine.js';
+import type { LocalModelCatalog } from './LocalModelCatalog.js';
+
+/**
+ * What the application hosting the Cube page gives it (PLAN §3.5, Settled
+ * before M1.8). The host chooses the engine and the models; Cube keeps no
+ * auth, config or telemetry of its own and uses the host's application store
+ * for commands, user data, the clipboard, the theme, notifications, alerts and
+ * telemetry.
+ */
+export interface CubeHost {
+  readonly applicationStore: GenericLegendApplicationStore;
+  readonly engine: CubeEngine;
+  readonly modelCatalog: LocalModelCatalog;
+}

package/src/stores/CubeNodeEditorState.ts

@@ -0,0 +1,255 @@
+/**
+ * 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 { NodeRegistry, QueryNode } from '@finos/legend-cube';
+import {
+  action,
+  computed,
+  type IReactionDisposer,
+  makeObservable,
+  observable,
+  reaction,
+} from 'mobx';
+import {
+  CUBE_EDITOR_CLOSED_REASON,
+  getEditorClosedNotice,
+} from '../__lib__/LegendCubeLabels.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import type { CubeNodeDraft } from './editors/CubeNodeDraft.js';
+import { createCubeNodeDraft } from './editors/CubeNodeDraftRegistry.js';
+
+/**
+ * Whether two nodes of the same id save the same: their own fields, as the
+ * spec stores them, and the keys this version doesn't know. A node of a type
+ * the registry doesn't know is the same only as itself.
+ */
+export const isSameNodeContent = (
+  registry: NodeRegistry,
+  a: QueryNode,
+  b: QueryNode,
+): boolean => {
+  if (a === b) {
+    return true;
+  }
+  const definition = registry.get(a.type);
+  return (
+    definition !== undefined &&
+    a.type === b.type &&
+    JSON.stringify([definition.spec.encode(a), a.rest]) ===
+      JSON.stringify([definition.spec.encode(b), b.rest])
+  );
+};
+
+/**
+ * The node editor in the side panel (PLAN §7.4, spec §17.5). Opening it
+ * never changes which node Execute runs. Edits go to a draft, and only Apply,
+ * or closing the panel, stores them, as one undo step; Cancel drops them.
+ *
+ * The panel follows the cube (user's choice, 2026-10-07): when the node it
+ * shows is replaced or removed underneath it, by Undo, a re-check or a
+ * Remove, a panel with edits closes without applying them and says so; one
+ * without edits shows the new node, or closes when the node is gone.
+ */
+export class CubeNodeEditorState {
+  readonly editorState: CubeEditorState;
+
+  /** The id of the node the panel shows, while it is open */
+  nodeId: string | undefined;
+  /** The key of the node the draft was made from */
+  private nodeKey: number | undefined;
+  draft: CubeNodeDraft | undefined;
+  /** Why the panel closed by itself, until it opens again or is dismissed */
+  notice: string | undefined;
+
+  private readonly disposeSync: IReactionDisposer;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable<CubeNodeEditorState, 'nodeKey' | 'sync'>(this, {
+      nodeId: observable,
+      nodeKey: observable,
+      draft: observable.ref,
+      notice: observable,
+      node: computed,
+      edited: computed,
+      hasChanges: computed,
+      open: action,
+      canSwapInputs: computed,
+      apply: action,
+      swapInputs: action,
+      close: action,
+      cancel: action,
+      discard: action,
+      dismissNotice: action,
+      sync: action,
+    });
+    this.editorState = editorState;
+    this.disposeSync = reaction(
+      () => this.node,
+      () => this.sync(),
+    );
+  }
+
+  /** The node the panel shows, as the cube has it now */
+  get node(): QueryNode | undefined {
+    return this.nodeId === undefined
+      ? undefined
+      : this.editorState.document.query.getNode(this.nodeId);
+  }
+
+  /** The node Apply would store, built once per edit */
+  get edited(): QueryNode | undefined {
+    return this.draft?.build();
+  }
+
+  /** The draft saves differently from the node it was made from */
+  get hasChanges(): boolean {
+    const { draft, edited } = this;
+    return (
+      draft !== undefined &&
+      edited !== undefined &&
+      !isSameNodeContent(this.editorState.registry, edited, draft.original)
+    );
+  }
+
+  /** Opens the panel on a node, closing (and so applying) the one it showed */
+  open(nodeId: string): void {
+    if (nodeId === this.nodeId) {
+      this.notice = undefined;
+      return;
+    }
+    const node = this.editorState.document.query.getNode(nodeId);
+    if (!node) {
+      return;
+    }
+    this.close();
+    this.notice = undefined;
+    this.bind(node);
+  }
+
+  /**
+   * Stores the draft in place of the node, as one undo step, and goes on
+   * editing the stored node. Does nothing without changes, or while the cube
+   * is read-only.
+   */
+  apply(): void {
+    const { node, edited } = this;
+    if (
+      !node ||
+      !edited ||
+      node.key !== this.nodeKey ||
+      !this.hasChanges ||
+      this.editorState.readOnly
+    ) {
+      return;
+    }
+    const { query } = this.editorState.document;
+    if (query.canReplace(edited)) {
+      this.editorState.applyQuery(query.replace(edited));
+      this.bind(edited);
+    }
+  }
+
+  get canSwapInputs(): boolean {
+    const { node } = this;
+    return (
+      node !== undefined &&
+      !this.editorState.readOnly &&
+      this.editorState.document.query.canSwapInputs(node.id)
+    );
+  }
+
+  /**
+   * Swaps the node's two inputs (a Join's Swap Inputs, spec §17.6), applying
+   * the draft first, as one undo step, then goes on editing the swapped
+   * node, whose settings followed its inputs
+   */
+  swapInputs(): void {
+    const { node, edited } = this;
+    if (!node || !edited || node.key !== this.nodeKey || !this.canSwapInputs) {
+      return;
+    }
+    let { query } = this.editorState.document;
+    if (this.hasChanges && query.canReplace(edited)) {
+      query = query.replace(edited);
+    }
+    query = query.swapInputs(node.id);
+    this.editorState.applyQuery(query);
+    this.bind(query.getNode(node.id) ?? node);
+  }
+
+  /** Applies the draft, then closes the panel (spec §17.5: edits commit on close) */
+  close(): void {
+    this.apply();
+    this.reset();
+  }
+
+  /** Closes the panel, dropping the draft */
+  cancel(): void {
+    this.reset();
+  }
+
+  /**
+   * Closes the panel without applying the draft, e.g. when another cube is
+   * opened, saying so when that drops edits
+   */
+  discard(reason: CUBE_EDITOR_CLOSED_REASON): void {
+    const { nodeId } = this;
+    if (nodeId !== undefined && this.hasChanges) {
+      this.notice = getEditorClosedNotice(nodeId, reason);
+    }
+    this.reset();
+  }
+
+  dismissNotice(): void {
+    this.notice = undefined;
+  }
+
+  /** Stops following the cube; call when the page closes */
+  dispose(): void {
+    this.disposeSync();
+  }
+
+  private bind(node: QueryNode): void {
+    this.nodeId = node.id;
+    this.nodeKey = node.key;
+    this.draft = createCubeNodeDraft(node, this.editorState);
+  }
+
+  private reset(): void {
+    this.nodeId = undefined;
+    this.nodeKey = undefined;
+    this.draft = undefined;
+  }
+
+  /** Runs whenever the node with the panel's id is another object, or gone */
+  private sync(): void {
+    const { node } = this;
+    if (this.nodeId === undefined || node?.key === this.nodeKey) {
+      return;
+    }
+    if (this.hasChanges) {
+      this.discard(
+        node
+          ? CUBE_EDITOR_CLOSED_REASON.NODE_CHANGED
+          : CUBE_EDITOR_CLOSED_REASON.NODE_REMOVED,
+      );
+    } else if (node) {
+      this.bind(node);
+    } else {
+      this.reset();
+    }
+  }
+}

package/src/stores/CubeShowPureState.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 { GeneratorFn } from '@finos/legend-shared';
+import { action, flow, makeObservable, observable } from 'mobx';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+} from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+/**
+ * Show Pure: the Pure text of what Execute would run, the capture node's
+ * execution lambda with the row limit, as the engine renders it. For display
+ * only: the text is never parsed back (PLAN §8.7).
+ */
+export class CubeShowPureState {
+  readonly editorState: CubeEditorState;
+
+  isOpen = false;
+  text: string | undefined;
+  /** Why the engine couldn't render the query; shown in the dialog */
+  error: CubeEngineError | undefined;
+  isRendering = false;
+  /** Counts renders, so one that finishes after the dialog closed is dropped */
+  private request = 0;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable(this, {
+      isOpen: observable,
+      text: observable,
+      error: observable.ref,
+      isRendering: observable,
+      open: flow,
+      close: action,
+    });
+    this.editorState = editorState;
+  }
+
+  /** Opens the dialog and renders the query; does nothing when Execute can't run */
+  *open(): GeneratorFn<void> {
+    const { execution, document, emitter, rowLimit, host } = this.editorState;
+    const runtime = document.context?.runtime;
+    if (!execution.canExecute || runtime === undefined) {
+      return;
+    }
+    const request = ++this.request;
+    this.isOpen = true;
+    this.text = undefined;
+    this.error = undefined;
+    this.isRendering = true;
+    try {
+      const text = (yield host.engine.renderPure(
+        emitter.emitExecutionLambda({ rowLimit, runtime }),
+      )) as string;
+      if (request === this.request) {
+        this.text = text;
+      }
+    } catch (error) {
+      if (request === this.request) {
+        this.error =
+          error instanceof CubeEngineError
+            ? error
+            : new CubeEngineError(
+                CubeEngineErrorKind.COMPILE,
+                error instanceof Error ? error.message : String(error),
+              );
+      }
+    } finally {
+      if (request === this.request) {
+        this.isRendering = false;
+      }
+    }
+  }
+
+  close(): void {
+    this.request++;
+    this.isOpen = false;
+    this.isRendering = false;
+    this.text = undefined;
+    this.error = undefined;
+  }
+}