@finos/legend-cube-builder 0.0.5 → 0.0.6

package/src/stores/CubeExamples.ts

@@ -15,6 +15,9 @@
  */
 
 import {
+  Explode,
+  Extend,
+  type JsonObject,
   AggregationFunction,
   Pivot,
   ColumnComparisonFilter,
@@ -59,6 +62,7 @@ import {
 import {
   CUBE_SALES_DATABASE,
   CUBE_SALES_MODEL,
+  CUBE_SALES_ORDERS_TABLE,
   CUBE_SALES_RUNTIME,
   CUBE_SALES_SCHEMA,
 } from './fixtures/CubeSalesDuckDbModel.js';
@@ -131,8 +135,8 @@ const SALES: CubeExampleDataset = {
   id: 'sales',
   name: 'Sales (DuckDB)',
   description:
-    'Made-up sales of tea and coffee by country and year, on DuckDB, which runs Pivot',
-  tables: ['sales'],
+    'Made-up sales of tea and coffee by country and year, and orders as JSON documents, on DuckDB, which runs Pivot and reads JSON',
+  tables: ['sales', 'orders'],
   model: CUBE_SALES_MODEL,
   runtime: CUBE_SALES_RUNTIME,
   database: CUBE_SALES_DATABASE,
@@ -188,6 +192,77 @@ const equal = (column: string, value: string): ColumnComparisonFilter =>
     value,
   });
 
+/** An order's document read as JSON: Parse as JSON's column, as the engine parses its text (PLAN §11.20) */
+const ORDER_DOCUMENT_COLUMN = {
+  name: 'document_json',
+  code: 'x | $x.document->toOne()->fromJson()',
+  lambda: {
+    _type: 'lambda',
+    body: [
+      {
+        _type: 'func',
+        function: 'fromJson',
+        parameters: [
+          {
+            _type: 'func',
+            function: 'toOne',
+            parameters: [
+              {
+                _type: 'property',
+                parameters: [{ _type: 'var', name: 'x' }],
+                property: 'document',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    parameters: [{ _type: 'var', name: 'x' }],
+  },
+};
+
+/** An order line's field as an Extend column, `x | $x.item->get('<key>')->to(@<type>)`, as the engine parses it */
+const orderLineColumn = (
+  key: string,
+  type: string,
+): { name: string; code: string; lambda: JsonObject } => ({
+  name: key,
+  code: `x | $x.item->get('${key}')->to(@${type})`,
+  lambda: {
+    _type: 'lambda',
+    body: [
+      {
+        _type: 'func',
+        function: 'to',
+        parameters: [
+          {
+            _type: 'func',
+            function: 'get',
+            parameters: [
+              {
+                _type: 'property',
+                parameters: [{ _type: 'var', name: 'x' }],
+                property: 'item',
+              },
+              { _type: 'string', value: key },
+            ],
+          },
+          {
+            _type: 'genericTypeInstance',
+            genericType: {
+              multiplicityArguments: [],
+              rawType: { _type: 'packageableType', fullPath: type },
+              typeArguments: [],
+              typeVariableValues: [],
+            },
+          },
+        ],
+      },
+    ],
+    parameters: [{ _type: 'var', name: 'x' }],
+  },
+});
+
 export const CUBE_EXAMPLES: readonly CubeExample[] = Object.freeze([
   example(
     NORTHWIND,
@@ -523,4 +598,47 @@ export const CUBE_EXAMPLES: readonly CubeExample[] = Object.freeze([
       connections: chain(['relational101', 'pivot101', 'sort101']),
     }),
   ),
+  example(
+    SALES,
+    'sales-orders-json',
+    'Orders from JSON',
+    "Reads each order's JSON document as a Variant column: explore its fields from the column's menu",
+    (table) => ({
+      nodes: [
+        table('relational101', CUBE_SALES_ORDERS_TABLE),
+        new Extend('extend101', [ORDER_DOCUMENT_COLUMN]),
+      ],
+      connections: chain(['relational101', 'extend101']),
+    }),
+  ),
+  example(
+    SALES,
+    'sales-order-lines-json',
+    'Order lines from JSON',
+    "One row per order line, from the array in each order's JSON document, with its product and quantity",
+    (table) => ({
+      nodes: [
+        table('relational101', CUBE_SALES_ORDERS_TABLE),
+        new Extend('extend101', [ORDER_DOCUMENT_COLUMN]),
+        new Explode('explode101', 'document_json', ['items'], 'item'),
+        new Extend('extend102', [
+          orderLineColumn('product', 'String'),
+          orderLineColumn('qty', 'Integer'),
+        ]),
+        // a lateral join keeps no order: the lines by order, then product
+        new Sort('sort101', [
+          { column: 'id', direction: SortDirection.ASC },
+          { column: 'product', direction: SortDirection.ASC },
+          { column: 'qty', direction: SortDirection.ASC },
+        ]),
+      ],
+      connections: chain([
+        'relational101',
+        'extend101',
+        'explode101',
+        'extend102',
+        'sort101',
+      ]),
+    }),
+  ),
 ]);

package/src/stores/CubeExamplesState.ts

@@ -94,7 +94,15 @@ export class CubeExamplesState {
     this.close();
     const document = example.createDocument();
     this.editorState.importDocument(document, false);
-    yield when(() => !this.editorState.isResolvingSources);
+    // its tables typed, and its expressions checked by the engine, as an
+    // example's Extend parsing JSON is (PLAN §11.20)
+    yield when(
+      () =>
+        !this.editorState.isResolvingSources &&
+        !this.editorState.document.query.nodes.some((node) =>
+          this.editorState.isTypingNode(node),
+        ),
+    );
     const { execution } = this.editorState;
     // not if the user has moved on, e.g. undone the opening: typing the
     // tables replaces the document but keeps its context, which is this

package/src/stores/CubeGridQuickActions.ts

@@ -76,6 +76,28 @@ export enum CubeGridCellKind {
   EMPTY = 'empty',
 }
 
+/**
+ * What keeps the grid's actions that add a node after the node that ran from
+ * being used, in order (the quick actions, Explore JSON and Parse as JSON,
+ * PLAN §11.20): rows from an earlier query, edits not applied yet, a run in
+ * flight, a cube that can't change; `undefined` when nothing does
+ */
+export const getCubeGridActionBlocker = (
+  editorState: CubeEditorState,
+): string | undefined => {
+  const { execution, document } = editorState;
+  return execution.result?.query !== document.query || execution.isStale
+    ? CUBE_QUICK_ACTION_DISABLED_REASON.STALE_ROWS
+    : // choosing would apply the edits first, leaving these rows stale
+      editorState.hasEditsToApply || editorState.nodeEditor.hasPendingInput()
+      ? CUBE_QUICK_ACTION_DISABLED_REASON.EDITING
+      : execution.isRunning
+        ? CUBE_QUICK_ACTION_DISABLED_REASON.RUNNING
+        : editorState.readOnly
+          ? READ_ONLY_CUBE_TITLE
+          : undefined;
+};
+
 /**
  * The quick actions on a cell of the shown rows (spec §12.4, PLAN §11.4,
  * §11.5 and §11.10): "Sort by" adds an ascending Sort on the cell's column,
@@ -109,18 +131,7 @@ export const getCubeGridQuickActions = (
     cellKind === CubeGridCellKind.VALUE
       ? buildDrilldownKeyRule(column.name, column.type, cell)
       : undefined;
-  // what keeps both from being used, in order
-  const blocked =
-    result.query !== query || execution.isStale
-      ? CUBE_QUICK_ACTION_DISABLED_REASON.STALE_ROWS
-      : // choosing would apply the edits first, leaving these rows stale
-        editorState.hasEditsToApply || editorState.nodeEditor.hasPendingInput()
-        ? CUBE_QUICK_ACTION_DISABLED_REASON.EDITING
-        : execution.isRunning
-          ? CUBE_QUICK_ACTION_DISABLED_REASON.RUNNING
-          : editorState.readOnly
-            ? READ_ONLY_CUBE_TITLE
-            : undefined;
+  const blocked = getCubeGridActionBlocker(editorState);
   const sortReason =
     blocked ??
     (isSortableType(column.type)

package/src/stores/CubePureText.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+// Pure text Cube writes for the engine to parse, as a user would type it: an
+// Extend's columns from Explore JSON (PLAN §11.20), and the column names the
+// expression editors insert.
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
+/** A Pure string literal: quoted, its backslashes and quotes escaped */
+export const pureStringLiteral = (text: string): string =>
+  `'${text.replace(/\\/gu, '\\\\').replace(/'/gu, "\\'")}'`;
+
+/** How an expression reads a column: `$x.NAME`, or `$x.'a name'` for one that isn't an identifier */
+export const columnAccessOf = (name: string): string =>
+  IDENTIFIER.test(name) ? `$x.${name}` : `$x.${pureStringLiteral(name)}`;

package/src/stores/CubeTourState.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 { action, computed, flowResult, makeObservable, observable } from 'mobx';
+import {
+  CUBE_EDITOR_TOUR,
+  CUBE_TOUR_EXAMPLE_ID,
+  type CubeTourStep,
+} from '../__lib__/LegendCubeTour.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import { isCubeSampleDataOffered } from './CubeHost.js';
+
+/** Whether a step can be shown: its controls are on the page */
+export type CubeTourStepShown = (step: CubeTourStep) => boolean;
+
+/**
+ * The editor's guided tour (PLAN §11.21): one step at a time, each pointing
+ * at its controls; a step whose controls aren't on the page is skipped. It
+ * starts on the cube as it is, the node editor's edits applied first; on an
+ * empty cube, where examples are offered, it opens one to show (one undo
+ * step). Nothing starts it but the user.
+ */
+export class CubeTourState {
+  readonly editorState: CubeEditorState;
+  readonly steps: readonly CubeTourStep[] = CUBE_EDITOR_TOUR;
+
+  isOpen = false;
+  /** The step shown, an index into `steps` */
+  index = 0;
+  /** Whether this tour opened its example */
+  openedExample = false;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable(this, {
+      isOpen: observable,
+      index: observable,
+      openedExample: observable,
+      step: computed,
+      start: action,
+      move: action,
+      close: action,
+    });
+    this.editorState = editorState;
+  }
+
+  get step(): CubeTourStep | undefined {
+    return this.isOpen ? this.steps[this.index] : undefined;
+  }
+
+  /**
+   * Starts the tour at its first step; not while the node editor keeps its
+   * edits open, as other actions wait for it
+   */
+  start(): void {
+    const { editorState } = this;
+    if (this.isOpen || !editorState.nodeEditor.finish()) {
+      return;
+    }
+    const example =
+      editorState.document.query.isEmpty &&
+      !editorState.readOnly &&
+      isCubeSampleDataOffered(editorState.host)
+        ? editorState.examples.examples.find(
+            (candidate) => candidate.id === CUBE_TOUR_EXAMPLE_ID,
+          )
+        : undefined;
+    this.openedExample = example !== undefined;
+    this.index = 0;
+    this.isOpen = true;
+    if (example) {
+      // the tour goes on while it opens and runs: its steps show as they can
+      flowResult(editorState.examples.openExample(example)).catch(
+        editorState.host.applicationStore.alertUnhandledError,
+      );
+    }
+  }
+
+  /**
+   * The step `by` steps on (1) or back (-1), skipping those not shown; past
+   * the last, the tour ends; before the first, it stays
+   */
+  move(by: 1 | -1, isShown: CubeTourStepShown): void {
+    for (
+      let index = this.index + by;
+      index >= 0 && index < this.steps.length;
+      index += by
+    ) {
+      const step = this.steps[index];
+      if (step && isShown(step)) {
+        this.index = index;
+        return;
+      }
+    }
+    if (by === 1) {
+      this.close();
+    }
+  }
+
+  close(): void {
+    this.isOpen = false;
+    this.index = 0;
+  }
+}

package/src/stores/LegendCubeHost.ts

@@ -0,0 +1,243 @@
+/**
+ * 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 { DepotServerClient } from '@finos/legend-server-depot';
+import {
+  LakehouseContractServerClient,
+  LakehouseIngestServerClient,
+  LakehousePlatformServerClient,
+} from '@finos/legend-server-lakehouse';
+import { MarketplaceServerClient } from '@finos/legend-server-marketplace';
+import { EXTERNAL_APPLICATION_NAVIGATION__generateCubeMarketplaceDataProductUrl } from '../__lib__/LegendCubeNavigation.js';
+import type { CubeConnectionExplorer } from '../graph-manager/CubeConnectionExplorer.js';
+import { CubeDataProductEnvironmentType } from '../graph-manager/CubeDataProduct.js';
+import type { CubeDataProductCatalog } from '../graph-manager/CubeDataProductCatalog.js';
+import type { CubeEngine } from '../graph-manager/CubeEngine.js';
+import { CubeEngineClientSettings } from '../graph-manager/CubeEngineClientSettings.js';
+import type { CubeIngestCatalog } from '../graph-manager/CubeIngestCatalog.js';
+import type { CubeProjectCatalog } from '../graph-manager/CubeProjectCatalog.js';
+import type { CubeServiceCatalog } from '../graph-manager/CubeServiceCatalog.js';
+import {
+  buildCubeConnectionExplorer,
+  buildCubeDataProductCatalog,
+  buildCubeEngine,
+  buildCubeIngestCatalog,
+  buildCubeLakehouseEnvironment,
+  buildCubeProjectCatalog,
+  buildCubeServiceCatalog,
+  type CubeEngineConfig,
+  type CubeLakehouseServices,
+} from '../graph-manager/protocol/pure/CubeEngineBuilder.js';
+import { getCubeRememberedWarehouse } from './CubeDataProductWarehouse.js';
+import type { CubeHost } from './CubeHost.js';
+import { LocalModelCatalog } from './LocalModelCatalog.js';
+
+/**
+ * The servers of a Legend deployment hosting the Cube page, as its config
+ * names them (PLAN §11.18): the engine, and each of the others only where the
+ * deployment has one. Legend Query and Legend Analytics each read theirs from
+ * their own config.
+ */
+export interface LegendCubeHostConfig {
+  readonly engine: CubeEngineConfig;
+  /** Published projects (PLAN §6.3) and, with a lakehouse, the data products' models */
+  readonly depotServerUrl?: string | undefined;
+  /** The lakehouse's contracts: data products need it, and a depot (PLAN §6.8) */
+  readonly lakehouseContractUrl?: string | undefined;
+  /** The lakehouse platform, which names the ingest servers: ingest data sets need it (PLAN §6.7) */
+  readonly lakehousePlatformUrl?: string | undefined;
+  /** The marketplace server, whose search the data product tab uses */
+  readonly marketplaceServerUrl?: string | undefined;
+  /** Legend Marketplace, which a production data product links to */
+  readonly marketplaceApplicationUrl?: string | undefined;
+  /** Legend Marketplace's production-parallel deployment, which a production-parallel data product links to */
+  readonly marketplaceProductionParallelUrl?: string | undefined;
+  /** The stereotype marking access point groups open to everyone, as Studio and Marketplace configure it */
+  readonly enterpriseStereotype?: CubeLakehouseServices['enterpriseStereotype'];
+  /** The lakehouse environment the host remembers for the viewer */
+  readonly getPreferredEnvironment?: (() => string | undefined) | undefined;
+}
+
+/**
+ * What Cube needs to read and run data products (PLAN §6.8), with the
+ * deployment's lakehouse and depot: none without both, so a deployment
+ * without them offers no data products. With a marketplace server too, its
+ * search is used; with the lakehouse platform, ingest data sets are offered.
+ */
+export const buildLegendCubeLakehouseServices = (
+  applicationStore: GenericLegendApplicationStore,
+  config: LegendCubeHostConfig,
+): CubeLakehouseServices | undefined => {
+  const { tracerService } = applicationStore;
+  if (!config.lakehouseContractUrl || !config.depotServerUrl) {
+    return undefined;
+  }
+  const contractServerClient = new LakehouseContractServerClient({
+    baseUrl: config.lakehouseContractUrl,
+  });
+  contractServerClient.setTracerService(tracerService);
+  const depotServerClient = new DepotServerClient({
+    serverUrl: config.depotServerUrl,
+  });
+  depotServerClient.setTracerService(tracerService);
+  let marketplaceServerClient: MarketplaceServerClient | undefined;
+  if (config.marketplaceServerUrl) {
+    marketplaceServerClient = new MarketplaceServerClient({
+      serverUrl: config.marketplaceServerUrl,
+      // the client only stores it, never reading it, and Cube calls no subscription route
+      subscriptionUrl: '',
+    });
+    marketplaceServerClient.setTracerService(tracerService);
+  }
+  // ingest data sets need the platform, which names the ingest servers; the
+  // ingest client has no server of its own: each call names one
+  let platformServerClient: LakehousePlatformServerClient | undefined;
+  let ingestServerClient: LakehouseIngestServerClient | undefined;
+  if (config.lakehousePlatformUrl) {
+    platformServerClient = new LakehousePlatformServerClient(
+      config.lakehousePlatformUrl,
+    );
+    platformServerClient.setTracerService(tracerService);
+    ingestServerClient = new LakehouseIngestServerClient(undefined);
+    ingestServerClient.setTracerService(tracerService);
+  }
+  return {
+    platformServerClient,
+    ingestServerClient,
+    contractServerClient,
+    depotServerClient,
+    marketplaceServerClient,
+    getAccessToken: () => applicationStore.getAccessToken(),
+    getCurrentUser: () => applicationStore.identityService.currentUser,
+    getPreferredEnvironment: config.getPreferredEnvironment,
+    enterpriseStereotype: config.enterpriseStereotype,
+    // the marketplace of the deployment's class, where its deployment is
+    getMarketplaceLink: (target) => {
+      const marketplaceUrl =
+        target.environmentType ===
+        CubeDataProductEnvironmentType.PRODUCTION_PARALLEL
+          ? config.marketplaceProductionParallelUrl
+          : config.marketplaceApplicationUrl;
+      return marketplaceUrl
+        ? EXTERNAL_APPLICATION_NAVIGATION__generateCubeMarketplaceDataProductUrl(
+            marketplaceUrl,
+            target.dataProductId,
+            target.deploymentId,
+            target.accessPointGroup,
+          )
+        : undefined;
+    },
+  };
+};
+
+/** The published projects in the deployment's depot, or none without a depot */
+export const buildLegendCubeProjectCatalog = (
+  applicationStore: GenericLegendApplicationStore,
+  config: LegendCubeHostConfig,
+): CubeProjectCatalog | undefined => {
+  if (!config.depotServerUrl) {
+    return undefined;
+  }
+  const depotServerClient = new DepotServerClient({
+    serverUrl: config.depotServerUrl,
+  });
+  depotServerClient.setTracerService(applicationStore.tracerService);
+  return buildCubeProjectCatalog(depotServerClient);
+};
+
+/** What tests give the host in place of what it would build */
+export interface LegendCubeHostParts {
+  readonly engine?: CubeEngine | undefined;
+  readonly connectionExplorer?: CubeConnectionExplorer | undefined;
+  readonly projectCatalog?: CubeProjectCatalog | undefined;
+}
+
+/**
+ * A Legend deployment as the host of the Cube page (PLAN §3.5, §11.18): the
+ * application's store, the engine and the bundled models, direct database
+ * connections read through the engine, the services in its registry, and
+ * the deployment's projects, data products and ingest data sets where it has
+ * the servers for them. Legend Query and Legend Analytics each build one per
+ * visit to the page, from their own config.
+ */
+export class LegendCubeHost implements CubeHost {
+  readonly applicationStore: GenericLegendApplicationStore;
+  readonly engine: CubeEngine;
+  readonly modelCatalog: LocalModelCatalog;
+  readonly connectionExplorer: CubeConnectionExplorer;
+  readonly dataProductCatalog: CubeDataProductCatalog | undefined;
+  readonly ingestCatalog: CubeIngestCatalog | undefined;
+  readonly projectCatalog: CubeProjectCatalog | undefined;
+  readonly serviceCatalog: CubeServiceCatalog;
+  /** The engine URL and compression Cube's engine clients share, which Dev Settings changes */
+  readonly engineClientSettings: CubeEngineClientSettings;
+
+  constructor(
+    applicationStore: GenericLegendApplicationStore,
+    config: LegendCubeHostConfig,
+    parts?: LegendCubeHostParts,
+  ) {
+    this.applicationStore = applicationStore;
+    const { tracerService } = applicationStore;
+    this.engineClientSettings = new CubeEngineClientSettings(config.engine);
+    const lakehouse = buildLegendCubeLakehouseServices(
+      applicationStore,
+      config,
+    );
+    this.ingestCatalog = lakehouse
+      ? buildCubeIngestCatalog(
+          config.engine,
+          tracerService,
+          lakehouse,
+          this.engineClientSettings,
+        )
+      : undefined;
+    this.engine =
+      parts?.engine ??
+      buildCubeEngine(config.engine, tracerService, {
+        ingestCatalog: this.ingestCatalog,
+        lakehouseEnvironment: lakehouse
+          ? buildCubeLakehouseEnvironment(lakehouse)
+          : undefined,
+        getRememberedWarehouse: () =>
+          getCubeRememberedWarehouse(applicationStore.userDataService),
+        clientSettings: this.engineClientSettings,
+      });
+    this.dataProductCatalog = lakehouse
+      ? buildCubeDataProductCatalog(lakehouse)
+      : undefined;
+    this.modelCatalog = new LocalModelCatalog(this.engine);
+    // its own client, configured as the engine's
+    this.connectionExplorer =
+      parts?.connectionExplorer ??
+      buildCubeConnectionExplorer(
+        config.engine,
+        tracerService,
+        this.engineClientSettings,
+      );
+    // it reads nothing until the source dialog's Project tab opens
+    this.projectCatalog =
+      parts?.projectCatalog ??
+      buildLegendCubeProjectCatalog(applicationStore, config);
+    // in progress (PLAN §6.4); it reads nothing until the Service tab opens
+    this.serviceCatalog = buildCubeServiceCatalog(
+      config.engine,
+      tracerService,
+      this.engineClientSettings,
+    );
+  }
+}