├── .auto-changelog ├── .github └── workflows │ └── publish.yml ├── .gitignore ├── .husky ├── .gitignore └── pre-commit ├── .lintstagedrc.json ├── .npmrc ├── README.md ├── cspell.json ├── eslint.config.js ├── lib ├── constants │ └── upload-file.constant.ts ├── decorators │ ├── enums.decorators.ts │ ├── id.decorator.ts │ ├── number.decorator.ts │ ├── pagination.decorator.ts │ ├── query-boolean.decorator.ts │ ├── query-strings.decorator.ts │ ├── real-ip.decorators.ts │ ├── require-upload-file.decorator.ts │ ├── require-upload-files.decorator.ts │ ├── sort.decorator.ts │ ├── sorts.decorator.ts │ ├── timestamp.decorator.ts │ ├── timezone.decorator.ts │ ├── user-agent.decorator.ts │ └── value.decorator.ts ├── filters │ └── file-upload.filter.ts ├── helpers │ ├── file.helper.ts │ ├── get-params.helper.ts │ └── sort.helper.ts ├── index.ts ├── interceptors │ ├── require-upload-file-interceptor.ts │ └── require-upload-files-interceptor.ts ├── interfaces │ ├── and-where-query.interface.ts │ └── custom-condition.interface.ts ├── types │ ├── column-type.type.ts │ ├── file-upload-configurations.type.ts │ ├── file-upload-options.type.ts │ ├── file-upload-params.type.ts │ ├── files-upload-params.type.ts │ ├── multer-options.type.ts │ ├── sort-direction.type.ts │ ├── sort-params.type.ts │ └── sorts-params.type.ts └── validators │ ├── exist-ids.validator.ts │ ├── exists.validator.ts │ └── unique.validator.ts ├── nest-cli.json ├── package-lock.json ├── package.json ├── prettier.config.js ├── renovate.json ├── sample ├── app.controller.ts ├── app.enum.ts ├── app.module.ts ├── i18n │ └── en │ │ ├── error.json │ │ └── validation.json └── main.ts ├── tsconfig.build.json └── tsconfig.json /.auto-changelog: -------------------------------------------------------------------------------- 1 | { 2 | "output": "CHANGELOG.md", 3 | "template": "keepachangelog", 4 | "unreleased": true, 5 | "ignoreCommitPattern": "^(?!(feat|fix|\\[feat\\]|\\[fix\\]))(.*)$", 6 | "commitLimit": false, 7 | "commitUrl": "https://github.com/hodfords-solutions/nestjs-base-decorator/commit/{id}" 8 | } -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Publish Package to npmjs 2 | on: 3 | push: 4 | branches: 5 | - main 6 | jobs: 7 | lint: 8 | uses: hodfords-solutions/actions/.github/workflows/lint.yaml@main 9 | build: 10 | uses: hodfords-solutions/actions/.github/workflows/publish.yaml@main 11 | with: 12 | build_path: dist/lib 13 | secrets: 14 | NPM_TOKEN: ${{ secrets.NPM_TOKEN }} 15 | update-docs: 16 | uses: hodfords-solutions/actions/.github/workflows/update-doc.yaml@main 17 | needs: build 18 | secrets: 19 | DOC_SSH_PRIVATE_KEY: ${{ secrets.DOC_SSH_PRIVATE_KEY }} 20 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # compiled output 2 | /dist 3 | /node_modules 4 | 5 | # Logs 6 | logs 7 | *.log 8 | npm-debug.log* 9 | yarn-debug.log* 10 | yarn-error.log* 11 | lerna-debug.log* 12 | 13 | # OS 14 | .DS_Store 15 | 16 | # Tests 17 | /coverage 18 | /.nyc_output 19 | 20 | # IDEs and editors 21 | /.idea 22 | .project 23 | .classpath 24 | .c9/ 25 | *.launch 26 | .settings/ 27 | *.sublime-workspace 28 | 29 | # IDE - VSCode 30 | .vscode/* 31 | !.vscode/settings.json 32 | !.vscode/tasks.json 33 | !.vscode/launch.json 34 | !.vscode/extensions.json 35 | 36 | .env -------------------------------------------------------------------------------- /.husky/.gitignore: -------------------------------------------------------------------------------- 1 | _ 2 | -------------------------------------------------------------------------------- /.husky/pre-commit: -------------------------------------------------------------------------------- 1 | npm run lint-staged 2 | -------------------------------------------------------------------------------- /.lintstagedrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "lib/**/*.ts": ["cspell", "prettier --write", "eslint --fix --max-warnings 0"] 3 | } 4 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} 2 | registry=https://registry.npmjs.org/ 3 | always-auth=true -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | Nest Logo 3 |

4 | 5 |

6 | Nestjs-Base-Decorator provides a collection of useful, ready-to-use custom decorators for NestJS, designed to enhance and simplify common functionality in your applications. These decorators will help you write cleaner and more maintainable code, reducing the need for repetitive boilerplate. 7 |

8 | 9 | ## Installation 🤖 10 | 11 | To begin using it, we first install the required dependencies. 12 | 13 | ``` 14 | npm install @hodfords/nestjs-base-decorator 15 | ``` 16 | 17 | ## Table of Contents 18 | 19 | - [Installation 🤖](#installation-) 20 | - [Table of Contents](#table-of-contents) 21 | - [Usage 🚀](#usage-) 22 | - [Param Decorators](#param-decorators) 23 | - [@EnumQuery()](#enumquery) 24 | - [@EnumsQuery()](#enumsquery) 25 | - [@Id()](#id) 26 | - [@Ids()](#ids) 27 | - [@Int()](#int) 28 | - [@Ints()](#ints) 29 | - [@Pagination()](#pagination) 30 | - [@QueryBoolean()](#queryboolean) 31 | - [@QueryStrings()](#querystrings) 32 | - [@RealIp()](#realip) 33 | - [@RequireToUploadFile()](#requiretouploadfile) 34 | - [@RequireToUploadFiles()](#requiretouploadfiles) 35 | - [@Sort()](#sort) 36 | - [@Sorts()](#sorts) 37 | - [@Timestamp()](#timestamp) 38 | - [@Timezone()](#timezone) 39 | - [@UserAgent()](#useragent) 40 | - [@Value()](#value) 41 | - [Validators](#validators) 42 | 43 | ## Usage 🚀 44 | 45 | ### Param Decorators 46 | 47 | #### @EnumQuery() 48 | 49 | Use the `EnumQuery` decorator when you expect a single enum value as a query parameter. This will validate the query parameter against a predefined enum and generate Swagger documentation for it. 50 | 51 | Parameters: 52 | 53 | - `options`: 54 | - `key`: The name of the query parameter (required). 55 | - `enum`: The enum to validate against (required). 56 | - `separator`: The delimiter for multiple values (optional, default: `,`). 57 | - `description`: A description for Swagger documentation (optional). 58 | - `nullable`: If true, the query parameter is allowed to be `null` (optional, default: `false`). 59 | - `singleValue`: Only used internally for `EnumQuery` to indicate a single value (you don't need to set this manually). 60 | 61 | Example for usage: 62 | 63 | ```typescript 64 | 65 | import { Controller, Get } from '@nestjs/common'; 66 | import { EnumQuery } from '@hodfords/nestjs-base-decorator'; 67 | 68 | enum StatusEnum { 69 | ACTIVE = 'active', 70 | INACTIVE = 'inactive', 71 | } 72 | 73 | @Controller() 74 | export class ItemController { 75 | @Get('items') 76 | getItemByStatus( 77 | @EnumQuery({ 78 | key: 'status', 79 | enum: StatusEnum, 80 | description: 'Status of the item', 81 | nullable: false, 82 | }) 83 | status: StatusEnum, 84 | ) { 85 | return status; 86 | } 87 | } 88 | 89 | /* 90 | Request: GET /items?status=active 91 | Response: active 92 | */ 93 | ``` 94 | 95 | #### @EnumsQuery() 96 | 97 | Use the `EnumsQuery` decorator when you expect multiple enum values as query parameters, separated by a custom delimiter (default is `,`). This will validate the query parameters against a predefined enum and generate Swagger documentation for them. 98 | 99 | Parameters: 100 | 101 | - `options`: 102 | 103 | - `key`: The name of the query parameter (required). 104 | - `enum`: The enum to validate against (required). 105 | - `separator`: The delimiter for multiple values (optional, default: `,`). 106 | - `description`: A description for Swagger documentation (optional). 107 | - `nullable`: If true, the query parameter is allowed to be `null` (optional, default: `false`). 108 | - `singleValue`: Only used internally for `EnumQuery` to indicate a single value (you don't need to set this manually). 109 | 110 | Example for usage: 111 | 112 | ```typescript 113 | import { Controller, Get } from '@nestjs/common'; 114 | import { EnumsQuery } from '@hodfords/nestjs-base-decorator'; 115 | 116 | enum CategoryEnum { 117 | ELECTRONICS = 'electronics', 118 | FASHION = 'fashion', 119 | BOOKS = 'books', 120 | } 121 | 122 | @Controller() 123 | export class ProductController { 124 | @Get('products') 125 | getProductsByCategories( 126 | @EnumsQuery({ 127 | key: 'categories', 128 | enum: CategoryEnum, 129 | description: 'Categories of the product', 130 | separator: ',', 131 | nullable: false, 132 | }) 133 | categories: CategoryEnum[], 134 | ) { 135 | return categories; 136 | } 137 | } 138 | 139 | /* 140 | Request: GET /products?categories=books,fashion 141 | Response: ["books", "fashion"] 142 | */ 143 | ``` 144 | 145 | #### @Id() 146 | 147 | Use the `Id` decorator to validate a single UUID, either from the route parameters or query parameters. If the provided value is not a valid UUID, it will throw a `UuidException` from the `@hodfords/nestjs-exception` package. 148 | 149 | Parameters: 150 | 151 | - `options` (`string` | `ParamOptions`): 152 | 153 | - `key`: The name of the parameter in the request (required). 154 | - `nullable`: If `true`, the parameter is allowed to be null (optional, default: `false`). 155 | 156 | Example for usage: 157 | 158 | ```typescript 159 | import { Controller, Get } from '@nestjs/common'; 160 | import { Id } from '@hodfords/nestjs-base-decorator'; 161 | 162 | @Controller('users') 163 | export class UserController { 164 | @Get(':id') 165 | getUserById(@Id('id') id: string) { 166 | return id; 167 | } 168 | } 169 | 170 | /* 171 | Request: GET users/8be26127-c0ed-4cad-bd45-7f40dcf53e89 172 | Response: 8be26127-c0ed-4cad-bd45-7f40dcf53e89 173 | */ 174 | ``` 175 | 176 | #### @Ids() 177 | 178 | Use the `Ids` decorator when you need to validate multiple UUIDs passed as a comma-separated list in the `query` parameters. If any value in the list is not a valid UUID, it throws a `UuidException` from the `@hodfords/nestjs-exception` package. 179 | 180 | Parameters: 181 | 182 | - `options` (`string` | `ParamOptions`): 183 | 184 | - `key`: The name of the parameter in the request (required). 185 | - `nullable`: If `true`, the parameter is allowed to be null (optional, default: `false`). 186 | 187 | Example for usage: 188 | 189 | ```typescript 190 | import { Controller, Get } from '@nestjs/common'; 191 | import { Ids } from '@hodfords/nestjs-base-decorator'; 192 | 193 | @Controller('users') 194 | export class UserController { 195 | @Get() 196 | getUsersByIds(@Ids('ids') ids: string[]) { 197 | return ids; 198 | } 199 | } 200 | 201 | /* 202 | Request: GET users?ids=8be26127-c0ed-4cad-bd45-7f40dcf53e89,1b3a0d50-2695-49e7-9498-c4cb1cada6e9 203 | Response: ["8be26127-c0ed-4cad-bd45-7f40dcf53e89","1b3a0d50-2695-49e7-9498-c4cb1cada6e9"] 204 | */ 205 | ``` 206 | 207 | #### @Int() 208 | 209 | The `Int` decorator is used to validate a single integer, either from route parameters or query parameters. 210 | 211 | Parameters: `key` (default: `'id'`) 212 | 213 | Example for usage: 214 | 215 | ```typescript 216 | import { Controller, Get } from '@nestjs/common'; 217 | import { Int } from '@hodfords/nestjs-base-decorator'; 218 | 219 | @Controller('users') 220 | export class UserController { 221 | @Get(':id') 222 | getUserById(@Int('id') id: number) { 223 | return id; 224 | } 225 | } 226 | 227 | /* 228 | Request: GET /users/123 229 | Response: 123 230 | */ 231 | ``` 232 | 233 | #### @Ints() 234 | 235 | The `Ints` decorator is used to validate multiple integers passed as a comma-separated list in query parameters. 236 | 237 | Parameters: `key` (default: `'ids'`) 238 | 239 | Example for usage: 240 | 241 | ```typescript 242 | import { Controller, Get } from '@nestjs/common'; 243 | import { Ints } from '@hodfords/nestjs-base-decorator'; 244 | 245 | @Controller('users') 246 | export class UserController { 247 | @Get() 248 | getUsersByIds(@Ints('ids') ids: number[]) { 249 | return ids; 250 | } 251 | } 252 | 253 | /* 254 | Request: GET /users?ids=123,456 255 | Response: [123,456] 256 | */ 257 | ``` 258 | 259 | #### @Pagination() 260 | 261 | The `Pagination` decorator is used to handle pagination logic by extracting the `page` and `perPage` parameters from the query string of an incoming request. The decorator also includes automatic Swagger documentation using `nestjs/swagger`. 262 | 263 | Parameters: 264 | 265 | - `paginationParams`: 266 | - `page`: The current page number (optional, default: 1). 267 | - `perPage`: The number of items per page (optional, default: 10, max: 1000). 268 | 269 | Example for usage: 270 | 271 | ```typescript 272 | import { Controller, Get } from '@nestjs/common'; 273 | import { Pagination, PaginationParams } from '@hodfords/nestjs-base-decorator'; 274 | 275 | @Controller('users') 276 | export class UserController { 277 | @Get() 278 | getUsers( 279 | @Pagination() pagination: PaginationParams 280 | ) { 281 | return `Page: ${pagination.page}, Per Page: ${pagination.perPage}`; 282 | } 283 | } 284 | 285 | /* 286 | Request: GET /users?page=1&perPage=10 287 | Response: Page: 1, Per Page: 10 288 | */ 289 | ``` 290 | 291 | #### @QueryBoolean() 292 | 293 | The `QueryBoolean` decorator allows you to extract and validate boolean values from the query parameters in a NestJS route. It checks if the query parameter is `'true'` and returns `true`, otherwise it returns `false`. 294 | 295 | Parameters: `key`, `options` (`ApiQueryOptions`) 296 | 297 | Example for usage: 298 | 299 | ```typescript 300 | import { Controller, Get } from '@nestjs/common'; 301 | import { QueryBoolean } from '@hodfords/nestjs-base-decorator'; 302 | 303 | @Controller('users') 304 | export class UsersController { 305 | @Get() 306 | getUsers(@QueryBoolean('isActive') isActive: boolean) { 307 | return isActive; 308 | } 309 | } 310 | 311 | /* 312 | Request: GET /users?isActive=true 313 | Response: true 314 | 315 | Request: GET /users?isActive=123 316 | Response: false 317 | */ 318 | ``` 319 | 320 | #### @QueryStrings() 321 | 322 | The `QueryStrings` decorator extracts query parameters from HTTP requests, parses them as comma-separated strings, and ensures uniqueness by eliminating duplicates. Additionally, it integrates with `@nestjs/swagger` to automatically document the query parameters in the Swagger UI. 323 | 324 | Parameters: `key`, `options` (`ApiQueryOptions`) 325 | 326 | Example for usage: 327 | 328 | ```typescript 329 | import { Controller, Get } from '@nestjs/common'; 330 | import { QueryStrings } from '@hodfords/nestjs-base-decorator'; 331 | 332 | @Controller() 333 | export class AppController { 334 | constructor() {} 335 | 336 | @Get() 337 | findTags(@QueryStrings('tags') tags: string[]): string[] { 338 | return tags; 339 | } 340 | } 341 | 342 | /* 343 | Request: GET ?tags=name,age 344 | Response: ["name, "age"] 345 | */ 346 | ``` 347 | 348 | #### @RealIp() 349 | 350 | The `RealIp` decorator is a custom NestJS decorator that retrieves the client's real IP address from an incoming HTTP request. It leverages the `@supercharge/request-ip` library to accurately identify the IP address, even if the client is behind a proxy or using a load balancer. 351 | 352 | Example for usage: 353 | 354 | ```typescript 355 | import { Controller, Get } from '@nestjs/common'; 356 | import { RealIp } from '@hodfords/nestjs-base-decorator'; 357 | 358 | @Controller('users') 359 | export class UserController { 360 | 361 | @Get('ip') 362 | getClientIp(@RealIp() ip: string): string { 363 | return `Client IP: ${ip}`; 364 | } 365 | } 366 | 367 | /* 368 | Request: GET /ip 369 | Response: "Client IP": "203.0.113.195" 370 | */ 371 | ``` 372 | 373 | #### @RequireToUploadFile() 374 | 375 | The `RequireToUploadFile` decorator is a custom NestJS decorator that simplifies file upload handling for single and multiple file uploads. It leverages NestJS `Interceptors` and custom interceptors to validate file uploads. The decorator allows developers to specify file upload configurations like file size limits, allowed MIME types, and custom storage engines. 376 | 377 | Parameters: 378 | 379 | - `fieldName`: Specifies the form field name used to upload the file(s). 380 | - `options`: An object that configures the file upload behavior. It includes: 381 | - `fileSize`: Maximum file size (in bytes) for the upload. Default is set to `10 * 1024 * 1024`. 382 | - `allowedMimeTypes`: Array of allowed MIME types for the uploaded files. Default is `['image/png', 383 | 'image/jpeg', 384 | 'image/jpg', 385 | 'image/svg+xml', 386 | 'image/bmp', 387 | 'image/heic', 388 | 'image/heif', 389 | 'application/pdf', 390 | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 391 | 'application/vnd.ms-excel']`. 392 | - `maxCount`: Maximum number of files that can be uploaded in a single request. 393 | - `storageEngine`: Custom storage engine for handling uploaded files (e.g., disk storage or cloud storage). 394 | 395 | Example for usage: 396 | 397 | ```typescript 398 | import { Controller, Post, UploadedFiles } from '@nestjs/common'; 399 | import { RequireToUploadFile } from '@hodfords/nestjs-base-decorator'; 400 | 401 | @Controller('files') 402 | export class FileController { 403 | @Post('upload') 404 | @RequireToUploadFile({ fieldName: 'file' }) 405 | uploadFile(@UploadedFiles() file: Express.Multer.File[]) { 406 | return file; 407 | } 408 | } 409 | ``` 410 | 411 | If you want only upload with one file and present it as a object, you can follow below: 412 | 413 | ```typescript 414 | import { Controller, Post, UploadedFile } from '@nestjs/common'; 415 | import { RequireToUploadFile } from '@hodfords/nestjs-base-decorator'; 416 | 417 | @Controller('files') 418 | export class FileController { 419 | @Post('upload') 420 | @RequireToUploadFile({ fieldName: 'file', options: { maxCount: 1 } }) 421 | uploadFile(@UploadedFile() file: Express.Multer.File) { 422 | return file; 423 | } 424 | } 425 | ``` 426 | 427 | #### @RequireToUploadFiles() 428 | 429 | The `RequireToUploadFiles` decorator simplifies the process of uploading multiple files with different field names in NestJS. It uses the `FileFieldsInterceptor` from `@nestjs/platform-express` to manage multiple file uploads from distinct form fields and allows customization through file upload options. The decorator integrates with custom interceptors for additional validation and handling of the uploaded files. 430 | 431 | Parameters: 432 | 433 | - `fieldNames`: 434 | - `name`: The name of the form field. 435 | - `maxCount`: (Optional) Maximum number of files allowed for this field. If not provided, defaults to the global `maxCount` value. 436 | - `options`: 437 | - `fileSize`: Maximum file size (in bytes). 438 | - `allowedMimeTypes`: Array of allowed MIME types for uploaded files. 439 | - `maxCount`: Default maximum number of files allowed per field. 440 | - `storageEngine`: Custom storage engine to handle file uploads. 441 | 442 | Example for usage: 443 | 444 | ```typescript 445 | import { Controller, Post, UploadedFile } from '@nestjs/common'; 446 | import { RequireToUploadFile } from '@hodfords/nestjs-base-decorator'; 447 | 448 | @Controller('files') 449 | export class FileController { 450 | @Post('upload') 451 | @RequireToUploadFiles({ 452 | fieldNames: [ 453 | { name: 'profile', maxCount: 1 }, 454 | { name: 'documents', maxCount: 5 } 455 | ] 456 | }) 457 | uploadUserFiles(@UploadedFiles() files: { profile: Express.Multer.File[]; documents: Express.Multer.File[] }) { 458 | return files; 459 | } 460 | } 461 | ``` 462 | 463 | #### @Sort() 464 | 465 | The `Sort` decorator simplifies handling sorting parameters in NestJS controllers. It defines two query parameters, `sortField` and `sortDirection`, allowing API clients to specify how to sort data in their requests. The decorator integrates with Swagger for automatic API documentation and validates the sorting fields and directions against predefined sets of allowed values. 466 | 467 | Parameters: 468 | 469 | - `sortParams`: 470 | - `allowedFields`: An array of allowed fields for sorting (e.g., `['name', 'createdAt']`). 471 | - `default`: An object with default sorting parameters: 472 | - `sortField`: The default field to sort by. 473 | - `sortDirection`: The default sorting direction (`ASC` or `DESC`). 474 | 475 | Example for usage: 476 | 477 | ```typescript 478 | import { Controller, Get, Query } from '@nestjs/common'; 479 | import { Sort, SortParams } from '@hodfords/nestjs-base-decorator'; 480 | 481 | @Controller('users') 482 | export class UserController { 483 | 484 | @Get() 485 | getUsers(@Sort({ allowedFields: ['name', 'createdAt'], default: { sortField: 'createdAt', sortDirection: 'DESC' } }) query: SortParams) { 486 | const { sortField, sortDirection } = query; 487 | return `Sorted by ${sortField} in ${sortDirection} order`; 488 | } 489 | } 490 | 491 | /* 492 | Request: GET ?sortField=createdAt&sortDirection=DESC 493 | Response: Sorted by createdAt in DESC order 494 | */ 495 | ``` 496 | 497 | #### @Sorts() 498 | 499 | The `Sorts` decorator provides an elegant solution for handling multiple sorting fields in NestJS controllers. It allows clients to specify multiple fields and their respective sort directions. The decorator automatically generates Swagger documentation for these parameters and ensures proper validation of both fields and directions. 500 | 501 | Parameters: 502 | 503 | - `sortParams`: 504 | - `allowedFields`: An array of allowed fields for sorting (e.g., `['name', 'createdAt']`). 505 | - `default`: An object with default sorting parameters: 506 | - `sortField`: The default field to sort by. 507 | - `sortDirection`: The default sorting direction (`ASC` or `DESC`). 508 | 509 | Example for usage: 510 | 511 | ```typescript 512 | import { Controller, Get, Query } from '@nestjs/common'; 513 | import { Sorts, SortMultipleParams } from '@hodfords/nestjs-base-decorator'; 514 | 515 | @Controller('users') 516 | export class UserController { 517 | 518 | @Get() 519 | getUsers( 520 | @Sorts({ allowedFields: ['name', 'createdAt'], default: { sortField: 'createdAt', sortDirection: 'DESC' } }) 521 | query: SortMultipleParams[] 522 | ) { 523 | return query; 524 | } 525 | } 526 | 527 | /* 528 | Request: GET ?sortFields=createdAt,name:DESC 529 | Response: [ 530 | { 531 | "field": "createdAt", 532 | "direction": "ASC" 533 | }, 534 | { 535 | "field": "name", 536 | "direction": "DESC" 537 | } 538 | ] 539 | */ 540 | ``` 541 | 542 | #### @Timestamp() 543 | 544 | The `Timestamp` decorator is used to extract and validate a timestamp from the request parameters or query in a NestJS controller. It ensures the timestamp is valid and handles optional or nullable parameters. 545 | 546 | Parameters: 547 | 548 | - `options`: 549 | - `key`: The name of the parameter to extract (required). 550 | - `nullable`: Indicates if the timestamp can be nullable (optional, default: `false`). 551 | 552 | Example for usage: 553 | 554 | ```typescript 555 | import { Controller, Get, Query } from '@nestjs/common'; 556 | import { Timestamp } from '@hodfords/nestjs-base-decorator'; 557 | 558 | @Controller('events') 559 | export class EventController { 560 | 561 | @Get() 562 | getEvents(@Timestamp('timestamp') timestamp: number) { 563 | return timestamp; 564 | } 565 | } 566 | 567 | /* 568 | Request: GET /events?timestamp=1581739337 569 | Response: 1581739337 570 | */ 571 | ``` 572 | 573 | #### @Timezone() 574 | 575 | The `Timezone` decorator is designed to validate and extract a timezone string from request parameters or query in a NestJS controller. It leverages the `dayjs` library along with the `timezone` and `utc` plugins to ensure that the provided timezone is valid. 576 | 577 | Parameters: 578 | 579 | - `options`: 580 | - `key`: The name of the parameter to extract (required). 581 | - `nullable`: Indicates if the timestamp can be nullable (optional, default: `false`). 582 | 583 | Example for usage: 584 | 585 | ```typescript 586 | import { Controller, Get, Query } from '@nestjs/common'; 587 | import { Timezone } from '@hodfords/nestjs-base-decorator'; 588 | 589 | @Controller('events') 590 | export class EventController { 591 | 592 | @Get() 593 | getEvents(@Timezone('timezone') timezone: string) { 594 | return timezone; 595 | } 596 | } 597 | 598 | /* 599 | Request: GET ?timezone=America/New_York 600 | Response: America/New_York 601 | */ 602 | ``` 603 | 604 | #### @UserAgent() 605 | 606 | The `UserAgent` decorator is a simple utility that extracts the `User-Agent` header from incoming requests in a NestJS application. This header typically contains information about the client's browser, operating system, and device. 607 | 608 | Example for usage: 609 | 610 | ```typescript 611 | import { Controller, Get, Query } from '@nestjs/common'; 612 | import { UserAgent } from '@hodfords/nestjs-base-decorator'; 613 | 614 | @Controller('users') 615 | export class UserController { 616 | 617 | @Get('user-agent') 618 | getUserAgent(@UserAgent() userAgent: string) { 619 | return userAgent; 620 | } 621 | } 622 | ``` 623 | 624 | #### @Value() 625 | 626 | The `Value` decorator is used to extract the `value` property from the payload of a microservice request in NestJS. It is a wrapper around the `Payload` decorator provided by `@nestjs/microservices`, allowing you to directly access the `value` property in microservice message handlers. 627 | 628 | Example for usage: 629 | 630 | ```typescript 631 | import { Controller } from '@nestjs/common'; 632 | import { EventPattern } from '@nestjs/microservices'; 633 | import { Value } from '@hodfords/nestjs-base-decorator'; 634 | 635 | @Controller() 636 | export class MathController { 637 | 638 | @EventPattern('math.add') 639 | handleAddition(@Value() value: number) { 640 | return `Value received: ${value}`; 641 | } 642 | } 643 | 644 | ``` 645 | 646 | ### Validators 647 | 648 | #### @ExistIds() 649 | 650 | The `@ExistIds()` decorator is used to validate whether all provided IDs exist in a specified database table column. It uses `TypeORM` to query the table and check if the given values match the records in the database. 651 | 652 | Parameters: 653 | 654 | - `table`: The `Entity` class (which extends `BaseEntity`) represents the database table where the validation will be performed. 655 | - `allowEmpty`: A boolean to allow empty arrays as valid input (optional, default: `false`). 656 | - `validationOptions`: `ValidationOptions` from `class-validator` to configure custom messages and options. 657 | 658 | Example for usage: 659 | 660 | ```typescript 661 | import { ExistIds } from '@hodfords/nestjs-base-decorator'; 662 | import { Entity } from 'typeorm'; 663 | import { BaseEntity } from '@hodfords/typeorm-helper'; 664 | 665 | @Entity() 666 | export class UserEntity extends BaseEntity { 667 | @PrimaryGeneratedColumn('uuid') 668 | id: string; 669 | } 670 | 671 | class UserRequestDto { 672 | @ExistIds(UserEntity) 673 | userIds: string[]; 674 | } 675 | ``` 676 | 677 | #### @Exists() 678 | 679 | The `@Exists()` decorator is used to validate if a specific value exists in a column of a database table. It supports case-insensitive searches and custom query conditions to allow more flexible validations. 680 | 681 | Parameters: 682 | 683 | - `table`: The `Entity` class (which extends `BaseEntity`) represents the database table where the validation will be performed. 684 | - `column`: The column name in the database to check the existence of the value. 685 | - `caseInsensitive`: A boolean to enable case-insensitive comparison (option, default: `false`). 686 | - `customs`: An array of custom conditions that apply additional filters to the query (optional). 687 | - `validationOptions`: `ValidationOptions` from `class-validator` to configure custom messages and options (optional). 688 | 689 | ```typescript 690 | import { Exists } from '@hodfords/nestjs-base-decorator'; 691 | import { Entity } from 'typeorm'; 692 | import { IsEmail } from 'class-validator'; 693 | import { BaseEntity } from '@hodfords/typeorm-helper'; 694 | 695 | @Entity() 696 | export class UserEntity extends BaseEntity { 697 | @Column() 698 | email: string; 699 | } 700 | 701 | class UserRequestDto { 702 | @Exists(UserEntity, 'email') 703 | @IsEmail() 704 | email: string; 705 | } 706 | ``` 707 | 708 | ## License 709 | 710 | This project is licensed under the MIT License 711 | -------------------------------------------------------------------------------- /cspell.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "0.2", 3 | "language": "en", 4 | "words": [ 5 | "hodfords", 6 | "ILIKE", 7 | "Ints", 8 | "nestjs", 9 | "npmjs", 10 | "officedocument", 11 | "openxmlformats", 12 | "postbuild", 13 | "spreadsheetml", 14 | "typeorm", 15 | "uuidv4" 16 | ], 17 | "flagWords": [ 18 | "hte" 19 | ], 20 | "ignorePaths": [ 21 | "node_modules", 22 | "test", 23 | "*.spec.ts", 24 | "cspell.json" 25 | ] 26 | } 27 | -------------------------------------------------------------------------------- /eslint.config.js: -------------------------------------------------------------------------------- 1 | module.exports = require('@hodfords/nestjs-eslint-config'); 2 | -------------------------------------------------------------------------------- /lib/constants/upload-file.constant.ts: -------------------------------------------------------------------------------- 1 | export const FILES_UPLOAD_MAXIMUM = 5; 2 | 3 | export const FILE_UPLOAD_MAX_SIZE = 10 * 1024 * 1024; 4 | 5 | export const FILE_UPLOAD_DESTINATION = './tmp/upload-files'; 6 | 7 | export const ALLOWED_FILE_UPLOAD_MIME_TYPES = [ 8 | 'image/png', 9 | 'image/jpeg', 10 | 'image/jpg', 11 | 'image/svg+xml', 12 | 'image/bmp', 13 | 'image/heic', 14 | 'image/heif', 15 | 'application/pdf', 16 | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 17 | 'application/vnd.ms-excel' 18 | ]; 19 | -------------------------------------------------------------------------------- /lib/decorators/enums.decorators.ts: -------------------------------------------------------------------------------- 1 | import { ValidateFieldException } from '@hodfords/nestjs-exception'; 2 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 3 | import { ApiQuery } from '@nestjs/swagger'; 4 | import { SwaggerEnumType } from '@nestjs/swagger/dist/types/swagger-enum.type'; 5 | import { getParamOptions, ParamOptions } from '../helpers/get-params.helper'; 6 | 7 | type EnumsParamOptions = ParamOptions & { 8 | enum: SwaggerEnumType; 9 | separator?: string; 10 | description?: string; 11 | singleValue?: boolean; 12 | example?: string; 13 | }; 14 | 15 | const enumsDecorator = createParamDecorator((options: EnumsParamOptions, ctx: ExecutionContext) => { 16 | const paramOptions = getParamOptions(options, 'id'); 17 | const request = ctx.switchToHttp().getRequest(); 18 | const { separator = ',' } = options; 19 | 20 | const values: string[] = (request.params[paramOptions.key] || request.query[paramOptions.key])?.split(separator); 21 | if (!values && paramOptions.nullable) { 22 | return values; 23 | } 24 | 25 | const enumValues = Object.values(options.enum).map((item) => String(item)); 26 | if (options.singleValue) { 27 | if ((!values?.at(0) && !paramOptions.nullable) || (values?.at(0) && !enumValues.includes(values[0]))) { 28 | throw new ValidateFieldException(options.key, 'invalid_enum_value', 'invalidEnum'); 29 | } 30 | 31 | return values[0]; 32 | } 33 | 34 | const hasMismatched = values.some((item) => !enumValues.includes(item)); 35 | if (hasMismatched) { 36 | throw new ValidateFieldException(options.key, 'invalid_enum_value', 'invalidEnum'); 37 | } 38 | 39 | return values; 40 | }); 41 | 42 | export function EnumQuery(options: EnumsParamOptions) { 43 | return (target: any, key: string, descriptor: any) => { 44 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, key); 45 | if (propertyDescriptor) { 46 | ApiQuery({ 47 | description: options.description, 48 | name: options.key, 49 | enum: options.enum, 50 | required: !options.nullable 51 | })(target, key, propertyDescriptor); 52 | } 53 | return enumsDecorator({ ...options, singleValue: true })(target, key, descriptor); 54 | }; 55 | } 56 | 57 | export function EnumsQuery(options: EnumsParamOptions) { 58 | return (target: any, key: string, descriptor: any) => { 59 | const enumKeys = Object.keys(options.enum).filter((item) => isNaN(+item)); 60 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, key); 61 | if (propertyDescriptor) { 62 | ApiQuery({ 63 | description: options.description || `Available enums: ${enumKeys}`, 64 | example: options.example || 'value1,value2,...', 65 | name: options.key, 66 | required: !options.nullable 67 | })(target, key, propertyDescriptor); 68 | } 69 | return enumsDecorator(options)(target, key, descriptor); 70 | }; 71 | } 72 | -------------------------------------------------------------------------------- /lib/decorators/id.decorator.ts: -------------------------------------------------------------------------------- 1 | import { UuidException } from '@hodfords/nestjs-exception'; 2 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 3 | import { validate } from 'uuid'; 4 | import { getParamOptions, ParamOptions } from '../helpers/get-params.helper'; 5 | 6 | export const Id = createParamDecorator((options: ParamOptions | string, ctx: ExecutionContext) => { 7 | const paramOptions = getParamOptions(options, 'id'); 8 | const request = ctx.switchToHttp().getRequest(); 9 | const id = request.params[paramOptions.key] || request.query[paramOptions.key]; 10 | if (!id && paramOptions.nullable) { 11 | return id; 12 | } 13 | if (!validate(id)) { 14 | throw new UuidException(paramOptions.key); 15 | } 16 | return id; 17 | }); 18 | 19 | export const Ids = createParamDecorator((options: ParamOptions | string, ctx: ExecutionContext) => { 20 | const paramOptions = getParamOptions(options, 'ids'); 21 | const request = ctx.switchToHttp().getRequest(); 22 | const ids = request.query[paramOptions.key]; 23 | if (!ids) { 24 | return []; 25 | } 26 | return ids 27 | .split(',') 28 | .map((id: string) => { 29 | if (!id && paramOptions.nullable) { 30 | return id; 31 | } 32 | if (!validate(id)) { 33 | throw new UuidException(paramOptions.key); 34 | } 35 | return id; 36 | }) 37 | .filter((id: string) => id); 38 | }); 39 | -------------------------------------------------------------------------------- /lib/decorators/number.decorator.ts: -------------------------------------------------------------------------------- 1 | import { UuidException } from '@hodfords/nestjs-exception'; 2 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 3 | 4 | export const Int = createParamDecorator((key: string, ctx: ExecutionContext) => { 5 | if (!key) { 6 | key = 'id'; 7 | } 8 | const request = ctx.switchToHttp().getRequest(); 9 | const id = request.params[key] || request.query[key]; 10 | 11 | const value = parseInt(id); 12 | if (isNaN(value)) { 13 | throw new UuidException(key); 14 | } 15 | return value; 16 | }); 17 | 18 | export const Ints = createParamDecorator((key: string, ctx: ExecutionContext) => { 19 | const request = ctx.switchToHttp().getRequest(); 20 | const ids = request.query[key || 'ids']; 21 | 22 | if (!ids) { 23 | return []; 24 | } 25 | 26 | return ids.split(',').map((id: string) => { 27 | const value = parseInt(id); 28 | if (isNaN(value)) { 29 | throw new UuidException(key); 30 | } 31 | return value; 32 | }); 33 | }); 34 | -------------------------------------------------------------------------------- /lib/decorators/pagination.decorator.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import { ApiQuery } from '@nestjs/swagger'; 3 | 4 | export const Pagination = createParamDecorator( 5 | (paginationParams: PaginationInputParams | undefined, ctx: ExecutionContext) => { 6 | if (!paginationParams) { 7 | paginationParams = { 8 | page: 'page', 9 | perPage: 'perPage' 10 | }; 11 | } 12 | if (!paginationParams.page) { 13 | paginationParams.page = 'page'; 14 | } 15 | if (!paginationParams.perPage) { 16 | paginationParams.perPage = 'perPage'; 17 | } 18 | 19 | const request = ctx.switchToHttp().getRequest(); 20 | const defaultPerPage = 10; 21 | const maxPerPage = 1000; 22 | 23 | return { 24 | page: Math.max(request.query[paginationParams.page], 1) || 1, 25 | perPage: Math.min(request.query[paginationParams.perPage] || defaultPerPage, maxPerPage) || defaultPerPage 26 | }; 27 | }, 28 | [ 29 | ((target: any, key: string | symbol) => { 30 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, key); 31 | if (propertyDescriptor) { 32 | ApiQuery({ 33 | name: 'page', 34 | schema: { default: 1, type: 'number', minimum: 1 }, 35 | required: false 36 | })(target, key, propertyDescriptor); 37 | ApiQuery({ 38 | name: 'perPage', 39 | schema: { default: 10, type: 'number', minimum: 1, maximum: 1000 }, 40 | required: false 41 | })(target, key, propertyDescriptor); 42 | } 43 | }) as ParameterDecorator 44 | ] 45 | ); 46 | 47 | export interface PaginationParams { 48 | page: number; 49 | perPage: number; 50 | } 51 | 52 | export interface PaginationInputParams { 53 | page?: string; 54 | perPage?: string; 55 | } 56 | -------------------------------------------------------------------------------- /lib/decorators/query-boolean.decorator.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import { ApiQuery, ApiQueryOptions } from '@nestjs/swagger'; 3 | 4 | const queryBooleanDecorator = createParamDecorator((key: string, ctx: ExecutionContext) => { 5 | const request = ctx.switchToHttp().getRequest(); 6 | return request.query[key] === 'true'; 7 | }); 8 | 9 | export function QueryBoolean(key: string, options: ApiQueryOptions = {}) { 10 | return (target: any, property: string, descriptor: any) => { 11 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, property); 12 | if (propertyDescriptor) { 13 | ApiQuery({ 14 | name: key, 15 | required: false, 16 | type: Boolean, 17 | ...options 18 | })(target, property, propertyDescriptor); 19 | } 20 | return queryBooleanDecorator(key)(target, property, descriptor); 21 | }; 22 | } 23 | -------------------------------------------------------------------------------- /lib/decorators/query-strings.decorator.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import { ApiQuery, ApiQueryOptions } from '@nestjs/swagger'; 3 | 4 | const queryStringsDecorator = createParamDecorator((key: string, ctx: ExecutionContext): string[] => { 5 | const request = ctx.switchToHttp().getRequest(); 6 | const value = request.query[key]; 7 | if (value !== null && value !== undefined && typeof value === 'string') { 8 | return [...new Set(value.split(','))]; 9 | } 10 | return []; 11 | }); 12 | 13 | export function QueryStrings(key: string, options: ApiQueryOptions = {}) { 14 | return (target: any, property: string, descriptor: any) => { 15 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, property); 16 | if (propertyDescriptor) { 17 | ApiQuery({ 18 | name: key, 19 | required: false, 20 | type: String, 21 | example: `value1,value2,...`, 22 | ...options 23 | })(target, property, propertyDescriptor); 24 | } 25 | return queryStringsDecorator(key)(target, property, descriptor); 26 | }; 27 | } 28 | -------------------------------------------------------------------------------- /lib/decorators/real-ip.decorators.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import * as requestIp from '@supercharge/request-ip'; 3 | 4 | export const RealIp = createParamDecorator((data: unknown, ctx: ExecutionContext) => { 5 | const request = ctx.switchToHttp().getRequest(); 6 | return requestIp.getClientIp(request); 7 | }); 8 | -------------------------------------------------------------------------------- /lib/decorators/require-upload-file.decorator.ts: -------------------------------------------------------------------------------- 1 | import { applyDecorators, UseInterceptors } from '@nestjs/common'; 2 | import { FileInterceptor, FilesInterceptor } from '@nestjs/platform-express'; 3 | import { getFileUploadConfigurations } from '../helpers/file.helper'; 4 | import { RequireToUploadFileInterceptor } from '../interceptors/require-upload-file-interceptor'; 5 | import { RequireToUploadFilesInterceptor } from '../interceptors/require-upload-files-interceptor'; 6 | import { FileUploadParamsType } from '../types/file-upload-params.type'; 7 | 8 | export function RequireToUploadFile({ fieldName, options }: FileUploadParamsType) { 9 | const { maxCount, multerOptions } = getFileUploadConfigurations(options || {}); 10 | const isArray = maxCount > 1; 11 | 12 | if (isArray) { 13 | return applyDecorators( 14 | UseInterceptors(FilesInterceptor(fieldName, maxCount, multerOptions)), 15 | UseInterceptors(RequireToUploadFilesInterceptor) 16 | ); 17 | } else { 18 | return applyDecorators( 19 | UseInterceptors(FileInterceptor(fieldName, multerOptions)), 20 | UseInterceptors(RequireToUploadFileInterceptor) 21 | ); 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /lib/decorators/require-upload-files.decorator.ts: -------------------------------------------------------------------------------- 1 | import { applyDecorators, SetMetadata, UseInterceptors } from '@nestjs/common'; 2 | import { FileFieldsInterceptor } from '@nestjs/platform-express'; 3 | import { getFileUploadConfigurations } from '../helpers/file.helper'; 4 | import { RequireToUploadFilesInterceptor } from '../interceptors/require-upload-files-interceptor'; 5 | import { FilesUploadParamsType } from '../types/files-upload-params.type'; 6 | 7 | export function RequireToUploadFiles({ fieldNames, options }: FilesUploadParamsType) { 8 | const { maxCount: defaultMaxCount, multerOptions } = getFileUploadConfigurations(options || {}); 9 | const uploadFields = fieldNames.map(({ name, maxCount }) => { 10 | return { 11 | name, 12 | maxCount: maxCount && maxCount > 0 ? maxCount : defaultMaxCount 13 | }; 14 | }); 15 | 16 | const names = uploadFields.map(({ name }) => name); 17 | return applyDecorators( 18 | SetMetadata('fieldNames', names), 19 | UseInterceptors(FileFieldsInterceptor(uploadFields, multerOptions)), 20 | UseInterceptors(RequireToUploadFilesInterceptor) 21 | ); 22 | } 23 | -------------------------------------------------------------------------------- /lib/decorators/sort.decorator.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import { ApiQuery } from '@nestjs/swagger'; 3 | import { getAllowedFieldsEnums, validateDirection, validateField } from '../helpers/sort.helper'; 4 | import { SortDirection } from '../types/sort-direction.type'; 5 | import { SortParamsType } from '../types/sort-params.type'; 6 | 7 | export function Sort(sortParams: SortParamsType): any { 8 | return (target: any, key: string, descriptor: any) => { 9 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, key); 10 | 11 | if (propertyDescriptor) { 12 | ApiQuery({ 13 | name: 'sortField', 14 | enum: getAllowedFieldsEnums(sortParams), 15 | schema: { default: sortParams?.default?.sortField || 'createdAt', type: 'string' }, 16 | required: false 17 | })(target, key, propertyDescriptor); 18 | ApiQuery({ 19 | name: 'sortDirection', 20 | schema: { default: 'DESC', type: 'string' }, 21 | enum: ['ASC', 'DESC'], 22 | required: false 23 | })(target, key, propertyDescriptor); 24 | } 25 | return sortDecorator(sortParams)(target, key, descriptor); 26 | }; 27 | } 28 | 29 | const sortDecorator = createParamDecorator((sortParams: SortParamsType, ctx: ExecutionContext): SortParams => { 30 | if (!sortParams) { 31 | sortParams = { sortField: 'sortField', sortDirection: 'sortDirection' }; 32 | } 33 | if (!sortParams.sortField) { 34 | sortParams.sortField = 'sortField'; 35 | } 36 | if (!sortParams.sortDirection) { 37 | sortParams.sortDirection = 'sortDirection'; 38 | } 39 | 40 | const request = ctx.switchToHttp().getRequest(); 41 | const sortField = request.query[sortParams.sortField] || sortParams?.default?.sortField || 'createdAt'; 42 | const sortDirection = request.query[sortParams.sortDirection] || sortParams?.default?.sortDirection || 'DESC'; 43 | 44 | validateField(getAllowedFieldsEnums(sortParams), sortField); 45 | validateDirection(sortDirection); 46 | 47 | return { 48 | sortField, 49 | sortDirection 50 | }; 51 | }); 52 | 53 | export type SortParams = { 54 | sortField: string; 55 | sortDirection: SortDirection; 56 | }; 57 | -------------------------------------------------------------------------------- /lib/decorators/sorts.decorator.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import { ApiQuery } from '@nestjs/swagger'; 3 | import { getAllowedFieldsEnums, validateDirection, validateField } from '../helpers/sort.helper'; 4 | import { SortDirection } from '../types/sort-direction.type'; 5 | import { SortsParamsType } from '../types/sorts-params.type'; 6 | 7 | export function Sorts(sortParams: SortsParamsType): any { 8 | return (target: any, key: string, descriptor: any) => { 9 | const propertyDescriptor = Object.getOwnPropertyDescriptor(target, key); 10 | if (propertyDescriptor) { 11 | ApiQuery({ 12 | description: `Available values: ${getAllowedFieldsEnums(sortParams)}`, 13 | example: 'field1,field2:[ ASC(default) | DESC ],...', 14 | name: 'sortFields', 15 | schema: { 16 | default: 17 | `${sortParams?.default?.sortField}:${sortParams?.default?.sortDirection || 'DESC'}` || 18 | 'createdAt:DESC', 19 | type: 'string' 20 | }, 21 | required: false 22 | })(target, key, propertyDescriptor); 23 | } 24 | return sortDecorator(sortParams)(target, key, descriptor); 25 | }; 26 | } 27 | 28 | const sortDecorator = createParamDecorator( 29 | (sortParams: SortsParamsType, ctx: ExecutionContext): SortMultipleParams[] => { 30 | const request = ctx.switchToHttp().getRequest(); 31 | 32 | if (!sortParams) { 33 | sortParams = { sortFields: 'sortFields' }; 34 | } 35 | if (!sortParams.sortFields) { 36 | sortParams.sortFields = 'sortFields'; 37 | } 38 | 39 | const fields: string = request.query[sortParams.sortFields] ? request.query[sortParams.sortFields].trim() : ''; 40 | 41 | const sortFields = 42 | fields || `${sortParams?.default?.sortField}:${sortParams?.default?.sortDirection}` || 'createdAt:DESC'; 43 | return sortFields 44 | .split(',') 45 | .filter((sort) => sort) 46 | .map((sort: string) => { 47 | const sortArr: string[] = sort.split(':', 2); 48 | const sortOrder: SortMultipleParams = { 49 | field: sortArr[0].trim(), 50 | direction: ((sortArr[1] ? sortArr[1].toUpperCase() : undefined) as any) || 'ASC' 51 | }; 52 | validateField(getAllowedFieldsEnums(sortParams), sortOrder.field, true); 53 | validateDirection(sortOrder.direction); 54 | 55 | return sortOrder; 56 | }); 57 | } 58 | ); 59 | 60 | export type SortMultipleParams = { 61 | field: string; 62 | direction: SortDirection; 63 | }; 64 | -------------------------------------------------------------------------------- /lib/decorators/timestamp.decorator.ts: -------------------------------------------------------------------------------- 1 | import { ValidateFieldException } from '@hodfords/nestjs-exception'; 2 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 3 | import dayjs from 'dayjs'; 4 | import { getParamOptions, ParamOptions } from '../helpers/get-params.helper'; 5 | 6 | export const Timestamp = createParamDecorator((options: ParamOptions | string, ctx: ExecutionContext) => { 7 | const paramOptions = getParamOptions(options); 8 | const request = ctx.switchToHttp().getRequest(); 9 | const timestamp = request.params[paramOptions.key] || request.query[paramOptions.key]; 10 | 11 | if (!timestamp && paramOptions.nullable) { 12 | return timestamp; 13 | } 14 | 15 | if (!dayjs.unix(timestamp).isValid()) { 16 | throw new ValidateFieldException(paramOptions.key, 'invalid_timestamp', 'invalidTimestamp'); 17 | } 18 | 19 | return timestamp; 20 | }); 21 | -------------------------------------------------------------------------------- /lib/decorators/timezone.decorator.ts: -------------------------------------------------------------------------------- 1 | import { BadRequestException, createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | import dayjs from 'dayjs'; 3 | import timezone from 'dayjs/plugin/timezone'; 4 | import utc from 'dayjs/plugin/utc'; 5 | import { getParamOptions, ParamOptions } from '../helpers/get-params.helper'; 6 | 7 | dayjs.extend(utc); 8 | dayjs.extend(timezone); 9 | 10 | export const Timezone = createParamDecorator((options: ParamOptions | string, ctx: ExecutionContext) => { 11 | const paramOptions = getParamOptions(options); 12 | const request = ctx.switchToHttp().getRequest(); 13 | const timezone = request.params[paramOptions.key] || request.query[paramOptions.key]; 14 | if (!timezone && paramOptions.nullable) { 15 | return timezone; 16 | } 17 | 18 | try { 19 | const dayjsLocal = dayjs(new Date()); 20 | if (dayjsLocal.tz(timezone)) { 21 | return timezone; 22 | } 23 | throw new BadRequestException({ translate: 'error.invalid_timezone' }); 24 | } catch { 25 | throw new BadRequestException({ translate: 'error.invalid_timezone' }); 26 | } 27 | }); 28 | -------------------------------------------------------------------------------- /lib/decorators/user-agent.decorator.ts: -------------------------------------------------------------------------------- 1 | import { createParamDecorator, ExecutionContext } from '@nestjs/common'; 2 | 3 | export const UserAgent = createParamDecorator((options: unknown, ctx: ExecutionContext) => { 4 | const request = ctx.switchToHttp().getRequest(); 5 | 6 | return request.headers['user-agent']; 7 | }); 8 | -------------------------------------------------------------------------------- /lib/decorators/value.decorator.ts: -------------------------------------------------------------------------------- 1 | import { Payload } from '@nestjs/microservices'; 2 | 3 | export function Value(): ParameterDecorator { 4 | return (target: any, key: string | symbol | undefined, descriptor: any): void => { 5 | return Payload('value')(target, key, descriptor); 6 | }; 7 | } 8 | -------------------------------------------------------------------------------- /lib/filters/file-upload.filter.ts: -------------------------------------------------------------------------------- 1 | import { BadRequestException } from '@nestjs/common'; 2 | import { Request } from 'express'; 3 | 4 | function isValidFileType(file: Express.Multer.File, allowedMimeTypes: string[]): boolean { 5 | const splitFileName = file.originalname.split('.'); 6 | 7 | return splitFileName.length >= 2 && allowedMimeTypes.includes(file.mimetype); 8 | } 9 | 10 | function isValidUploadMultipleFiles(files: Array, allowedMimeTypes: string[]): boolean { 11 | return !!files.length && files.every((file) => isValidFileType(file, allowedMimeTypes)); 12 | } 13 | 14 | export function fileUploadFilter( 15 | req: Request, 16 | attachment: Express.Multer.File | Array, 17 | allowedMimeTypes: string[], 18 | callback: (error: Error | null, acceptFile: boolean) => void 19 | ) { 20 | const attachments = Array.isArray(attachment) ? attachment : [attachment]; 21 | if (!isValidUploadMultipleFiles(attachments, allowedMimeTypes)) { 22 | callback(new BadRequestException({ translate: 'error.invalid_file_format' }), false); 23 | } 24 | 25 | callback(null, true); 26 | } 27 | -------------------------------------------------------------------------------- /lib/helpers/file.helper.ts: -------------------------------------------------------------------------------- 1 | import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface'; 2 | import { Request } from 'express'; 3 | import { diskStorage } from 'multer'; 4 | import { extname } from 'path'; 5 | import { v4 as uuidv4 } from 'uuid'; 6 | import { 7 | ALLOWED_FILE_UPLOAD_MIME_TYPES, 8 | FILES_UPLOAD_MAXIMUM, 9 | FILE_UPLOAD_DESTINATION, 10 | FILE_UPLOAD_MAX_SIZE 11 | } from '../constants/upload-file.constant'; 12 | import { fileUploadFilter } from '../filters/file-upload.filter'; 13 | import { FileUploadConfigurationsType } from '../types/file-upload-configurations.type'; 14 | import { FileUploadOptionsType } from '../types/file-upload-options.type'; 15 | import { MulterOptionsType } from '../types/multer-options.type'; 16 | 17 | export function fileNameGenerator( 18 | req: Request, 19 | file: Express.Multer.File, 20 | callback: (error: Error | null, fileName: string) => void 21 | ): void { 22 | const fileExtName = extname(file.originalname); 23 | callback(null, `${uuidv4()}${fileExtName}`); 24 | } 25 | 26 | export function getMulterOptions(params: MulterOptionsType): MulterOptions { 27 | const { 28 | fileSize = FILE_UPLOAD_MAX_SIZE, 29 | allowedMimeTypes = ALLOWED_FILE_UPLOAD_MIME_TYPES, 30 | storageEngine 31 | } = params; 32 | const storage = storageEngine 33 | ? storageEngine 34 | : diskStorage({ 35 | destination: FILE_UPLOAD_DESTINATION, 36 | filename: fileNameGenerator 37 | }); 38 | 39 | return { 40 | limits: { fileSize }, 41 | storage, 42 | fileFilter: ( 43 | req: Request, 44 | file: Express.Multer.File, 45 | callback: (error: Error | null, acceptFile: boolean) => void 46 | ) => fileUploadFilter(req, file, allowedMimeTypes, callback) 47 | }; 48 | } 49 | 50 | export function getFileUploadConfigurations(options: FileUploadOptionsType): FileUploadConfigurationsType { 51 | const maxCount = options?.maxCount || FILES_UPLOAD_MAXIMUM; 52 | const multerOptions = getMulterOptions({ 53 | fileSize: options?.fileSize || FILE_UPLOAD_MAX_SIZE, 54 | allowedMimeTypes: options?.allowedMimeTypes || ALLOWED_FILE_UPLOAD_MIME_TYPES, 55 | storageEngine: options?.storageEngine 56 | }); 57 | 58 | return { 59 | maxCount, 60 | multerOptions 61 | }; 62 | } 63 | -------------------------------------------------------------------------------- /lib/helpers/get-params.helper.ts: -------------------------------------------------------------------------------- 1 | import { isString, isUndefined } from '@nestjs/common/utils/shared.utils'; 2 | 3 | export type ParamOptions = { 4 | key: string; 5 | nullable: boolean; 6 | }; 7 | 8 | export function getParamOptions(options: ParamOptions | string, defaultKey = '') { 9 | const newOptions: ParamOptions = { 10 | key: defaultKey, 11 | nullable: false 12 | }; 13 | if (isUndefined(options)) { 14 | newOptions.key = defaultKey; 15 | } else if (isString(options)) { 16 | newOptions.key = options; 17 | } else { 18 | newOptions.nullable = options.nullable; 19 | newOptions.key = options.key ? options.key : defaultKey; 20 | } 21 | 22 | return newOptions; 23 | } 24 | -------------------------------------------------------------------------------- /lib/helpers/sort.helper.ts: -------------------------------------------------------------------------------- 1 | import { ValidateException } from '@hodfords/nestjs-exception'; 2 | import { SortDirection } from '../types/sort-direction.type'; 3 | import { SortParamsType } from '../types/sort-params.type'; 4 | import { isString } from 'lodash'; 5 | 6 | function getDefaultSortFields(sortParams: SortParamsType): string[] { 7 | const defaultSortField = sortParams?.default?.sortField; 8 | return defaultSortField ? [defaultSortField] : ['createdAt']; 9 | } 10 | 11 | export function getAllowedFieldsEnums(sortParams: SortParamsType): string[] { 12 | const defaultSortFieldEnums = getDefaultSortFields(sortParams); 13 | const allowedFields = sortParams?.allowedFields || []; 14 | 15 | return [...defaultSortFieldEnums, ...allowedFields]; 16 | } 17 | 18 | export function validateDirection(direction: SortDirection): void { 19 | if (!isString(direction) || !['ASC', 'DESC'].includes(direction)) { 20 | throw new ValidateException([ 21 | { 22 | property: 'sortDirection', 23 | constraints: { 24 | invalidDirection: { message: 'The sort direction is invalid.', detail: { direction } } 25 | } 26 | } 27 | ]); 28 | } 29 | } 30 | 31 | export function validateField(allowedFields: string[], field: string, isSortMultiple: boolean = false) { 32 | if (!isString(field) || !allowedFields.includes(field)) { 33 | throw new ValidateException([ 34 | { 35 | property: `sortField${isSortMultiple ? 's' : ''}`, 36 | constraints: { 37 | invalidField: { message: 'The sort field is invalid.', detail: { field } } 38 | } 39 | } 40 | ]); 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /lib/index.ts: -------------------------------------------------------------------------------- 1 | export * from './decorators/enums.decorators'; 2 | export * from './decorators/id.decorator'; 3 | export * from './decorators/number.decorator'; 4 | export * from './decorators/pagination.decorator'; 5 | export * from './decorators/query-boolean.decorator'; 6 | export * from './decorators/query-strings.decorator'; 7 | export * from './decorators/real-ip.decorators'; 8 | export * from './decorators/require-upload-file.decorator'; 9 | export * from './decorators/require-upload-files.decorator'; 10 | export * from './decorators/sort.decorator'; 11 | export * from './decorators/sorts.decorator'; 12 | export * from './decorators/timestamp.decorator'; 13 | export * from './decorators/timezone.decorator'; 14 | export * from './decorators/user-agent.decorator'; 15 | export * from './decorators/value.decorator'; 16 | export * from './filters/file-upload.filter'; 17 | export * from './helpers/file.helper'; 18 | export * from './helpers/get-params.helper'; 19 | export * from './interfaces/and-where-query.interface'; 20 | export * from './types/column-type.type'; 21 | export * from './types/file-upload-options.type'; 22 | export * from './types/file-upload-params.type'; 23 | export * from './types/files-upload-params.type'; 24 | export * from './types/sort-direction.type'; 25 | export * from './types/sort-params.type'; 26 | export * from './types/sorts-params.type'; 27 | export * from './validators/exist-ids.validator'; 28 | export * from './validators/exists.validator'; 29 | export * from './validators/unique.validator'; 30 | -------------------------------------------------------------------------------- /lib/interceptors/require-upload-file-interceptor.ts: -------------------------------------------------------------------------------- 1 | import { 2 | CallHandler, 3 | ExecutionContext, 4 | Injectable, 5 | NestInterceptor, 6 | UnprocessableEntityException 7 | } from '@nestjs/common'; 8 | 9 | @Injectable() 10 | export class RequireToUploadFileInterceptor implements NestInterceptor { 11 | intercept(context: ExecutionContext, next: CallHandler) { 12 | const request = context.switchToHttp().getRequest(); 13 | 14 | if (!request.file) { 15 | throw new UnprocessableEntityException({ translate: 'error.file_is_required' }); 16 | } 17 | 18 | return next.handle(); 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /lib/interceptors/require-upload-files-interceptor.ts: -------------------------------------------------------------------------------- 1 | import { 2 | CallHandler, 3 | ExecutionContext, 4 | Injectable, 5 | NestInterceptor, 6 | UnprocessableEntityException 7 | } from '@nestjs/common'; 8 | import { Reflector } from '@nestjs/core'; 9 | import { isObject } from 'lodash'; 10 | 11 | @Injectable() 12 | export class RequireToUploadFilesInterceptor implements NestInterceptor { 13 | constructor(private reflector: Reflector) {} 14 | 15 | intercept(context: ExecutionContext, next: CallHandler) { 16 | const request = context.switchToHttp().getRequest(); 17 | const fieldNames = this.reflector.get('fieldNames', context.getHandler()); 18 | 19 | if (!request.files) { 20 | throw new UnprocessableEntityException({ translate: 'error.files_are_required' }); 21 | } 22 | 23 | if (Array.isArray(request.files) && !request.files.length) { 24 | throw new UnprocessableEntityException({ translate: 'error.files_are_required' }); 25 | } 26 | 27 | if (fieldNames && isObject(request.files) && !Array.isArray(request.files)) { 28 | for (const filedName of fieldNames) { 29 | if (!request.files[filedName]?.length) { 30 | throw new UnprocessableEntityException({ translate: 'error.files_are_required' }); 31 | } 32 | } 33 | } 34 | 35 | return next.handle(); 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /lib/interfaces/and-where-query.interface.ts: -------------------------------------------------------------------------------- 1 | import { ObjectLiteral } from 'typeorm/common/ObjectLiteral'; 2 | import { Brackets } from 'typeorm/query-builder/Brackets'; 3 | 4 | export interface AndWhereQuery { 5 | query: string | Brackets | ((qb: this) => string) | ObjectLiteral | ObjectLiteral[]; 6 | parameters?: ObjectLiteral; 7 | } 8 | -------------------------------------------------------------------------------- /lib/interfaces/custom-condition.interface.ts: -------------------------------------------------------------------------------- 1 | import { ColumnTypes } from '../types/column-type.type'; 2 | 3 | export interface CustomCondition { 4 | value: ((...args: any[]) => ColumnTypes) | ColumnTypes; 5 | exclude?: boolean; 6 | column: string; 7 | } 8 | -------------------------------------------------------------------------------- /lib/types/column-type.type.ts: -------------------------------------------------------------------------------- 1 | export type ColumnTypes = string | number | boolean | null | undefined; 2 | -------------------------------------------------------------------------------- /lib/types/file-upload-configurations.type.ts: -------------------------------------------------------------------------------- 1 | import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface'; 2 | 3 | export type FileUploadConfigurationsType = { 4 | maxCount: number; 5 | multerOptions: MulterOptions; 6 | }; 7 | -------------------------------------------------------------------------------- /lib/types/file-upload-options.type.ts: -------------------------------------------------------------------------------- 1 | import { StorageEngine } from 'multer'; 2 | 3 | export type FileUploadOptionsType = { 4 | maxCount?: number; 5 | fileSize?: number; 6 | allowedMimeTypes?: string[]; 7 | storageEngine?: StorageEngine; 8 | }; 9 | -------------------------------------------------------------------------------- /lib/types/file-upload-params.type.ts: -------------------------------------------------------------------------------- 1 | import { FileUploadOptionsType } from './file-upload-options.type'; 2 | 3 | export type FileUploadParamsType = { 4 | fieldName: string; 5 | options?: FileUploadOptionsType; 6 | }; 7 | -------------------------------------------------------------------------------- /lib/types/files-upload-params.type.ts: -------------------------------------------------------------------------------- 1 | import { MulterField } from '@nestjs/platform-express/multer/interfaces/multer-options.interface'; 2 | import { FileUploadOptionsType } from './file-upload-options.type'; 3 | 4 | export type FilesUploadParamsType = { 5 | fieldNames: MulterField[]; 6 | options?: FileUploadOptionsType; 7 | }; 8 | -------------------------------------------------------------------------------- /lib/types/multer-options.type.ts: -------------------------------------------------------------------------------- 1 | import { FileUploadOptionsType } from './file-upload-options.type'; 2 | 3 | export type MulterOptionsType = Pick; 4 | -------------------------------------------------------------------------------- /lib/types/sort-direction.type.ts: -------------------------------------------------------------------------------- 1 | export type SortDirection = 'ASC' | 'DESC'; 2 | -------------------------------------------------------------------------------- /lib/types/sort-params.type.ts: -------------------------------------------------------------------------------- 1 | export type SortParamsType = 2 | | undefined 3 | | { 4 | allowedFields?: string[]; 5 | sortField?: string; 6 | sortDirection?: string; 7 | default?: 8 | | null 9 | | undefined 10 | | { 11 | sortField: string; 12 | sortDirection?: string; 13 | }; 14 | }; 15 | -------------------------------------------------------------------------------- /lib/types/sorts-params.type.ts: -------------------------------------------------------------------------------- 1 | export type SortsParamsType = 2 | | undefined 3 | | { 4 | allowedFields?: string[]; 5 | sortFields?: string; 6 | default?: 7 | | null 8 | | undefined 9 | | { 10 | sortField: string; 11 | sortDirection?: string; 12 | }; 13 | }; 14 | -------------------------------------------------------------------------------- /lib/validators/exist-ids.validator.ts: -------------------------------------------------------------------------------- 1 | import { 2 | registerDecorator, 3 | ValidationArguments, 4 | ValidationOptions, 5 | ValidatorConstraint, 6 | ValidatorConstraintInterface 7 | } from 'class-validator'; 8 | import { BaseEntity } from 'typeorm'; 9 | import { getDataSource } from '@hodfords/typeorm-helper'; 10 | import { uniq } from 'lodash'; 11 | 12 | @ValidatorConstraint({ async: true }) 13 | export class ExistIdsValidator implements ValidatorConstraintInterface { 14 | async validate(value: any, args: ValidationArguments) { 15 | const data = args.constraints[0]; 16 | const allowEmpty = data.allowEmpty; 17 | 18 | if (!value?.length && !allowEmpty) { 19 | return false; 20 | } 21 | 22 | if (!value?.length && allowEmpty) { 23 | return true; 24 | } 25 | 26 | const result = await getDataSource() 27 | .createQueryBuilder() 28 | .from(data.table, data.table.name) 29 | .select('id') 30 | .where(` "${data.column}" IN (:...value)`, { value }) 31 | .getRawMany(); 32 | 33 | return result.length === uniq(value).length; 34 | } 35 | } 36 | 37 | export function ExistIds( 38 | table: { new (): BaseEntity }, 39 | allowEmpty: boolean = false, 40 | validationOptions?: ValidationOptions 41 | ) { 42 | validationOptions = { ...validationOptions, each: false, message: 'each value in $property does not exist.' }; 43 | 44 | return function (object: any, propertyName: string) { 45 | registerDecorator({ 46 | target: object.constructor, 47 | propertyName, 48 | options: validationOptions, 49 | constraints: [ 50 | { 51 | table, 52 | column: 'id', 53 | allowEmpty 54 | } 55 | ], 56 | validator: ExistIdsValidator 57 | }); 58 | }; 59 | } 60 | -------------------------------------------------------------------------------- /lib/validators/exists.validator.ts: -------------------------------------------------------------------------------- 1 | import { getDataSource } from '@hodfords/typeorm-helper'; 2 | import { isFunction, isNil, isUndefined } from '@nestjs/common/utils/shared.utils'; 3 | import { 4 | registerDecorator, 5 | ValidationArguments, 6 | ValidationOptions, 7 | ValidatorConstraint, 8 | ValidatorConstraintInterface 9 | } from 'class-validator'; 10 | import { BaseEntity, SelectQueryBuilder } from 'typeorm'; 11 | import { AndWhereQuery } from '../interfaces/and-where-query.interface'; 12 | import { CustomCondition } from '../interfaces/custom-condition.interface'; 13 | import { ColumnTypes } from '../types/column-type.type'; 14 | 15 | // TODO Upgrade typeorm 16 | @ValidatorConstraint({ async: true }) 17 | export class ExistsValidator implements ValidatorConstraintInterface { 18 | async validate(value: any, args: ValidationArguments) { 19 | const body = args.object as any; 20 | const data = args.constraints[0]; 21 | const customs = data.customs || []; 22 | const query = getDataSource().createQueryBuilder().from(data.table, data.table.name).select('id'); 23 | if (data.caseInsensitive) { 24 | query.where(` "${data.column}" ILIKE :value`, { value }); 25 | } else { 26 | query.where(` "${data.column}" = :value`, { value }); 27 | } 28 | 29 | this.buildCustomQuery(query, body, customs); 30 | 31 | return !!(await query.limit(1).getRawOne()); 32 | } 33 | 34 | private buildCustomQuery(query: SelectQueryBuilder, body: any, customs: any[]) { 35 | for (const custom of customs) { 36 | const customValue: ColumnTypes = isFunction(custom.value) ? custom.value(body) : custom.value; 37 | const columnName = custom.column; 38 | 39 | if (custom.exclude) { 40 | const excludeQueryBuilder: AndWhereQuery = { 41 | query: ` "${columnName}" != :${columnName}`, 42 | parameters: { 43 | [columnName]: customValue 44 | } 45 | }; 46 | 47 | if (isUndefined(customValue) || isNil(customValue)) { 48 | excludeQueryBuilder.query = ` "${columnName}" IS NOT NULL`; 49 | delete excludeQueryBuilder.parameters; 50 | } 51 | 52 | query.andWhere(excludeQueryBuilder.query, excludeQueryBuilder.parameters); 53 | } else { 54 | const queryBuilder: AndWhereQuery = { 55 | query: ` "${columnName}" = :${columnName}`, 56 | parameters: { 57 | [columnName]: customValue 58 | } 59 | }; 60 | 61 | if (isUndefined(customValue) || isNil(customValue)) { 62 | queryBuilder.query = ` "${columnName}" IS NULL`; 63 | delete queryBuilder.parameters; 64 | } 65 | 66 | query.andWhere(queryBuilder.query, queryBuilder.parameters); 67 | } 68 | } 69 | } 70 | } 71 | 72 | export function Exists( 73 | table: { new (): BaseEntity }, 74 | column: string, 75 | caseInsensitive: boolean = false, 76 | customs?: CustomCondition[], 77 | validationOptions?: ValidationOptions 78 | ) { 79 | const message = { message: 'The $property does not exist.' }; 80 | if (validationOptions && validationOptions.each) { 81 | message.message = 'each value in $property does not exist.'; 82 | } 83 | validationOptions = { ...message, ...validationOptions } as any; 84 | return function (object: any, propertyName: string) { 85 | registerDecorator({ 86 | target: object.constructor, 87 | propertyName, 88 | options: validationOptions, 89 | constraints: [ 90 | { 91 | table, 92 | column, 93 | caseInsensitive, 94 | customs 95 | } 96 | ], 97 | validator: ExistsValidator 98 | }); 99 | }; 100 | } 101 | -------------------------------------------------------------------------------- /lib/validators/unique.validator.ts: -------------------------------------------------------------------------------- 1 | import { 2 | registerDecorator, 3 | ValidationArguments, 4 | ValidationOptions, 5 | ValidatorConstraint, 6 | ValidatorConstraintInterface 7 | } from 'class-validator'; 8 | import { BaseEntity } from 'typeorm'; 9 | import { CustomCondition } from '../interfaces/custom-condition.interface'; 10 | import { ExistsValidator } from './exists.validator'; 11 | 12 | @ValidatorConstraint({ async: true }) 13 | export class UniqueValidator implements ValidatorConstraintInterface { 14 | async validate(value: any, args: ValidationArguments) { 15 | return !(await new ExistsValidator().validate(value, args)); 16 | } 17 | } 18 | 19 | /** 20 | * Check value is unique in table 21 | */ 22 | export function Unique( 23 | table: { new (): BaseEntity }, 24 | column: string, 25 | caseInsensitive: boolean = false, 26 | customs?: CustomCondition[], 27 | validationOptions?: ValidationOptions 28 | ) { 29 | const message = { message: 'The $property has already been taken.' }; 30 | if (validationOptions && validationOptions.each) { 31 | message.message = 'each value in $property has already been taken.'; 32 | } 33 | validationOptions = { ...message, ...validationOptions } as any; 34 | return function (object: any, propertyName: string) { 35 | registerDecorator({ 36 | target: object.constructor, 37 | propertyName, 38 | options: validationOptions, 39 | constraints: [ 40 | { 41 | table, 42 | column, 43 | caseInsensitive, 44 | customs 45 | } 46 | ], 47 | validator: UniqueValidator 48 | }); 49 | }; 50 | } 51 | -------------------------------------------------------------------------------- /nest-cli.json: -------------------------------------------------------------------------------- 1 | { 2 | "collection": "@nestjs/schematics", 3 | "sourceRoot": "./", 4 | "entryFile": "sample/main.js", 5 | "compilerOptions": { 6 | "assets": [ 7 | { 8 | "include": "sample/**/*", 9 | "outDir": "dist/sample" 10 | }, 11 | { 12 | "include": "lib/**/*", 13 | "outDir": "dist/lib" 14 | } 15 | ] 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@hodfords/nestjs-base-decorator", 3 | "version": "11.0.1", 4 | "description": "Provides common decorators for simplifying and standardizing NestJS application development", 5 | "main": "index.js", 6 | "scripts": { 7 | "prebuild": "rimraf dist", 8 | "start:dev": "npm run prebuild && nest start --watch", 9 | "build": "tsc", 10 | "format": "prettier --write \"lib/**/*.ts\"", 11 | "postbuild": "cp package.json dist/lib && cp README.md dist/lib && cp .npmrc dist/lib", 12 | "prepare": "is-ci || husky", 13 | "version": "auto-changelog && git add CHANGELOG.md", 14 | "release:patch": "git add CHANGELOG.md && npm version patch --tag-version-prefix='' -f -m 'chore: release to %s'", 15 | "release:push": "git push --no-verify && git push --tags --no-verify", 16 | "cspell": "cspell", 17 | "lint": "eslint \"lib/**/*.ts\" --fix --max-warnings 0", 18 | "lint-staged": "lint-staged" 19 | }, 20 | "repository": { 21 | "type": "git", 22 | "url": "git+https://github.com/hodfords-solutions/nestjs-base-decorator.git" 23 | }, 24 | "keywords": [], 25 | "author": "", 26 | "license": "ISC", 27 | "bugs": { 28 | "url": "https://github.com/hodfords-solutions/nestjs-base-decorator/issues" 29 | }, 30 | "homepage": "https://github.com/hodfords-solutions/nestjs-base-decorator#readme", 31 | "devDependencies": { 32 | "@hodfords/typeorm-helper": "11.0.1", 33 | "@hodfords/nestjs-cls-translation": "11.0.2", 34 | "@hodfords/nestjs-exception": "11.0.2", 35 | "@hodfords/nestjs-eslint-config": "11.0.1", 36 | "@hodfords/nestjs-prettier-config": "11.0.1", 37 | "@nestjs/common": "11.0.11", 38 | "@nestjs/core": "11.0.11", 39 | "@nestjs/platform-express": "11.0.11", 40 | "@nestjs/swagger": "11.0.6", 41 | "@nestjs/testing": "11.0.11", 42 | "@nestjs/typeorm": "11.0.0", 43 | "@types/lodash": "4.17.16", 44 | "@types/multer": "1.4.12", 45 | "@types/node": "22.13.10", 46 | "@types/uuid": "10.0.0", 47 | "@types/validator": "13.12.2", 48 | "auto-changelog": "2.5.0", 49 | "class-validator": "0.14.1", 50 | "class-transformer": "0.5.1", 51 | "cspell": "8.17.5", 52 | "eslint": "9.22.0", 53 | "husky": "9.1.7", 54 | "is-ci": "4.1.0", 55 | "lint-staged": "15.5.0", 56 | "lodash": "4.17.21", 57 | "prettier": "3.5.3", 58 | "rimraf": "6.0.1", 59 | "rxjs": "7.8.2", 60 | "typeorm": "0.3.21", 61 | "typescript": "5.8.2", 62 | "uuid": "11.1.0" 63 | }, 64 | "dependencies": { 65 | "@nestjs/microservices": "11.0.11", 66 | "@supercharge/request-ip": "1.2.0", 67 | "dayjs": "1.11.13" 68 | } 69 | } 70 | -------------------------------------------------------------------------------- /prettier.config.js: -------------------------------------------------------------------------------- 1 | module.exports = require('@hodfords/nestjs-prettier-config'); 2 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": ["config:base"], 4 | "prConcurrentLimit": 5, 5 | "assignees": ["hodfords_dung_senior_dev"], 6 | "labels": ["renovate"] 7 | } 8 | -------------------------------------------------------------------------------- /sample/app.controller.ts: -------------------------------------------------------------------------------- 1 | import { Controller, Get, Post, UploadedFiles } from '@nestjs/common'; 2 | import { ApiBody, ApiConsumes, ApiParam, ApiQuery } from '@nestjs/swagger'; 3 | import { 4 | EnumQuery, 5 | EnumsQuery, 6 | Id, 7 | Ids, 8 | Int, 9 | Ints, 10 | Pagination, 11 | PaginationParams, 12 | QueryStrings, 13 | RealIp, 14 | RequireToUploadFile, 15 | RequireToUploadFiles, 16 | Sort, 17 | SortMultipleParams, 18 | SortParams, 19 | Sorts, 20 | Timestamp, 21 | Timezone, 22 | UserAgent 23 | } from 'lib'; 24 | import { CategoryEnum, StatusEnum } from './app.enum'; 25 | 26 | @Controller() 27 | export class AppController { 28 | @Get('enum-query') 29 | getEnumQuery( 30 | @EnumQuery({ 31 | key: 'status', 32 | enum: StatusEnum, 33 | description: 'Status of the item', 34 | nullable: false 35 | }) 36 | status: StatusEnum 37 | ) { 38 | return status; 39 | } 40 | 41 | @Get('enums-query') 42 | getEnumsQuery( 43 | @EnumsQuery({ 44 | key: 'categories', 45 | enum: CategoryEnum, 46 | description: 'Categories of the product', 47 | separator: ',', 48 | nullable: false 49 | }) 50 | categories: CategoryEnum[] 51 | ): CategoryEnum[] { 52 | return categories; 53 | } 54 | 55 | @Get('id/:id') 56 | @ApiParam({ 57 | name: 'id', 58 | type: String 59 | }) 60 | getId(@Id() id: string): string { 61 | return id; 62 | } 63 | 64 | @Get('ids') 65 | @ApiQuery({ 66 | name: 'ids', 67 | type: String 68 | }) 69 | getIds(@Ids() ids: string[]): string[] { 70 | return ids; 71 | } 72 | 73 | @Get('int/:id') 74 | @ApiParam({ 75 | name: 'id', 76 | type: Number 77 | }) 78 | getInt(@Int() id: number): number { 79 | return id; 80 | } 81 | 82 | @Get('ints') 83 | @ApiQuery({ 84 | name: 'ids', 85 | type: String 86 | }) 87 | getInts(@Ints() ids: number[]): number[] { 88 | return ids; 89 | } 90 | 91 | @Get('pagination') 92 | getPagination(@Pagination() pagination: PaginationParams): PaginationParams { 93 | return pagination; 94 | } 95 | 96 | @Get('query-strings') 97 | getQueryStrings(@QueryStrings('tags') tags: string[]): string[] { 98 | return tags; 99 | } 100 | 101 | @Get('ip') 102 | getClientIp(@RealIp() ip: string): string { 103 | return ip; 104 | } 105 | 106 | @Post('upload') 107 | @RequireToUploadFile({ fieldName: 'file' }) 108 | @ApiConsumes('multipart/form-data') 109 | @ApiBody({ 110 | required: true, 111 | type: 'multipart/form-data', 112 | schema: { 113 | type: 'object', 114 | properties: { 115 | file: { 116 | type: 'string', 117 | format: 'binary' 118 | } 119 | } 120 | } 121 | }) 122 | uploadFile(@UploadedFiles() file: Express.Multer.File[]): Express.Multer.File[] { 123 | return file; 124 | } 125 | 126 | @Post('uploads') 127 | @ApiConsumes('multipart/form-data') 128 | @ApiBody({ 129 | required: true, 130 | type: 'multipart/form-data', 131 | schema: { 132 | type: 'object', 133 | properties: { 134 | profile: { 135 | type: 'string', 136 | format: 'binary' 137 | }, 138 | documents: { 139 | type: 'string', 140 | format: 'binary' 141 | } 142 | } 143 | } 144 | }) 145 | @RequireToUploadFiles({ 146 | fieldNames: [ 147 | { name: 'profile', maxCount: 1 }, 148 | { name: 'documents', maxCount: 5 } 149 | ] 150 | }) 151 | uploadUserFiles(@UploadedFiles() files: { profile: Express.Multer.File[]; documents: Express.Multer.File[] }) { 152 | return files; 153 | } 154 | 155 | @Get('sort') 156 | getSort( 157 | @Sort({ allowedFields: ['name', 'createdAt'], default: { sortField: 'createdAt', sortDirection: 'DESC' } }) 158 | query: SortParams 159 | ): SortParams { 160 | return query; 161 | } 162 | 163 | @Get('sorts') 164 | getUsers( 165 | @Sorts({ allowedFields: ['name', 'createdAt'], default: { sortField: 'createdAt', sortDirection: 'DESC' } }) 166 | query: SortMultipleParams[] 167 | ): SortMultipleParams[] { 168 | return query; 169 | } 170 | 171 | @Get('timestamp') 172 | @ApiQuery({ 173 | name: 'timestamp', 174 | type: Number 175 | }) 176 | getEvents(@Timestamp('timestamp') timestamp: number): number { 177 | return timestamp; 178 | } 179 | 180 | @Get('timezone') 181 | @ApiQuery({ 182 | name: 'timezone', 183 | type: String 184 | }) 185 | getTimezone(@Timezone('timezone') timezone: string): string { 186 | return timezone; 187 | } 188 | 189 | @Get('user-agent') 190 | getUserAgent(@UserAgent() userAgent: string): string { 191 | return userAgent; 192 | } 193 | } 194 | -------------------------------------------------------------------------------- /sample/app.enum.ts: -------------------------------------------------------------------------------- 1 | export enum StatusEnum { 2 | ACTIVE = 'active', 3 | INACTIVE = 'inactive' 4 | } 5 | 6 | export enum CategoryEnum { 7 | ELECTRONICS = 'electronics', 8 | FASHION = 'fashion', 9 | BOOKS = 'books' 10 | } 11 | -------------------------------------------------------------------------------- /sample/app.module.ts: -------------------------------------------------------------------------------- 1 | import { RequestResolver, TranslationModule } from '@hodfords/nestjs-cls-translation'; 2 | import { HttpExceptionFilter } from '@hodfords/nestjs-exception'; 3 | import { Module } from '@nestjs/common'; 4 | import { APP_FILTER } from '@nestjs/core'; 5 | import { HeaderResolver } from 'nestjs-i18n'; 6 | import path from 'path'; 7 | import { AppController } from './app.controller'; 8 | 9 | const i18nConfig = TranslationModule.forRoot({ 10 | fallbackLanguage: 'en', 11 | loaderOptions: { 12 | path: path.join(__dirname, 'i18n/'), 13 | watch: true 14 | }, 15 | resolvers: [new HeaderResolver(['language'])], 16 | defaultLanguageKey: 'language', 17 | clsResolvers: [new RequestResolver([{ key: 'language', type: 'headers' }])] 18 | }); 19 | 20 | @Module({ 21 | imports: [i18nConfig], 22 | controllers: [AppController], 23 | providers: [ 24 | { 25 | provide: APP_FILTER, 26 | useClass: HttpExceptionFilter 27 | } 28 | ] 29 | }) 30 | export class AppModule {} 31 | -------------------------------------------------------------------------------- /sample/i18n/en/error.json: -------------------------------------------------------------------------------- 1 | { 2 | "field_malformed": "The {field} is malformed.", 3 | "invalid_timezone": "Invalid timezone", 4 | "files_are_required": "Files are required", 5 | "file_is_required": "File is required" 6 | } 7 | -------------------------------------------------------------------------------- /sample/i18n/en/validation.json: -------------------------------------------------------------------------------- 1 | { 2 | "field_malformed": "This field is malformed.", 3 | "invalid_enum_value": "Invalid enum value", 4 | "invalid_timestamp": "Invalid timestamp" 5 | } 6 | -------------------------------------------------------------------------------- /sample/main.ts: -------------------------------------------------------------------------------- 1 | import { NestFactory } from '@nestjs/core'; 2 | import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'; 3 | import { AppModule } from './app.module'; 4 | import { ValidationPipe } from '@nestjs/common'; 5 | 6 | async function bootstrap() { 7 | const app = await NestFactory.create(AppModule); 8 | app.useGlobalPipes(new ValidationPipe({ whitelist: true, stopAtFirstError: true })); 9 | 10 | const config = new DocumentBuilder().build(); 11 | const document = SwaggerModule.createDocument(app, config); 12 | SwaggerModule.setup('docs', app, document); 13 | 14 | await app.listen(3001); 15 | } 16 | bootstrap(); 17 | -------------------------------------------------------------------------------- /tsconfig.build.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "./tsconfig.json", 3 | "exclude": ["node_modules", "test", "dist", "**/*spec.ts"] 4 | } 5 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "module": "commonjs", 4 | "moduleResolution": "node", 5 | "esModuleInterop": true, 6 | "declaration": true, 7 | "removeComments": true, 8 | "emitDecoratorMetadata": true, 9 | "experimentalDecorators": true, 10 | "allowSyntheticDefaultImports": true, 11 | "target": "es2017", 12 | "sourceMap": true, 13 | "outDir": "./dist", 14 | "baseUrl": "./", 15 | "incremental": true, 16 | "strict": true, 17 | "strictPropertyInitialization": false, 18 | "noUnusedLocals": true, 19 | "noUnusedParameters": false, 20 | "noImplicitReturns": true, 21 | "useUnknownInCatchVariables": true, 22 | }, 23 | "exclude": [ 24 | "tests", 25 | "src", 26 | "dist", 27 | "node_modules" 28 | ] 29 | } 30 | --------------------------------------------------------------------------------