@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/__test-utils__/CubeDirectConnectionFixtures.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 { PlainObject } from '@finos/legend-shared';
+
+// Connections to small, self-contained test databases, as the protocol JSON a
+// direct-connection cube saves (PLAN §6.8). Each setup first drops what it
+// creates, because the engine keeps an H2 server and a DuckDB connection
+// between calls, and uses its own schema, so tests can share an engine
+
+export const DIRECT_H2_SCHEMA = 'CUBE_DIRECT';
+export const DIRECT_DUCKDB_SCHEMA = 'cube_direct';
+
+/**
+ * An H2 database the engine creates in its own H2 server, in the schema given:
+ * each test file uses its own, as files run at once against one engine
+ */
+export const directH2Connection = (schema: string): PlainObject => ({
+  _type: 'RelationalDatabaseConnection',
+  type: 'H2',
+  databaseType: 'H2',
+  datasourceSpecification: {
+    _type: 'h2Local',
+    testDataSetupSqls: [
+      `drop schema if exists ${schema} cascade`,
+      `create schema ${schema}`,
+      `create table ${schema}.ORDERS (ORDER_ID INT PRIMARY KEY, CUSTOMER_ID VARCHAR(5) NOT NULL, AMOUNT DECIMAL(10,2))`,
+      `insert into ${schema}.ORDERS values (1, 'ALFKI', 12.34), (2, 'ANATR', 5.00)`,
+    ],
+  },
+  authenticationStrategy: { _type: 'h2Default' },
+});
+
+/**
+ * An in-memory DuckDB database (an empty path), so no file is read or
+ * written, in the schema given
+ */
+export const directDuckDBConnection = (schema: string): PlainObject => ({
+  _type: 'RelationalDatabaseConnection',
+  type: 'DuckDB',
+  databaseType: 'DuckDB',
+  datasourceSpecification: {
+    _type: 'duckDB',
+    path: '',
+    testDataSetupSqls: [
+      `drop schema if exists ${schema} cascade`,
+      `create schema ${schema}`,
+      `create table ${schema}.orders (order_id INTEGER PRIMARY KEY, customer_id VARCHAR(5) NOT NULL, amount DECIMAL(10,2))`,
+      `insert into ${schema}.orders values (1, 'ALFKI', 12.34), (2, 'ANATR', 5.00)`,
+    ],
+  },
+  authenticationStrategy: { _type: 'test' },
+});
+
+export const DIRECT_H2_CONNECTION = directH2Connection(DIRECT_H2_SCHEMA);
+export const DIRECT_DUCKDB_CONNECTION =
+  directDuckDBConnection(DIRECT_DUCKDB_SCHEMA);

package/src/__test-utils__/CubeEngineTestSupport.ts

@@ -117,13 +117,14 @@ export const CUBE_ENGINE_TEST__jsonToGrammar_lambda = async (
  */
 export const CUBE_ENGINE_TEST__execute = async (
   input: object | string,
+  serializationFormat = 'DEFAULT',
 ): Promise<{ ok: boolean; status: number; text: () => Promise<string> }> => {
   const response = await axios.post<unknown, AxiosResponse<string>>(
     `${PURE_API}/execution/execute`,
     input,
     {
       headers: JSON_HEADERS,
-      params: { serializationFormat: 'DEFAULT' },
+      params: { serializationFormat },
       responseType: 'text',
       transformResponse: (data: string) => data,
       validateStatus: () => true,
@@ -170,3 +171,41 @@ export const CUBE_ENGINE_TEST__generatePlanSql = async (
   visit(parseLosslessJSON(data));
   return sql;
 };
+/**
+ * The protocol JSON of a value specification's text, parsed with its source
+ * information under the source id, given as the client's unread response
+ * (an Extend column's expression, PLAN §11.7), so it is read losslessly
+ */
+export const CUBE_ENGINE_TEST__grammarToJson_valueSpecification = async (
+  code: string,
+  sourceId: string,
+): Promise<{ ok: boolean; status: number; text: () => Promise<string> }> => {
+  const response = await axios.post<unknown, AxiosResponse<string>>(
+    `${PURE_API}/grammar/grammarToJson/valueSpecification`,
+    code,
+    {
+      headers: { [HttpHeader.CONTENT_TYPE]: ContentType.TEXT_PLAIN },
+      params: { sourceId, returnSourceInformation: true },
+      responseType: 'text',
+      transformResponse: (data: string) => data,
+      validateStatus: () => true,
+    },
+  );
+  return {
+    ok: response.status >= 200 && response.status < 300,
+    status: response.status,
+    text: async () => response.data,
+  };
+};
+
+/** Generates the execution plan of a query, never running it; a body given as text is sent as it is */
+export const CUBE_ENGINE_TEST__generatePlan = async (
+  input: object | string,
+): Promise<PlainObject> =>
+  (
+    await axios.post<unknown, AxiosResponse<PlainObject>>(
+      `${PURE_API}/execution/generatePlan`,
+      input,
+      { headers: JSON_HEADERS },
+    )
+  ).data;

package/src/__test-utils__/CubeExpressionTestUtils.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 {
+  buildSchemasAndValidity,
+  ExpressionFilter,
+  Extend,
+  getExpressionFilterSignature,
+  getExtendSignature,
+  type JsonObject,
+  PrimitiveType,
+  type Query,
+} from '@finos/legend-cube';
+
+// Extend columns and filter conditions for tests (PLAN §11.7, §11.11),
+// written as the engine's JSON, as a node stores it: number literals as their
+// digits
+
+/** `x | <body>` and the pieces of a body */
+export const TEST__expression = {
+  lambda: (body: JsonObject): JsonObject => ({
+    _type: 'lambda',
+    parameters: [{ _type: 'var', name: 'x' }],
+    body: [body],
+  }),
+  /** `$x.<name>` */
+  column: (name: string): JsonObject => ({
+    _type: 'property',
+    property: name,
+    parameters: [{ _type: 'var', name: 'x' }],
+  }),
+  call: (name: string, ...parameters: JsonObject[]): JsonObject => ({
+    _type: 'func',
+    function: name,
+    parameters,
+  }),
+  /** The two operands of `+`, `*`, … */
+  pair: (first: JsonObject, second: JsonObject): JsonObject => ({
+    _type: 'collection',
+    multiplicity: { lowerBound: 2, upperBound: 2 },
+    values: [first, second],
+  }),
+  integer: (value: number): JsonObject => ({
+    _type: 'integer',
+    value: String(value),
+  }),
+  string: (value: string): JsonObject => ({ _type: 'string', value }),
+};
+
+/** A new column: its name, its lambda, and the type the engine gives it */
+export type TEST__ExtendColumn = readonly [string, JsonObject, string];
+
+/**
+ * An Extend of these columns, typed as given for the input Cube infers for
+ * `input`'s selected node, so it is valid without the engine; the engine
+ * tests check the types are the engine's. With an invalid input, untyped.
+ */
+export const TEST__typedExtend = (
+  id: string,
+  input: Query,
+  columns: readonly TEST__ExtendColumn[],
+): Extend => {
+  const schema = buildSchemasAndValidity(input).schemas.get(
+    input.selected ?? '',
+  );
+  const extendColumns = columns.map(([name, lambda]) => ({
+    name,
+    code: name,
+    lambda,
+  }));
+  // an invalid input, e.g. a table not resolved yet: nothing to type it for
+  if (!schema) {
+    return new Extend(id, extendColumns);
+  }
+  return new Extend(id, extendColumns, {
+    kind: 'typed',
+    signature: getExtendSignature(schema, extendColumns),
+    types: columns.map(([, , type]) => PrimitiveType.get(type)),
+  });
+};
+
+/**
+ * A Filter by Expression of this condition, checked for the input Cube infers
+ * for `input`'s selected node, so it is valid without the engine; the engine
+ * tests check the engine takes it. With an invalid input, not checked.
+ */
+export const TEST__checkedExpressionFilter = (
+  id: string,
+  input: Query,
+  code: string,
+  lambda: JsonObject,
+): ExpressionFilter => {
+  const filter = new ExpressionFilter(id, code, lambda);
+  const schema = buildSchemasAndValidity(input).schemas.get(
+    input.selected ?? '',
+  );
+  return schema
+    ? filter.withCheck({
+        kind: 'checked',
+        signature: getExpressionFilterSignature(schema, lambda),
+      })
+    : filter;
+};
+
+/** `a: x | $x.ORDER_ID + 1` and `b: x | $x.a * 2`, the second using the first, both Integer */
+export const TEST__ORDER_ID_EXTEND_COLUMNS: readonly TEST__ExtendColumn[] = [
+  [
+    'a',
+    TEST__expression.lambda(
+      TEST__expression.call(
+        'plus',
+        TEST__expression.pair(
+          TEST__expression.column('ORDER_ID'),
+          TEST__expression.integer(1),
+        ),
+      ),
+    ),
+    'Integer',
+  ],
+  [
+    'b',
+    TEST__expression.lambda(
+      TEST__expression.call(
+        'times',
+        TEST__expression.pair(
+          TEST__expression.column('a'),
+          TEST__expression.integer(2),
+        ),
+      ),
+    ),
+    'Integer',
+  ],
+];

package/src/__test-utils__/CubeFunctionTestOutline.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { resolveCubeType, Schema, SchemaColumn } from '@finos/legend-cube';
+import type {
+  CubeModelOutline,
+  CubeOutlineFunction,
+} from '../graph-manager/CubeEngine.js';
+import {
+  NORTHWIND_DATABASE,
+  NORTHWIND_RUNTIME,
+} from './CubeNorthwindTestQueries.js';
+import { FAKE_NORTHWIND_OUTLINE } from './FakeCubeEngine.js';
+
+// The fake Northwind outline with functions that return a relation (PLAN
+// §6.5), and a second runtime: one function of each kind
+
+export const ARCHIVE_RUNTIME = 'northwind::ArchiveRuntime';
+
+const fn = (
+  name: string,
+  parameters: CubeOutlineFunction['parameters'] = [],
+  extra: Partial<CubeOutlineFunction> = {},
+): CubeOutlineFunction => ({
+  path: `northwind::${name}`,
+  signature: `northwind::${name}__Relation_1_`,
+  parameters,
+  columns: [{ name: 'ORDER_ID', type: 'Integer' }],
+  ...extra,
+});
+
+export const ALL_ORDERS = fn('allOrders');
+export const ORDERS_ABOVE = fn('ordersAbove', [
+  { name: 'min', type: 'Float', multiplicity: '[1]' },
+  { name: 'status', type: 'String', multiplicity: '[0..1]' },
+]);
+export const SHIPPED = fn('shipped', [], { runtime: NORTHWIND_RUNTIME });
+export const ARCHIVED = fn('archived', [], { runtime: ARCHIVE_RUNTIME });
+export const ORDERS_OF = fn(
+  'ordersOf',
+  [{ name: 'ids', type: 'Integer', multiplicity: '[*]' }],
+  {
+    problem:
+      'Its parameter "ids" takes [*] values; Cube takes one value, or none',
+  },
+);
+
+export const FUNCTIONS_OUTLINE: CubeModelOutline = {
+  ...FAKE_NORTHWIND_OUTLINE,
+  runtimes: [
+    ...FAKE_NORTHWIND_OUTLINE.runtimes,
+    {
+      path: ARCHIVE_RUNTIME,
+      storePaths: [NORTHWIND_DATABASE],
+      connections: [
+        { storePath: NORTHWIND_DATABASE, databaseType: 'Postgres' },
+      ],
+    },
+  ],
+  functions: [ALL_ORDERS, ORDERS_ABOVE, SHIPPED, ARCHIVED, ORDERS_OF],
+};
+
+export const FUNCTION_SCHEMA = new Schema([
+  new SchemaColumn('ORDER_ID', resolveCubeType('Integer'), true),
+]);

package/src/__test-utils__/CubeLambdaCorpus.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 {
+  buildSchemasAndValidity,
+  CubeLambdaReadError,
+  decodeCubeSpec,
+  ExpressionFilter,
+  getExpressionFilterSignature,
+  lambda,
+  QueryEmitter,
+  RelationalTableSource,
+  type CubeDocument,
+  type CubeSourceStep,
+  type IR,
+  type Query,
+} from '@finos/legend-cube';
+import { readdirSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+// The lambdas Cube writes for the core's saved spec samples (PLAN §10.3),
+// for Import Pure's round trips (PLAN §11.18): for each node that can be
+// written, as a matview saves it and as Show Pure shows a run of it
+
+const FIXTURES = resolve(
+  __dirname,
+  '../../../legend-cube/src/spec/__tests__/fixtures',
+);
+
+export interface TEST__CubeLambdaSample {
+  /** `<file>/<node id>` */
+  readonly key: string;
+  readonly document: CubeDocument;
+  readonly nodeId: string;
+  /** The node's relation, as a matview saves it: `{| <relation>}`, written with its rows' order */
+  readonly relation: IR;
+  /** A run of the node with no row limit, as Show Pure shows it: lets, the capture's sort, `from()` */
+  readonly run: IR;
+}
+
+/** Every node of every sample that can be written, by key */
+export const TEST__cubeLambdaSamples = (): TEST__CubeLambdaSample[] =>
+  readdirSync(FIXTURES)
+    .filter((file) => file.endsWith('.cube.json'))
+    .sort()
+    .flatMap((file) => {
+      const { document } = decodeCubeSpec(
+        JSON.parse(readFileSync(join(FIXTURES, file), 'utf-8')),
+      );
+      const runtime = document.context?.runtime;
+      if (runtime === undefined) {
+        return [];
+      }
+      const emitter = new QueryEmitter(document.query);
+      return document.query.nodes
+        .filter((node) => emitter.canEmit(node.id))
+        .map((node) => ({
+          key: `${file}/${node.id}`,
+          document,
+          nodeId: node.id,
+          relation: lambda(
+            [],
+            [emitter.emitRelation(node.id, { withRowOrder: true })],
+          ),
+          run: new QueryEmitter(
+            document.query.selected === node.id
+              ? document.query
+              : document.query.select(node.id),
+          ).emitExecutionLambda({ runtime }),
+        }));
+    });
+
+/** Each table of the lambda bound to the sample's own source of it, with its saved columns */
+export const TEST__bindSampleSources =
+  (document: CubeDocument) =>
+  (source: IR): CubeSourceStep => {
+    const table = document.query.nodes.find(
+      (node): node is RelationalTableSource =>
+        node instanceof RelationalTableSource &&
+        source.k === 'storeAccessor' &&
+        source.path.join('.') ===
+          [node.database, node.schema, node.table].join('.'),
+    );
+    if (!table) {
+      throw new CubeLambdaReadError(`No table for ${JSON.stringify(source)}`);
+    }
+    return {
+      type: RelationalTableSource.TYPE,
+      create: (id) =>
+        new RelationalTableSource(
+          id,
+          {
+            database: table.database,
+            schema: table.schema,
+            table: table.table,
+          },
+          table.resolution,
+        ),
+    };
+  };
+
+/**
+ * The query with each Filter by Expression checked, as the editor has the
+ * engine check them on import: the samples' conditions are all Booleans
+ */
+export const TEST__checkedAsTheEngineWould = (query: Query): Query =>
+  query.nodes.reduce((checked, node) => {
+    if (!(node instanceof ExpressionFilter) || !node.lambda) {
+      return checked;
+    }
+    const [inputId] = checked.getInputIds(node.id);
+    const input =
+      inputId === undefined
+        ? undefined
+        : buildSchemasAndValidity(checked).schemas.get(inputId);
+    return input
+      ? checked.replace(
+          node.withCheck({
+            kind: 'checked',
+            signature: getExpressionFilterSignature(input, node.lambda),
+          }),
+        )
+      : checked;
+  }, query);

package/src/__test-utils__/CubeOperationsTestUtils.ts

@@ -145,6 +145,89 @@ export const TEST__inferredSchema = (
   return schema as Schema;
 };
 
+/** A node of a query to type with the engine, under a key of its own */
+export interface TEST__TypingTarget {
+  key: string;
+  query: Query;
+  nodeId: string;
+}
+
+/**
+ * Every node of the query that can be emitted, keyed `<prefix>/<node id>`, in
+ * the query's node order
+ */
+export const TEST__emittableNodes = (
+  prefix: string,
+  query: Query,
+): TEST__TypingTarget[] => {
+  const emitter = new QueryEmitter(query);
+  return query.nodes
+    .filter((node) => emitter.canEmit(node.id))
+    .map((node) => ({ key: `${prefix}/${node.id}`, query, nodeId: node.id }));
+};
+
+/** The engine's schema of each target, in one engine call */
+export const TEST__engineSchemas = async (
+  engine: CubeEngine,
+  targets: readonly TEST__TypingTarget[],
+): Promise<Map<string, Schema | Error>> =>
+  engine.typeLambdas(
+    CUBE_NORTHWIND_MODEL,
+    new Map(
+      targets.map(({ key, query, nodeId }) => [
+        key,
+        new QueryEmitter(query).emitTypingLambda(nodeId),
+      ]),
+    ),
+  );
+
+/**
+ * How Cube's schema of a node differs from the engine's, one line per
+ * difference: names, positions and types with their parameters must be the
+ * same. Nullability must be the same too, except on the columns in
+ * `widerNullable`, where the engine misreports it (outer-join padding, the
+ * FULL merged key: PLAN §4.7, §11.5) and Cube must say nullable. With
+ * `oneWay`, Cube may be wider on any column.
+ */
+export const TEST__typingDifferences = (
+  key: string,
+  cube: Schema | undefined,
+  engineSchema: Schema | Error | undefined,
+  options: {
+    widerNullable?: readonly string[] | undefined;
+    oneWay?: boolean | undefined;
+  } = {},
+): string[] => {
+  if (!cube) {
+    return [`${key}: Cube infers no schema`];
+  }
+  if (!(engineSchema instanceof Schema)) {
+    return [`${key}: the engine gives no schema (${engineSchema?.message})`];
+  }
+  const describe = (schema: Schema): string[] =>
+    schema.columns.map((column) => `${column.name}: ${column.type.fullName}`);
+  if (describe(cube).join() !== describe(engineSchema).join()) {
+    return [
+      `${key}: columns [${describe(cube).join(', ')}], the engine's [${describe(engineSchema).join(', ')}]`,
+    ];
+  }
+  const wider = new Set(options.widerNullable ?? []);
+  return cube.columns.flatMap((column, index) => {
+    const engineNullable = engineSchema.columns[index]?.nullable === true;
+    if (wider.has(column.name)) {
+      return column.nullable
+        ? []
+        : [`${key}: ${column.name} should be nullable`];
+    }
+    return column.nullable === engineNullable ||
+      (options.oneWay && column.nullable)
+      ? []
+      : [
+          `${key}: ${column.name} is ${column.nullable ? '' : 'not '}nullable, the engine's ${engineNullable ? '' : 'not '}nullable`,
+        ];
+  });
+};
+
 /**
  * The engine types the node as Cube infers it: the same names, in the same
  * order, of the same types and parameters. Cube's nullability may only be
@@ -155,23 +238,15 @@ export const TEST__expectEngineTyping = async (
   query: Query,
   nodeId = query.selected ?? '',
 ): Promise<void> => {
-  const cube = TEST__inferredSchema(query, nodeId);
-  const typed = (
-    await engine.typeLambdas(
-      CUBE_NORTHWIND_MODEL,
-      new Map([[nodeId, new QueryEmitter(query).emitTypingLambda(nodeId)]]),
-    )
-  ).get(nodeId);
-  expect(typed).toBeInstanceOf(Schema);
-  const engineSchema = typed as Schema;
+  const typed = await TEST__engineSchemas(engine, [
+    { key: nodeId, query, nodeId },
+  ]);
   expect(
-    cube.columns.map((column) => [column.name, column.type.fullName]),
-  ).toEqual(
-    engineSchema.columns.map((column) => [column.name, column.type.fullName]),
-  );
-  cube.columns.forEach((column, index) => {
-    if (engineSchema.columns[index]?.nullable) {
-      expect([column.name, column.nullable]).toEqual([column.name, true]);
-    }
-  });
+    TEST__typingDifferences(
+      nodeId,
+      TEST__inferredSchema(query, nodeId),
+      typed.get(nodeId),
+      { oneWay: true },
+    ),
+  ).toEqual([]);
 };