@furkanogutcu/nest-common 1.0.0 → 1.0.1

package/README.md

@@ -12,6 +12,10 @@ This package is designed to standardize structures you repeatedly use in your Ne
 - [Installation](#installation)
 - [Features](#features)
   - [Exceptions](#1-exceptions)
+  - [API Responses](#2-api-responses)
+  - [Validators and Pipes](#3-validators-and-pipes)
+  - [Decorators](#4-decorators)
+  - [Utilities](#5-utilities)
 - [Development](#development)
 - [License](#license)
 
@@ -39,25 +43,27 @@ No additional installation steps are needed beyond installing the package.
 
 - **Custom Exception Classes**: Comprehensive set of HTTP-based exception classes for consistent error responses.
 
-  | Exception Class | HTTP Status | Description |
-  |-----------------|-------------|-------------|
-  | `AppException` | - | Base exception class for all custom exceptions |
-  | `AppBadRequestException` | 400 | For invalid input, malformed requests |
-  | `AppUnauthorizedException` | 401 | For authentication failures |
-  | `AppForbiddenException` | 403 | For authorization failures |
-  | `AppNotFoundException` | 404 | For resources that couldn't be found |
-  | `AppConflictException` | 409 | For conflicting requests (e.g., duplicate entries) |
-  | `AppUnprocessableEntityException` | 422 | For semantically incorrect requests |
-  | `AppInternalException` | 500 | For server-side errors |
-  | `AppTooManyRequestException` | 429 | For rate limiting scenarios |
-  | `AppValidationException` | 400 | Specifically for input validation errors |
+  | Exception Class                   | HTTP Status | Description                                        |
+  | --------------------------------- | ----------- | -------------------------------------------------- |
+  | `AppException`                    | -           | Base exception class for all custom exceptions     |
+  | `AppBadRequestException`          | 400         | For invalid input, malformed requests              |
+  | `AppUnauthorizedException`        | 401         | For authentication failures                        |
+  | `AppForbiddenException`           | 403         | For authorization failures                         |
+  | `AppNotFoundException`            | 404         | For resources that couldn't be found               |
+  | `AppConflictException`            | 409         | For conflicting requests (e.g., duplicate entries) |
+  | `AppUnprocessableEntityException` | 422         | For semantically incorrect requests                |
+  | `AppInternalException`            | 500         | For server-side errors                             |
+  | `AppTooManyRequestException`      | 429         | For rate limiting scenarios                        |
+  | `AppValidationException`          | 400         | Specifically for input validation errors           |
 
 - **Global Exception Filter**: Automatically catches and transforms exceptions throughout your application.
+
   - Centralized error handling logic
   - Consistent error response format
   - Easy to configure through NestJS's dependency injection
 
 - **Exception Transformers**: Converts various error types to standardized app exceptions.
+
   - NestJS built-in exception transformer
   - TypeORM exception transformer
 
@@ -155,6 +161,168 @@ The `type` field in validation error details can have the following values:
 
 For more detailed information about the filters, transformers, and interfaces included in the exceptions package, please check the source code.
 
+### 2. API Responses
+
+#### Features
+
+- **Standardized Response Types**: Comprehensive set of response interfaces for consistent API responses.
+  - `APIResponse`: Generic type for creating standardized responses
+  - `APIResponseOnlyMessage`: Simple message-only response
+  - `PaginatedAPIResponse`: Response format for paginated data with metadata
+
+#### Usage
+
+```typescript
+import { Controller, Get, Post, Body, Param, Query } from '@nestjs/common';
+import {
+  APIResponse,
+  APIResponseOnlyMessage,
+  PaginatedAPIResponse,
+  Pagination,
+  PaginationParams,
+} from '@furkanogutcu/nest-common';
+import { User } from './user.entity';
+import { CreateUserDto } from './dto/create-user.dto';
+
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get()
+  async findAll(@Pagination() { skip, take }: PaginationParams): Promise<PaginatedAPIResponse<User>> {
+    const { items, metadata } = await this.usersService.findAll({ skip, take });
+
+    return {
+      data: items,
+      metadata,
+    };
+  }
+
+  @Get(':id')
+  async findOne(@Param('id') id: string): Promise<APIResponse<'user', User>> {
+    const user = await this.usersService.findOne(id);
+
+    return {
+      user,
+    };
+  }
+
+  @Post()
+  async create(@Body() createUserDto: CreateUserDto): Promise<APIResponseOnlyMessage> {
+    await this.usersService.create(createUserDto);
+
+    return {
+      message: 'User created successfully',
+    };
+  }
+}
+```
+
+### 3. Validators and Pipes
+
+#### Features
+
+- **Zod Validation Pipe**: Extended validation pipe for NestJS using Zod schema validation.
+
+  - Seamless integration with NestJS validation pipeline
+  - Throws consistent `AppValidationException` on validation errors
+  - Compatible with Zod schemas
+
+- **Common Validation Schemas**:
+  - `paginationSchema`: For standardizing pagination parameters
+  - `orderBySchema`: For standardizing sorting/ordering parameters
+  - `searchSchema`: For standardizing search parameters
+
+#### Usage
+
+##### Setting up validation globally
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_PIPE } from '@nestjs/core';
+import { AppZodValidationPipe } from '@furkanogutcu/nest-common';
+
+@Module({
+  imports: [
+    // Your other modules
+  ],
+  controllers: [
+    // Your controllers
+  ],
+  providers: [
+    // Your other providers
+    {
+      provide: APP_PIPE,
+      useClass: AppZodValidationPipe,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+### 4. Decorators
+
+#### Features
+
+- **Parameter Decorators**: Decorators for common query parameter extraction and validation.
+  - `@Pagination()`: Extracts and validates pagination parameters
+  - `@OrderBy()`: Extracts and validates ordering parameters
+  - `@Search()`: Extracts and validates search parameters
+
+#### Usage
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { Pagination, OrderBy, Search, PaginationParams, OrderByParam, SearchParams } from '@furkanogutcu/nest-common';
+
+@Controller('users')
+export class UsersController {
+  @Get()
+  findAll(
+    @Pagination() { skip, take }: PaginationParams,
+    @OrderBy<User>(['created_at']) orderBy: OrderByParam<User>,
+    @Search<User>(['email']) search: SearchParams<User>,
+  ) {
+    // Implement your service call with these validated parameters
+    return this.usersService.findAll({ skip, take, orderBy, where: search });
+  }
+}
+```
+
+### 5. Utilities
+
+#### Features
+
+- **Asynchronous Utilities**:
+  - `exponentialRetry`: Retry a function with exponential backoff
+  - `sleep`: Simple promise-based delay utility
+
+#### Usage
+
+```typescript
+import { exponentialRetry, sleep } from '@furkanogutcu/nest-common';
+
+// Retry a function with exponential backoff
+async function fetchWithRetry() {
+  return exponentialRetry(
+    async () => {
+      // Potentially failing operation (e.g., API call)
+      return await externalApiCall();
+    },
+    {
+      maxAttempts: 5, // Maximum of 5 attempts
+      baseDelayMs: 1000, // Starting delay of 1000ms (will grow exponentially)
+    },
+  );
+}
+
+// Simple delay utility
+async function processWithDelay() {
+  await sleep(2000); // Wait for 2 seconds
+  // Continue execution
+}
+```
+
 ## Development
 
 ### Requirements

package/dist/utils/exponential-retry.util.d.ts

@@ -1 +1,5 @@
-export declare function exponentialRetry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelayMs?: number): Promise<T>;
+export interface ExponentialRetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+}
+export declare function exponentialRetry<T>(fn: () => Promise<T>, options?: ExponentialRetryOptions): Promise<T>;

package/dist/utils/exponential-retry.util.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exponentialRetry = exponentialRetry;
 const sleep_util_1 = require("./sleep.util");
-async function exponentialRetry(fn, maxAttempts = 3, baseDelayMs = 2000) {
+async function exponentialRetry(fn, options) {
+    const maxAttempts = options?.maxAttempts ?? 3;
+    const baseDelayMs = options?.baseDelayMs ?? 2000;
     let lastError = null;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {

package/dist/utils/exponential-retry.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"exponential-retry.util.js","sourceRoot":"","sources":["../../src/utils/exponential-retry.util.ts"],"names":[],"mappings":";;AAEA,4CAsBC;AAxBD,6CAAqC;AAE9B,KAAK,UAAU,gBAAgB,CACpC,EAAoB,EACpB,cAAsB,CAAC,EACvB,cAAsB,IAAI;IAE1B,IAAI,SAAS,GAAiB,IAAI,CAAC;IAEnC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAEtE,IAAI,OAAO,KAAK,WAAW;gBAAE,MAAM,SAAS,CAAC;YAE7C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;YAEjD,MAAM,IAAA,kBAAK,EAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,SAAS,IAAI,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"exponential-retry.util.js","sourceRoot":"","sources":["../../src/utils/exponential-retry.util.ts"],"names":[],"mappings":";;AAOA,4CAqBC;AA5BD,6CAAqC;AAO9B,KAAK,UAAU,gBAAgB,CAAI,EAAoB,EAAE,OAAiC;IAC/F,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,IAAI,CAAC;IAEjD,IAAI,SAAS,GAAiB,IAAI,CAAC;IAEnC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAEtE,IAAI,OAAO,KAAK,WAAW;gBAAE,MAAM,SAAS,CAAC;YAE7C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC;YAEjD,MAAM,IAAA,kBAAK,EAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,SAAS,IAAI,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;AAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furkanogutcu/nest-common",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Package of common structures for NestJS.",
   "author": "Furkan Ogutcu",
   "license": "MIT",