feat(common): add error format option to validation pipe

Add a new `errorFormat` option to `ValidationPipeOptions` that allows
users to choose between two validation error formats:

- 'list' (default): Returns an array of error message strings with
  parent path prepended to messages (current behavior)
- 'grouped': Returns an object with property paths as keys and arrays
  of unmodified constraint messages as values

The 'grouped' format separates property paths from error messages,
which prevents custom validation messages from being modified with
parent path prefixes.

Closes #16268

Author: at7211

packages/common/pipes/validation.pipe.ts

@@ -20,6 +20,11 @@ import {
 import { loadPackage } from '../utils/load-package.util';
 import { isNil, isUndefined } from '../utils/shared.utils';
 
+/**
+ * @publicApi
+ */
+export type ValidationErrorFormat = 'list' | 'grouped';
+
 /**
  * @publicApi
  */
@@ -33,6 +38,12 @@ export interface ValidationPipeOptions extends ValidatorOptions {
   expectedType?: Type<any>;
   validatorPackage?: ValidatorPackage;
   transformerPackage?: TransformerPackage;
+  /**
+   * Specifies the format of validation error messages.
+   * - 'list': Returns an array of error message strings (default)
+   * - 'grouped': Returns an object with property paths as keys and arrays of error messages as values
+   */
+  errorFormat?: ValidationErrorFormat;
 }
 
 let classValidator: ValidatorPackage = {} as any;
@@ -59,6 +70,7 @@ export class ValidationPipe implements PipeTransform<any> {
   protected expectedType: Type<any> | undefined;
   protected exceptionFactory: (errors: ValidationError[]) => any;
   protected validateCustomDecorators: boolean;
+  protected errorFormat: ValidationErrorFormat;
 
   constructor(@Optional() options?: ValidationPipeOptions) {
     options = options || {};
@@ -69,6 +81,7 @@ export class ValidationPipe implements PipeTransform<any> {
       expectedType,
       transformOptions,
       validateCustomDecorators,
+      errorFormat,
       ...validatorOptions
     } = options;
 
@@ -81,6 +94,7 @@ export class ValidationPipe implements PipeTransform<any> {
     this.validateCustomDecorators = validateCustomDecorators || false;
     this.errorHttpStatusCode = errorHttpStatusCode || HttpStatus.BAD_REQUEST;
     this.expectedType = expectedType;
+    this.errorFormat = errorFormat || 'list';
     this.exceptionFactory =
       options.exceptionFactory || this.createExceptionFactory();
 
@@ -183,6 +197,12 @@ export class ValidationPipe implements PipeTransform<any> {
       if (this.isDetailedOutputDisabled) {
         return new HttpErrorByCode[this.errorHttpStatusCode]();
       }
+      if (this.errorFormat === 'grouped') {
+        const errors = this.groupValidationErrors(validationErrors);
+        return new HttpErrorByCode[this.errorHttpStatusCode]({
+          message: errors,
+        });
+      }
       const errors = this.flattenValidationErrors(validationErrors);
       return new HttpErrorByCode[this.errorHttpStatusCode](errors);
     };
@@ -310,6 +330,25 @@ export class ValidationPipe implements PipeTransform<any> {
       .toArray();
   }
 
+  protected groupValidationErrors(
+    validationErrors: ValidationError[],
+    parentPath?: string,
+  ): Record<string, string[]> {
+    const result: Record<string, string[]> = {};
+    for (const error of validationErrors) {
+      const path = parentPath
+        ? `${parentPath}.${error.property}`
+        : error.property;
+      if (error.constraints) {
+        result[path] = Object.values(error.constraints);
+      }
+      if (error.children && error.children.length) {
+        Object.assign(result, this.groupValidationErrors(error.children, path));
+      }
+    }
+    return result;
+  }
+
   protected mapChildrenToValidationErrors(
     error: ValidationError,
     parentPath?: string,

packages/common/test/pipes/validation.pipe.spec.ts

@@ -183,6 +183,46 @@ describe('ValidationPipe', () => {
           ]);
         }
       });
+
+      describe('when errorFormat is "grouped"', () => {
+        beforeEach(() => {
+          target = new ValidationPipe({ errorFormat: 'grouped' });
+        });
+
+        it('should return grouped errors with property paths as keys', async () => {
+          try {
+            const model = new TestModelWithNested();
+            model.test = new TestModel2();
+            await target.transform(model, {
+              type: 'body',
+              metatype: TestModelWithNested,
+            });
+          } catch (err) {
+            expect(err.getResponse().message).to.be.eql({
+              prop: ['prop must be a string'],
+              'test.prop1': ['prop1 must be a string'],
+              'test.prop2': ['prop2 must be a boolean value'],
+            });
+          }
+        });
+
+        it('should return grouped errors for nested arrays', async () => {
+          try {
+            const model = new TestModelForNestedArrayValidation();
+            model.test = [new TestModel2()];
+            await target.transform(model, {
+              type: 'body',
+              metatype: TestModelForNestedArrayValidation,
+            });
+          } catch (err) {
+            expect(err.getResponse().message).to.be.eql({
+              prop: ['prop must be a string'],
+              'test.0.prop1': ['prop1 must be a string'],
+              'test.0.prop2': ['prop2 must be a boolean value'],
+            });
+          }
+        });
+      });
     });
     describe('when validation transforms', () => {
       it('should return a TestModel instance', async () => {