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

package/src/stores/CubeSourcePickerState.ts

@@ -0,0 +1,426 @@
+/**
+ * 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 CubeContext,
+  getRelationalDisplayName,
+  type ModelContext,
+  RELATIONAL_TABLE_SOURCE_DEFINITION,
+  RelationalTableSource,
+} from '@finos/legend-cube';
+import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
+import {
+  action,
+  computed,
+  flow,
+  flowResult,
+  makeObservable,
+  observable,
+} from 'mobx';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  CubeTableFlag,
+  type CubeModelOutline,
+  type CubeOutlineDatabase,
+  type CubeOutlineRuntime,
+  type CubeOutlineSchema,
+  type CubeOutlineTable,
+} from '../graph-manager/CubeEngine.js';
+import { getRuntimesForDatabase } from '../graph-manager/CubeModelOutlineHelper.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import { type BundledModel, createTextModel } from './LocalModelCatalog.js';
+
+const toMessage = (error: unknown): string => {
+  assertErrorThrown(error);
+  return error instanceof CubeEngineError ? error.firstLine : error.message;
+};
+
+/** Whether a table can be picked: a table with a column Cube can't read can't */
+export const isTableSelectable = (table: CubeOutlineTable): boolean =>
+  !table.flags.includes(CubeTableFlag.UNAVAILABLE);
+
+/**
+ * The source picker (PLAN §6.2.7, Settled before M1.8): model, then database,
+ * then a runtime keyed by that database, then schema and table. A step with
+ * a single choice is picked automatically. The first table fixes the cube's
+ * model and runtime; later tables come from the same database and runtime.
+ * A table is added only once its schema has resolved.
+ */
+export class CubeSourcePickerState {
+  readonly editorState: CubeEditorState;
+
+  isOpen = false;
+  model: ModelContext | undefined;
+  /** The model is Pure text the user pastes, not a bundled one */
+  isPastingModel = false;
+  pastedModelText = '';
+  /** The model the paste box last loaded: only it keeps the box shown */
+  private pastedModel: ModelContext | undefined;
+  outline: CubeModelOutline | undefined;
+  isLoadingModel = false;
+  databasePath: string | undefined;
+  runtimePath: string | undefined;
+  schemaName: string | undefined;
+  tableName: string | undefined;
+  tableSearch = '';
+  isResolving = false;
+  /** Why the outline or the table couldn't be loaded, shown in the dialog */
+  error: string | undefined;
+  /** Counts Add presses: closing the dialog moves it on, so the pending Add is dropped */
+  private confirmRequest = 0;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable(this, {
+      isOpen: observable,
+      model: observable.ref,
+      isPastingModel: observable,
+      pastedModelText: observable,
+      outline: observable.ref,
+      isLoadingModel: observable,
+      databasePath: observable,
+      runtimePath: observable,
+      schemaName: observable,
+      tableName: observable,
+      tableSearch: observable,
+      isResolving: observable,
+      error: observable,
+      fixedContext: computed,
+      fixedDatabasePath: computed,
+      databases: computed,
+      runtimes: computed,
+      schemas: computed,
+      tables: computed,
+      canConfirm: computed,
+      open: action,
+      close: action,
+      selectDatabase: action,
+      selectRuntime: action,
+      selectSchema: action,
+      selectTable: action,
+      setTableSearch: action,
+      startPastingModel: action,
+      setPastedModelText: action,
+      selectModel: flow,
+      loadPastedModel: flow,
+      confirm: flow,
+    });
+    this.editorState = editorState;
+  }
+
+  get models(): readonly BundledModel[] {
+    return this.editorState.host.modelCatalog.models;
+  }
+
+  /** Once the cube has a model, every table comes from it */
+  get fixedContext(): CubeContext | undefined {
+    return this.editorState.document.context;
+  }
+
+  /** Once the cube has a table, every other one comes from its database */
+  get fixedDatabasePath(): string | undefined {
+    return this.editorState.document.query.nodes.find(
+      (node): node is RelationalTableSource =>
+        node instanceof RelationalTableSource,
+    )?.database;
+  }
+
+  get databases(): readonly CubeOutlineDatabase[] {
+    const databases = this.outline?.databases ?? [];
+    const fixedRuntime = this.fixedContext?.runtime;
+    return databases.filter(
+      (database) =>
+        (this.fixedDatabasePath === undefined ||
+          database.path === this.fixedDatabasePath) &&
+        (fixedRuntime === undefined ||
+          (this.outline &&
+            getRuntimesForDatabase(this.outline, database.path).some(
+              (runtime) => runtime.path === fixedRuntime,
+            ))),
+    );
+  }
+
+  get runtimes(): readonly CubeOutlineRuntime[] {
+    if (!this.outline || this.databasePath === undefined) {
+      return [];
+    }
+    const fixedRuntime = this.fixedContext?.runtime;
+    return getRuntimesForDatabase(this.outline, this.databasePath).filter(
+      (runtime) => fixedRuntime === undefined || runtime.path === fixedRuntime,
+    );
+  }
+
+  get schemas(): readonly CubeOutlineSchema[] {
+    return (
+      this.databases.find((database) => database.path === this.databasePath)
+        ?.schemas ?? []
+    );
+  }
+
+  /** The schema's tables, views left out, filtered by the search text */
+  get tables(): readonly CubeOutlineTable[] {
+    const search = this.tableSearch.trim().toLowerCase();
+    return (
+      this.schemas.find((schema) => schema.name === this.schemaName)?.tables ??
+      []
+    ).filter(
+      (table) =>
+        !table.isView &&
+        getRelationalDisplayName(table.name).toLowerCase().includes(search),
+    );
+  }
+
+  get canConfirm(): boolean {
+    const table = this.tables.find(
+      (candidate) => candidate.name === this.tableName,
+    );
+    return (
+      !this.isLoadingModel &&
+      !this.isResolving &&
+      this.model !== undefined &&
+      this.runtimePath !== undefined &&
+      table !== undefined &&
+      isTableSelectable(table)
+    );
+  }
+
+  /**
+   * Opens the dialog on the cube's model, or on the only model offered. A
+   * model whose outline failed to load is loaded again. Does nothing while
+   * the cube is read-only.
+   */
+  open(): void {
+    if (this.editorState.readOnly) {
+      return;
+    }
+    this.isOpen = true;
+    this.error = undefined;
+    const model =
+      this.fixedContext?.model ??
+      (this.models.length === 1 && !this.isPastingModel
+        ? this.models[0]?.model
+        : this.model);
+    if (!model) {
+      return;
+    }
+    if (model !== this.model || !this.outline) {
+      flowResult(this.selectModel(model)).catch(
+        this.editorState.host.applicationStore.alertUnhandledError,
+      );
+    } else if (
+      this.databasePath !== undefined &&
+      !this.databases.some((database) => database.path === this.databasePath)
+    ) {
+      // the cube changed since the last pick, e.g. by undo
+      const [onlyDatabase, ...otherDatabases] = this.databases;
+      this.selectDatabase(
+        onlyDatabase && !otherDatabases.length ? onlyDatabase.path : undefined,
+      );
+    }
+  }
+
+  /** Closes the dialog; a table still being typed is not added */
+  close(): void {
+    this.isOpen = false;
+    this.confirmRequest++;
+    this.isResolving = false;
+  }
+
+  /** Offers a text box for a Pure model in place of the bundled ones */
+  startPastingModel(): void {
+    this.isPastingModel = true;
+    this.model = undefined;
+    this.outline = undefined;
+    this.error = undefined;
+    this.isLoadingModel = false;
+    this.resetFrom('database');
+  }
+
+  setPastedModelText(text: string): void {
+    this.pastedModelText = text;
+  }
+
+  /**
+   * Loads the pasted Pure text as the model: the cube will hold the text
+   * itself, so it counts towards the size a saved cube can have
+   */
+  *loadPastedModel(): GeneratorFn<void> {
+    if (this.pastedModelText.trim()) {
+      this.pastedModel = createTextModel(this.pastedModelText);
+      yield flowResult(this.selectModel(this.pastedModel));
+    }
+  }
+
+  /**
+   * Loads a model's outline. Any model but the one the paste box loaded ends
+   * pasting, e.g. a bundled model, or the model of a cube opened meanwhile.
+   */
+  *selectModel(model: ModelContext): GeneratorFn<void> {
+    this.isPastingModel = model === this.pastedModel;
+    this.model = model;
+    this.outline = undefined;
+    this.error = undefined;
+    this.resetFrom('database');
+    this.isLoadingModel = true;
+    try {
+      const outline = (yield this.editorState.host.modelCatalog.loadOutline(
+        model,
+      )) as CubeModelOutline;
+      if (this.model !== model) {
+        return;
+      }
+      this.outline = outline;
+      const [onlyDatabase, ...otherDatabases] = this.databases;
+      if (onlyDatabase && !otherDatabases.length) {
+        this.selectDatabase(onlyDatabase.path);
+      }
+    } catch (error) {
+      if (this.model === model) {
+        this.error = toMessage(error);
+      }
+    } finally {
+      if (this.model === model) {
+        this.isLoadingModel = false;
+      }
+    }
+  }
+
+  selectDatabase(path: string | undefined): void {
+    this.databasePath = path;
+    this.resetFrom('runtime');
+    const [onlyRuntime, ...otherRuntimes] = this.runtimes;
+    if (onlyRuntime && !otherRuntimes.length) {
+      this.runtimePath = onlyRuntime.path;
+    }
+    const [onlySchema, ...otherSchemas] = this.schemas;
+    if (onlySchema && !otherSchemas.length) {
+      this.schemaName = onlySchema.name;
+    }
+  }
+
+  selectRuntime(path: string | undefined): void {
+    this.runtimePath = path;
+  }
+
+  selectSchema(name: string | undefined): void {
+    this.schemaName = name;
+    this.resetFrom('table');
+  }
+
+  selectTable(name: string | undefined): void {
+    this.tableName = name;
+    this.error = undefined;
+  }
+
+  setTableSearch(search: string): void {
+    this.tableSearch = search;
+  }
+
+  /**
+   * Types the picked table with the engine, then adds it; the first table
+   * also sets the cube's model and runtime, in the same undo step. The cube
+   * may have changed while the engine answered: the table is added only if
+   * the cube still has the same model and runtime and can take it.
+   */
+  *confirm(): GeneratorFn<void> {
+    if (!this.canConfirm) {
+      return;
+    }
+    const { editorState } = this;
+    const model = this.model as ModelContext;
+    const runtime = this.runtimePath as string;
+    const coordinates = {
+      database: this.databasePath as string,
+      schema: this.schemaName as string,
+      table: this.tableName as string,
+    };
+    const contextBefore = editorState.document.context;
+    // the engine stamps the table's accessor with its node id, so the id comes first
+    const id = editorState.document.query.generateId(
+      RelationalTableSource.TYPE,
+    );
+    const request = ++this.confirmRequest;
+    this.isResolving = true;
+    this.error = undefined;
+    try {
+      const typed = (yield editorState.host.engine.resolveSchemas(
+        model,
+        new Map([
+          [id, [coordinates.database, coordinates.schema, coordinates.table]],
+        ]),
+      )) as Awaited<ReturnType<typeof editorState.host.engine.resolveSchemas>>;
+      if (request !== this.confirmRequest) {
+        return;
+      }
+      const schema = typed.get(id);
+      if (schema === undefined || schema instanceof CubeEngineError) {
+        throw (
+          schema ??
+          new CubeEngineError(
+            CubeEngineErrorKind.COMPILE,
+            `The engine gave no schema for this table`,
+          )
+        );
+      }
+      const node = RELATIONAL_TABLE_SOURCE_DEFINITION.resolve(
+        RELATIONAL_TABLE_SOURCE_DEFINITION.fromCoordinates(id, coordinates),
+        { kind: 'resolved', schema },
+      );
+      const { document } = editorState;
+      if (document.context !== contextBefore || !document.query.canAdd(node)) {
+        throw new Error(
+          `The cube changed while the table was loading; pick the table again.`,
+        );
+      }
+      const query = document.query.add(node);
+      // the first table sets the model and runtime; a cube saved with a model
+      // but no runtime takes the picked runtime and keeps the rest
+      editorState.applyDocument(
+        document.context?.runtime !== undefined
+          ? document.withQuery(query)
+          : document
+              .withContext({
+                ...document.context,
+                model: document.context?.model ?? model,
+                runtime,
+              })
+              .withQuery(query),
+      );
+      this.isOpen = false;
+      this.resetFrom('table');
+    } catch (error) {
+      if (request === this.confirmRequest) {
+        this.error = toMessage(error);
+      }
+    } finally {
+      if (request === this.confirmRequest) {
+        this.isResolving = false;
+      }
+    }
+  }
+
+  private resetFrom(step: 'database' | 'runtime' | 'table'): void {
+    if (step === 'database') {
+      this.databasePath = undefined;
+    }
+    if (step === 'database' || step === 'runtime') {
+      this.runtimePath = undefined;
+      this.schemaName = undefined;
+    }
+    this.tableName = undefined;
+    this.tableSearch = '';
+  }
+}

package/src/stores/CubeSpecTransferState.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 {
+  CubeSpecDecodeError,
+  MAX_SPEC_BYTES,
+  parseCubeSpec,
+  serializeCubeSpec,
+} from '@finos/legend-cube';
+import {
+  ContentType,
+  downloadFileUsingDataURI,
+  type GeneratorFn,
+  readFileAsText,
+} from '@finos/legend-shared';
+import { action, flow, makeObservable, observable } from 'mobx';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+export enum CUBE_SPEC_TRANSFER_MODE {
+  EXPORT = 'export',
+  IMPORT = 'import',
+}
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/** Why a spec can't be imported; a broken document names the path of the problem */
+export const getSpecImportError = (error: unknown): string =>
+  error instanceof CubeSpecDecodeError
+    ? error.path
+      ? `Can't import the spec: ${error.path} ${error.detail}`
+      : `Can't import the spec: it ${error.detail}`
+    : `Can't import the spec: ${errorMessage(error)}`;
+
+/** A file name for a cube's spec, from its name */
+export const getCubeSpecFileName = (name: string | undefined): string => {
+  const base = name?.trim().replace(/[^\w.-]+/gu, '_') ?? '';
+  return `${base.length ? base : 'cube'}.cube.json`;
+};
+
+/**
+ * Export and import of the saved spec (PLAN §10.3), the only way to keep a
+ * cube until the Cube store (M8). Both are developer tools for now, labelled
+ * "(dev)" (Settled before M1.8).
+ */
+export class CubeSpecTransferState {
+  readonly editorState: CubeEditorState;
+
+  mode: CUBE_SPEC_TRANSFER_MODE | undefined;
+  /** The spec to export, once written */
+  exportText: string | undefined;
+  /** The spec text to import, pasted or read from a file */
+  importText = '';
+  /** Why the export or the import failed */
+  error: string | undefined;
+  isReadingFile = false;
+  /** Counts file reads, so a read that finishes after another starts is dropped */
+  private fileRequest = 0;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable<CubeSpecTransferState, 'fileRequest'>(this, {
+      mode: observable,
+      exportText: observable,
+      importText: observable,
+      error: observable,
+      isReadingFile: observable,
+      fileRequest: observable,
+      openExport: action,
+      openImport: action,
+      close: action,
+      setImportText: action,
+      importSpec: action,
+      readImportFile: flow,
+    });
+    this.editorState = editorState;
+  }
+
+  /** Writes the cube's spec, invalid queries included; a spec over the size cap is refused */
+  openExport(): void {
+    this.mode = CUBE_SPEC_TRANSFER_MODE.EXPORT;
+    this.error = undefined;
+    this.exportText = undefined;
+    const { document, registry } = this.editorState;
+    try {
+      this.exportText = serializeCubeSpec(document, registry);
+    } catch (error) {
+      this.error = errorMessage(error);
+    }
+  }
+
+  openImport(): void {
+    this.mode = CUBE_SPEC_TRANSFER_MODE.IMPORT;
+    this.error = undefined;
+    this.importText = '';
+    this.isReadingFile = false;
+  }
+
+  close(): void {
+    this.mode = undefined;
+    this.exportText = undefined;
+    this.importText = '';
+    this.error = undefined;
+    this.fileRequest++;
+    this.isReadingFile = false;
+  }
+
+  setImportText(text: string): void {
+    this.importText = text;
+    this.error = undefined;
+  }
+
+  async copyExport(): Promise<void> {
+    if (this.exportText !== undefined) {
+      await this.editorState.host.applicationStore.clipboardService.copyTextToClipboard(
+        this.exportText,
+        { notifySuccessMessage: 'Cube spec copied to the clipboard' },
+      );
+    }
+  }
+
+  downloadExport(): void {
+    if (this.exportText !== undefined) {
+      downloadFileUsingDataURI(
+        getCubeSpecFileName(this.editorState.document.name),
+        this.exportText,
+        ContentType.APPLICATION_JSON,
+      );
+    }
+  }
+
+  /** Reads a spec file into the import text; a file over the size cap is refused unread */
+  *readImportFile(file: File): GeneratorFn<void> {
+    const request = ++this.fileRequest;
+    this.error = undefined;
+    if (file.size > MAX_SPEC_BYTES) {
+      // a file being read before this one is dropped
+      this.isReadingFile = false;
+      this.error = `The file is too large to import: a spec is at most ${MAX_SPEC_BYTES} bytes`;
+      return;
+    }
+    this.isReadingFile = true;
+    try {
+      const text = (yield readFileAsText(file)) as string;
+      if (request === this.fileRequest) {
+        this.importText = text;
+      }
+    } catch (error) {
+      if (request === this.fileRequest) {
+        // the browser's FileReader rejects with its error event, not an Error
+        const reason =
+          error instanceof Error
+            ? error.message
+            : error instanceof ProgressEvent &&
+                error.target instanceof FileReader
+              ? (error.target.error?.message ?? 'the browser could not read it')
+              : String(error);
+        this.error = `Can't read the file: ${reason}`;
+      }
+    } finally {
+      if (request === this.fileRequest) {
+        this.isReadingFile = false;
+      }
+    }
+  }
+
+  /**
+   * Opens the spec in place of the cube, as one undo step, and never runs it.
+   * A spec that can't be read leaves the cube as it was and says why: a
+   * broken document names the path of the problem, e.g. `query.nodes[2].database`.
+   */
+  importSpec(): boolean {
+    let decoded: ReturnType<typeof parseCubeSpec>;
+    try {
+      decoded = parseCubeSpec(this.importText, {
+        registry: this.editorState.registry,
+      });
+    } catch (error) {
+      this.error = getSpecImportError(error);
+      return false;
+    }
+    this.editorState.importDocument(decoded.document, decoded.readOnly);
+    this.close();
+    return true;
+  }
+}

package/src/stores/LocalModelCatalog.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { ModelContext } from '@finos/legend-cube';
+import type {
+  CubeEngine,
+  CubeModelOutline,
+} from '../graph-manager/CubeEngine.js';
+import { CUBE_NORTHWIND_MODEL } from './fixtures/CubeNorthwindModel.js';
+
+// The models of the slice (PLAN §6.2.3): Pure text bundled with Cube, or
+// pasted by the user. Picking one gives the model context the cube saves, the
+// text itself (§6.2.2), so a saved cube needs no catalog to open.
+
+export interface BundledModel {
+  readonly id: string;
+  readonly label: string;
+  readonly model: ModelContext;
+}
+
+export const BUNDLED_MODELS: readonly BundledModel[] = Object.freeze([
+  {
+    id: 'cube-northwind',
+    label: 'Northwind (Cube fixture)',
+    model: CUBE_NORTHWIND_MODEL,
+  },
+]);
+
+/** The model context of pasted Pure text */
+export const createTextModel = (code: string): ModelContext =>
+  Object.freeze({ _type: 'text', code });
+
+/**
+ * Loads the outlines of models through the engine port, each model's once:
+ * the picker asks again whenever it opens
+ */
+export class LocalModelCatalog {
+  readonly models = BUNDLED_MODELS;
+  private readonly engine: CubeEngine;
+  private readonly outlines = new Map<string, Promise<CubeModelOutline>>();
+
+  constructor(engine: CubeEngine) {
+    this.engine = engine;
+  }
+
+  loadOutline(model: ModelContext): Promise<CubeModelOutline> {
+    const key = JSON.stringify(model);
+    let outline = this.outlines.get(key);
+    if (!outline) {
+      outline = this.engine.loadModel(model);
+      // a failed load is tried again next time
+      outline.catch(() => this.outlines.delete(key));
+      this.outlines.set(key, outline);
+    }
+    return outline;
+  }
+}