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

package/src/__test-utils__/CubeNorthwindTestQueries.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 {
+  ColumnComparisonFilter,
+  CompositeFilter,
+  CompositeFilterOperator,
+  Connection,
+  Filter,
+  FilterOperator,
+  type FilterRule,
+  Join,
+  JoinType,
+  PrimitiveType,
+  Query,
+  RelationalTableSource,
+  Schema,
+  SchemaColumn,
+} from '@finos/legend-cube';
+
+// Cube queries over Northwind, typed as the engine types the Cube fixture
+// (PLAN §8.5), for the serializer's and the engine's tests
+
+export const NORTHWIND_DATABASE =
+  'showcase::northwind::store::NorthwindDatabase';
+export const NORTHWIND_RUNTIME = 'showcase::northwind::mapping::StoreRuntime';
+
+const P = 'meta::pure::precisePrimitives::';
+
+const column = (
+  name: string,
+  path: string,
+  nullable = true,
+  params: number[] = [],
+): SchemaColumn =>
+  new SchemaColumn(name, PrimitiveType.get(path, params), nullable);
+const varchar = (name: string, length: number, nullable = true): SchemaColumn =>
+  column(name, `${P}Varchar`, nullable, [length]);
+const smallInt = (name: string, nullable = true): SchemaColumn =>
+  column(name, `${P}SmallInt`, nullable);
+const date = (name: string): SchemaColumn => column(name, 'StrictDate');
+
+export const ORDERS_COLUMNS = [
+  smallInt('ORDER_ID', false),
+  varchar('CUSTOMER_ID', 5),
+  smallInt('EMPLOYEE_ID'),
+  date('ORDER_DATE'),
+  date('REQUIRED_DATE'),
+  date('SHIPPED_DATE'),
+  smallInt('SHIP_VIA'),
+  column('FREIGHT', `${P}Double`),
+  varchar('SHIP_NAME', 40),
+  varchar('SHIP_ADDRESS', 60),
+  varchar('SHIP_CITY', 15),
+  varchar('SHIP_REGION', 15),
+  varchar('SHIP_POSTAL_CODE', 10),
+  varchar('SHIP_COUNTRY', 15),
+];
+
+export const CUSTOMERS_COLUMNS = [
+  varchar('CUSTOMER_ID', 5, false),
+  varchar('COMPANY_NAME', 40, false),
+  varchar('CONTACT_NAME', 30),
+  varchar('CONTACT_TITLE', 30),
+  varchar('ADDRESS', 60),
+  varchar('CITY', 15),
+  varchar('REGION', 15),
+  varchar('POSTAL_CODE', 10),
+  varchar('COUNTRY', 15),
+  varchar('PHONE', 24),
+  varchar('FAX', 24),
+];
+
+export const northwindTable = (
+  id: string,
+  name: string,
+  columns: SchemaColumn[],
+): RelationalTableSource =>
+  new RelationalTableSource(
+    id,
+    { database: NORTHWIND_DATABASE, schema: 'NORTHWIND', table: name },
+    { kind: 'resolved', schema: new Schema(columns) },
+  );
+
+/** France since 1997, by employees 1 and 4 (PLAN §8.5) */
+export const SLICE_FILTER: FilterRule = new CompositeFilter(
+  CompositeFilterOperator.AND,
+  [
+    new ColumnComparisonFilter('SHIP_COUNTRY', FilterOperator.EQUAL, {
+      kind: 'string',
+      value: 'France',
+    }),
+    new ColumnComparisonFilter(
+      'ORDER_DATE',
+      FilterOperator.GREATER_THAN_OR_EQUAL,
+      { kind: 'strictDate', value: '1997-01-01' },
+    ),
+    new ColumnComparisonFilter('EMPLOYEE_ID', FilterOperator.IN, [
+      { kind: 'integer', value: '1' },
+      { kind: 'integer', value: '4' },
+    ]),
+  ],
+);
+
+/** The slice (PLAN §8.5): ORDERS ⋈ CUSTOMERS on CUSTOMER_ID, then the filter, captured at the filter */
+export const sliceQuery = (
+  filter: FilterRule = SLICE_FILTER,
+  joinType = JoinType.INNER,
+): Query =>
+  new Query(
+    [
+      northwindTable('relational101', 'ORDERS', ORDERS_COLUMNS),
+      northwindTable('relational102', 'CUSTOMERS', CUSTOMERS_COLUMNS),
+      new Join('join101', {
+        leftColumns: ['CUSTOMER_ID'],
+        rightColumns: ['CUSTOMER_ID'],
+        joinType,
+      }),
+      new Filter('filter101', filter),
+    ],
+    [
+      new Connection('relational101', 'join101', 'leftTds'),
+      new Connection('relational102', 'join101', 'rightTds'),
+      new Connection('join101', 'filter101', 'tds'),
+    ],
+    'filter101',
+  );
+
+/**
+ * ORDERS ⟗ a CUSTOMERS-like table on CUSTOMER_ID, nullable on both sides with
+ * different lengths (so `toOne()`, a merge and a cast), captured at the join
+ */
+export const fullJoinQuery = (): Query =>
+  new Query(
+    [
+      northwindTable('relational101', 'ORDERS', ORDERS_COLUMNS),
+      northwindTable('relational102', 'CUSTOMERS', [
+        varchar('CUSTOMER_ID', 40),
+        varchar('COMPANY_NAME', 40),
+      ]),
+      new Join('join101', {
+        leftColumns: ['CUSTOMER_ID'],
+        rightColumns: ['CUSTOMER_ID'],
+        joinType: JoinType.FULL_OUTER,
+      }),
+    ],
+    [
+      new Connection('relational101', 'join101', 'leftTds'),
+      new Connection('relational102', 'join101', 'rightTds'),
+    ],
+    'join101',
+  );

package/src/__test-utils__/CubePageTestUtils.tsx

@@ -0,0 +1,96 @@
+/**
+ * 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 {
+  ApplicationFrameworkProvider,
+  ApplicationStoreProvider,
+  type GenericLegendApplicationStore,
+} from '@finos/legend-application';
+import { TEST__BrowserEnvironmentProvider } from '@finos/legend-application/test';
+import type { CubeDocument } from '@finos/legend-cube';
+import {
+  act,
+  type RenderResult,
+  render,
+  waitFor,
+} from '@testing-library/react';
+import type { CubeEditorState } from '../stores/CubeEditorState.js';
+
+/** React Flow watches the canvas with an IntersectionObserver, which jsdom lacks */
+class TEST__IntersectionObserver {
+  observe(): void {
+    // nothing is ever in view under jsdom
+  }
+  unobserve(): void {
+    // nothing to stop watching
+  }
+  disconnect(): void {
+    // nothing to stop watching
+  }
+  takeRecords(): IntersectionObserverEntry[] {
+    return [];
+  }
+}
+
+/** Lets the canvas mount under jsdom; call before rendering it */
+export const TEST__installCanvasDomStubs = (): void => {
+  if (!('IntersectionObserver' in window)) {
+    Object.defineProperty(window, 'IntersectionObserver', {
+      configurable: true,
+      writable: true,
+      value: TEST__IntersectionObserver,
+    });
+  }
+};
+
+/**
+ * Renders an element inside a Legend application, as a host would, and waits
+ * for the element with the given test id: the framework renders nothing until
+ * the application store has initialized
+ */
+export const TEST__renderInCubeApplication = async (
+  element: React.ReactNode,
+  applicationStore: GenericLegendApplicationStore,
+  readyTestId: string,
+): Promise<RenderResult> => {
+  TEST__installCanvasDomStubs();
+  const renderResult = render(
+    <ApplicationStoreProvider store={applicationStore}>
+      <TEST__BrowserEnvironmentProvider initialEntries={['/']}>
+        <ApplicationFrameworkProvider>{element}</ApplicationFrameworkProvider>
+      </TEST__BrowserEnvironmentProvider>
+    </ApplicationStoreProvider>,
+  );
+  await waitFor(() => renderResult.getByTestId(readyTestId));
+  return renderResult;
+};
+
+/**
+ * Imports a cube into a rendered page, as Import does, and waits for its
+ * tables to be typed again, so nothing changes after the test has ended
+ */
+export const TEST__importDocument = async (
+  editorState: CubeEditorState,
+  document: CubeDocument,
+  readOnly = false,
+): Promise<void> => {
+  act(() => editorState.importDocument(document, readOnly));
+  await waitFor(() => {
+    if (editorState.isResolvingSources) {
+      throw new Error('The imported tables are still being typed');
+    }
+  });
+};

package/src/__test-utils__/CubeTestApplication.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 {
+  ApplicationStore,
+  type GenericLegendApplicationStore,
+  LegendApplicationConfig,
+  type LegendApplicationPlugin,
+  LegendApplicationPluginManager,
+} from '@finos/legend-application';
+import { TEST__getApplicationVersionData } from '@finos/legend-application/test';
+import type { CubeHost } from '../stores/CubeHost.js';
+import { LocalModelCatalog } from '../stores/LocalModelCatalog.js';
+import {
+  createFakeCubeEngine,
+  type FakeCubeEngine,
+  type FakeCubeEngineAnswers,
+} from './FakeCubeEngine.js';
+
+// A bare Legend application for Cube's jsdom tests, as the data-space viewer's
+// tests build theirs: the builder may not use the query builder's test helpers
+
+export class TEST__LegendCubePluginManager extends LegendApplicationPluginManager<LegendApplicationPlugin> {
+  private constructor() {
+    super();
+  }
+
+  static create(): TEST__LegendCubePluginManager {
+    return new TEST__LegendCubePluginManager();
+  }
+}
+
+class TEST__LegendCubeApplicationConfig extends LegendApplicationConfig {
+  override getDefaultApplicationStorageKey(): string {
+    return 'test';
+  }
+}
+
+/** A fresh application store: build one per test, since it initializes once */
+export const TEST__createCubeApplicationStore = (
+  plugins: LegendApplicationPlugin[] = [],
+): GenericLegendApplicationStore => {
+  const pluginManager = TEST__LegendCubePluginManager.create();
+  pluginManager.usePlugins(plugins).install();
+  return new ApplicationStore(
+    new TEST__LegendCubeApplicationConfig({
+      configData: { env: 'TEST', appName: 'TEST' },
+      versionData: TEST__getApplicationVersionData(),
+      baseAddress: '/',
+    }),
+    pluginManager,
+  );
+};
+
+/** A host over a fake engine, with the bundled models */
+export const TEST__createCubeHost = (
+  answers?: FakeCubeEngineAnswers,
+  applicationStore = TEST__createCubeApplicationStore(),
+): { host: CubeHost; fake: FakeCubeEngine } => {
+  const fake = createFakeCubeEngine(answers);
+  return {
+    host: {
+      applicationStore,
+      engine: fake.engine,
+      modelCatalog: new LocalModelCatalog(fake.engine),
+    },
+    fake,
+  };
+};

package/src/__test-utils__/FakeCubeEngine.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 { jest } from '@jest/globals';
+import { Schema } from '@finos/legend-cube';
+import {
+  type CubeEngine,
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeModelOutline,
+  type CubeResult,
+} from '../graph-manager/CubeEngine.js';
+import {
+  CUSTOMERS_COLUMNS,
+  NORTHWIND_DATABASE,
+  NORTHWIND_RUNTIME,
+  ORDERS_COLUMNS,
+} from './CubeNorthwindTestQueries.js';
+
+// A CubeEngine for jsdom tests (PLAN §11.1 M1.8a): canned answers, no network.
+// Each method is a jest.fn, kept in its own variable so tests can read its
+// calls or change its answer.
+
+/** Northwind as the fake knows it: two tables, one runtime keyed by the database */
+export const FAKE_NORTHWIND_OUTLINE: CubeModelOutline = {
+  databases: [
+    {
+      path: NORTHWIND_DATABASE,
+      schemas: [
+        {
+          name: 'NORTHWIND',
+          tables: [
+            {
+              name: 'ORDERS',
+              isView: false,
+              columnCount: ORDERS_COLUMNS.length,
+              flags: [],
+              untypedColumns: [],
+            },
+            {
+              name: 'CUSTOMERS',
+              isView: false,
+              columnCount: CUSTOMERS_COLUMNS.length,
+              flags: [],
+              untypedColumns: [],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  runtimes: [{ path: NORTHWIND_RUNTIME, storePaths: [NORTHWIND_DATABASE] }],
+};
+
+/** The schemas the fake gives, keyed by `<schema>.<table>` as the outline names them */
+export const FAKE_NORTHWIND_SCHEMAS: ReadonlyMap<string, Schema> = new Map([
+  ['NORTHWIND.ORDERS', new Schema(ORDERS_COLUMNS)],
+  ['NORTHWIND.CUSTOMERS', new Schema(CUSTOMERS_COLUMNS)],
+]);
+
+export const EMPTY_CUBE_RESULT: CubeResult = {
+  columns: [],
+  rows: [],
+  sql: [],
+  durationMs: 0,
+};
+
+export interface FakeCubeEngineAnswers {
+  readonly outline?: CubeModelOutline;
+  /** keyed by `<schema>.<table>`; a table not in it gets a compile error */
+  readonly schemas?: ReadonlyMap<string, Schema>;
+  readonly result?: CubeResult;
+  readonly pure?: string;
+}
+
+export interface FakeCubeEngine {
+  readonly engine: CubeEngine;
+  readonly loadModel: jest.Mock<CubeEngine['loadModel']>;
+  readonly resolveSchemas: jest.Mock<CubeEngine['resolveSchemas']>;
+  readonly typeLambdas: jest.Mock<CubeEngine['typeLambdas']>;
+  readonly execute: jest.Mock<CubeEngine['execute']>;
+  readonly renderPure: jest.Mock<CubeEngine['renderPure']>;
+}
+
+/** A fresh fake: build one per test, since jest.fn keeps its calls across tests */
+export const createFakeCubeEngine = (
+  answers: FakeCubeEngineAnswers = {},
+): FakeCubeEngine => {
+  const schemas = answers.schemas ?? FAKE_NORTHWIND_SCHEMAS;
+  const loadModel = jest.fn<CubeEngine['loadModel']>(async () =>
+    Promise.resolve(answers.outline ?? FAKE_NORTHWIND_OUTLINE),
+  );
+  const resolveSchemas = jest.fn<CubeEngine['resolveSchemas']>(
+    async (_model, accessors) =>
+      Promise.resolve(
+        new Map(
+          [...accessors].map(([nodeId, [, schema, table]]) => [
+            nodeId,
+            schemas.get(`${schema}.${table}`) ??
+              new CubeEngineError(
+                CubeEngineErrorKind.COMPILE,
+                `The table "${schema}.${table}" can't be found`,
+                nodeId,
+              ),
+          ]),
+        ),
+      ),
+  );
+  const typeLambdas = jest.fn<CubeEngine['typeLambdas']>(async () =>
+    Promise.resolve(new Map()),
+  );
+  const execute = jest.fn<CubeEngine['execute']>(async () =>
+    Promise.resolve(answers.result ?? EMPTY_CUBE_RESULT),
+  );
+  const renderPure = jest.fn<CubeEngine['renderPure']>(async () =>
+    Promise.resolve(answers.pure ?? ''),
+  );
+  return {
+    engine: { loadModel, resolveSchemas, typeLambdas, execute, renderPure },
+    loadModel,
+    resolveSchemas,
+    typeLambdas,
+    execute,
+    renderPure,
+  };
+};

package/src/components/CubeButton.tsx

@@ -0,0 +1,35 @@
+/**
+ * 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 { clsx } from '@finos/legend-art';
+
+/** A small text button in the page's toolbars and lists, coloured by the theme's tokens */
+export const CubeButton: React.FC<
+  React.ButtonHTMLAttributes<HTMLButtonElement> & { primary?: boolean }
+> = ({ className, primary, ...props }) => (
+  <button
+    {...props}
+    // these buttons never submit a form
+    type="button"
+    className={clsx(
+      'h-6 shrink-0 rounded-sm border px-2 text-base enabled:cursor-pointer disabled:cursor-not-allowed disabled:text-[var(--color-text-disabled)]',
+      primary
+        ? 'border-[var(--color-accent)] bg-[var(--color-accent)] text-[var(--color-text-on-accent)] enabled:hover:bg-[var(--color-accent-hover)] disabled:border-[var(--color-border-default)] disabled:bg-[var(--color-bg-panel-header)]'
+        : 'border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] text-[var(--color-text-primary)] enabled:hover:bg-[var(--color-bg-hover)]',
+      className,
+    )}
+  />
+);