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

package/src/graph-manager/protocol/pure/v1/V1_CubeLambdaSerializer.ts

@@ -0,0 +1,257 @@
+/**
+ * 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 { IR, LiteralValue, Origin } from '@finos/legend-cube';
+import { parseLosslessJSON, type PlainObject } from '@finos/legend-shared';
+
+// Cube IR → V1 protocol lambda JSON (PLAN §8.3, §8.5), built as plain JSON,
+// never through legend-graph's value-specification classes, whose serializer
+// drops `sourceInformation`. Numbers are lossless number values, so the
+// request body must be written with `stringifyLosslessJSON`.
+
+/** The prefix of the source ids Cube stamps, `cube:<nodeId>:<role>` */
+export const V1_CUBE_SOURCE_ID_PREFIX = 'cube:';
+
+/** A JSON number token: what an integer, float or decimal literal must be */
+const NUMBER_TOKEN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u;
+
+/** The source id of an origin */
+export const V1_buildCubeSourceId = (origin: Origin): string =>
+  `${V1_CUBE_SOURCE_ID_PREFIX}${origin.nodeId}:${origin.role}`;
+
+/**
+ * The origin a source id names, or none when Cube didn't stamp it. A role
+ * never contains `:`, so a node id that does still reads back whole.
+ */
+export const V1_parseCubeSourceId = (
+  sourceId: string | undefined,
+): Origin | undefined => {
+  if (!sourceId?.startsWith(V1_CUBE_SOURCE_ID_PREFIX)) {
+    return undefined;
+  }
+  const rest = sourceId.slice(V1_CUBE_SOURCE_ID_PREFIX.length);
+  const at = rest.lastIndexOf(':');
+  if (at <= 0 || at === rest.length - 1) {
+    return undefined;
+  }
+  return { nodeId: rest.slice(0, at), role: rest.slice(at + 1) };
+};
+
+const stamped = (json: PlainObject, origin: Origin | undefined): PlainObject =>
+  origin
+    ? {
+        ...json,
+        sourceInformation: { sourceId: V1_buildCubeSourceId(origin) },
+      }
+    : json;
+
+/** A lossless JSON number for a numeric literal's text, written digit for digit */
+const numberToken = (text: string): unknown => {
+  if (!NUMBER_TOKEN.test(text)) {
+    throw new Error(`"${text}" is not a number Cube can send`);
+  }
+  return parseLosslessJSON(text);
+};
+
+const serializeLiteral = (value: LiteralValue): PlainObject => {
+  switch (value.kind) {
+    case 'string':
+    case 'boolean':
+    case 'strictDate':
+    case 'dateTime':
+      return { _type: value.kind, value: value.value };
+    case 'integer':
+    case 'float':
+    case 'decimal':
+      return { _type: value.kind, value: numberToken(value.value) };
+    case 'enum':
+      // enumeration values are emitted as `enumValue`, with their enumeration
+      throw new Error(
+        `Can't send the enumeration value "${value.value}" as a literal`,
+      );
+    default: {
+      const unknown: never = value;
+      throw new Error(`Unknown literal ${JSON.stringify(unknown)}`);
+    }
+  }
+};
+
+/**
+ * The protocol JSON of an IR node. Every protocol node is stamped with the
+ * origin of its IR node, or else of its nearest ancestor that has one.
+ */
+const serialize = (ir: IR, inherited: Origin | undefined): PlainObject => {
+  switch (ir.k) {
+    case 'func': {
+      const origin = ir.origin ?? inherited;
+      return stamped(
+        {
+          _type: 'func',
+          function: ir.name,
+          parameters: ir.params.map((param) => serialize(param, origin)),
+        },
+        origin,
+      );
+    }
+    case 'property': {
+      const origin = ir.origin ?? inherited;
+      return stamped(
+        {
+          _type: 'property',
+          property: ir.name,
+          parameters: [serialize(ir.receiver, origin)],
+        },
+        origin,
+      );
+    }
+    case 'var':
+      return stamped({ _type: 'var', name: ir.name }, inherited);
+    case 'lambda':
+      return stamped(
+        {
+          _type: 'lambda',
+          parameters: ir.params.map((name) =>
+            stamped({ _type: 'var', name }, inherited),
+          ),
+          body: ir.body.map((statement) => serialize(statement, inherited)),
+        },
+        inherited,
+      );
+    case 'literal':
+      return stamped(serializeLiteral(ir.value), ir.origin ?? inherited);
+    case 'collection':
+      return stamped(
+        {
+          _type: 'collection',
+          multiplicity: {
+            lowerBound: ir.values.length,
+            upperBound: ir.values.length,
+          },
+          values: ir.values.map((value) => serialize(value, inherited)),
+        },
+        inherited,
+      );
+    case 'colSpec':
+      // the engine reports a missing column on the spec's value, which is
+      // also what a column list holds, so the value is stamped too
+      return stamped(
+        {
+          _type: 'classInstance',
+          type: 'colSpec',
+          value: stamped(
+            {
+              name: ir.name,
+              ...(ir.fn1 ? { function1: serialize(ir.fn1, inherited) } : {}),
+              ...(ir.fn2 ? { function2: serialize(ir.fn2, inherited) } : {}),
+            },
+            inherited,
+          ),
+        },
+        inherited,
+      );
+    case 'colSpecArray':
+      return stamped(
+        {
+          _type: 'classInstance',
+          type: 'colSpecArray',
+          value: {
+            colSpecs: ir.specs.map((spec) => {
+              if (spec.k !== 'colSpec') {
+                throw new Error(
+                  `A column list holds only column specs, not "${spec.k}"`,
+                );
+              }
+              return (serialize(spec, inherited) as { value: PlainObject })
+                .value;
+            }),
+          },
+        },
+        inherited,
+      );
+    case 'storeAccessor': {
+      const origin = ir.origin ?? inherited;
+      // the engine reports a wrong database, schema or table on the value
+      return stamped(
+        {
+          _type: 'classInstance',
+          type: '>',
+          value: stamped({ path: [...ir.path] }, origin),
+        },
+        origin,
+      );
+    }
+    case 'elementPtr':
+      return stamped(
+        { _type: 'packageableElementPtr', fullPath: ir.path },
+        inherited,
+      );
+    case 'genericType':
+      return stamped(
+        {
+          _type: 'genericTypeInstance',
+          genericType: {
+            rawType: { _type: 'packageableType', fullPath: ir.path },
+            typeArguments: [],
+            multiplicityArguments: [],
+            typeVariableValues: (ir.params ?? []).map((param) =>
+              stamped(
+                { _type: 'integer', value: numberToken(String(param)) },
+                inherited,
+              ),
+            ),
+          },
+        },
+        inherited,
+      );
+    case 'enumValue': {
+      const origin = ir.origin ?? inherited;
+      return stamped(
+        {
+          _type: 'property',
+          property: ir.value,
+          parameters: [
+            stamped(
+              { _type: 'packageableElementPtr', fullPath: ir.enumPath },
+              origin,
+            ),
+          ],
+        },
+        origin,
+      );
+    }
+    case 'let':
+    case 'block':
+      // window isolation (PLAN §8.6) comes with Partition, in M5
+      throw new Error(`Can't send "${ir.k}" yet`);
+    case 'raw':
+      return ir.json as PlainObject;
+    default: {
+      const unknown: never = ir;
+      throw new Error(`Unknown IR ${JSON.stringify(unknown)}`);
+    }
+  }
+};
+
+/**
+ * The protocol JSON of a lambda Cube emitted (a typing or an execution
+ * lambda), with lossless numbers: write it with `stringifyLosslessJSON`.
+ */
+export const V1_serializeCubeLambda = (ir: IR): PlainObject => {
+  if (ir.k !== 'lambda') {
+    throw new Error(`Only a lambda can be sent, not "${ir.k}"`);
+  }
+  return serialize(ir, undefined);
+};

package/src/graph-manager/protocol/pure/v1/V1_CubeModelOutlineBuilder.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 { getRelationalDisplayName } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
+import {
+  CubeTableFlag,
+  type CubeModelOutline,
+  type CubeOutlineConnection,
+  type CubeOutlineDatabase,
+  type CubeOutlineRuntime,
+  type CubeOutlineSchema,
+  type CubeOutlineTable,
+} from '../../../CubeEngine.js';
+
+// The databases and runtimes of a parsed model (`{_type: 'data', elements}`),
+// for the source picker (PLAN §6.2.3-§6.2.6). Read as plain JSON: only names,
+// column types and store paths are needed, and an element's full protocol
+// deserializer needs the graph manager's plugins.
+
+const DATABASE_TYPE = 'relational';
+const RUNTIME_TYPE = 'runtime';
+const CONNECTION_TYPE = 'connection';
+const CONNECTION_POINTER_TYPE = 'connectionPointer';
+const RELATIONAL_CONNECTION_TYPE = 'RelationalDatabaseConnection';
+/** The only runtime value whose store keys Cube can read; others are hidden */
+const ENGINE_RUNTIME_TYPE = 'engineRuntime';
+
+/** The flag a column type gives its table, if any (PLAN §6.2.6) */
+const COLUMN_TYPE_FLAGS: Record<string, CubeTableFlag> = {
+  // the engine fails to type the whole table
+  Binary: CubeTableFlag.UNAVAILABLE,
+  Varbinary: CubeTableFlag.UNAVAILABLE,
+  // typed with a length of 1
+  Char: CubeTableFlag.LENGTH_UNKNOWN,
+  // an ARRAY column is parsed as Other; both are typed as a bare String
+  Other: CubeTableFlag.TYPE_UNKNOWN,
+};
+
+const asObject = (value: unknown): PlainObject =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as PlainObject)
+    : {};
+
+const asList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value : [];
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined;
+
+const elementPath = (element: PlainObject): string => {
+  const name = asString(element.name) ?? '';
+  const pkg = asString(element.package);
+  return pkg ? `${pkg}::${name}` : name;
+};
+
+const buildTable = (json: unknown): CubeOutlineTable => {
+  const table = asObject(json);
+  const columns = asList(table.columns).map(asObject);
+  const flags = new Set<CubeTableFlag>();
+  const untypedColumns: string[] = [];
+  columns.forEach((column) => {
+    const flag = COLUMN_TYPE_FLAGS[asString(asObject(column.type)._type) ?? ''];
+    if (flag) {
+      flags.add(flag);
+    }
+    if (flag === CubeTableFlag.TYPE_UNKNOWN) {
+      // unquoted, as the engine names the column in the table's schema
+      untypedColumns.push(
+        getRelationalDisplayName(asString(column.name) ?? ''),
+      );
+    }
+  });
+  return {
+    name: asString(table.name) ?? '',
+    isView: false,
+    columnCount: columns.length,
+    flags: Object.values(CubeTableFlag).filter((flag) => flags.has(flag)),
+    untypedColumns,
+  };
+};
+
+const buildView = (json: unknown): CubeOutlineTable => {
+  const view = asObject(json);
+  return {
+    name: asString(view.name) ?? '',
+    isView: true,
+    columnCount: asList(view.columnMappings).length,
+    flags: [],
+    untypedColumns: [],
+  };
+};
+
+const buildSchema = (json: unknown): CubeOutlineSchema => {
+  const schema = asObject(json);
+  return {
+    name: asString(schema.name) ?? '',
+    tables: [
+      ...asList(schema.tables).map(buildTable),
+      ...asList(schema.views).map(buildView),
+    ],
+  };
+};
+
+const buildDatabase = (element: PlainObject): CubeOutlineDatabase => ({
+  path: elementPath(element),
+  // included stores are not followed (v1)
+  schemas: asList(element.schemas).map(buildSchema),
+});
+
+/** The database type of a relational connection value: its `type`, else its `databaseType` */
+const getRelationalDatabaseType = (value: PlainObject): string | undefined =>
+  value._type === RELATIONAL_CONNECTION_TYPE
+    ? (asString(value.type) ?? asString(value.databaseType))
+    : undefined;
+
+/**
+ * The database type of a runtime's connection, embedded or a pointer to a
+ * connection element (`connectionTypes`, by path); none for one that isn't
+ * relational
+ */
+const getConnectionDatabaseType = (
+  json: unknown,
+  connectionTypes: ReadonlyMap<string, string>,
+): string | undefined => {
+  const connection = asObject(json);
+  if (connection._type === CONNECTION_POINTER_TYPE) {
+    const path = asString(connection.connection);
+    return path === undefined ? undefined : connectionTypes.get(path);
+  }
+  return getRelationalDatabaseType(connection);
+};
+
+/** The stores a runtime's connections are keyed by, in both syntaxes; none when it can't be read */
+const buildRuntime = (
+  element: PlainObject,
+  connectionTypes: ReadonlyMap<string, string>,
+): CubeOutlineRuntime | undefined => {
+  const value = asObject(element.runtimeValue);
+  if (value._type !== ENGINE_RUNTIME_TYPE) {
+    return undefined;
+  }
+  const storePaths = [
+    // `connections: [<store>: [...]]`
+    ...asList(value.connections).map((connection) =>
+      asString(asObject(asObject(connection).store).path),
+    ),
+    // `connectionStores: [<connection>: [<store>, ...]]`
+    ...asList(value.connectionStores).flatMap((connectionStore) =>
+      asList(asObject(connectionStore).storePointers).map((pointer) =>
+        asString(asObject(pointer).path),
+      ),
+    ),
+  ].filter((path): path is string => path !== undefined);
+  const connections: CubeOutlineConnection[] = [];
+  const addConnection = (
+    storePath: string | undefined,
+    databaseType: string | undefined,
+  ): void => {
+    if (
+      storePath !== undefined &&
+      databaseType !== undefined &&
+      !connections.some(
+        (connection) =>
+          connection.storePath === storePath &&
+          connection.databaseType === databaseType,
+      )
+    ) {
+      connections.push({ storePath, databaseType });
+    }
+  };
+  asList(value.connections).forEach((json) => {
+    const storeConnections = asObject(json);
+    const storePath = asString(asObject(storeConnections.store).path);
+    asList(storeConnections.storeConnections).forEach((identified) =>
+      addConnection(
+        storePath,
+        getConnectionDatabaseType(
+          asObject(identified).connection,
+          connectionTypes,
+        ),
+      ),
+    );
+  });
+  asList(value.connectionStores).forEach((json) => {
+    const connectionStore = asObject(json);
+    const databaseType = getConnectionDatabaseType(
+      connectionStore.connectionPointer,
+      connectionTypes,
+    );
+    asList(connectionStore.storePointers).forEach((pointer) =>
+      addConnection(asString(asObject(pointer).path), databaseType),
+    );
+  });
+  return {
+    path: elementPath(element),
+    storePaths: [...new Set(storePaths)],
+    connections,
+  };
+};
+
+/** The outline of a parsed model: its Database elements and its readable runtimes, in model order */
+export const V1_buildCubeModelOutline = (
+  modelData: PlainObject,
+): CubeModelOutline => {
+  const elements = asList(modelData.elements).map(asObject);
+  // the database type of each relational connection element, by path
+  const connectionTypes = new Map<string, string>();
+  elements
+    .filter((element) => element._type === CONNECTION_TYPE)
+    .forEach((element) => {
+      const databaseType = getRelationalDatabaseType(
+        asObject(element.connectionValue),
+      );
+      if (databaseType !== undefined) {
+        connectionTypes.set(elementPath(element), databaseType);
+      }
+    });
+  return {
+    databases: elements
+      .filter((element) => element._type === DATABASE_TYPE)
+      .map(buildDatabase),
+    runtimes: elements
+      .filter((element) => element._type === RUNTIME_TYPE)
+      .map((element) => buildRuntime(element, connectionTypes))
+      .filter(
+        (runtime): runtime is CubeOutlineRuntime => runtime !== undefined,
+      ),
+  };
+};

package/src/graph-manager/protocol/pure/v1/V1_CubeRelationTypeAdapter.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 {
+  V1_CInteger,
+  V1_PackageableType,
+  V1_relationTypeModelSchema,
+} from '@finos/legend-graph';
+import type { PlainObject } from '@finos/legend-shared';
+import { deserialize } from 'serializr';
+
+// The engine's relation type → a Cube schema (PLAN §6.2.6), read through
+// legend-graph's protocol schema. Its graph-manager wrappers are bypassed:
+// they drop type parameters (D8).
+
+/**
+ * The schema of a relation type: one column per relation column, in order,
+ * typed by its path and parameters (an unknown type is opaque) and nullable
+ * when it may be empty
+ */
+export const V1_buildCubeSchema = (json: PlainObject): Schema => {
+  const relationType = deserialize(V1_relationTypeModelSchema, json);
+  return new Schema(
+    relationType.columns.map((column) => {
+      const { rawType, typeVariableValues } = column.genericType;
+      if (!(rawType instanceof V1_PackageableType)) {
+        throw new Error(`Column "${column.name}" has a type Cube can't read`);
+      }
+      const params = typeVariableValues.map((value) => {
+        if (!(value instanceof V1_CInteger)) {
+          throw new Error(
+            `Column "${column.name}" has a type parameter Cube can't read`,
+          );
+        }
+        return value.value;
+      });
+      return new SchemaColumn(
+        column.name,
+        resolveCubeType(rawType.fullPath, params),
+        column.multiplicity.lowerBound === 0,
+      );
+    }),
+  );
+};