Custom Handler Guide

Custom Handler Guide - Override Default Operations

Overview

When you need to customize the behavior of CRUD operations beyond what the default implementation provides, you can use inject and handler to create custom logic. This allows you to:

• Override default pagination behavior

• Add custom business logic

• Use custom services instead of direct Prisma queries

• Implement complex filtering or data transformation

• Return custom response formats

When to Use Custom Handlers

Use inject and handler when:

1. Default behavior doesn't meet your requirements - You need custom pagination, filtering, or data processing

2. Business logic is required - You need to call services, perform calculations, or apply complex rules

3. Custom response format - You need to return data in a different structure than the default

4. Performance optimization - You need to optimize queries or add caching

Syntax

{
  type: 'LIST' | 'GET' | 'CREATE' | 'UPDATE' | 'DELETE_BY_ID',
  inject: [Service1, Service2, ...], // Services/classes to inject
  handler: async (params, service1, service2, ...) => {
    // Custom logic here
    return result;
  }
}

Handler Parameters by Operation Type

LIST Operation

handler: async (query: FilterDTO, ...injectedServices) => {
  // query: The query parameters (FilterDTO)
  // ...injectedServices: Services injected via inject array
  return {
    data: [...],
    total: number,
    page?: number,    // Optional, if pagination is used
    limit?: number    // Optional, if pagination is used
  };
}

GET Operation

handler: async (id: string | number, ...injectedServices) => {
  // id: The entity ID
  // ...injectedServices: Services injected via inject array
  return entity;
}

CREATE Operation

handler: async (body: CreateDTO, ...injectedServices) => {
  // body: The request body (CreateDTO)
  // ...injectedServices: Services injected via inject array
  return createdEntity;
}

UPDATE Operation

handler: async (id: string | number, body: UpdateDTO, ...injectedServices) => {
  // id: The entity ID
  // body: The request body (UpdateDTO)
  // ...injectedServices: Services injected via inject array
  return updatedEntity;
}

DELETE_BY_ID Operation

handler: async (id: string | number, ...injectedServices) => {
  // id: The entity ID
  // ...injectedServices: Services injected via inject array
  return deletedEntity; // or void
}

Examples

Example 1: Custom LIST with Flexible Pagination

Use Case: Allow pagination to be optional, and support returning all data when pagination=false.

import { CrudGeneratorConfig } from '@tradinos/cms-backend-entity';
import { PrismaClient } from 'src/prisma/prisma.client';
import { CategoryFilterDTO } from './dto/category-filter.dto';
import { CategoryDto } from './dto/category.dto';
import { selectCategoryValidator } from './validators/select-category.validator';

export const CategoryEntityOperations: CrudGeneratorConfig<'category'> = {
  dto: CategoryDto,
  path: 'categories',
  operations: [
    {
      type: 'LIST',
      inject: [PrismaClient],
      handler: async (query: CategoryFilterDTO, prisma: PrismaClient) => {
        const { page, limit, pagination, orderBy, direction, ...filterParams } = query;

        // Build order by clause
        const orderByClause = orderBy ? {
          [orderBy]: direction ?? 'asc',
        } : {};

        // Build where clause
        const whereClause = {};

        // If pagination is false, return all data (with optional limit)
        if (pagination === false) {
          const data = await prisma.category.findMany({
            where: whereClause,
            orderBy: orderByClause,
            ...(limit && { take: limit }),
            select: selectCategoryValidator(),
          });

          return {
            data,
            total: data.length,
          };
        }

        // If pagination is true or not specified, use default pagination
        const skip = page ? page * (limit || 10) : 0;
        const take = limit || 10;

        const [data, total] = await Promise.all([
          prisma.category.findMany({
            where: whereClause,
            orderBy: orderByClause,
            skip,
            take,
            select: selectCategoryValidator(),
          }),
          prisma.category.count({ where: whereClause }),
        ]);

        return {
          data,
          total,
          page: page || 0,
          limit: take,
        };
      },
      order: {
        queryParams: CategoryFilterDTO,
        mapper: (query: CategoryFilterDTO) => ({
          ...(query.orderBy && {
            [query.orderBy]: query.direction ?? 'asc',
          }),
        }),
      },
    },
  ],
  prismaConfig: {
    entityName: 'category',
    select: selectCategoryValidator(),
  },
} as const;

Key Points:

• Uses inject: [PrismaClient] to inject Prisma client

• Custom handler receives query: CategoryFilterDTO as first parameter

• Handler implements custom pagination logic based on pagination flag

• Returns different response formats based on pagination mode

Example 2: Using Custom Service Instead of Direct Prisma

Use Case: Use a service layer for business logic instead of direct database access.

import { CrudGeneratorConfig } from '@tradinos/cms-backend-entity';
import { CredentialService } from './credential.service';
import { CreateCredentialDto, UpdateCredentialDto } from './dtos/credential.dto';

export const CredentialEntityOperations: CrudGeneratorConfig<'emailCredentials'> = {
  dto: CreateCredentialDto,
  path: 'credential',
  operations: [
    {
      type: 'CREATE',
      body: CreateCredentialDto,
      inject: [CredentialService],
      handler: (createCredentialDto: CreateCredentialDto, credentialService: CredentialService) => {
        return credentialService.create(createCredentialDto);
      }
    },
    {
      type: 'GET',
      inject: [CredentialService],
      handler: (id, credentialService: CredentialService) => {
        return credentialService.getById(id);
      }
    },
    {
      type: 'UPDATE',
      body: UpdateCredentialDto,
      inject: [CredentialService],
      handler: (id: any, updateCredentialDto: UpdateCredentialDto, credentialService: CredentialService) => {
        return credentialService.update(updateCredentialDto);
      }
    },
  ],
  prismaConfig: {
    entityName: 'emailCredentials',
    select: selectCredentialValidator(),
  },
} as const;

Key Points:

• Uses inject: [CredentialService] to inject a custom service

• Handler delegates all logic to the service

• Service can contain business logic, validation, or additional processing

Example 3: Multiple Injected Services

Use Case: Use multiple services in a single handler.

{
  type: 'CREATE',
  body: CreateDTO,
  inject: [Service1, Service2, PrismaClient],
  handler: async (body: CreateDTO, service1: Service1, service2: Service2, prisma: PrismaClient) => {
    // Use service1 for validation
    await service1.validate(body);
    
    // Use service2 for processing
    const processed = await service2.process(body);
    
    // Use Prisma for database operation
    const result = await prisma.entity.create({
      data: processed
    });
    
    return result;
  }
}

Key Points:

• Multiple services can be injected in order

• Handler parameters match the order of inject array

• Each service is available as a typed parameter

Combining with Other Options

You can combine handler with other operation options:

{
  type: 'LIST',
  inject: [PrismaClient],
  handler: async (query, prisma) => {
    // Custom handler logic
  },
  order: {
    queryParams: FilterDTO,
    mapper: (query) => ({ /* order mapping */ }),
  },
  filter: {
    queryParams: FilterDTO,
    mapper: (query) => ({ /* filter mapping */ }),
  },
}

Note: When using a custom handler, the filter and order mappers are still available for documentation and type safety, but the handler is responsible for applying them.

Default Behavior vs Custom Handler

Default Behavior (No Handler)

{
  type: 'LIST',
  filter: {
    queryParams: FilterDTO,
    mapper: (query) => ({ /* filter mapping */ }),
  },
  order: {
    queryParams: FilterDTO,
    mapper: (query) => ({ /* order mapping */ }),
  },
}

• Uses default pagination (page-based)

• Applies filter and order mappers automatically

• Returns standard response format

Custom Handler

{
  type: 'LIST',
  inject: [PrismaClient],
  handler: async (query, prisma) => {
    // Full control over query execution
    // Custom pagination logic
    // Custom response format
  },
}

• Full control over query execution

• Can implement custom pagination (cursor-based, offset-based, etc.)

• Can add custom business logic

• Can return custom response format

• Must manually apply filtering and ordering if needed

Best Practices

1. Use Services for Business Logic: If you have complex business logic, create a service and inject it rather than putting all logic in the handler.

2. Keep Handlers Focused: Handlers should be focused on orchestrating the operation, not containing all business logic.

3. Type Safety: Always type your handler parameters correctly for better IDE support and type safety.

4. Error Handling: Consider error handling in your handlers, especially for async operations.

5. Performance: Use Promise.all for parallel operations when possible (like fetching data and count simultaneously).

6. Select Validators: Always use selectCategoryValidator() or similar validators to ensure consistent field selection.

Common Patterns

Pattern 1: Conditional Pagination

handler: async (query, prisma) => {
  if (query.pagination === false) {
    // Return all data
  } else {
    // Use pagination
  }
}

Pattern 2: Service Delegation

handler: async (body, service) => {
  return service.create(body);
}

Pattern 3: Data Transformation

handler: async (query, prisma) => {
  const data = await prisma.entity.findMany({...});
  return {
    data: data.map(item => transformItem(item)),
    total: data.length
  };
}

Pattern 4: Complex Filtering

handler: async (query, prisma) => {
  const whereClause = buildComplexWhereClause(query);
  return prisma.entity.findMany({
    where: whereClause,
    ...
  });
}

Summary

• Use inject to provide services or dependencies to your handler

• Use handler to override default operation behavior

• Handler parameters depend on the operation type

• You can inject multiple services in order

• Custom handlers give you full control but require more code

• Combine with other options like filter and order for type safety