@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/stores/CubeNodeEditorState.ts

@@ -16,10 +16,14 @@
 
 import {
   canFixJoinDuplicates,
+  canRenameConcatInput,
+  canRestrictConcatInput,
   fixJoinDuplicates,
   type NodeRegistry,
   type Query,
   type QueryNode,
+  renameConcatInput,
+  restrictConcatInput,
   type Schema,
 } from '@finos/legend-cube';
 import {
@@ -33,6 +37,7 @@ import {
 import {
   CUBE_EDITOR_CLOSED_REASON,
   getEditorClosedNotice,
+  getEditorKeptOpenNotice,
 } from '../__lib__/LegendCubeLabels.js';
 import type { CubeEditorState } from './CubeEditorState.js';
 import type { CubeNodeDraft } from './editors/CubeNodeDraft.js';
@@ -61,9 +66,11 @@ export const isSameNodeContent = (
 };
 
 /**
- * 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 node editor (PLAN §7.4, §11.8, spec §17.5). Opening it never changes
+ * which node Execute runs. Edits go to a draft, and only Apply, or closing
+ * the editor, stores them, as one undo step; Cancel drops them. Every close
+ * that applies goes through `finish`, which first lets the editor's fields
+ * commit text typed but not yet stored.
  *
  * 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
@@ -80,13 +87,27 @@ export class CubeNodeEditorState {
   draft: CubeNodeDraft | undefined;
   /** Why the panel closed by itself, until it opens again or is dismissed */
   notice: string | undefined;
+  /** A node the keyboard goes back to, once its editor closed from the keyboard */
+  nodeToFocus: string | undefined;
+  /** How many dropdowns, pickers or dialogs opened from the editor hold it open */
+  private holds = 0;
+  /** What commits the editor's pending input, e.g. a field's text not yet stored, in order */
+  private flushers: { flush: () => void; isPending: () => boolean }[] = [];
 
   private readonly disposeSync: IReactionDisposer;
 
   constructor(editorState: CubeEditorState) {
-    makeObservable<CubeNodeEditorState, 'nodeKey' | 'sync'>(this, {
+    makeObservable<CubeNodeEditorState, 'nodeKey' | 'holds' | 'sync'>(this, {
       nodeId: observable,
       nodeKey: observable,
+      holds: observable,
+      nodeToFocus: observable,
+      runFromKeyboard: action,
+      clearNodeToFocus: action,
+      isHeld: computed,
+      holdOpen: action,
+      finish: action,
+      finishApplied: action,
       draft: observable.ref,
       notice: observable,
       node: computed,
@@ -95,9 +116,13 @@ export class CubeNodeEditorState {
       open: action,
       canSwapInputs: computed,
       canRenameDuplicateColumns: computed,
+      canRenameConcatInput: computed,
+      canRestrictConcatInput: computed,
       apply: action,
       swapInputs: action,
       renameDuplicateColumns: action,
+      renameConcatInput: action,
+      restrictConcatInput: action,
       close: action,
       cancel: action,
       discard: action,
@@ -133,7 +158,10 @@ export class CubeNodeEditorState {
     );
   }
 
-  /** Opens the panel on a node, closing (and so applying) the one it showed */
+  /**
+   * Opens the editor on a node, finishing (and so applying) the one it showed;
+   * does nothing while that one is held open, or kept open saying why
+   */
   open(nodeId: string): void {
     if (nodeId === this.nodeId) {
       this.notice = undefined;
@@ -143,9 +171,11 @@ export class CubeNodeEditorState {
     if (!node) {
       return;
     }
-    this.close();
     this.notice = undefined;
-    this.bind(node);
+    if (this.finish()) {
+      // the node as the cube has it once the other editor finished
+      this.bind(this.editorState.document.query.getNode(nodeId) ?? node);
+    }
   }
 
   /**
@@ -160,7 +190,8 @@ export class CubeNodeEditorState {
       !edited ||
       node.key !== this.nodeKey ||
       !this.hasChanges ||
-      this.editorState.readOnly
+      this.editorState.readOnly ||
+      this.draft?.applyDisabledReason !== undefined
     ) {
       return;
     }
@@ -259,10 +290,244 @@ export class CubeNodeEditorState {
     this.bind(fixed.getNode(node.id) ?? node);
   }
 
-  /** Applies the draft, then closes the panel (spec §17.5: edits commit on close) */
+  /**
+   * The query with the draft applied and the node's input schemas, when the
+   * node is the one the panel was opened on and the cube can be changed
+   */
+  private get fixable():
+    | { node: QueryNode; query: Query; inputSchemas: (Schema | undefined)[] }
+    | undefined {
+    const { node } = this;
+    return node && node.key === this.nodeKey && !this.editorState.readOnly
+      ? { node, ...this.queryWithEdits }
+      : undefined;
+  }
+
+  /**
+   * Applies a fix of the query made from the draft applied, as one undo step,
+   * then goes on editing the node
+   */
+  private applyFix(
+    fix: (
+      query: Query,
+      nodeId: string,
+      inputSchemas: (Schema | undefined)[],
+    ) => Query,
+  ): void {
+    const { fixable } = this;
+    if (!fixable) {
+      return;
+    }
+    const { node, query, inputSchemas } = fixable;
+    const fixed = fix(query, node.id, inputSchemas);
+    this.editorState.applyQuery(fixed);
+    this.bind(fixed.getNode(node.id) ?? node);
+  }
+
+  /**
+   * Whether the concat being edited can be fixed by a Rename before its
+   * second input (PLAN §11.5, Q6), and the cube isn't read-only
+   */
+  get canRenameConcatInput(): boolean {
+    const { fixable } = this;
+    return (
+      fixable !== undefined &&
+      canRenameConcatInput(
+        fixable.query,
+        fixable.node.id,
+        fixable.inputSchemas[0],
+        fixable.inputSchemas[1],
+      )
+    );
+  }
+
+  /** Adds the Rename before the concat's second input, as one undo step */
+  renameConcatInput(): void {
+    if (this.canRenameConcatInput) {
+      this.applyFix((query, nodeId, [first, second]) =>
+        renameConcatInput(query, nodeId, first, second),
+      );
+    }
+  }
+
+  /**
+   * Whether the concat being edited can be fixed by a Restrict before its
+   * wider input (PLAN §11.5, Q6), and the cube isn't read-only
+   */
+  get canRestrictConcatInput(): boolean {
+    const { fixable } = this;
+    return (
+      fixable !== undefined &&
+      canRestrictConcatInput(
+        fixable.query,
+        fixable.node.id,
+        fixable.inputSchemas[0],
+        fixable.inputSchemas[1],
+      )
+    );
+  }
+
+  /** Adds the Restrict before the concat's wider input, as one undo step */
+  restrictConcatInput(): void {
+    if (this.canRestrictConcatInput) {
+      this.applyFix((query, nodeId, [first, second]) =>
+        restrictConcatInput(query, nodeId, first, second),
+      );
+    }
+  }
+
+  /**
+   * Applies the draft, then closes the panel (spec §17.5: edits commit on
+   * close). A draft whose Apply waits, e.g. an Extend whose expressions
+   * aren't validated, keeps the panel open and says why, rather than
+   * dropping or storing what can't be applied yet; Cancel drops it.
+   */
   close(): void {
+    if (this.keepOpenWhileWaiting()) {
+      return;
+    }
     this.apply();
     this.reset();
+    this.notice = undefined;
+  }
+
+  /**
+   * Whether a dropdown, picker or dialog opened from the editor is open: then
+   * nothing outside it closes the editor, and the page's shortcuts wait
+   * (spec §17.5)
+   */
+  get isHeld(): boolean {
+    return this.holds > 0;
+  }
+
+  /**
+   * Holds the editor open while something opened from it is open; call the
+   * returned function, once, when that closes
+   */
+  holdOpen(): () => void {
+    this.holds += 1;
+    let released = false;
+    return action(() => {
+      if (!released) {
+        released = true;
+        this.holds -= 1;
+      }
+    });
+  }
+
+  /**
+   * Has `finish` commit the editor's pending input first, e.g. by moving the
+   * focus out of a field that stores its text on blur; returns the function
+   * that removes it. One asked to run first runs before the others: the
+   * editor's blur, so a field's text is stored before what reads it.
+   */
+  addFlusher(
+    flush: () => void,
+    options?: {
+      first?: boolean;
+      /** Whether it has input to commit, e.g. text typed and not applied */
+      isPending?: () => boolean;
+    },
+  ): () => void {
+    const flusher = { flush, isPending: options?.isPending ?? (() => false) };
+    this.flushers = options?.first
+      ? [flusher, ...this.flushers]
+      : [...this.flushers, flusher];
+    return () => {
+      this.flushers = this.flushers.filter((other) => other !== flusher);
+    };
+  }
+
+  /**
+   * Whether the editor holds input a flusher would commit on closing, e.g. a
+   * warehouse typed and not applied; read when asked, not observed
+   */
+  hasPendingInput(): boolean {
+    return this.flushers.some((flusher) => flusher.isPending());
+  }
+
+  /**
+   * Keeps the editor open, saying why, when its draft's Apply waits, e.g. an
+   * Extend whose expressions aren't validated (PLAN §11.7), rather than
+   * dropping or storing what can't be applied yet; says whether it did
+   */
+  private keepOpenWhileWaiting(): boolean {
+    const { nodeId, draft } = this;
+    const waiting = draft?.applyDisabledReason;
+    if (
+      nodeId === undefined ||
+      waiting === undefined ||
+      !this.hasChanges ||
+      this.editorState.readOnly
+    ) {
+      return false;
+    }
+    this.notice = getEditorKeptOpenNotice(nodeId, waiting);
+    return true;
+  }
+
+  /**
+   * Finishes with the editor as anything but Cancel does (PLAN §11.8): commits
+   * its pending input, then closes it, applying the edits as one undo step.
+   * Edits the query can't take close it with a notice instead of vanishing.
+   * Does nothing while something opened from the editor holds it open, and
+   * keeps it open, saying why, while its Apply waits (PLAN §11.7).
+   */
+  private finishWith(): 'held' | 'kept' | 'dropped' | 'closed' {
+    if (this.nodeId === undefined) {
+      return 'closed';
+    }
+    if (this.isHeld) {
+      return 'held';
+    }
+    this.flushers.forEach((flusher) => flusher.flush());
+    if (this.keepOpenWhileWaiting()) {
+      return 'kept';
+    }
+    const { edited } = this;
+    if (
+      edited !== undefined &&
+      this.hasChanges &&
+      !this.editorState.readOnly &&
+      !this.editorState.document.query.canReplace(edited)
+    ) {
+      this.discard(CUBE_EDITOR_CLOSED_REASON.CANNOT_APPLY);
+      return 'dropped';
+    }
+    this.close();
+    return 'closed';
+  }
+
+  /** Finishes with the editor (`finishWith`); says whether it is closed */
+  finish(): boolean {
+    const finished = this.finishWith();
+    return finished === 'dropped' || finished === 'closed';
+  }
+
+  /**
+   * Finishes with the editor (`finishWith`); says whether its edits, if any,
+   * are now in the cube, so what comes next acts on them: false while it is
+   * held or kept open, or when its edits had to be dropped
+   */
+  finishApplied(): boolean {
+    return this.finishWith() === 'closed';
+  }
+
+  /**
+   * Runs what a shortcut does (F9, Ctrl+Z), which may finish the editor: when
+   * it closes the editor while the keyboard was in it, the keyboard goes back
+   * to the node (PLAN §11.8), as on Escape. The canvas takes the request.
+   */
+  runFromKeyboard(run: () => void, focusWasInEditor: boolean): void {
+    const { nodeId } = this;
+    run();
+    if (focusWasInEditor && nodeId !== undefined && this.nodeId === undefined) {
+      this.nodeToFocus = nodeId;
+    }
+  }
+
+  clearNodeToFocus(): void {
+    this.nodeToFocus = undefined;
   }
 
   /** Closes the panel, dropping the draft */
@@ -310,6 +575,10 @@ export class CubeNodeEditorState {
       return;
     }
     if (this.hasChanges) {
+      if (node && this.draft?.follow(node)) {
+        this.nodeKey = node.key;
+        return;
+      }
       this.discard(
         node
           ? CUBE_EDITOR_CLOSED_REASON.NODE_CHANGED

package/src/stores/CubeQueryRun.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 IR,
+  type ModelContext,
+  needsDatabaseType,
+  type Query,
+  QueryEmitter,
+  type Schema,
+} from '@finos/legend-cube';
+import { flowResult } from 'mobx';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeResultValue,
+} from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+/** A query to run up to its selected node, with what it runs in */
+export interface CubeQueryRunRequest {
+  /** The query, its selected node the one to run */
+  readonly query: Query;
+  readonly model: ModelContext;
+  readonly runtime: string;
+  /** The schema Cube infers for the node: the engine's columns must be these */
+  readonly schema: Schema;
+  /** The most rows to keep: one more is fetched to tell whether there are more */
+  readonly rowLimit: number;
+  readonly abortController: AbortController;
+  /** What the Runs panel calls the run, e.g. `Execute` (PLAN §11.16) */
+  readonly label: string;
+}
+
+export interface CubeQueryRunResult {
+  /** At most `rowLimit` rows, by the schema's column positions */
+  readonly rows: readonly (readonly CubeResultValue[])[];
+  /** The engine returned more than `rowLimit` rows */
+  readonly limited: boolean;
+  readonly sql: readonly string[];
+  readonly durationMs: number;
+  /** The execution lambda that ran, its row limit included */
+  readonly lambda: IR;
+}
+
+/** Thrown when a run is aborted while it waits for the model's outline */
+export class CubeQueryRunAborted extends Error {
+  constructor() {
+    super('The run was stopped');
+    this.name = 'CubeQueryRunAborted';
+  }
+}
+
+/** Runs the query and checks the engine's columns, keeping the lambda once it is written */
+const runAndCheck = async (
+  editorState: CubeEditorState,
+  request: CubeQueryRunRequest,
+  sent: { lambda?: IR },
+): Promise<CubeQueryRunResult> => {
+  const { query, model, runtime, schema, rowLimit, abortController } = request;
+  const nodeId = query.selected;
+  if (nodeId === undefined) {
+    throw new Error('A query to run has a selected node');
+  }
+  let databaseType: string | undefined;
+  if (needsDatabaseType(query, nodeId)) {
+    await flowResult(editorState.loadModelOutline(model));
+    if (abortController.signal.aborted) {
+      throw new CubeQueryRunAborted();
+    }
+    databaseType = editorState.getRunDatabaseType(
+      query,
+      nodeId,
+      model,
+      runtime,
+    );
+  }
+  const lambda = new QueryEmitter(
+    query,
+    editorState.registry,
+  ).emitExecutionLambda({ rowLimit, runtime, databaseType });
+  sent.lambda = lambda;
+  const response = await editorState.host.engine.execute(model, lambda, {
+    abortController,
+  });
+  // 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}`,
+      nodeId,
+    );
+  }
+  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`,
+      nodeId,
+    );
+  }
+  const limited = response.rows.length > rowLimit;
+  return {
+    rows: limited ? response.rows.slice(0, rowLimit) : response.rows,
+    limited,
+    sql: response.sql,
+    durationMs: response.durationMs,
+    lambda,
+  };
+};
+
+/**
+ * Runs a query up to its selected node (PLAN §8.2, §9), as Execute and the
+ * grid's fetches do (PLAN §11.10): a Drop, Slice, Limit or Distinct is written
+ * for the database it runs on (PLAN §11.4), which the model's outline gives,
+ * loaded once and waited for only then; the row limit is the emitter's
+ * `limit(rowLimit + 1)`. The engine's columns are checked against the schema,
+ * since rows are read by position. Rejects with a `CubeEngineError`, or a
+ * `CubeQueryRunAborted` when aborted before the engine is called. Each run
+ * is recorded in the Runs panel under its label with the lambda it sent,
+ * one that failed too; a stopped one isn't (PLAN §11.16).
+ */
+export const runCubeQuery = async (
+  editorState: CubeEditorState,
+  request: CubeQueryRunRequest,
+): Promise<CubeQueryRunResult> => {
+  const startedAt = Date.now();
+  const sent: { lambda?: IR } = {};
+  try {
+    const result = await runAndCheck(editorState, request, sent);
+    // a run stopped while it ran is let go of, even when it answers
+    if (!request.abortController.signal.aborted) {
+      editorState.runStats.record(request.label, result);
+    }
+    return result;
+  } catch (error) {
+    if (
+      !request.abortController.signal.aborted &&
+      !(error instanceof CubeQueryRunAborted)
+    ) {
+      editorState.runStats.record(request.label, {
+        durationMs: Date.now() - startedAt,
+        lambda: sent.lambda,
+        error:
+          error instanceof CubeEngineError
+            ? error.firstLine
+            : error instanceof Error
+              ? error.message
+              : String(error),
+      });
+    }
+    throw error;
+  }
+};

package/src/stores/CubeRunStatsState.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 { IR } from '@finos/legend-cube';
+import { action, makeObservable, observable } from 'mobx';
+
+/** How many of the latest runs are kept (spec §12.6) */
+export const MAX_CUBE_RUN_STATS = 15;
+
+/**
+ * One run on the engine: an Execute, a fetch of the grid's rows, an export,
+ * the Pivot editor's value load; one that failed too (PLAN §11.16)
+ */
+export interface CubeRunStat {
+  readonly id: number;
+  /** What ran, e.g. `Execute` or `Rows of SHIP_COUNTRY "France"` */
+  readonly label: string;
+  /** When it finished, in milliseconds since the epoch */
+  readonly finishedAt: number;
+  readonly durationMs: number;
+  /** The SQL statements the engine ran */
+  readonly sql: readonly string[];
+  /**
+   * The execution lambda sent, as it ran (its row limit included), for its
+   * Pure and JSON (PLAN §11.16); `undefined` when the run failed before one
+   * was written
+   */
+  readonly lambda: IR | undefined;
+  /** Why the run failed, the engine's first line; `undefined` for one that ran */
+  readonly error: string | undefined;
+}
+
+/** What a run gives to be recorded */
+export interface CubeRunRecord {
+  readonly durationMs: number;
+  readonly sql?: readonly string[] | undefined;
+  readonly lambda: IR | undefined;
+  readonly error?: string | undefined;
+}
+
+/**
+ * The latest runs of the page, newest first, at most `MAX_CUBE_RUN_STATS`
+ * (spec §12.6, PLAN §11.10): each Execute, fetch, export and Pivot value
+ * load records one, failed or not; a stopped one records nothing (PLAN
+ * §11.16). They are the page's, not the cube's, and aren't saved.
+ */
+export class CubeRunStatsState {
+  entries: readonly CubeRunStat[] = [];
+  private count = 0;
+
+  constructor() {
+    makeObservable<CubeRunStatsState, 'count'>(this, {
+      entries: observable.ref,
+      count: false,
+      record: action,
+      clear: action,
+    });
+  }
+
+  record(label: string, run: CubeRunRecord): void {
+    this.entries = [
+      {
+        id: ++this.count,
+        label,
+        finishedAt: Date.now(),
+        durationMs: run.durationMs,
+        sql: run.sql ?? [],
+        lambda: run.lambda,
+        error: run.error,
+      },
+      ...this.entries,
+    ].slice(0, MAX_CUBE_RUN_STATS);
+  }
+
+  clear(): void {
+    this.entries = [];
+  }
+}

package/src/stores/CubeRunningStepLambda.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { lambda, needsDatabaseType } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
+import { flowResult } from 'mobx';
+import { formatDisabledReasons } from '../__lib__/LegendCubeLabels.js';
+import { serializeCubeLambdaForHost } from '../graph-manager/protocol/pure/CubeEngineBuilder.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+/**
+ * The query of the step that runs, as a lambda for a host to keep, e.g. as
+ * a materialized view of a Studio ingest definition: written for the
+ * database it runs on, as Execute writes it, but with no runtime and no row
+ * limit, which whoever runs it adds. Fails when Execute can't run.
+ */
+export const buildCubeRunningStepLambda = async (
+  editorState: CubeEditorState,
+): Promise<PlainObject> => {
+  const { execution, document, emitter } = editorState;
+  const { query, context } = document;
+  const captureId = query.selected;
+  const runtime = context?.runtime;
+  const model = context?.model;
+  if (
+    !execution.canExecute ||
+    captureId === undefined ||
+    runtime === undefined ||
+    model === undefined
+  ) {
+    throw new Error(formatDisabledReasons(execution.disabledReasons));
+  }
+  let databaseType: string | undefined;
+  if (needsDatabaseType(query, captureId)) {
+    await flowResult(editorState.loadModelOutline(model));
+    databaseType = editorState.getRunDatabaseType(
+      query,
+      captureId,
+      model,
+      runtime,
+    );
+  }
+  return serializeCubeLambdaForHost(
+    lambda(
+      [],
+      [emitter.emitRelation(captureId, { withRowOrder: true, databaseType })],
+    ),
+  );
+};