⚙️ Category Handlers

Category handlers provide core business logic functions for category management operations in Nodeblocks applications. These handlers encapsulate common patterns for category database operations, data transformation, and response formatting.

---

🎯 Overview

Category handlers are designed to:

• Encapsulate category business logic in reusable functions
• Handle category database operations with proper error management
• Transform category data between different formats
• Ensure type safety with TypeScript integration
• Support composition with other category blocks

---

📋 Category Handler Types

Category Async Handlers

Functions that perform asynchronous category operations (database calls, API requests, etc.).

Category Sync Handlers

Functions that perform synchronous category operations (data transformation, validation, etc.).

Category Terminator Handlers

Functions that format and return the final category response.

---

🔧 Available Category Handlers

createCategory

Creates a new category in the database.

Purpose: Handles creation of categories with validation and entity management

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody: Category creation data
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with categoryId or error

Payload Requirements:

• params.requestBody must contain category data
• context.db must be available for database operations

Key Features:

• Validates request body is present and not empty
• Creates base entity with timestamps and ID
• Inserts category into database
• Returns categoryId on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { createCategory } = handlers;

// Use in composition
const categoryPipeline = compose(categorySchema, validateRequest, createCategory, terminator);

---

getCategoryById

Retrieves a single category by ID.

Purpose: Fetches category data with existence validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.categoryId or context.data.categoryId: Category ID to retrieve
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with category or error

Payload Requirements:

• Category ID must be provided in params.requestParams.categoryId or context.data.categoryId
• context.db must be available for database operations

Key Features:

• Validates categoryId is provided
• Finds category by ID in database
• Returns 404 if category not found
• Returns category data on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { getCategoryById } = handlers;

// Use in composition
const categoryPipeline = compose(idSchema, validateId, getCategoryById, normalizeTerminator);

---

findCategories

Finds multiple categories with optional filtering.

Purpose: Handles querying categories with filter support

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestQuery: Optional filter criteria for categories
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with categories array or error

Payload Requirements:

• params.requestQuery is optional - if provided, used as MongoDB filter
• context.db must be available for database operations

Key Features:

• Accepts optional filter from request query
• Returns all categories if no filter provided
• Returns array of categories
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { findCategories } = handlers;

// Use in composition
const categoryPipeline = compose(findCategories, listTerminator);

---

updateCategory

Updates an existing category by ID.

Purpose: Handles updating categories with validation and conflict detection

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.categoryId or context.data.categoryId: Category ID to update
  • params.requestBody: Category data to update
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with update result or error

Payload Requirements:

• Category ID must be provided in params.requestParams.categoryId or context.data.categoryId
• params.requestBody must contain category data to update
• context.db must be available for database operations

Key Features:

• Validates categoryId is provided
• Validates request body is present and not empty
• Updates base entity with timestamps
• Checks if category exists before updating
• Returns update result on success
• Handles not found and update failures

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { updateCategory } = handlers;

// Use in composition
const categoryPipeline = compose(updateCategory, terminator);

---

deleteCategory

Deletes a category by ID.

Purpose: Handles safe deletion of categories with existence validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.categoryId or context.data.categoryId: Category ID to delete
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with deletion result or error

Payload Requirements:

• Category ID must be provided in params.requestParams.categoryId or context.data.categoryId
• context.db must be available for database operations

Key Features:

• Validates categoryId is provided
• Deletes category by ID from database
• Returns 404 if category not found
• Returns deletion result on success
• Handles database errors gracefully

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { deleteCategory } = handlers;

// Use in composition
const categoryPipeline = compose(deleteCategory, deleteTerminator);

---

enableCategory

Enables a category by setting its status to active.

Purpose: Handles category activation with status validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.categoryId or context.data.categoryId: Category ID to enable
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with enable result or error

Payload Requirements:

• Category ID must be provided in params.requestParams.categoryId or context.data.categoryId
• context.db must be available for database operations

Key Features:

• Validates categoryId is provided
• Sets category status to 'active'
• Checks if category exists before enabling
• Returns enable result on success
• Handles not found and enable failures

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { enableCategory } = handlers;

// Use in composition
const categoryPipeline = compose(enableCategory, enableTerminator);

---

disableCategory

Disables a category by setting its status to inactive.

Purpose: Handles category deactivation with status validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.categoryId or context.data.categoryId: Category ID to disable
  • context.db: Database connection

Returns: Result<RouteHandlerPayload, Error> - Success with disable result or error

Payload Requirements:

• Category ID must be provided in params.requestParams.categoryId or context.data.categoryId
• context.db must be available for database operations

Key Features:

• Validates categoryId is provided
• Sets category status to 'inactive'
• Checks if category exists before disabling
• Returns disable result on success
• Handles not found and disable failures

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { disableCategory } = handlers;

// Use in composition
const categoryPipeline = compose(disableCategory, disableTerminator);

---

🎯 Category Terminator Handlers

normalizeCategoryTerminator

Normalizes category data by removing database-specific fields.

Purpose: Cleans category data for API response

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.category: Category object from previous handler

Returns: Normalized category object

Payload Requirements:

• context.data.category must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { normalizeCategoryTerminator } = handlers;

// Use in composition
const categoryPipeline = compose(getCategoryById, normalizeCategoryTerminator);

---

normalizeCategoriesListTerminator

Normalizes categories list by removing database-specific fields from each item.

Purpose: Cleans categories array data for API response

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.categories: Array of category objects from previous handler

Returns: Array of normalized category objects

Payload Requirements:

• context.data.categories must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { normalizeCategoriesListTerminator } = handlers;

// Use in composition
const categoryPipeline = compose(findCategories, normalizeCategoriesListTerminator);

---

deleteCategoryTerminator

Terminates category deletion with proper status code.

Purpose: Formats successful deletion response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.deleteCategory: Deletion result from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

• context.data.deleteCategory must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { deleteCategoryTerminator } = handlers;

// Use in composition
const categoryPipeline = compose(deleteCategory, deleteCategoryTerminator);

---

enableCategoryTerminator

Terminates category enabling with proper status code.

Purpose: Formats successful category activation response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.enableCategory: Enable result from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

• context.data.enableCategory must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { enableCategoryTerminator } = handlers;

// Use in composition
const categoryPipeline = compose(enableCategory, enableCategoryTerminator);

---

disableCategoryTerminator

Terminates category disabling with proper status code.

Purpose: Formats successful category deactivation response with 204 status

Parameters:

• result: Result<RouteHandlerPayload, Error> - Result containing payload or error
  • context.data.disableCategory: Disable result from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

• context.data.disableCategory must be available from previous handler

Usage:

import { handlers } from '@nodeblocks/backend-sdk';

const { disableCategoryTerminator } = handlers;

// Use in composition
const categoryPipeline = compose(disableCategory, disableCategoryTerminator);