@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/graph-manager/CubeIngestCatalog.ts

@@ -0,0 +1,202 @@
+/**
+ * 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 { Schema } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
+import type { CubeDataProductEnvironmentType } from './CubeDataProduct.js';
+import type { CubeEngineError, NodeId } from './CubeEngine.js';
+
+// The deployed ingest definitions of a host's lakehouse (PLAN §6.7), as Data
+// Cube's producer source lists them: the viewer's ingest environment for a
+// class, its producer deployments, a deployment's SDLC-deployed definitions,
+// and a definition's data sets
+
+/** A data set of a deployed ingest definition, as the definition declares it */
+export class CubeIngestDataSet {
+  readonly name: string;
+  /** Its columns: the declared ones, then the milestoning ones of its write mode; none when they can't be read */
+  readonly schema: Schema | undefined;
+  /** Why it can't be picked, e.g. it is a materialized view; none when it can */
+  readonly disabledReason: string | undefined;
+  readonly primaryKey: readonly string[];
+
+  constructor(fields: {
+    name: string;
+    schema?: Schema | undefined;
+    disabledReason?: string | undefined;
+    primaryKey?: readonly string[];
+  }) {
+    this.name = fields.name;
+    this.schema = fields.schema;
+    this.disabledReason = fields.disabledReason;
+    this.primaryKey = fields.primaryKey ?? [];
+  }
+
+  get isPickable(): boolean {
+    return this.disabledReason === undefined && this.schema !== undefined;
+  }
+}
+
+/** The viewer's ingest environment for a class: shown in the Ingest tab, never saved */
+export class CubeIngestEnvironment {
+  readonly environmentType: CubeDataProductEnvironmentType;
+  /** The environment's name, as the platform lists it */
+  readonly name: string;
+  /** The environment a run's lakehouse runtime names */
+  readonly runtimeEnvironment: string;
+  /**
+   * The warehouse a new cube starts with, when the environment has one, e.g.
+   * the runtime of a Studio project; else the one the viewer last picked
+   */
+  readonly warehouse: string | undefined;
+
+  constructor(fields: {
+    environmentType: CubeDataProductEnvironmentType;
+    name: string;
+    runtimeEnvironment: string;
+    warehouse?: string | undefined;
+  }) {
+    this.environmentType = fields.environmentType;
+    this.name = fields.name;
+    this.runtimeEnvironment = fields.runtimeEnvironment;
+    this.warehouse = fields.warehouse;
+  }
+}
+
+/** A producer deployment of the viewer's ingest environment */
+export class CubeIngestProducer {
+  /** Its deployment id, as text */
+  readonly deploymentId: string;
+  readonly urn: string;
+
+  constructor(fields: { deploymentId: string; urn: string }) {
+    this.deploymentId = fields.deploymentId;
+    this.urn = fields.urn;
+  }
+}
+
+/** A definition a producer deployment deployed from SDLC */
+export class CubeIngestDefinitionCandidate {
+  readonly urn: string;
+  /** The IngestDefinition element's path */
+  readonly definition: string;
+  readonly groupId: string;
+  readonly artifactId: string;
+
+  constructor(fields: {
+    urn: string;
+    definition: string;
+    groupId: string;
+    artifactId: string;
+  }) {
+    this.urn = fields.urn;
+    this.definition = fields.definition;
+    this.groupId = fields.groupId;
+    this.artifactId = fields.artifactId;
+  }
+
+  /** The definition's element name: the last segment of its path */
+  get name(): string {
+    const index = this.definition.lastIndexOf('::');
+    return index < 0 ? this.definition : this.definition.slice(index + 2);
+  }
+}
+
+/** A producer deployment's definitions: those Cube reads, and how many it left out */
+export interface CubeIngestDefinitionList {
+  readonly candidates: readonly CubeIngestDefinitionCandidate[];
+  /** Definitions not deployed from SDLC, or deployed to another class */
+  readonly droppedCount: number;
+}
+
+/** Where a saved ingest source's data set is */
+export interface CubeIngestDataSetLocation {
+  readonly ingestDefinitionUrn: string;
+  readonly ingestDefinition: string;
+  readonly dataSet: string;
+}
+
+/**
+ * The deployed ingest definitions, for the source dialog and for re-checking
+ * saved sources: its own port, so hosts without them need none. Calls fail
+ * with a `CubeEngineError`: with no node for listing and describing, with
+ * the node's id for schemas
+ */
+export interface CubeIngestCatalog {
+  /** The classes the host lists, the default first */
+  readonly environmentTypes: readonly CubeDataProductEnvironmentType[];
+
+  /** The viewer's ingest environment for a class */
+  resolveEnvironment(
+    environmentType: CubeDataProductEnvironmentType,
+  ): Promise<CubeIngestEnvironment>;
+
+  /** The producer deployments of the viewer's ingest environment for a class */
+  listProducers(
+    environmentType: CubeDataProductEnvironmentType,
+  ): Promise<readonly CubeIngestProducer[]>;
+
+  /** A producer deployment's SDLC-deployed definitions of the class */
+  listDefinitions(
+    environmentType: CubeDataProductEnvironmentType,
+    producerDeploymentId: string,
+  ): Promise<CubeIngestDefinitionList>;
+
+  /**
+   * A definition's data sets, typed from what it declares. `fresh` reads the
+   * definition again rather than what this page visit read
+   */
+  describe(
+    urn: string,
+    environmentType: CubeDataProductEnvironmentType,
+    options?: { readonly fresh?: boolean | undefined },
+  ): Promise<readonly CubeIngestDataSet[]>;
+
+  /**
+   * The schema of each saved source, from its definition as deployed: one
+   * entry per key, failures included. `fresh` reads the definitions again
+   */
+  resolveSchemas(
+    environmentType: CubeDataProductEnvironmentType,
+    sources: ReadonlyMap<NodeId, CubeIngestDataSetLocation>,
+    options?: { readonly fresh?: boolean | undefined },
+  ): Promise<Map<NodeId, Schema | CubeEngineError>>;
+}
+
+/**
+ * Where an ingest cube's engine reads the definitions it types and runs on,
+ * as protocol JSON, by URN, and the environment a run's lakehouse runtime
+ * names: the ingest servers for the deployed ones, or the host's own, e.g.
+ * Studio's workspace. Calls fail with a `CubeEngineError`
+ */
+export interface CubeIngestDefinitionSource {
+  /** A definition's element, as protocol JSON, by its URN, for the cube's class */
+  getDefinitionElement(
+    urn: string,
+    environmentType: CubeDataProductEnvironmentType,
+  ): Promise<PlainObject>;
+  /** The environment a run's lakehouse runtime names, for the cube's class */
+  getRuntimeEnvironment(
+    environmentType: CubeDataProductEnvironmentType,
+  ): Promise<string>;
+  /**
+   * Every element a typing's or a run's model holds, as protocol JSON, when
+   * the host has more than the definitions, e.g. Studio's whole workspace,
+   * whose definitions' materialized views read other elements; the
+   * definitions alone otherwise
+   */
+  getModelElements?(): Promise<readonly PlainObject[]>;
+}

package/src/graph-manager/CubeLakehouseEnvironment.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { CubeDataProductProject } from './CubeDataProduct.js';
+
+/**
+ * The viewer's lakehouse environment (PLAN §6.8), which a data product run
+ * names in its lakehouse runtime: its own port, so hosts without a lakehouse
+ * need none. Fails with a `CubeEngineError` when the viewer has none
+ */
+export interface CubeLakehouseEnvironment {
+  /** The viewer's environment for the project's class, e.g. `env`, or `env-pp` for production-parallel */
+  resolveEnvironment(project: CubeDataProductProject): Promise<string>;
+}

package/src/graph-manager/CubeLakehouseRuntime.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+
+/**
+ * The lakehouse runtimes, by the kind the engine's protocol names them
+ * (legend-graph's subtypes of the base lakehouse runtime): a Databricks one
+ * will be another (PLAN §11.12)
+ */
+export enum CubeLakehouseRuntimeKind {
+  LAKEHOUSE = 'LakehouseRuntime',
+  SINGLE_STORE = 'LakehouseSingleStoreRuntime',
+}
+
+/** The runtime Cube writes for a data product or ingest cube (PLAN §6.8) */
+export const CUBE_LAKEHOUSE_RUNTIME_KIND = CubeLakehouseRuntimeKind.LAKEHOUSE;
+
+/**
+ * The engine's database type each lakehouse runtime routes to (PLAN §11.12):
+ * every `LakehouseRuntime` to Snowflake, for now (user, 2026-10-11); a
+ * SingleStore runtime to SingleStore, the engine's `MemSQL`. The one place to
+ * change when the routing changes or a runtime is added.
+ */
+const LAKEHOUSE_DATABASE_TYPES: ReadonlyMap<string, string> = new Map([
+  [CubeLakehouseRuntimeKind.LAKEHOUSE, 'Snowflake'],
+  [CubeLakehouseRuntimeKind.SINGLE_STORE, 'MemSQL'],
+]);
+
+/** The database type a lakehouse runtime of the kind runs on; none for a kind Cube doesn't know */
+export const getLakehouseDatabaseType = (kind: string): string | undefined =>
+  LAKEHOUSE_DATABASE_TYPES.get(kind);

package/src/graph-manager/CubeProject.ts

@@ -0,0 +1,117 @@
+/**
+ * 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';
+
+// A cube on a published project's Database (PLAN §6.2.2, §6.3) saves the
+// project at one released version as its model: the engine's alloy pointer,
+// sent to the engine as saved, which fetches the project from its depot. The
+// saved runtime is one of the project's own.
+
+/** The engine's model kind of a project pointer */
+export const CUBE_PROJECT_MODEL_TYPE = 'pointer';
+const ALLOY_SDLC_TYPE = 'alloy';
+
+/** A published project at one version */
+export interface CubeProjectCoordinates {
+  readonly groupId: string;
+  readonly artifactId: string;
+  readonly versionId: string;
+}
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+/** Whether a version can move: a SNAPSHOT, or the depot's `latest` and `HEAD` aliases */
+export const isCubeMovingProjectVersion = (versionId: string): boolean =>
+  versionId.endsWith('SNAPSHOT') ||
+  versionId === 'latest' ||
+  versionId === 'HEAD';
+
+/** The model of a cube on a project's Database */
+export const createCubeProjectModel = (
+  project: CubeProjectCoordinates,
+): ModelContext =>
+  ({
+    _type: CUBE_PROJECT_MODEL_TYPE,
+    sdlcInfo: {
+      _type: ALLOY_SDLC_TYPE,
+      groupId: project.groupId,
+      artifactId: project.artifactId,
+      version: project.versionId,
+      packageableElementPointers: [],
+    },
+  }) as unknown as ModelContext;
+
+const sdlcInfoOf = (
+  model: ModelContext,
+): Record<string, unknown> | undefined => {
+  const sdlcInfo = model.sdlcInfo;
+  return sdlcInfo && typeof sdlcInfo === 'object' && !Array.isArray(sdlcInfo)
+    ? (sdlcInfo as Record<string, unknown>)
+    : undefined;
+};
+
+/** Whether the model is a project pointer, whether or not Cube can run it */
+export const isCubeProjectModel = (model: ModelContext): boolean =>
+  model._type === CUBE_PROJECT_MODEL_TYPE &&
+  sdlcInfoOf(model)?._type === ALLOY_SDLC_TYPE;
+
+/**
+ * Why Cube can't run a project model, in words a user can act on; none when
+ * it can. Only released versions are read (user, 2026-10-09): a version that
+ * moves would change a saved cube's tables under it
+ */
+export const checkCubeProjectModel = (
+  model: ModelContext,
+): readonly string[] => {
+  const sdlcInfo = sdlcInfoOf(model);
+  if (!sdlcInfo) {
+    return [`The cube's project has no coordinates`];
+  }
+  const problems: string[] = [];
+  (['groupId', 'artifactId', 'version'] as const).forEach((key) => {
+    if (!isNonEmptyString(sdlcInfo[key])) {
+      problems.push(`The cube's project has no ${key}`);
+    }
+  });
+  const version = sdlcInfo.version;
+  if (isNonEmptyString(version) && isCubeMovingProjectVersion(version)) {
+    problems.push(
+      `Cube reads released versions only, not ${version}: pick a released version`,
+    );
+  }
+  return problems;
+};
+
+/** The project of a project model Cube can run; undefined for any other model */
+export const getCubeProjectCoordinates = (
+  model: ModelContext,
+): CubeProjectCoordinates | undefined => {
+  if (!isCubeProjectModel(model) || checkCubeProjectModel(model).length) {
+    return undefined;
+  }
+  const sdlcInfo = sdlcInfoOf(model) as Record<string, string>;
+  return {
+    groupId: sdlcInfo.groupId as string,
+    artifactId: sdlcInfo.artifactId as string,
+    versionId: sdlcInfo.version as string,
+  };
+};
+
+/** The project as people read it: `group:artifact` at its version */
+export const formatCubeProject = (project: CubeProjectCoordinates): string =>
+  `${project.groupId}:${project.artifactId} ${project.versionId}`;

package/src/graph-manager/CubeProjectCatalog.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { CubeModelOutline } from './CubeEngine.js';
+import type { CubeProjectCoordinates } from './CubeProject.js';
+
+// The published projects a cube can read Databases from (PLAN §6.3): the
+// port the source dialog's Project tab reads, over the host's depot
+
+/** A published project, without a version */
+export interface CubeProjectSummary {
+  readonly groupId: string;
+  readonly artifactId: string;
+}
+
+export interface CubeProjectCatalog {
+  /** Every published project, by group and artifact */
+  listProjects(): Promise<readonly CubeProjectSummary[]>;
+  /** The project's released versions, newest first: never a SNAPSHOT or an alias */
+  listVersions(project: CubeProjectSummary): Promise<readonly string[]>;
+  /**
+   * The project's own Databases and functions at the version, and the
+   * runtimes of the project and its dependencies; a dependency's Databases
+   * and functions are not offered (user, 2026-10-09, 2026-10-12)
+   */
+  loadOutline(project: CubeProjectCoordinates): Promise<CubeModelOutline>;
+}

package/src/graph-manager/CubeService.ts

@@ -0,0 +1,29 @@
+/**
+ * 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';
+
+// A cube on services (PLAN §6.4), in progress: its model only marks it as
+// one, with no runtime. How a service is read, and what it runs on, are
+// still to come
+
+export const CUBE_SERVICE_MODEL_TYPE = 'cubeService';
+
+export const createCubeServiceModel = (): ModelContext =>
+  ({ _type: CUBE_SERVICE_MODEL_TYPE }) as ModelContext;
+
+export const isCubeServiceModel = (model: ModelContext): boolean =>
+  model._type === CUBE_SERVICE_MODEL_TYPE;

package/src/graph-manager/CubeServiceCatalog.ts

@@ -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.
+ */
+
+// The deployed services a cube can pick (PLAN §6.4): the port the source
+// dialog's Service tab reads, over the engine's service registry
+
+/** A deployed service, as the registry lists it */
+export interface CubeServiceSummary {
+  /** The service's name, its element path */
+  readonly name: string;
+  readonly title?: string | undefined;
+  /** Its URL pattern, e.g. `/trades/byDesk`, which the engine's SQL reads it by */
+  readonly pattern: string;
+  readonly documentation: string;
+  /** Who owns it: its owners, or its deployment as `Deployment <id>`; none when the registry doesn't say */
+  readonly owners: readonly string[];
+}
+
+export interface CubeServiceCatalog {
+  /** Every deployed service, by title, then name */
+  listServices(): Promise<readonly CubeServiceSummary[]>;
+}