Split DamModule into composable sub-modules

.changeset/dam-dominant-color-service.md

@@ -0,0 +1,9 @@
+---
+"@comet/cms-api": minor
+---
+
+Deprecate `FilesService.calculateDominantColor`
+
+Computing the dominant color of an image was the only part of `FilesService` that used imgproxy. It moved to an internal service that `DamImagesModule` provides, so file handling no longer depends on imgproxy.
+
+`FilesService.calculateDominantColor` returns the color when `DamImagesModule` is registered, and `undefined` when it is not.

.changeset/dam-module-split.md

@@ -0,0 +1,17 @@
+---
+"@comet/cms-api": minor
+---
+
+Split `DamModule` into composable sub-modules
+
+`DamModule` is now a facade composing four sub-modules: `DamFilesModule` (file and folder storage, upload and serving), `DamImagesModule` (image scaling via imgproxy, dominant color), `DamBlocksModule` (block transformers) and `DamDependentsModule` (the `dependents` field on `DamFile`). `DamModule.register()` keeps its signature and still composes all four.
+
+`DamModule` and its sub-modules now throw when they are registered more than once in the same process. A second registration would mount the DAM routes twice and add the `dependents` field to the file type again, so it never worked as intended.
+
+Projects that only need DAM file upload and storage can register `DamFilesModule` on its own, without `ImgproxyModule` and without `DependenciesModule`:
+
+```ts
+DamFilesModule.register({ damConfig, Scope: DamScope, File: DamFile, Folder: DamFolder });
+```
+
+In that setup, `FilesService` receives no dominant color calculator, so uploads skip the color and `FilesService.calculateDominantColor` returns `undefined`.

packages/api/cms-api/src/dam/dam-blocks.module.ts

@@ -0,0 +1,34 @@
+import { DynamicModule, Global, Module } from "@nestjs/common";
+
+import { DamFileDownloadLinkBlockTransformerService } from "./blocks/dam-file-download-link-block-transformer.service";
+import { PixelImageBlockTransformerService } from "./blocks/pixel-image-block-transformer.service";
+import { SvgImageBlockTransformerService } from "./blocks/svg-image-block-transformer.service";
+import { DamVideoBlockTransformerService } from "./blocks/video/dam-video-block-transformer.service";
+
+@Global()
+@Module({})
+export class DamBlocksModule {
+    private static registered = false;
+
+    static register(): DynamicModule {
+        // The module is global and exports the block transformer services. DamModule registers it internally, so registering both
+        // would leave two instances of each service, one of them silently unused.
+        if (DamBlocksModule.registered) {
+            throw new Error(
+                "DamBlocksModule has already been registered. It is registered by DamModule, so register either DamModule or DamBlocksModule, not both.",
+            );
+        }
+        DamBlocksModule.registered = true;
+
+        return {
+            module: DamBlocksModule,
+            providers: [
+                PixelImageBlockTransformerService,
+                SvgImageBlockTransformerService,
+                DamVideoBlockTransformerService,
+                DamFileDownloadLinkBlockTransformerService,
+            ],
+            exports: [PixelImageBlockTransformerService, SvgImageBlockTransformerService, DamVideoBlockTransformerService],
+        };
+    }
+}

packages/api/cms-api/src/dam/dam-dependents.module.ts

@@ -0,0 +1,29 @@
+import { DynamicModule, Module, Type } from "@nestjs/common";
+
+import { DependentsResolverFactory } from "../dependencies/dependents.resolver.factory";
+import { FileInterface } from "./files/entities/file.entity";
+
+interface DamDependentsModuleOptions {
+    File: Type<FileInterface>;
+}
+
+@Module({})
+export class DamDependentsModule {
+    private static registered = false;
+
+    static register({ File }: DamDependentsModuleOptions): DynamicModule {
+        // Every registration creates another resolver adding the dependents field to the file type, which breaks the schema.
+        // DamModule registers the module internally, so registering both would do exactly that.
+        if (DamDependentsModule.registered) {
+            throw new Error(
+                "DamDependentsModule has already been registered. It is registered by DamModule, so register either DamModule or DamDependentsModule, not both.",
+            );
+        }
+        DamDependentsModule.registered = true;
+
+        return {
+            module: DamDependentsModule,
+            providers: [DependentsResolverFactory.create(File)],
+        };
+    }
+}

packages/api/cms-api/src/dam/dam-files.module.ts

@@ -0,0 +1,120 @@
+import { MikroOrmModule } from "@mikro-orm/nestjs";
+import { DynamicModule, Global, Module, Type, ValueProvider } from "@nestjs/common";
+import { TypeMetadataStorage } from "@nestjs/graphql";
+
+import { FileValidationService } from "../file-utils/file-validation.service";
+import { HasValidFilenameConstraint } from "./common/decorators/has-valid-filename.decorator";
+import { damDefaultAcceptedMimetypes } from "./common/mimeTypes/dam-default-accepted-mimetypes";
+import { DamConfig, damDefaultBasePath } from "./dam.config";
+import { DAM_CONFIG, DAM_FILE_VALIDATION_SERVICE } from "./dam.constants";
+import { createDamItemsResolver } from "./files/dam-items.resolver";
+import { DamItemsService } from "./files/dam-items.service";
+import { createDamMediaAlternativeResolver } from "./files/dam-media-alternatives/dam-media-alternative.resolver";
+import { DamMediaAlternative } from "./files/dam-media-alternatives/entities/dam-media-alternative.entity";
+import { FILE_ENTITY, FileInterface } from "./files/entities/file.entity";
+import { DamFileImage } from "./files/entities/file-image.entity";
+import { FolderInterface } from "./files/entities/folder.entity";
+import { FileLicensesResolver } from "./files/file-licenses.resolver";
+import { FileWarningService } from "./files/file-warning.service";
+import { createFilesController } from "./files/files.controller";
+import { createFilesResolver } from "./files/files.resolver";
+import { FilesService } from "./files/files.service";
+import { createFoldersController } from "./files/folders.controller";
+import { createFoldersResolver } from "./files/folders.resolver";
+import { FoldersService } from "./files/folders.service";
+import { ImageCropArea } from "./images/entities/image-crop-area.entity";
+import { DamScopeInterface } from "./types";
+
+interface DamFilesModuleOptions {
+    damConfig: Omit<DamConfig, "basePath"> & { basePath?: string };
+    Scope?: Type<DamScopeInterface>;
+    Folder: Type<FolderInterface>;
+    File: Type<FileInterface>;
+}
+
+@Global()
+@Module({})
+export class DamFilesModule {
+    private static registered = false;
+
+    static register({ damConfig: damConfigOptions, Scope, Folder, File }: DamFilesModuleOptions): DynamicModule {
+        // The module is global and declares the DAM file and folder routes. DamModule registers it internally, so registering
+        // both would mount those routes twice.
+        if (DamFilesModule.registered) {
+            throw new Error(
+                "DamFilesModule has already been registered. It is registered by DamModule, so register either DamModule or DamFilesModule, not both.",
+            );
+        }
+        DamFilesModule.registered = true;
+
+        if (File.name !== FILE_ENTITY) {
+            throw new Error(`DamModule: Your File entity must be named ${FILE_ENTITY}`);
+        }
+
+        const damConfig: DamConfig = {
+            ...damConfigOptions,
+            basePath: damConfigOptions.basePath ?? damDefaultBasePath,
+        };
+
+        const damConfigProvider: ValueProvider<DamConfig> = {
+            provide: DAM_CONFIG,
+            useValue: damConfig,
+        };
+
+        const fileValidationServiceProvider = {
+            provide: DAM_FILE_VALIDATION_SERVICE,
+            useValue: new FileValidationService({
+                maxFileSize: damConfig.maxFileSize,
+                acceptedMimeTypes: damConfig.acceptedMimeTypes ?? damDefaultAcceptedMimetypes,
+            }),
+        };
+
+        const DamItemsResolver = createDamItemsResolver({ File, Folder, Scope });
+        const FilesResolver = createFilesResolver({ File, Folder, Scope });
+        const FoldersResolver = createFoldersResolver({ Folder, Scope });
+        const DamMediaAlternativeResolver = createDamMediaAlternativeResolver({ File, Scope });
+
+        if (Scope) {
+            // Scope validation needs to happen after resolver generation. Otherwise the input type metadata has not been defined yet.
+            const scopeObjectType = TypeMetadataStorage.getObjectTypeMetadataByTarget(Scope);
+
+            if (scopeObjectType?.name !== "DamScope") {
+                throw new Error(
+                    `Invalid object type name for provided DAM scope class. Make sure to decorate the class with @ObjectType("DamScope")`,
+                );
+            }
+
+            const scopeInputType = TypeMetadataStorage.getInputTypeMetadataByTarget(Scope);
+
+            if (scopeInputType?.name !== "DamScopeInput") {
+                throw new Error(
+                    `Invalid input type name for provided DAM scope class. Make sure to decorate the class with @InputType("DamScopeInput")`,
+                );
+            }
+        }
+
+        return {
+            module: DamFilesModule,
+            imports: [MikroOrmModule.forFeature([File, Folder, DamFileImage, ImageCropArea, DamMediaAlternative])],
+            providers: [
+                damConfigProvider,
+                fileValidationServiceProvider,
+                DamItemsResolver,
+                DamItemsService,
+                FilesResolver,
+                FilesService,
+                FileLicensesResolver,
+                FoldersResolver,
+                FoldersService,
+                HasValidFilenameConstraint,
+                FileWarningService,
+                DamMediaAlternativeResolver,
+            ],
+            controllers: [
+                createFilesController({ Scope, damBasePath: damConfig.basePath }),
+                createFoldersController({ damBasePath: damConfig.basePath }),
+            ],
+            exports: [FilesService, FoldersService, DamItemsService, damConfigProvider],
+        };
+    }
+}

packages/api/cms-api/src/dam/dam-images.module.ts

@@ -0,0 +1,48 @@
+import { DynamicModule, Global, Module } from "@nestjs/common";
+
+import { DAM_DOMINANT_COLOR_CALCULATOR } from "./dam.constants";
+import { CalculateDominantImageColorCommand } from "./images/calculateDominantImageColor.command";
+import { DamDominantColorService } from "./images/dam-dominant-color.service";
+import { FileImagesResolver } from "./images/file-image.resolver";
+import { createImagesController } from "./images/images.controller";
+import { ImagesService } from "./images/images.service";
+import { IsAllowedImageAspectRatioConstraint } from "./images/validators/is-allowed-aspect-ratio.validator";
+import { IsAllowedImageSizeConstraint } from "./images/validators/is-allowed-image-size.validator";
+import { IsValidImageAspectRatioConstraint } from "./images/validators/is-valid-aspect-ratio.validator";
+
+interface DamImagesModuleOptions {
+    damBasePath: string;
+}
+
+@Global()
+@Module({})
+export class DamImagesModule {
+    private static registered = false;
+
+    static register({ damBasePath }: DamImagesModuleOptions): DynamicModule {
+        // The module is global and declares the DAM image routes. DamModule registers it internally, so registering both would
+        // mount those routes twice.
+        if (DamImagesModule.registered) {
+            throw new Error(
+                "DamImagesModule has already been registered. It is registered by DamModule, so register either DamModule or DamImagesModule, not both.",
+            );
+        }
+        DamImagesModule.registered = true;
+
+        return {
+            module: DamImagesModule,
+            providers: [
+                ImagesService,
+                DamDominantColorService,
+                { provide: DAM_DOMINANT_COLOR_CALCULATOR, useExisting: DamDominantColorService },
+                CalculateDominantImageColorCommand,
+                FileImagesResolver,
+                IsAllowedImageSizeConstraint,
+                IsAllowedImageAspectRatioConstraint,
+                IsValidImageAspectRatioConstraint,
+            ],
+            controllers: [createImagesController({ damBasePath })],
+            exports: [ImagesService, DamDominantColorService, DAM_DOMINANT_COLOR_CALCULATOR],
+        };
+    }
+}

packages/api/cms-api/src/dam/dam.config.ts

@@ -1,3 +1,5 @@
+export const damDefaultBasePath = "dam";
+
 export interface DamConfig {
     secret: string;
     allowedImageSizes: number[];

packages/api/cms-api/src/dam/dam.constants.ts

@@ -1,2 +1,3 @@
 export const DAM_CONFIG = "dam-config";
 export const DAM_FILE_VALIDATION_SERVICE = "dam-file-validation-service";
+export const DAM_DOMINANT_COLOR_CALCULATOR = "dam-dominant-color-calculator";