@finos/legend-cube-builder 0.0.4 → 0.0.6

package/src/stores/variant/CubeJsonExplorerState.ts

@@ -0,0 +1,378 @@
+/**
+ * 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 CubeDocument,
+  Explode,
+  Extend,
+  type ExtendColumn,
+  getVariantDatabaseProblem,
+  type QueryNode,
+  type SchemaColumn,
+} from '@finos/legend-cube';
+import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
+import {
+  action,
+  computed,
+  flow,
+  flowResult,
+  makeObservable,
+  observable,
+} from 'mobx';
+import {
+  CubeEngineError,
+  type CubeParsedExpression,
+} from '../../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from '../CubeEditorState.js';
+import { getCubeGridActionBlocker } from '../CubeGridQuickActions.js';
+import { CubeQueryRunAborted } from '../CubeQueryRun.js';
+import {
+  type CubeJsonField,
+  type CubeJsonOffer,
+  getCubeJsonFields,
+  getFreeCubeColumnName,
+} from './CubeJsonOffers.js';
+import { readCubeJsonSample } from './CubeJsonSampling.js';
+import type { CubeJsonSample } from './CubeJsonShape.js';
+
+/** A field's path as one key, for ticking */
+const pathKey = (path: readonly string[]): string => JSON.stringify(path);
+
+/** A ticked offer, by its field and its key */
+const offerKey = (path: readonly string[], offer: CubeJsonOffer): string =>
+  `${pathKey(path)} ${offer.key}`;
+
+/**
+ * Explore JSON (PLAN §11.20): a Variant column's documents, sampled through
+ * the cube's own query path (the query up to the node that ran, the column
+ * alone, its non-empty values), so the sample is listed in Runs and can be
+ * stopped; their fields as a tree; and the offers ticked, added after the
+ * node that ran as one undo step: an Extend of the columns, then an Explode
+ * Array for one row per element of an array. The engine parses each column's
+ * text first; the background check types the Extend, as any typed in the
+ * editor.
+ */
+export class CubeJsonExplorerState {
+  readonly editorState: CubeEditorState;
+
+  /** The column explored; `undefined` while closed */
+  column: SchemaColumn | undefined;
+  /** What was read: the first values, or every row */
+  sample: CubeJsonSample | undefined;
+  isReading = false;
+  isAdding = false;
+  /** Why the column couldn't be read, or the columns added */
+  error: string | undefined;
+  search = '';
+  /** The field whose offers show */
+  selectedPath: readonly string[] = [];
+  /** The ticked offers, by field and key */
+  ticked = new Map<string, CubeJsonOffer>();
+
+  /** The cube as it was when the dialog opened, and the node that ran */
+  private document: CubeDocument | undefined;
+  private afterId: string | undefined;
+  private controller: AbortController | undefined;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable<CubeJsonExplorerState, 'document' | 'afterId'>(this, {
+      column: observable.ref,
+      sample: observable.ref,
+      isReading: observable,
+      isAdding: observable,
+      error: observable,
+      search: observable,
+      selectedPath: observable.ref,
+      ticked: observable.shallow,
+      document: observable.ref,
+      afterId: observable,
+      isOpen: computed,
+      fields: computed,
+      selectedField: computed,
+      tickedOffers: computed,
+      open: flow,
+      read: flow,
+      add: flow,
+      stop: action,
+      close: action,
+      setSearch: action,
+      select: action,
+      toggle: action,
+    });
+    this.editorState = editorState;
+  }
+
+  get isOpen(): boolean {
+    return this.column !== undefined;
+  }
+
+  /** The column's fields, from what was read */
+  get fields(): CubeJsonField | undefined {
+    return this.column && this.sample
+      ? getCubeJsonFields(this.column.name, this.sample)
+      : undefined;
+  }
+
+  get selectedField(): CubeJsonField | undefined {
+    const key = pathKey(this.selectedPath);
+    const find = (field: CubeJsonField): CubeJsonField | undefined =>
+      pathKey(field.path) === key
+        ? field
+        : field.children.reduce<CubeJsonField | undefined>(
+            (found, child) => found ?? find(child),
+            undefined,
+          );
+    return this.fields ? find(this.fields) : undefined;
+  }
+
+  /** The offers ticked, in the order ticked */
+  get tickedOffers(): CubeJsonOffer[] {
+    return [...this.ticked.values()];
+  }
+
+  isTicked(path: readonly string[], offer: CubeJsonOffer): boolean {
+    return this.ticked.has(offerKey(path, offer));
+  }
+
+  /**
+   * Why Explore JSON can't be used on the column now: the grid's blockers
+   * (stale rows, edits, a run, a read-only cube), or a database without
+   * JSON; `undefined` when it can
+   */
+  getDisabledReason(): string | undefined {
+    const { editorState } = this;
+    const blocker = getCubeGridActionBlocker(editorState);
+    if (blocker) {
+      return blocker;
+    }
+    const { context, query } = editorState.document;
+    const nodeId = query.selected;
+    return context?.runtime === undefined || nodeId === undefined
+      ? undefined
+      : getVariantDatabaseProblem(
+          editorState.getRunDatabaseType(
+            query,
+            nodeId,
+            context.model,
+            context.runtime,
+          ),
+        );
+  }
+
+  /** Opens the dialog on a column of the rows shown, and reads its first values */
+  *open(column: SchemaColumn): GeneratorFn<void> {
+    const { editorState } = this;
+    const { document } = editorState;
+    this.stop();
+    this.column = column;
+    this.document = document;
+    this.afterId = document.query.selected;
+    this.sample = undefined;
+    this.error = undefined;
+    this.search = '';
+    this.selectedPath = [];
+    this.ticked.clear();
+    // the database the column's rows run on, which must read JSON: its
+    // model's outline may not have been needed by the run that showed them
+    const context = document.context;
+    const nodeId = this.afterId;
+    if (context?.runtime !== undefined && nodeId !== undefined) {
+      yield flowResult(editorState.loadModelOutline(context.model));
+      const problem = getVariantDatabaseProblem(
+        editorState.getRunDatabaseType(
+          document.query,
+          nodeId,
+          context.model,
+          context.runtime,
+        ),
+      );
+      if (problem) {
+        this.error = problem;
+        return;
+      }
+    }
+    yield flowResult(this.read(false));
+  }
+
+  /** Reads the column's first values, or every row: either replaces what was read */
+  *read(everyRow: boolean): GeneratorFn<void> {
+    const { editorState, column, document, afterId } = this;
+    if (
+      !column ||
+      !document ||
+      afterId === undefined ||
+      document.context?.runtime === undefined ||
+      this.isReading
+    ) {
+      return;
+    }
+    const controller = new AbortController();
+    this.controller = controller;
+    this.isReading = true;
+    this.error = undefined;
+    try {
+      const sample = (yield readCubeJsonSample(editorState, {
+        document,
+        afterId,
+        column,
+        everyRow,
+        abortController: controller,
+      })) as CubeJsonSample | undefined;
+      if (this.controller !== controller) {
+        return;
+      }
+      this.sample = sample;
+    } catch (error) {
+      if (
+        this.controller !== controller ||
+        error instanceof CubeQueryRunAborted
+      ) {
+        return;
+      }
+      assertErrorThrown(error);
+      this.error =
+        error instanceof CubeEngineError ? error.firstLine : error.message;
+    } finally {
+      if (this.controller === controller) {
+        this.controller = undefined;
+        this.isReading = false;
+      }
+    }
+  }
+
+  /** Stops a read in flight, keeping what was read before it */
+  stop(): void {
+    this.controller?.abort();
+    this.controller = undefined;
+    this.isReading = false;
+  }
+
+  setSearch(search: string): void {
+    this.search = search;
+  }
+
+  select(path: readonly string[]): void {
+    this.selectedPath = path;
+  }
+
+  /**
+   * Ticks or unticks an offer. One row per element can be ticked for one
+   * array at a time: two would give a row for each pair of their elements.
+   */
+  toggle(path: readonly string[], offer: CubeJsonOffer): void {
+    const key = offerKey(path, offer);
+    if (this.ticked.has(key)) {
+      this.ticked.delete(key);
+      return;
+    }
+    if (offer.explode) {
+      [...this.ticked].forEach(([other, ticked]) => {
+        if (ticked.explode) {
+          this.ticked.delete(other);
+        }
+      });
+    }
+    this.ticked.set(key, offer);
+  }
+
+  /**
+   * Adds the ticked offers after the node that ran, one undo step: an Extend
+   * of the columns, each under its default name or the next free one, then
+   * an Explode Array for the array ticked for one row per element, its
+   * element named the same way. The engine parses each column's text first,
+   * and the dialog stays open with the error if it can't. Nothing is added if
+   * the cube changed meanwhile.
+   */
+  *add(): GeneratorFn<void> {
+    const { editorState, document, afterId } = this;
+    const ticked = this.tickedOffers;
+    const offers = ticked.filter(
+      (offer): offer is CubeJsonOffer & { code: string } =>
+        offer.code !== undefined,
+    );
+    const exploded = ticked.find((offer) => offer.explode !== undefined);
+    if (
+      !document ||
+      afterId === undefined ||
+      (!offers.length && !exploded) ||
+      this.isAdding ||
+      editorState.document !== document
+    ) {
+      return;
+    }
+    this.isAdding = true;
+    this.error = undefined;
+    try {
+      const { query } = document;
+      const extendId = query.generateId(Extend.TYPE);
+      const taken = (
+        editorState.analysis.schemas.get(afterId)?.columns ?? []
+      ).map((column) => column.name);
+      const columns: ExtendColumn[] = [];
+      for (const [index, offer] of offers.entries()) {
+        const name = getFreeCubeColumnName(offer.name, [
+          ...taken,
+          ...columns.map((column) => column.name),
+        ]);
+        const parsed = (yield editorState.host.engine.parseExpression(
+          offer.code,
+          `${extendId}:${index}`,
+        )) as CubeParsedExpression;
+        columns.push({ name, code: offer.code, lambda: parsed.lambda });
+      }
+      // as the dialog found it: nothing changed while the engine parsed
+      if (editorState.document !== document) {
+        return;
+      }
+      const nodes: QueryNode[] = columns.length
+        ? [new Extend(extendId, columns)]
+        : [];
+      if (exploded?.explode) {
+        nodes.push(
+          new Explode(
+            query.generateId(Explode.TYPE),
+            exploded.explode.column,
+            exploded.explode.path,
+            getFreeCubeColumnName(exploded.name, [
+              ...taken,
+              ...columns.map((column) => column.name),
+            ]),
+          ),
+        );
+      }
+      editorState.addConfiguredNodes(nodes, afterId);
+      this.close();
+    } catch (error) {
+      assertErrorThrown(error);
+      this.error =
+        error instanceof CubeEngineError ? error.firstLine : error.message;
+    } finally {
+      this.isAdding = false;
+    }
+  }
+
+  close(): void {
+    this.stop();
+    this.column = undefined;
+    this.sample = undefined;
+    this.document = undefined;
+    this.afterId = undefined;
+    this.error = undefined;
+    this.search = '';
+    this.selectedPath = [];
+    this.ticked.clear();
+  }
+}

package/src/stores/variant/CubeJsonFieldsState.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 {
+  getVariantDatabaseProblem,
+  type Schema,
+  type SchemaColumn,
+} from '@finos/legend-cube';
+import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
+import {
+  action,
+  computed,
+  flow,
+  flowResult,
+  makeObservable,
+  observable,
+} from 'mobx';
+import { CubeEngineError } from '../../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from '../CubeEditorState.js';
+import { CubeQueryRunAborted } from '../CubeQueryRun.js';
+import {
+  type CubeJsonField,
+  filterCubeJsonFields,
+  getCubeJsonFields,
+} from './CubeJsonOffers.js';
+import { readCubeJsonSample } from './CubeJsonSampling.js';
+import type { CubeJsonSample } from './CubeJsonShape.js';
+
+/** A field's path as one key */
+const pathKey = (path: readonly string[]): string => JSON.stringify(path);
+
+/**
+ * A Variant input column's fields in an expression editor, Extend's or
+ * Filter by Expression's (PLAN §11.20, V.9): opened from the column's chip,
+ * read from a sample of the column just before the node being edited, so no
+ * run of the cube is needed and stale rows don't matter. The sample is read
+ * as Explore JSON reads one (listed in Runs, and it can be stopped); a field
+ * clicked writes its expression into the editor's.
+ */
+export class CubeJsonFieldsState {
+  readonly editorState: CubeEditorState;
+  /** The node being edited, whose input is read */
+  readonly nodeId: string;
+
+  /** The column whose fields are open; `undefined` while closed */
+  column: SchemaColumn | undefined;
+  /** What was read, and of which column */
+  sample:
+    | { readonly column: string; readonly sample: CubeJsonSample }
+    | undefined;
+  isReading = false;
+  /** Why the column couldn't be read */
+  error: string | undefined;
+  search = '';
+  /** The fields folded, by path; every field starts open */
+  readonly folded = observable.set<string>();
+  /** The field whose other forms show, by path */
+  formsOf: string | undefined;
+
+  private controller: AbortController | undefined;
+
+  constructor(editorState: CubeEditorState, nodeId: string) {
+    makeObservable(this, {
+      column: observable.ref,
+      sample: observable.ref,
+      isReading: observable,
+      error: observable,
+      search: observable,
+      formsOf: observable,
+      input: computed,
+      databaseProblem: computed,
+      fields: computed,
+      shownFields: computed,
+      toggle: flow,
+      read: flow,
+      stop: action,
+      close: action,
+      setSearch: action,
+      toggleFolded: action,
+      toggleForms: action,
+    });
+    this.editorState = editorState;
+    this.nodeId = nodeId;
+  }
+
+  /** The node's input: its id and schema, once known */
+  get input(): { id: string; schema: Schema } | undefined {
+    const [id] = this.editorState.document.query.getInputIds(this.nodeId);
+    const schema =
+      id === undefined ? undefined : this.editorState.analysis.schemas.get(id);
+    return id === undefined || !schema ? undefined : { id, schema };
+  }
+
+  /**
+   * Why the fields can't be read: the database the node's input runs on has
+   * no Variant functions; `undefined` when they can, or it isn't known yet
+   */
+  get databaseProblem(): string | undefined {
+    const { editorState, input } = this;
+    const { context, query } = editorState.document;
+    return input === undefined || context?.runtime === undefined
+      ? undefined
+      : getVariantDatabaseProblem(
+          editorState.getRunDatabaseType(
+            query,
+            input.id,
+            context.model,
+            context.runtime,
+          ),
+        );
+  }
+
+  /** The open column's fields, from what was read of it */
+  get fields(): CubeJsonField | undefined {
+    const { column, sample } = this;
+    return column && sample?.column === column.name
+      ? getCubeJsonFields(column.name, sample.sample)
+      : undefined;
+  }
+
+  /** The fields matching the search, with the fields they are in */
+  get shownFields(): CubeJsonField | undefined {
+    return this.fields && filterCubeJsonFields(this.fields, this.search);
+  }
+
+  isOpen(column: string): boolean {
+    return this.column?.name === column;
+  }
+
+  isFolded(path: readonly string[]): boolean {
+    return this.folded.has(pathKey(path));
+  }
+
+  areFormsShown(path: readonly string[]): boolean {
+    return this.formsOf === pathKey(path);
+  }
+
+  /**
+   * Opens a column's fields, reading its first values unless they were read
+   * already, or closes them if open. The model's databases are loaded first:
+   * a database without JSON functions is refused, with the reason.
+   */
+  *toggle(column: SchemaColumn): GeneratorFn<void> {
+    if (this.isOpen(column.name)) {
+      this.close();
+      return;
+    }
+    this.stop();
+    this.column = column;
+    this.error = undefined;
+    this.search = '';
+    this.formsOf = undefined;
+    if (this.sample?.column === column.name) {
+      return;
+    }
+    const { context } = this.editorState.document;
+    if (context) {
+      yield flowResult(this.editorState.loadModelOutline(context.model));
+    }
+    const problem = this.databaseProblem;
+    if (problem) {
+      this.error = problem;
+      return;
+    }
+    yield flowResult(this.read(false));
+  }
+
+  /** Reads the open column's first values, or every row, before the node */
+  *read(everyRow: boolean): GeneratorFn<void> {
+    const { editorState, column, input } = this;
+    if (!column || !input || this.isReading) {
+      return;
+    }
+    const controller = new AbortController();
+    this.controller = controller;
+    this.isReading = true;
+    this.error = undefined;
+    try {
+      const sample = (yield readCubeJsonSample(editorState, {
+        document: editorState.document,
+        afterId: input.id,
+        column,
+        everyRow,
+        abortController: controller,
+      })) as CubeJsonSample | undefined;
+      if (this.controller === controller && sample) {
+        this.sample = { column: column.name, sample };
+      }
+    } catch (error) {
+      if (
+        this.controller !== controller ||
+        error instanceof CubeQueryRunAborted
+      ) {
+        return;
+      }
+      assertErrorThrown(error);
+      this.error =
+        error instanceof CubeEngineError ? error.firstLine : error.message;
+    } finally {
+      if (this.controller === controller) {
+        this.controller = undefined;
+        this.isReading = false;
+      }
+    }
+  }
+
+  /** Stops a read in flight, keeping what was read before it */
+  stop(): void {
+    this.controller?.abort();
+    this.controller = undefined;
+    this.isReading = false;
+  }
+
+  /** Closes the fields, keeping what was read for when they open again */
+  close(): void {
+    this.stop();
+    this.column = undefined;
+    this.error = undefined;
+    this.formsOf = undefined;
+  }
+
+  setSearch(search: string): void {
+    this.search = search;
+  }
+
+  toggleFolded(path: readonly string[]): void {
+    const key = pathKey(path);
+    if (this.folded.has(key)) {
+      this.folded.delete(key);
+    } else {
+      this.folded.add(key);
+    }
+  }
+
+  toggleForms(path: readonly string[]): void {
+    const key = pathKey(path);
+    this.formsOf = this.formsOf === key ? undefined : key;
+  }
+}