@elsikora/nestjs-crud-automator 1.6.4 → 1.6.5

package/README.md

@@ -1,341 +1,456 @@
-# API Controller Configuration Documentation
+<p align="center">
+  <img src="https://6jft62zmy9nx2oea.public.blob.vercel-storage.com/nestjs-crud-automator-HhXThTDhKyqznMLCgdmWhsPa287fIi.png" width="500" alt="project-logo">
+</p>
 
-## Overview
+<h1 align="center">🚀 NestJS-Crud-Automator</h1>
+<p align="center"><em>A powerful library for automating CRUD operations in NestJS applications</em></p>
 
-The API Controller configuration is a TypeScript-based configuration system that provides a comprehensive way to define API endpoints with authentication, request/response handling, validation, and data transformation capabilities.
+<p align="center">
+    <a aria-label="ElsiKora logo" href="https://elsikora.com">
+  <img src="https://img.shields.io/badge/MADE%20BY%20ElsiKora-333333.svg?style=for-the-badge" alt="ElsiKora">
+</a> <img src="https://img.shields.io/badge/version-blue.svg?style=for-the-badge&logo=npm&logoColor=white" alt="version"> <img src="https://img.shields.io/badge/typescript-blue.svg?style=for-the-badge&logo=typescript&logoColor=white" alt="typescript"> <img src="https://img.shields.io/badge/nestjs-red.svg?style=for-the-badge&logo=nestjs&logoColor=white" alt="nestjs"> <img src="https://img.shields.io/badge/typeorm-orange.svg?style=for-the-badge&logo=database&logoColor=white" alt="typeorm"> <img src="https://img.shields.io/badge/license-green.svg?style=for-the-badge&logo=license&logoColor=white" alt="license">
+</p>
 
-## Table of Contents
 
-- [Basic Configuration Structure](#basic-configuration-structure)
-- [Route Configuration](#route-configuration)
-- [Authentication](#authentication)
-- [Request Handling](#request-handling)
-- [Response Handling](#response-handling)
-- [Data Transformation](#data-transformation)
-- [Validation](#validation)
-- [Relations Management](#relations-management)
-- [Auto DTO Configuration](#auto-dto-configuration)
+## 📚 Table of Contents
+- [Description](#-description)
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [Roadmap](#-roadmap)
+- [FAQ](#-faq)
+- [License](#-license)
 
-## Basic Configuration Structure
 
-The base configuration object follows this interface:
+## 📖 Description
+NestJS-Crud-Automator is a comprehensive library designed to reduce boilerplate code and accelerate development by automatically generating fully-featured CRUD operations for NestJS applications. By leveraging TypeORM entities and built-in decorators, developers can quickly scaffold controllers and services with standardized endpoints for creating, reading, updating, and deleting resources. The library provides rich validation, sophisticated request/response transformation, automatic Swagger documentation, and supports complex filtering operations for list endpoints. NestJS-Crud-Automator is ideal for enterprise applications, microservices architectures, and any project where consistent API design and reduced development time are priorities.
 
-```typescript
-interface IApiControllerProperties<E> {
-	entity: IApiBaseEntity;
-	name?: string;
-	path?: string;
-	routes: {
-		[R in EApiRouteType]?: TApiControllerPropertiesRoute<E, R>;
-	};
-}
-```
+## 🚀 Features
+- ✨ **Zero-configuration CRUD controllers with automatic Swagger documentation**
+- ✨ **Smart DTO generation for requests, responses, and query parameters**
+- ✨ **Advanced filtering system with support for complex query operations**
+- ✨ **Request transformation and validation pipeline**
+- ✨ **Authentication and authorization integration**
+- ✨ **Automatic relations handling with configurable loading strategies**
+- ✨ **Comprehensive TypeScript support with full type safety**
+- ✨ **Customizable error handling with correlation IDs for tracing**
+- ✨ **Efficient throttling support to prevent API abuse**
+- ✨ **ESM and CommonJS module support**
 
-### Properties:
+## 🛠 Installation
+```bash
+# Using npm
+npm install @elsikora/nestjs-crud-automator
 
-- `entity`: The base entity class for the controller
-- `name`: Optional name for the controller
-- `path`: Optional URL path for the controller
-- `routes`: Object containing route configurations
+# Using yarn
+yarn add @elsikora/nestjs-crud-automator
 
-## Route Configuration
+# Using pnpm
+pnpm add @elsikora/nestjs-crud-automator
 
-Routes are defined using the `EApiRouteType` enum, which includes:
+# Using bun
+bun add @elsikora/nestjs-crud-automator
 
-- CREATE
-- GET
-- GET_LIST
-- UPDATE
-- PARTIAL_UPDATE
-- DELETE
 
-Each route can be configured with:
+Ensure you have the required peer dependencies installed:
 
-- Authentication settings
-- Request handling
-- Response handling
-- Data transformations
-- Validation rules
 
-Example:
-
-```typescript
-{
-    [EApiRouteType.CREATE]: {
-        authentication: {...},
-        request: {...},
-        response: {...}
-    }
-}
+npm install @nestjs/common @nestjs/swagger typeorm class-transformer class-validator reflect-metadata
 ```
 
-## Authentication
+## 💡 Usage
+## Basic Usage
+
+NestJS-Crud-Automator provides a set of decorators that automate the creation of controllers and services for your entities.
 
-Authentication configuration allows you to specify:
+### Entity Definition
 
-- Bearer token strategies
-- Security strategies
-- Authentication guards
-- Authentication type
+First, define your TypeORM entity with the `ApiPropertyDescribe` decorators to provide metadata for Swagger and validation:
 
 ```typescript
-interface IApiControllerPropertiesRouteAuthentication {
-	bearerStrategies?: Array<string>;
-	guard: Type<IAuthGuard>;
-	securityStrategies?: Array<string>;
-	type: EApiAuthenticationType;
+import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
+import { ApiPropertyDescribe } from '@elsikora/nestjs-crud-automator';
+import { EApiPropertyDescribeType, EApiPropertyStringType } from '@elsikora/nestjs-crud-automator';
+
+@Entity('users')
+export class User {
+  @PrimaryGeneratedColumn('uuid')
+  @ApiPropertyDescribe({
+    type: EApiPropertyDescribeType.UUID,
+    description: 'Unique identifier'
+  })
+  id: string;
+
+  @Column()
+  @ApiPropertyDescribe({
+    type: EApiPropertyDescribeType.STRING,
+    description: 'User name',
+    format: EApiPropertyStringType.STRING,
+    minLength: 3,
+    maxLength: 50,
+    pattern: '/^[a-zA-Z0-9_-]+$/',
+    exampleValue: 'john_doe'
+  })
+  username: string;
+
+  @Column()
+  @ApiPropertyDescribe({
+    type: EApiPropertyDescribeType.STRING,
+    description: 'User email',
+    format: EApiPropertyStringType.EMAIL,
+    minLength: 5,
+    maxLength: 100,
+    pattern: '/^[\w-\.]+@([\w-]+\.)+[\w-]{2,}$/',
+    exampleValue: 'john@example.com'
+  })
+  email: string;
 }
 ```
 
-Example:
+### Service Implementation
+
+Create a service that extends the base functionality:
 
 ```typescript
-authentication: {
-    bearerStrategies: ["accountAuthorization"],
-    guard: AccountGuard,
-    securityStrategies: ["accountRequestSignature", "accountRequestTimestamp"],
-    type: EApiAuthenticationType.ACCOUNT
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { ApiServiceBase, ApiService } from '@elsikora/nestjs-crud-automator';
+import { User } from './user.entity';
+
+@Injectable()
+@ApiService({
+  entity: User
+})
+export class UserService extends ApiServiceBase<User> {
+  constructor(
+    @InjectRepository(User)
+    public repository: Repository<User>
+  ) {
+    super();
+  }
+  
+  // You can override the default methods or add custom methods
+  async findByEmail(email: string): Promise<User | undefined> {
+    return this.repository.findOne({
+      where: { email }
+    });
+  }
 }
 ```
 
-## Request Handling
-
-Request configuration includes:
+### Controller Implementation
 
-- Relations loading
-- Data transformation
-- Request validation
+Implement a controller with automatic CRUD endpoints:
 
 ```typescript
-interface IApiControllerPropertiesRouteBaseRequest<E, R> {
-	relations?: TApiControllerPropertiesRouteBaseRequestRelations<E>;
-	transformers?: TApiControllerPropertiesRouteBaseRequestTransformers<E, R>;
-	validators?: Array<IApiRequestValidator<E>>;
+import { Controller } from '@nestjs/common';
+import { ApiController } from '@elsikora/nestjs-crud-automator';
+import { User } from './user.entity';
+import { UserService } from './user.service';
+
+@ApiController({
+  entity: User,
+  name: 'Users',
+  path: 'users',
+  routes: {
+    // Configure routes (all enabled by default)
+  }
+})
+@Controller('users')
+export class UserController {
+  constructor(public service: UserService) {}
 }
 ```
 
-### Relations Loading Strategies
+## Advanced Configuration
 
-Two strategies are available:
+### Custom Route Configuration
 
-1. **AUTO**: Automatically loads relations
-2. **MANUAL**: Manually specify relations to load
+Customize each route with authentication, validation, and transformation:
 
 ```typescript
-relations: {
-    loadRelations: true,
-    relationsLoadStrategy: EApiControllerLoadRelationsStrategy.MANUAL,
-    relationsToLoad: ["bank"],
-    servicesLoadStrategy: EApiControllerLoadRelationsStrategy.MANUAL,
-    relationsServices: {
-        bank: "bankService"
+import { JwtAuthGuard } from '../auth/jwt-auth.guard';
+import { EApiControllerLoadRelationsStrategy, EApiAuthenticationType, EApiDtoType, EApiRouteType } from '@elsikora/nestjs-crud-automator';
+
+@ApiController({
+  entity: User,
+  name: 'Users',
+  path: 'users',
+  routes: {
+    [EApiRouteType.CREATE]: {
+      authentication: {
+        guard: JwtAuthGuard,
+        type: EApiAuthenticationType.USER,
+        bearerStrategies: ['jwt']
+      },
+      request: {
+        validators: [
+          {
+            errorType: EErrorStringAction.VALIDATION_ERROR,
+            exception: BadRequestException,
+            validationFunction: (body: Partial<User>) => {
+              return body.username && body.username.length >= 3;
+            }
+          }
+        ],
+        transformers: {
+          [EApiDtoType.BODY]: [
+            {
+              key: 'createdAt',
+              type: EApiControllerRequestTransformerType.DYNAMIC,
+              value: TRANSFORMER_VALUE_DTO_CONSTANT.REQUEST_TIMESTAMP
+            }
+          ]
+        }
+      }
+    },
+    [EApiRouteType.GET_LIST]: {
+      request: {
+        relations: {
+          shouldLoadRelations: true,
+          relationsLoadStrategy: EApiControllerLoadRelationsStrategy.AUTO,
+          servicesLoadStrategy: EApiControllerLoadRelationsStrategy.AUTO
+        }
+      }
     }
-}
+  }
+})
 ```
 
-## Response Handling
-
-Response configuration allows you to:
+### Working with Relations
 
-- Specify relations to include
-- Transform response data
+Configure automatic loading of relations:
 
 ```typescript
-interface IApiControllerPropertiesRouteBaseResponse<E, R> {
-	relations?: FindOptionsRelations<E>;
-	transformers?: TApiControllerPropertiesRouteBaseResponseTransformers<E, R>;
+import { Entity, PrimaryGeneratedColumn, Column, ManyToOne, OneToMany } from 'typeorm';
+import { ApiPropertyDescribe } from '@elsikora/nestjs-crud-automator';
+import { EApiPropertyDescribeType } from '@elsikora/nestjs-crud-automator';
+
+@Entity('posts')
+export class Post {
+  @PrimaryGeneratedColumn('uuid')
+  @ApiPropertyDescribe({
+    type: EApiPropertyDescribeType.UUID,
+    description: 'Post ID'
+  })
+  id: string;
+  
+  @Column()
+  @ApiPropertyDescribe({
+    type: EApiPropertyDescribeType.STRING,
+    // configuration...
+  })
+  title: string;
+  
+  @ManyToOne(() => User)
+  @ApiPropertyDescribe({
+    type: EApiPropertyDescribeType.RELATION,
+    description: 'Post author'
+  })
+  author: User;
 }
-```
-
-Example:
 
-```typescript
-response: {
-    relations: {
-        bank: true,
-        currency: true
-    },
-    transformers: {
-        [EApiDtoType.RESPONSE]: [
-            {
-                key: "user",
-                type: EApiControllerRequestTransformerType.DYNAMIC,
-                value: TRANSFORMER_VALUE_DTO_CONSTANT.REQUEST_IP
-            }
-        ]
+// In controller:
+@ApiController({
+  entity: Post,
+  name: 'Posts',
+  path: 'posts',
+  routes: {
+    [EApiRouteType.GET]: {
+      request: {
+        relations: {
+          shouldLoadRelations: true,
+          relationsLoadStrategy: EApiControllerLoadRelationsStrategy.MANUAL,
+          relationsToLoad: ['author'],
+          servicesLoadStrategy: EApiControllerLoadRelationsStrategy.MANUAL,
+          relationsServices: {
+            author: 'userService'
+          }
+        }
+      }
     }
+  }
+})
+export class PostController {
+  constructor(
+    public service: PostService,
+    public userService: UserService
+  ) {}
 }
 ```
 
-## Data Transformation
+## Advanced Filtering
 
-Transformers can be configured for different DTO types:
-
-- BODY
-- QUERY
-- REQUEST
-- RESPONSE
-
-Two types of transformers are available:
-
-1. **DYNAMIC**: Uses predefined constants
-2. **STATIC**: Uses static values
+The GET_LIST endpoint supports sophisticated filtering operations:
 
 ```typescript
-type TApiRequestTransformer<E> = {
-	key: keyof IApiGetListResponseResult<E> | keyof Partial<E> | keyof TApiFunctionGetListProperties<E>;
-} & (
-	| {
-			type: EApiControllerRequestTransformerType.DYNAMIC;
-			value: (typeof TRANSFORMER_VALUE_DTO_CONSTANT)[keyof typeof TRANSFORMER_VALUE_DTO_CONSTANT];
-	  }
-	| {
-			type: EApiControllerRequestTransformerType.STATIC;
-			value: string;
-	  }
-);
+// Request example for filtering
+// GET /users?page=1&limit=10&orderBy=createdAt&orderDirection=desc&username[operator]=cont&username[value]=john&createdAt[operator]=between&createdAt[values]=["2023-01-01","2023-12-31"]
 ```
 
-## Validation
-
-Validators can be configured for requests with:
-
-- Error type
-- Exception class
-- Validation function
+Supported operations include:
+- `eq` - Equal
+- `ne` - Not equal
+- `gt` - Greater than
+- `gte` - Greater than or equal
+- `lt` - Less than
+- `lte` - Less than or equal
+- `in` - In array
+- `notin` - Not in array
+- `cont` - Contains (for strings)
+- `starts` - Starts with
+- `ends` - Ends with
+- `isnull` - Is null
+- `notnull` - Is not null
+- `between` - Between two values
+
+## Custom DTOs and Validation
+
+You can provide custom DTOs instead of auto-generated ones:
 
 ```typescript
-interface IApiRequestValidator<E> {
-	errorType: EErrorStringAction;
-	exception: TApiException;
-	validationFunction: (entity: DeepPartial<E> | Partial<E> | TApiFunctionGetListProperties<E>) => boolean | Promise<boolean>;
+import { IsEmail, IsString, MinLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty()
+  @IsString()
+  @MinLength(3)
+  username: string;
+  
+  @ApiProperty()
+  @IsEmail()
+  email: string;
 }
-```
-
-Example:
 
-```typescript
-validators: [
-	{
-		errorType: EErrorStringAction.ADDRESS_NOT_MATCH_PATTERN,
-		exception: BadRequestException,
-		validationFunction: (account: Partial<Account>): boolean => (account.id?.includes("7") ? account.id.includes("AAAA") : true),
-	},
-];
+// In controller:
+@ApiController({
+  entity: User,
+  name: 'Users',
+  path: 'users',
+  routes: {
+    [EApiRouteType.CREATE]: {
+      dto: {
+        body: CreateUserDto,
+        response: UserResponseDto
+      }
+    }
+  }
+})
 ```
 
-## Auto DTO Configuration
+## Throttling and Rate Limiting
 
-Auto DTO allows automatic Data Transfer Object configuration:
+Implement rate limiting on endpoints:
 
 ```typescript
-autoDto?: {
-    [key in EApiDtoType]?: IApiControllerPropertiesRouteAutoDtoConfig;
-};
-```
+import { EApiRouteType } from '@elsikora/nestjs-crud-automator';
 
-Example:
-
-```typescript
-autoDto: {
-    [EApiDtoType.REQUEST]: {
-        validators: [
-            {
-                constraintClass: HasAtLeastOneOfListedProperties,
-                options: ["hybrid", "currencyId"]
-            }
-        ]
+@ApiController({
+  entity: User,
+  name: 'Users',
+  path: 'users',
+  routes: {
+    [EApiRouteType.CREATE]: {
+      // Apply method-level throttling
+      decorators: [
+        ApiMethod({
+          throttler: {
+            limit: 5,
+            ttl: 60000 // 1 minute
+          }
+        })
+      ]
     }
-}
+  }
+})
 ```
 
-## Usage Example
+## Correlation ID for Request Tracing
 
-Here's a complete example of a route configuration:
+Use the built-in correlation ID interceptor for request tracing:
 
 ```typescript
-[EApiRouteType.CREATE]: {
-    authentication: {
-        bearerStrategies: ["accountAuthorization"],
-        guard: AccountGuard,
-        securityStrategies: ["accountRequestSignature", "accountRequestTimestamp"],
-        type: EApiAuthenticationType.ACCOUNT
-    },
-    request: {
-        relations: {
-            loadRelations: true,
-            relationsLoadStrategy: EApiControllerLoadRelationsStrategy.MANUAL,
-            relationsServices: {
-                bank: "bankService"
-            },
-            relationsToLoad: ["bank"],
-            servicesLoadStrategy: EApiControllerLoadRelationsStrategy.MANUAL
-        },
-        transformers: {
-            [EApiDtoType.BODY]: [
-                {
-                    key: "user",
-                    type: EApiControllerRequestTransformerType.DYNAMIC,
-                    value: TRANSFORMER_VALUE_DTO_CONSTANT.AUTHORIZED_ENTITY
-                }
-            ]
-        },
-        validators: [
-            {
-                errorType: EErrorStringAction.ADDRESS_NOT_MATCH_PATTERN,
-                exception: BadRequestException,
-                validationFunction: (account: Partial<Account>): boolean =>
-                    (account.id?.includes("7") ? account.id.includes("AAAA") : true)
-            }
-        ]
+import { CorrelationIDResponseBodyInterceptor } from '@elsikora/nestjs-crud-automator';
+
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: CorrelationIDResponseBodyInterceptor,
     },
-    response: {
-        relations: {
-            bank: true,
-            currency: true
-        },
-        transformers: {
-            [EApiDtoType.RESPONSE]: [
-                {
-                    key: "user",
-                    type: EApiControllerRequestTransformerType.DYNAMIC,
-                    value: TRANSFORMER_VALUE_DTO_CONSTANT.REQUEST_IP
-                }
-            ]
-        }
-    }
-}
+  ],
+})
+export class AppModule {}
 ```
 
-## Best Practices
-
-1. **Authentication**
-
-   - Always specify appropriate bearer and security strategies
-   - Use proper guards for route protection
-   - Choose the correct authentication type
-
-2. **Relations**
-
-   - Use MANUAL strategy when you need precise control over relation loading
-   - Use AUTO strategy for simpler cases
-   - Always specify required services when using MANUAL strategy
-
-3. **Validation**
-
-   - Implement comprehensive validation rules
-   - Use appropriate error types and exceptions
-   - Consider both sync and async validation functions
-
-4. **Transformation**
-   - Use DYNAMIC transformers for runtime values
-   - Use STATIC transformers for constant values
-   - Consider the DTO type when applying transformations
-
-## Notes
-
-- All configurations are type-safe with TypeScript
-- Relations loading can be controlled at a granular level
-- Transformers can be applied at multiple stages of request/response handling
-- Validation can be both synchronous and asynchronous
-- Auto DTO configuration provides a simplified way to handle data transfer objects
+This will ensure all responses and errors include a correlation ID for tracing through logs.
+
+## 🛣 Roadmap
+| Task / Feature | Status |
+|---------------|--------|
+| ## Future Development | 🚧 In Progress |
+| - GraphQL support with automatic query and mutation generation | 🚧 In Progress |
+| - Integration with NestJS caching mechanisms | 🚧 In Progress |
+| - Extension to support NoSQL databases beyond TypeORM | 🚧 In Progress |
+| - Event sourcing support for audit logging | 🚧 In Progress |
+| - Expanded filtering capabilities with full-text search | 🚧 In Progress |
+| - Integration with file upload handling | 🚧 In Progress |
+| - Custom response serialization strategies | 🚧 In Progress |
+| - Enhanced performance optimization options | 🚧 In Progress |
+| - More comprehensive test utilities | 🚧 In Progress |
+| - Custom pagination strategies | 🚧 In Progress |
+| (done) Zero-configuration CRUD controllers with automatic Swagger documentation | 🚧 In Progress |
+| (done) Smart DTO generation for requests, responses, and query parameters | 🚧 In Progress |
+| (done) Advanced filtering system with support for complex query operations | 🚧 In Progress |
+
+## ❓ FAQ
+## Frequently Asked Questions
+
+### Does this library work with NestJS microservices?
+Yes, NestJS-Crud-Automator is designed to work with both monolithic NestJS applications and microservices architectures.
+
+### How does performance compare to manually written controllers?
+The library is optimized for performance and should have minimal overhead compared to manually written controllers. In many cases, the standardized patterns may even lead to better performance through consistent implementations.
+
+### Can I use this with custom database schemas?
+Yes, as long as you use TypeORM, the library works with any valid entity configuration, including custom database schemas.
+
+### How can I extend the automatically generated endpoints?
+You can always add additional methods to your controller that handle special cases or extend the functionality of the auto-generated endpoints.
+
+### Is there a way to disable certain CRUD operations?
+Yes, you can disable any operation by setting `isEnabled: false` in the route configuration object.
+
+### How does this library handle transactions?
+The library uses TypeORM's underlying transaction mechanisms. You can implement transaction handling in your custom service methods.
+
+### Does this work with MongoDB?
+Yes, as long as you use TypeORM with MongoDB, the library should work properly with MongoDB entities.
+
+### How can I migrate from the base NestJS CRUD module?
+The library provides a significantly different API from NestJS's CRUD module, so migration will require changing your decorators and service implementations. However, the entity structure can remain largely the same.
+
+## 🔒 License
+This project is licensed under **MIT License
+
+Copyright (c) 2025 ElsiKora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.**.