@finos/legend-cube-builder 0.0.5 → 0.0.6

package/src/stores/variant/CubeJson.ts

@@ -0,0 +1,229 @@
+/**
+ * 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.
+ */
+
+// A Variant cell's JSON document (PLAN §11.20), as the engine sends it: its
+// compact text. Read here with each number kept as written, so `1` and `1.0`
+// stay apart and an id past 2^53 keeps its digits, and each object's keys in
+// the order written (a JS object would put keys that look like integers first).
+
+/** A JSON value, numbers kept as written and keys in their order */
+export type CubeJsonNode =
+  | {
+      readonly kind: 'object';
+      readonly entries: readonly (readonly [string, CubeJsonNode])[];
+    }
+  | { readonly kind: 'array'; readonly items: readonly CubeJsonNode[] }
+  | { readonly kind: 'number'; readonly text: string }
+  | { readonly kind: 'string'; readonly value: string }
+  | { readonly kind: 'boolean'; readonly value: boolean }
+  | { readonly kind: 'null' };
+
+const WHITESPACE = new Set([' ', '\t', '\n', '\r']);
+const NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/uy;
+
+/** A JSON document; throws a `SyntaxError` on text that isn't one */
+export const parseCubeJson = (text: string): CubeJsonNode => {
+  let at = 0;
+  const fail = (what: string): never => {
+    throw new SyntaxError(`${what} at ${at} in JSON`);
+  };
+  const skipWhitespace = (): void => {
+    while (at < text.length && WHITESPACE.has(text.charAt(at))) {
+      at += 1;
+    }
+  };
+  const readString = (): string => {
+    const start = at;
+    at += 1;
+    while (at < text.length && text.charAt(at) !== '"') {
+      at += text.charAt(at) === '\\' ? 2 : 1;
+    }
+    if (at >= text.length) {
+      fail('An unterminated string');
+    }
+    at += 1;
+    // a string loses nothing through JSON.parse: only numbers do
+    return JSON.parse(text.slice(start, at)) as string;
+  };
+  const readValue = (): CubeJsonNode => {
+    skipWhitespace();
+    const char = text.charAt(at);
+    if (char === '{') {
+      at += 1;
+      const entries: (readonly [string, CubeJsonNode])[] = [];
+      skipWhitespace();
+      if (text.charAt(at) === '}') {
+        at += 1;
+        return { kind: 'object', entries };
+      }
+      for (;;) {
+        skipWhitespace();
+        if (text.charAt(at) !== '"') {
+          fail('A key expected');
+        }
+        const key = readString();
+        skipWhitespace();
+        if (text.charAt(at) !== ':') {
+          fail('":" expected');
+        }
+        at += 1;
+        entries.push([key, readValue()]);
+        skipWhitespace();
+        if (text.charAt(at) === ',') {
+          at += 1;
+        } else if (text.charAt(at) === '}') {
+          at += 1;
+          return { kind: 'object', entries };
+        } else {
+          fail('"," or "}" expected');
+        }
+      }
+    }
+    if (char === '[') {
+      at += 1;
+      const items: CubeJsonNode[] = [];
+      skipWhitespace();
+      if (text.charAt(at) === ']') {
+        at += 1;
+        return { kind: 'array', items };
+      }
+      for (;;) {
+        items.push(readValue());
+        skipWhitespace();
+        if (text.charAt(at) === ',') {
+          at += 1;
+        } else if (text.charAt(at) === ']') {
+          at += 1;
+          return { kind: 'array', items };
+        } else {
+          fail('"," or "]" expected');
+        }
+      }
+    }
+    if (char === '"') {
+      return { kind: 'string', value: readString() };
+    }
+    for (const [word, node] of [
+      ['true', { kind: 'boolean', value: true }],
+      ['false', { kind: 'boolean', value: false }],
+      ['null', { kind: 'null' }],
+    ] as const) {
+      if (text.startsWith(word, at)) {
+        at += word.length;
+        return node;
+      }
+    }
+    NUMBER.lastIndex = at;
+    const number = NUMBER.exec(text);
+    if (!number) {
+      return fail('A value expected');
+    }
+    at += number[0].length;
+    return { kind: 'number', text: number[0] };
+  };
+  const value = readValue();
+  skipWhitespace();
+  if (at < text.length) {
+    fail('Text after the value');
+  }
+  return value;
+};
+
+/** The document, or `undefined` for text that isn't JSON */
+export const readCubeJson = (text: string): CubeJsonNode | undefined => {
+  try {
+    return parseCubeJson(text);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * A key or a string shown bare when it can't be mistaken for anything else:
+ * not empty, none of the notation's punctuation or a line break, no space at
+ * either end, and not a number, `true`, `false` or `null`; JSON-quoted
+ * otherwise
+ */
+const showText = (text: string): string =>
+  text !== '' &&
+  !/[,:{}[\]"\n\r\t]/u.test(text) &&
+  text === text.trim() &&
+  !/^(?:true|false|null|-?\d.*)$/u.test(text)
+    ? text
+    : JSON.stringify(text);
+
+const showNode = (node: CubeJsonNode): string => {
+  switch (node.kind) {
+    case 'object':
+      return `{${node.entries.map(([key, value]) => `${showText(key)}: ${showNode(value)}`).join(', ')}}`;
+    case 'array':
+      return `[${node.items.map(showNode).join(', ')}]`;
+    case 'string':
+      return showText(node.value);
+    case 'number':
+      return node.text;
+    case 'boolean':
+      return String(node.value);
+    case 'null':
+      return 'null';
+    default:
+      return '';
+  }
+};
+
+/**
+ * A Variant cell on one line, for the eye (PLAN §11.20, as legend-lite's
+ * Data Cube shows one): `{name: ann, tier: gold}`, `[a, b]`, numbers as
+ * written. Text that isn't JSON is shown as it is; the value itself stays the
+ * JSON text, for copying and export.
+ */
+export const formatCubeJsonLine = (text: string): string => {
+  const node = readCubeJson(text);
+  return node ? showNode(node) : text;
+};
+
+/** The document as JSON, indented two spaces, numbers as written */
+export const formatCubeJsonPretty = (node: CubeJsonNode, depth = 0): string => {
+  const indent = '  '.repeat(depth + 1);
+  const closing = '  '.repeat(depth);
+  switch (node.kind) {
+    case 'object':
+      return node.entries.length === 0
+        ? '{}'
+        : `{\n${node.entries
+            .map(
+              ([key, value]) =>
+                `${indent}${JSON.stringify(key)}: ${formatCubeJsonPretty(value, depth + 1)}`,
+            )
+            .join(',\n')}\n${closing}}`;
+    case 'array':
+      return node.items.length === 0
+        ? '[]'
+        : `[\n${node.items
+            .map((item) => `${indent}${formatCubeJsonPretty(item, depth + 1)}`)
+            .join(',\n')}\n${closing}]`;
+    case 'string':
+      return JSON.stringify(node.value);
+    case 'number':
+      return node.text;
+    case 'boolean':
+      return String(node.value);
+    case 'null':
+      return 'null';
+    default:
+      return '';
+  }
+};

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();
+  }
+}