@dismissible/nestjs-validation 0.0.2-canary.5daf195.0

package/README.md

@@ -0,0 +1,206 @@
+# @dismissible/nestjs-validation
+
+A validation service for NestJS applications using class-validator and class-transformer.
+
+> **Part of the Dismissible API** - This library is part of the [Dismissible API](https://dismissible.io) ecosystem. Visit [dismissible.io](https://dismissible.io) for more information and documentation.
+
+## Overview
+
+This library provides a `ValidationService` that wraps `class-validator` and `class-transformer` to provide a consistent validation API for DTOs and class instances in NestJS applications.
+
+## Installation
+
+```bash
+npm install @dismissible/nestjs-validation
+```
+
+You'll also need to install the peer dependencies:
+
+```bash
+npm install class-validator class-transformer
+```
+
+## Getting Started
+
+### Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ValidationModule } from '@dismissible/nestjs-validation';
+
+@Module({
+  imports: [ValidationModule],
+})
+export class AppModule {}
+```
+
+### Validating DTOs
+
+The `ValidationService` can validate plain objects against DTO classes:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ValidationService } from '@dismissible/nestjs-validation';
+import { IsString, IsEmail, IsOptional } from 'class-validator';
+
+class CreateUserDto {
+  @IsString()
+  name!: string;
+
+  @IsEmail()
+  email!: string;
+
+  @IsOptional()
+  @IsString()
+  phone?: string;
+}
+
+@Injectable()
+export class UserService {
+  constructor(private readonly validationService: ValidationService) {}
+
+  async createUser(data: unknown) {
+    // Validates and transforms the data, throws BadRequestException if invalid
+    const dto = await this.validationService.validateDto(CreateUserDto, data);
+
+    // dto is now a validated instance of CreateUserDto
+    // Use dto.name, dto.email, etc.
+  }
+}
+```
+
+### Validating Existing Instances
+
+You can also validate class instances that have already been created:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ValidationService } from '@dismissible/nestjs-validation';
+import { IsString, IsDate } from 'class-validator';
+
+class MyDto {
+  @IsString()
+  name!: string;
+
+  @IsDate()
+  createdAt!: Date;
+}
+
+@Injectable()
+export class MyService {
+  constructor(private readonly validationService: ValidationService) {}
+
+  async validateInstance(dto: MyDto) {
+    // Validates the instance, throws BadRequestException if invalid
+    await this.validationService.validateInstance(dto);
+  }
+}
+```
+
+### Error Handling
+
+The validation service throws `BadRequestException` with formatted error messages when validation fails:
+
+```typescript
+import { BadRequestException } from '@nestjs/common';
+import { ValidationService } from '@dismissible/nestjs-validation';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly validationService: ValidationService) {}
+
+  async handleRequest(data: unknown) {
+    try {
+      const dto = await this.validationService.validateDto(MyDto, data);
+      // Process valid data
+    } catch (error) {
+      if (error instanceof BadRequestException) {
+        // Handle validation errors
+        console.error('Validation failed:', error.message);
+      }
+      throw error;
+    }
+  }
+}
+```
+
+## API Reference
+
+### ValidationService
+
+#### `validateDto<T>(dtoClass, data): Promise<T>`
+
+Validates and transforms plain data into a DTO instance.
+
+**Parameters:**
+
+- `dtoClass: ClassConstructor<T>` - The DTO class to validate against
+- `data: unknown` - The data to validate
+
+**Returns:** `Promise<T>` - A validated instance of the DTO class
+
+**Throws:** `BadRequestException` if validation fails
+
+#### `validateInstance<T>(instance): Promise<void>`
+
+Validates an existing class instance.
+
+**Parameters:**
+
+- `instance: T` - The instance to validate
+
+**Throws:** `BadRequestException` if validation fails
+
+### ValidationModule
+
+A NestJS module that provides `ValidationService` as a singleton.
+
+**Exports:**
+
+- `ValidationService` - The validation service
+
+## Features
+
+- Automatic transformation using `class-transformer`
+- Validation using `class-validator` decorators
+- Nested validation error extraction
+- Formatted error messages
+- Type-safe DTOs with TypeScript generics
+
+## Example: Using in a Controller
+
+```typescript
+import { Controller, Post, Body } from '@nestjs/common';
+import { ValidationService } from '@dismissible/nestjs-validation';
+import { IsString, IsEmail } from 'class-validator';
+
+class CreateUserDto {
+  @IsString()
+  name!: string;
+
+  @IsEmail()
+  email!: string;
+}
+
+@Controller('users')
+export class UserController {
+  constructor(private readonly validationService: ValidationService) {}
+
+  @Post()
+  async create(@Body() body: unknown) {
+    const dto = await this.validationService.validateDto(CreateUserDto, body);
+    // Use validated dto
+    return { message: `Creating user: ${dto.name}` };
+  }
+}
+```
+
+## Related Packages
+
+This validation service is used by:
+
+- `@dismissible/nestjs-dismissible` - Validates dismissible items
+
+## License
+
+MIT

package/jest.config.ts

@@ -0,0 +1,27 @@
+export default {
+  displayName: 'validation',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.json' }],
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/libs/validation',
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.spec.ts',
+    '!src/**/*.interface.ts',
+    '!src/**/*.dto.ts',
+    '!src/**/*.enum.ts',
+    '!src/**/index.ts',
+    '!src/**/*.module.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dismissible/nestjs-validation",
+  "version": "0.0.2-canary.5daf195.0",
+  "description": "Validation service module for NestJS applications using class-validator and class-transformer",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "class-validator": "^0.14.0",
+    "class-transformer": "^0.5.0",
+    "reflect-metadata": "^0.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": false
+    },
+    "class-validator": {
+      "optional": false
+    },
+    "class-transformer": {
+      "optional": false
+    },
+    "reflect-metadata": {
+      "optional": false
+    }
+  },
+  "keywords": [
+    "nestjs",
+    "validation",
+    "class-validator",
+    "class-transformer",
+    "dto"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DismissibleIo/dismissible-api"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,34 @@
+{
+  "name": "validation",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/validation/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/validation",
+        "main": "libs/validation/src/index.ts",
+        "tsConfig": "libs/validation/tsconfig.lib.json",
+        "assets": ["libs/validation/package.json", "libs/validation/README.md"],
+        "generatePackageJson": true
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["libs/validation/**/*.ts"]
+      }
+    },
+    "npm-publish": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npm publish --access public",
+        "cwd": "dist/libs/validation"
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './validation.service';
+export * from './validation.module';
+export * from './transform-boolean.decorator';
+export * from './transform-comma-separated.decorator';

package/src/transform-boolean.decorator.spec.ts

@@ -0,0 +1,102 @@
+import 'reflect-metadata';
+import { IsBoolean } from 'class-validator';
+import { plainToInstance } from 'class-transformer';
+import { TransformBoolean } from './transform-boolean.decorator';
+
+class TestConfig {
+  @IsBoolean()
+  @TransformBoolean()
+  value!: boolean;
+}
+
+class TestConfigWithDefault {
+  @IsBoolean()
+  @TransformBoolean(true)
+  value!: boolean;
+}
+
+describe('TransformBoolean', () => {
+  describe('without default value', () => {
+    it('should transform string "true" to boolean true', () => {
+      const config = plainToInstance(TestConfig, { value: 'true' });
+      expect(config.value).toBe(true);
+    });
+
+    it('should transform string "false" to boolean false', () => {
+      const config = plainToInstance(TestConfig, { value: 'false' });
+      expect(config.value).toBe(false);
+    });
+
+    it('should keep boolean true as true', () => {
+      const config = plainToInstance(TestConfig, { value: true });
+      expect(config.value).toBe(true);
+    });
+
+    it('should keep boolean false as false', () => {
+      const config = plainToInstance(TestConfig, { value: false });
+      expect(config.value).toBe(false);
+    });
+
+    it('should transform other string values to false', () => {
+      const config = plainToInstance(TestConfig, { value: 'yes' });
+      expect(config.value).toBe(false);
+    });
+
+    it('should handle case-insensitive "true"', () => {
+      const config = plainToInstance(TestConfig, { value: 'TRUE' });
+      expect(config.value).toBe(true);
+    });
+
+    it('should handle case-insensitive "True"', () => {
+      const config = plainToInstance(TestConfig, { value: 'True' });
+      expect(config.value).toBe(true);
+    });
+
+    it('should preserve undefined when no default provided', () => {
+      const config = plainToInstance(TestConfig, { value: undefined });
+      expect(config.value).toBeUndefined();
+    });
+
+    it('should preserve null when no default provided', () => {
+      const config = plainToInstance(TestConfig, { value: null });
+      expect(config.value).toBeNull();
+    });
+
+    it('should preserve other types when no default provided', () => {
+      const config = plainToInstance(TestConfig, { value: 123 });
+      expect(config.value).toBe(123);
+    });
+  });
+
+  describe('with default value', () => {
+    it('should use default value for undefined', () => {
+      const config = plainToInstance(TestConfigWithDefault, { value: undefined });
+      expect(config.value).toBe(true);
+    });
+
+    it('should use default value for null', () => {
+      const config = plainToInstance(TestConfigWithDefault, { value: null });
+      expect(config.value).toBe(true);
+    });
+
+    it('should use default value for other types', () => {
+      const config = plainToInstance(TestConfigWithDefault, { value: 123 });
+      expect(config.value).toBe(true);
+    });
+
+    it('should still transform string "true" to boolean true', () => {
+      const config = plainToInstance(TestConfigWithDefault, { value: 'true' });
+      expect(config.value).toBe(true);
+    });
+
+    it('should still transform string "false" to boolean false', () => {
+      const config = plainToInstance(TestConfigWithDefault, { value: 'false' });
+      expect(config.value).toBe(false);
+    });
+
+    it('should still keep boolean true as true', () => {
+      const config = plainToInstance(TestConfigWithDefault, { value: true });
+      expect(config.value).toBe(true);
+    });
+  });
+});

package/src/transform-boolean.decorator.ts

@@ -0,0 +1,29 @@
+import { Transform } from 'class-transformer';
+
+/**
+ * Transforms string values to boolean, preserving existing boolean values.
+ * Useful for environment variable configuration where boolean values may be passed as strings.
+ *
+ * @param defaultValue - Optional default value to return if the value is not a boolean or string.
+ *                       If not provided, the original value is returned unchanged.
+ *
+ * @example
+ * ```typescript
+ * class Config {
+ *   @IsBoolean()
+ *   @TransformBoolean()
+ *   enabled!: boolean;
+ * }
+ * ```
+ */
+export function TransformBoolean(defaultValue?: boolean): PropertyDecorator {
+  return Transform(({ value }) => {
+    if (typeof value === 'boolean') {
+      return value;
+    }
+    if (typeof value === 'string') {
+      return value.toLowerCase() === 'true';
+    }
+    return defaultValue !== undefined ? defaultValue : value;
+  });
+}

package/src/transform-comma-separated.decorator.spec.ts

@@ -0,0 +1,40 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { TransformCommaSeparated } from './transform-comma-separated.decorator';
+
+class TestConfig {
+  @TransformCommaSeparated()
+  value!: string[] | string;
+}
+
+describe('TransformCommaSeparated', () => {
+  it('should transform comma-separated string into array of trimmed strings', () => {
+    const config = plainToInstance(TestConfig, { value: 'GET,POST,DELETE' });
+    expect(config.value).toEqual(['GET', 'POST', 'DELETE']);
+  });
+
+  it('should trim whitespace from each element', () => {
+    const config = plainToInstance(TestConfig, { value: 'a , b , c' });
+    expect(config.value).toEqual(['a', 'b', 'c']);
+  });
+
+  it('should handle single value string', () => {
+    const config = plainToInstance(TestConfig, { value: 'GET' });
+    expect(config.value).toEqual(['GET']);
+  });
+
+  it('should return array as-is when value is already an array', () => {
+    const config = plainToInstance(TestConfig, { value: ['a', 'b'] });
+    expect(config.value).toEqual(['a', 'b']);
+  });
+
+  it('should handle empty string', () => {
+    const config = plainToInstance(TestConfig, { value: '' });
+    expect(config.value).toEqual(['']);
+  });
+
+  it('should handle string with only whitespace', () => {
+    const config = plainToInstance(TestConfig, { value: '  ' });
+    expect(config.value).toEqual(['']);
+  });
+});

package/src/transform-comma-separated.decorator.ts

@@ -0,0 +1,16 @@
+import { Transform } from 'class-transformer';
+
+/**
+ * Transforms a comma-separated string into an array of trimmed strings.
+ * If the value is already an array, it is returned as-is.
+ *
+ * @example
+ * // Input: "GET,POST,DELETE" → Output: ["GET", "POST", "DELETE"]
+ * // Input: "a , b , c" → Output: ["a", "b", "c"]
+ * // Input: ["a", "b"] → Output: ["a", "b"]
+ */
+export function TransformCommaSeparated(): PropertyDecorator {
+  return Transform(({ value }) =>
+    typeof value === 'string' ? value.split(',').map((s) => s.trim()) : value,
+  );
+}

package/src/validation.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { ValidationService } from './validation.service';
+
+@Module({
+  providers: [ValidationService],
+  exports: [ValidationService],
+})
+export class ValidationModule {}

package/src/validation.service.spec.ts

@@ -0,0 +1,170 @@
+import { BadRequestException } from '@nestjs/common';
+import { ValidationService } from './validation.service';
+import { IsString, IsOptional, Length, IsEmail } from 'class-validator';
+
+class TestDto {
+  @IsString()
+  @Length(1, 10)
+  name: string;
+
+  @IsEmail()
+  email: string;
+
+  @IsOptional()
+  @IsString()
+  description?: string;
+}
+
+describe('ValidationService', () => {
+  let service: ValidationService;
+
+  beforeEach(() => {
+    service = new ValidationService();
+  });
+
+  describe('validateDto', () => {
+    it('should validate a valid DTO successfully', async () => {
+      const data = {
+        name: 'test',
+        email: 'test@example.com',
+        description: 'optional field',
+      };
+
+      const result = await service.validateDto(TestDto, data);
+
+      expect(result).toBeInstanceOf(TestDto);
+      expect(result.name).toBe('test');
+      expect(result.email).toBe('test@example.com');
+      expect(result.description).toBe('optional field');
+    });
+
+    it('should validate a valid DTO with optional fields missing', async () => {
+      const data = {
+        name: 'test',
+        email: 'test@example.com',
+      };
+
+      const result = await service.validateDto(TestDto, data);
+
+      expect(result).toBeInstanceOf(TestDto);
+      expect(result.name).toBe('test');
+      expect(result.email).toBe('test@example.com');
+      expect(result.description).toBeUndefined();
+    });
+
+    it('should throw BadRequestException for invalid string length', async () => {
+      const data = {
+        name: 'this name is too long',
+        email: 'test@example.com',
+      };
+
+      await expect(service.validateDto(TestDto, data)).rejects.toThrow(BadRequestException);
+    });
+
+    it('should throw BadRequestException for invalid email', async () => {
+      const data = {
+        name: 'test',
+        email: 'invalid-email',
+      };
+
+      await expect(service.validateDto(TestDto, data)).rejects.toThrow(BadRequestException);
+    });
+
+    it('should throw BadRequestException for missing required fields', async () => {
+      const data = {
+        name: 'test',
+      };
+
+      await expect(service.validateDto(TestDto, data)).rejects.toThrow(BadRequestException);
+    });
+
+    it('should combine multiple validation errors', async () => {
+      const data = {
+        name: 'this name is way too long for validation',
+        email: 'invalid-email',
+      };
+
+      try {
+        await service.validateDto(TestDto, data);
+        fail('Should have thrown BadRequestException');
+      } catch (error) {
+        expect(error).toBeInstanceOf(BadRequestException);
+        const message = (error as BadRequestException).message;
+        expect(message).toContain('name must be shorter than or equal to 10 characters');
+        expect(message).toContain('email must be an email');
+      }
+    });
+
+    it('should handle empty data', async () => {
+      const data = {};
+
+      await expect(service.validateDto(TestDto, data)).rejects.toThrow(BadRequestException);
+    });
+
+    it('should handle null data', async () => {
+      const data = null;
+
+      await expect(service.validateDto(TestDto, data)).rejects.toThrow(BadRequestException);
+    });
+  });
+
+  describe('validateInstance', () => {
+    it('should validate a valid instance successfully', async () => {
+      const instance = new TestDto();
+      instance.name = 'test';
+      instance.email = 'test@example.com';
+
+      await expect(service.validateInstance(instance)).resolves.toBeUndefined();
+    });
+
+    it('should throw BadRequestException for invalid instance', async () => {
+      const instance = new TestDto();
+      instance.name = 'this name is too long';
+      instance.email = 'invalid-email';
+
+      await expect(service.validateInstance(instance)).rejects.toThrow(BadRequestException);
+    });
+
+    it('should handle instance with missing required fields', async () => {
+      const instance = new TestDto();
+      instance.name = 'test';
+
+      await expect(service.validateInstance(instance)).rejects.toThrow(BadRequestException);
+    });
+  });
+
+  describe('error message formatting', () => {
+    it('should format single error correctly', async () => {
+      const data = {
+        name: 'test',
+        email: 'invalid-email',
+      };
+
+      try {
+        await service.validateDto(TestDto, data);
+        fail('Should have thrown BadRequestException');
+      } catch (error) {
+        expect(error).toBeInstanceOf(BadRequestException);
+        expect(error.message).toBe('email must be an email');
+      }
+    });
+
+    it('should format multiple errors with semicolon separator', async () => {
+      const data = {
+        name: '',
+        email: 'invalid',
+      };
+
+      try {
+        await service.validateDto(TestDto, data);
+        fail('Should have thrown BadRequestException');
+      } catch (error) {
+        expect(error).toBeInstanceOf(BadRequestException);
+        const message = (error as BadRequestException).message;
+        expect(message).toContain(';');
+        expect(message).toContain('name must be longer than or equal to 1 characters');
+        expect(message).toContain('email must be an email');
+      }
+    });
+  });
+});

package/src/validation.service.ts

@@ -0,0 +1,55 @@
+import { Injectable, BadRequestException } from '@nestjs/common';
+import { validate, ValidationError } from 'class-validator';
+import { plainToInstance, ClassConstructor } from 'class-transformer';
+
+@Injectable()
+export class ValidationService {
+  async validateDto<T extends object>(dtoClass: ClassConstructor<T>, data: unknown): Promise<T> {
+    if (data === null || data === undefined) {
+      throw new BadRequestException('Data cannot be null or undefined');
+    }
+
+    const dtoInstance = plainToInstance(dtoClass, data);
+    const validationErrors = await validate(dtoInstance as object);
+
+    if (validationErrors.length > 0) {
+      const errorMessages = this.formatValidationErrors(validationErrors);
+      throw new BadRequestException(errorMessages);
+    }
+
+    return dtoInstance;
+  }
+
+  async validateInstance<T extends object>(instance: T): Promise<void> {
+    const validationErrors = await validate(instance as object);
+
+    if (validationErrors.length > 0) {
+      const errorMessages = this.formatValidationErrors(validationErrors);
+      throw new BadRequestException(errorMessages);
+    }
+  }
+
+  private formatValidationErrors(errors: ValidationError[]): string {
+    return errors
+      .map((error) => this.extractErrorMessage(error))
+      .filter((message) => message.length > 0)
+      .join('; ');
+  }
+
+  private extractErrorMessage(error: ValidationError): string {
+    const messages: string[] = [];
+
+    if (error.constraints) {
+      messages.push(...Object.values(error.constraints));
+    }
+
+    if (error.children && error.children.length > 0) {
+      const childMessages = error.children
+        .map((child) => this.extractErrorMessage(child))
+        .filter((message) => message.length > 0);
+      messages.push(...childMessages);
+    }
+
+    return messages.join(', ');
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ],
+  "compilerOptions": {
+    "esModuleInterop": true
+  }
+}

package/tsconfig.lib.json

@@ -0,0 +1,14 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "module": "commonjs",
+    "types": ["node"],
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "target": "ES2021"
+  },
+  "exclude": ["node_modules", "**/*.spec.ts", "**/*.test.ts"],
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["node", "jest"],
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "target": "ES2021"
+  },
+  "include": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}