V2 centralize relation optimistic logic (#15552)

# Introduction
This PR aims to deprecate having to manually handle optimistic side
effect foreign key addition in the whole v2 experience.
This PR implements the strong basis + builder refactor of the optimistic
computation of a given flat entity maps with its related flat entity
maps ( runner needs a small refactor on actions type definition first )
Flat entity maps updates through mutations are now only scoped to the
generic entity builder ( very isolated )

## What's next
- Refactor actions v2 type definition to gain grain over `metadataName`
and action operation ( `create` `delete` `update` ).
from `{type: 'create_view_field'}` to `{metadataName: 'view_field',
type: 'create' }`
- Use new optimistic tool computation tools
- Only invalidate impacted flat maps cache

## New tools
Strictly dynamically typed new flat entity maps tools
- `addFlatEntityToFlatEntityAndRelatedEntityMapsThroughMutationOrThrow`
-
`deleteFlatEntityFromFlatEntityAndRelatedEntityMapsThroughMutationOrThrow`

## Unit test
Adding basic unit testing coverage to introduced tools

## `FlatEntityValidationArgs`
From 
```ts
export type FlatEntityValidationArgs<T extends AllMetadataName> = {
  flatEntityToValidate: MetadataFlatEntity<T>;
  optimisticFlatEntityMaps: MetadataFlatEntityMaps<T>;
  mutableDependencyOptimisticFlatEntityMaps: MetadataValidationRelatedFlatEntityMaps<T>;
  workspaceId: string;
  remainingFlatEntityMapsToValidate: MetadataFlatEntityMaps<T>;
  buildOptions: WorkspaceMigrationBuilderOptions;
};

```

To
```ts
export type FlatEntityValidationArgs<T extends AllMetadataName> = {
  flatEntityToValidate: MetadataFlatEntity<T>;
  optimisticFlatEntityMapsAndRelatedFlatEntityMaps: MetadataFlatEntityAndRelatedFlatEntityMapsForValidation<T>;
  workspaceId: string;
  remainingFlatEntityMapsToValidate: MetadataFlatEntityMaps<T>;
  buildOptions: WorkspaceMigrationBuilderOptions;
};

```

Author: prastoin

packages/twenty-server/src/engine/core-modules/serverless/drivers/interfaces/serverless-driver.interface.ts

@@ -1,5 +1,5 @@
-import { type ServerlessFunctionEntity } from 'src/engine/metadata-modules/serverless-function/serverless-function.entity';
 import { type ServerlessFunctionExecutionStatus } from 'src/engine/metadata-modules/serverless-function/dtos/serverless-function-execution-result.dto';
+import { type ServerlessFunctionEntity } from 'src/engine/metadata-modules/serverless-function/serverless-function.entity';
 
 export type ServerlessExecuteError = {
   errorType: string;
@@ -15,6 +15,7 @@ export type ServerlessExecuteResult = {
   error?: ServerlessExecuteError;
 };
 
+// TODO refactor to be using FlatServerlessFunction
 export interface ServerlessDriver {
   delete(serverlessFunction: ServerlessFunctionEntity): Promise<void>;
   execute(

packages/twenty-server/src/engine/metadata-modules/flat-entity/constant/all-metadata-many-to-one-relations.constant.ts

@@ -2,6 +2,7 @@ import { type AllMetadataName } from 'twenty-shared/metadata';
 import { type ExtractPropertiesThatEndsWithId } from 'twenty-shared/types';
 
 import { type MetadataEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-entity.type';
+import { type MetadataFlatEntity } from 'src/engine/metadata-modules/flat-entity/types/metadata-flat-entity.type';
 
 type ExtractEntityRelations<TEntity extends MetadataEntity<AllMetadataName>> = {
   [K in ExtractPropertiesThatEndsWithId<TEntity, 'id' | 'workspaceId'>]: K;
@@ -11,46 +12,93 @@ type MetadataRelatedMetadataNames<T extends AllMetadataName> =
   keyof ExtractEntityRelations<MetadataEntity<T>>;
 
 type MetadataNameAndRelations = {
-  [T in AllMetadataName]: MetadataRelatedMetadataNames<T> extends never
+  [TSourceMetadataName in AllMetadataName]: MetadataRelatedMetadataNames<TSourceMetadataName> extends never
     ? Record<string, never>
     : {
-        [P in MetadataRelatedMetadataNames<T>]?: AllMetadataName;
+        [K in MetadataRelatedMetadataNames<TSourceMetadataName>]?: {
+          [TTargetMetadataName in AllMetadataName]?: {
+            metadataName: TTargetMetadataName;
+            flatEntityForeignKeyAggregator: keyof MetadataFlatEntity<TTargetMetadataName>;
+          };
+        }[AllMetadataName];
       };
 };
 
 export const ALL_METADATA_RELATED_METADATA_BY_FOREIGN_KEY = {
   fieldMetadata: {
-    objectMetadataId: 'objectMetadata',
+    objectMetadataId: {
+      metadataName: 'objectMetadata',
+      flatEntityForeignKeyAggregator: 'fieldMetadataIds',
+    },
   },
   objectMetadata: {},
   view: {
-    kanbanAggregateOperationFieldMetadataId: 'fieldMetadata',
-    calendarFieldMetadataId: 'fieldMetadata',
-    objectMetadataId: 'objectMetadata',
+    kanbanAggregateOperationFieldMetadataId: {
+      metadataName: 'fieldMetadata',
+      flatEntityForeignKeyAggregator: 'kanbanAggregateOperationViewIds',
+    },
+    calendarFieldMetadataId: {
+      metadataName: 'fieldMetadata',
+      flatEntityForeignKeyAggregator: 'calendarViewIds',
+    },
+    objectMetadataId: {
+      metadataName: 'objectMetadata',
+      flatEntityForeignKeyAggregator: 'viewIds',
+    },
   },
   viewField: {
-    viewId: 'view',
-    fieldMetadataId: 'fieldMetadata',
+    viewId: {
+      metadataName: 'view',
+      flatEntityForeignKeyAggregator: 'viewFieldIds',
+    },
+    fieldMetadataId: {
+      metadataName: 'fieldMetadata',
+      flatEntityForeignKeyAggregator: 'viewFieldIds',
+    },
   },
   viewGroup: {
-    viewId: 'view',
-    fieldMetadataId: 'fieldMetadata',
+    viewId: {
+      metadataName: 'view',
+      flatEntityForeignKeyAggregator: 'viewGroupIds',
+    },
+    fieldMetadataId: {
+      metadataName: 'fieldMetadata',
+      flatEntityForeignKeyAggregator: 'viewGroupIds',
+    },
   },
   index: {
-    objectMetadataId: 'objectMetadata',
+    objectMetadataId: {
+      metadataName: 'objectMetadata',
+      flatEntityForeignKeyAggregator: 'indexMetadataIds',
+    },
   },
   serverlessFunction: {},
   cronTrigger: {
-    serverlessFunctionId: 'serverlessFunction',
+    serverlessFunctionId: {
+      metadataName: 'serverlessFunction',
+      flatEntityForeignKeyAggregator: 'cronTriggerIds',
+    },
   },
   databaseEventTrigger: {
-    serverlessFunctionId: 'serverlessFunction',
+    serverlessFunctionId: {
+      metadataName: 'serverlessFunction',
+      flatEntityForeignKeyAggregator: 'databaseEventTriggerIds',
+    },
   },
   routeTrigger: {
-    serverlessFunctionId: 'serverlessFunction',
+    serverlessFunctionId: {
+      metadataName: 'serverlessFunction',
+      flatEntityForeignKeyAggregator: 'routeTriggerIds',
+    },
   },
   viewFilter: {
-    viewId: 'view',
-    fieldMetadataId: 'fieldMetadata',
+    viewId: {
+      metadataName: 'view',
+      flatEntityForeignKeyAggregator: 'viewFilterIds',
+    },
+    fieldMetadataId: {
+      metadataName: 'fieldMetadata',
+      flatEntityForeignKeyAggregator: 'viewFilterIds',
+    },
   },
 } as const satisfies MetadataNameAndRelations;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-flat-entity-and-related-flat-entity-maps-for-validation.type.ts

@@ -0,0 +1,15 @@
+import { type AllMetadataName } from 'twenty-shared/metadata';
+
+import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
+import { type MetadataRelatedFlatEntityMapsKeys } from 'src/engine/metadata-modules/flat-entity/types/metadata-related-flat-entity-maps-keys.type';
+import { type MetadataToFlatEntityMapsKey } from 'src/engine/metadata-modules/flat-entity/types/metadata-to-flat-entity-maps-key';
+import { type MetadataValidationRelatedMetadataNames } from 'src/engine/metadata-modules/flat-entity/types/metadata-validation-related-metadata-names.type';
+
+export type MetadataFlatEntityAndRelatedFlatEntityMapsForValidation<
+  T extends AllMetadataName,
+> = Pick<
+  AllFlatEntityMaps,
+  | MetadataRelatedFlatEntityMapsKeys<T>
+  | MetadataToFlatEntityMapsKey<T>
+  | MetadataToFlatEntityMapsKey<MetadataValidationRelatedMetadataNames<T>>
+>;

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-many-to-one-related-metadata-names.type.ts

@@ -6,5 +6,5 @@ import { type MetadataManyToOneJoinColumn } from 'src/engine/metadata-modules/fl
 export type MetadataManyToOneRelatedMetadataNames<T extends AllMetadataName> =
   Extract<
     (typeof ALL_METADATA_RELATED_METADATA_BY_FOREIGN_KEY)[T][MetadataManyToOneJoinColumn<T>],
-    AllMetadataName
-  >;
+    { metadataName: AllMetadataName }
+  >['metadataName'];

packages/twenty-server/src/engine/metadata-modules/flat-entity/types/metadata-validation-related-metadata-names.type.ts

@@ -1,16 +1,9 @@
-import { type IsEmptyRecord } from 'twenty-shared/types';
 import { type AllMetadataName } from 'twenty-shared/metadata';
 
 import { type ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION } from 'src/engine/metadata-modules/flat-entity/constant/all-metadata-required-metadata-for-validation.constant';
 
 export type MetadataValidationRelatedMetadataNames<T extends AllMetadataName> =
-  IsEmptyRecord<
-    (typeof ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION)[T]
-  > extends true
-    ? undefined
-    : NonNullable<
-        Extract<
-          keyof (typeof ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION)[T],
-          AllMetadataName
-        >
-      >;
+  Extract<
+    keyof (typeof ALL_METADATA_REQUIRED_METADATA_FOR_VALIDATION)[T],
+    AllMetadataName
+  >;

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/__tests__/add-flat-entity-to-flat-entity-and-related-entity-maps-through-mutation-or-throw.spec.ts

@@ -0,0 +1,94 @@
+import { FieldMetadataType } from 'twenty-shared/types';
+
+import { createEmptyFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/constant/create-empty-flat-entity-maps.constant';
+import { type MetadataFlatEntityAndRelatedFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/metadata-related-types.type';
+import { addFlatEntityToFlatEntityAndRelatedEntityMapsThroughMutationOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-and-related-entity-maps-through-mutation-or-throw.util';
+import { addFlatEntityToFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-maps-or-throw.util';
+import { getFlatFieldMetadataMock } from 'src/engine/metadata-modules/flat-field-metadata/__mocks__/get-flat-field-metadata.mock';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { getFlatObjectMetadataMock } from 'src/engine/metadata-modules/flat-object-metadata/__mocks__/get-flat-object-metadata.mock';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+import { type FlatView } from 'src/engine/metadata-modules/flat-view/types/flat-view.type';
+
+describe('addFlatEntityToFlatEntityAndRelatedEntityMapsThroughMutationOrThrow', () => {
+  it('should add a view and update related objectMetadata with viewId', () => {
+    const objectMetadataId = 'object-1';
+    const viewId = 'view-1';
+    const applicationId = '20202020-f3ad-452e-b5b6-2d49d3ea88b1';
+    const workspaceId = '20202020-bc64-4148-8a79-b3144f743694';
+    const mockObjectMetadata = getFlatObjectMetadataMock({
+      id: objectMetadataId,
+      universalIdentifier: 'object-universal-1',
+      viewIds: [],
+      fieldMetadataIds: [],
+      workspaceId,
+      imageIdentifierFieldMetadataId: '20202020-9d65-415f-b0e1-216a2e257ea4',
+      labelIdentifierFieldMetadataId: '20202020-1a62-405c-87fa-4d4fd215851b',
+      applicationId,
+    });
+
+    const mockFieldMEtadata = getFlatFieldMetadataMock({
+      objectMetadataId,
+      id: '202020-71a3-4856-a3d0-d08cea0ecec6',
+      type: FieldMetadataType.DATE,
+      workspaceId,
+      applicationId,
+      universalIdentifier: 'field-universal-1',
+      viewFieldIds: [],
+      viewGroupIds: [],
+      viewFilterIds: [],
+      calendarViewIds: [],
+    });
+
+    const mockView: Pick<FlatView, 'id'> & Partial<FlatView> = {
+      id: viewId,
+      workspaceId,
+      universalIdentifier: 'view-universal-1',
+      objectMetadataId: objectMetadataId,
+      viewFieldIds: [],
+      viewFilterIds: [],
+      viewGroupIds: [],
+      applicationId,
+      calendarFieldMetadataId: mockFieldMEtadata.id,
+    };
+
+    const flatEntityAndRelatedMapsToMutate: MetadataFlatEntityAndRelatedFlatEntityMaps<'view'> =
+      {
+        flatFieldMetadataMaps: addFlatEntityToFlatEntityMapsOrThrow({
+          flatEntity: mockFieldMEtadata,
+          flatEntityMaps: createEmptyFlatEntityMaps(),
+        }),
+        flatObjectMetadataMaps: addFlatEntityToFlatEntityMapsOrThrow({
+          flatEntity: mockObjectMetadata,
+          flatEntityMaps: createEmptyFlatEntityMaps(),
+        }),
+        flatViewMaps: createEmptyFlatEntityMaps(),
+      };
+
+    addFlatEntityToFlatEntityAndRelatedEntityMapsThroughMutationOrThrow({
+      metadataName: 'view',
+      flatEntity: mockView as FlatView,
+      flatEntityAndRelatedMapsToMutate,
+    });
+
+    expect(
+      flatEntityAndRelatedMapsToMutate.flatViewMaps.byId[mockView.id],
+    ).toMatchObject(mockView);
+
+    expect(
+      flatEntityAndRelatedMapsToMutate.flatObjectMetadataMaps.byId[
+        objectMetadataId
+      ],
+    ).toMatchObject<Partial<FlatObjectMetadata>>({
+      viewIds: [mockView.id],
+    });
+
+    expect(
+      flatEntityAndRelatedMapsToMutate.flatFieldMetadataMaps.byId[
+        mockFieldMEtadata.id
+      ],
+    ).toMatchObject<Partial<FlatFieldMetadata>>({
+      calendarViewIds: [mockView.id],
+    });
+  });
+});

packages/twenty-server/src/engine/metadata-modules/flat-entity/utils/__tests__/delete-flat-entity-from-flat-entity-and-related-entity-maps-through-mutation-or-throw.spec.ts

@@ -0,0 +1,104 @@
+import { FieldMetadataType } from 'twenty-shared/types';
+
+import { createEmptyFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/constant/create-empty-flat-entity-maps.constant';
+import { type MetadataFlatEntityAndRelatedFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/metadata-related-types.type';
+import { addFlatEntityToFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/add-flat-entity-to-flat-entity-maps-or-throw.util';
+import { deleteFlatEntityFromFlatEntityAndRelatedEntityMapsThroughMutationOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/delete-flat-entity-from-flat-entity-and-related-entity-maps-through-mutation-or-throw.util';
+import { getFlatFieldMetadataMock } from 'src/engine/metadata-modules/flat-field-metadata/__mocks__/get-flat-field-metadata.mock';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+import { getFlatObjectMetadataMock } from 'src/engine/metadata-modules/flat-object-metadata/__mocks__/get-flat-object-metadata.mock';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+import { type FlatView } from 'src/engine/metadata-modules/flat-view/types/flat-view.type';
+
+describe('deleteFlatEntityFromFlatEntityAndRelatedEntityMapsThroughMutationOrThrow', () => {
+  it('should delete a view and update related objectMetadata and fieldMetadata by removing viewId', () => {
+    const objectMetadataId = 'object-1';
+    const viewId = 'view-1';
+    const applicationId = '20202020-f3ad-452e-b5b6-2d49d3ea88b1';
+    const workspaceId = '20202020-bc64-4148-8a79-b3144f743694';
+
+    const mockObjectMetadata = getFlatObjectMetadataMock({
+      id: objectMetadataId,
+      universalIdentifier: 'object-universal-1',
+      viewIds: [viewId, 'something-else'],
+      fieldMetadataIds: [],
+      workspaceId,
+      imageIdentifierFieldMetadataId: '20202020-9d65-415f-b0e1-216a2e257ea4',
+      labelIdentifierFieldMetadataId: '20202020-1a62-405c-87fa-4d4fd215851b',
+      applicationId,
+    });
+
+    const mockFieldMetadata = getFlatFieldMetadataMock({
+      objectMetadataId,
+      id: '20202020-4087-423b-852a-91f91acf2df2',
+      type: FieldMetadataType.DATE,
+      universalIdentifier: 'field-universal-1',
+      viewFieldIds: [],
+      viewGroupIds: [],
+      viewFilterIds: [],
+      workspaceId,
+      calendarViewIds: [viewId],
+      applicationId,
+    });
+
+    const mockView: Partial<FlatView> = {
+      id: viewId,
+      universalIdentifier: 'view-universal-1',
+      objectMetadataId: objectMetadataId,
+      viewFieldIds: [],
+      viewFilterIds: [],
+      viewGroupIds: [],
+      workspaceId,
+      calendarFieldMetadataId: mockFieldMetadata.id,
+      createdAt: new Date('2024-01-01'),
+      updatedAt: new Date('2024-01-01'),
+      icon: 'icon',
+      isCompact: false,
+      name: 'View Name',
+      position: 0,
+      applicationId,
+    };
+
+    const flatEntityAndRelatedMapsToMutate: MetadataFlatEntityAndRelatedFlatEntityMaps<'view'> =
+      {
+        flatFieldMetadataMaps: addFlatEntityToFlatEntityMapsOrThrow({
+          flatEntity: mockFieldMetadata,
+          flatEntityMaps: createEmptyFlatEntityMaps(),
+        }),
+        flatObjectMetadataMaps: addFlatEntityToFlatEntityMapsOrThrow({
+          flatEntity: mockObjectMetadata,
+          flatEntityMaps: createEmptyFlatEntityMaps(),
+        }),
+        flatViewMaps: addFlatEntityToFlatEntityMapsOrThrow({
+          flatEntity: mockView as FlatView,
+          flatEntityMaps: createEmptyFlatEntityMaps(),
+        }),
+      };
+
+    deleteFlatEntityFromFlatEntityAndRelatedEntityMapsThroughMutationOrThrow({
+      metadataName: 'view',
+      flatEntity: mockView as FlatView,
+      flatEntityAndRelatedMapsToMutate,
+    });
+
+    expect(
+      flatEntityAndRelatedMapsToMutate.flatViewMaps.byId[viewId],
+    ).toBeUndefined();
+
+    expect(
+      flatEntityAndRelatedMapsToMutate.flatObjectMetadataMaps.byId[
+        objectMetadataId
+      ],
+    ).toMatchObject<Partial<FlatObjectMetadata>>({
+      viewIds: ['something-else'],
+    });
+
+    expect(
+      flatEntityAndRelatedMapsToMutate.flatFieldMetadataMaps.byId[
+        mockFieldMetadata.id
+      ],
+    ).toMatchObject<Partial<FlatFieldMetadata>>({
+      calendarViewIds: [],
+    });
+  });
+});