⚙️ User Handler Blocks

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

---

🎯 Overview

User handler blocks are designed to:

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

---

📋 User Handler Types

User Async Handlers

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

User Sync Handlers

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

User Terminator Handlers

Functions that format and return the final user response.

---

🔧 Available User Handlers

createUser

Creates a new user in the database.

Purpose: Handles creation of users with validation and entity management

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestBody: User creation data (name, email, etc.)
  • context.db: Database connection

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

Payload Requirements:

• params.requestBody must contain user data (name, email, etc.)
• 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 user into database
• Returns userId on success
• Handles database errors gracefully

Usage:

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

const { createUser } = handlers;

// Use in composition
const userPipeline = compose(createUser, terminator);

---

getUserById

Retrieves a single user by ID.

Purpose: Fetches user data with existence validation

Parameters:

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

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

Payload Requirements:

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

Key Features:

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

Usage:

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

const { getUserById } = handlers;

// Use in composition
const userPipeline = compose(getUserById, normalizeTerminator);

---

findUsers

Finds multiple users with optional filtering.

Purpose: Handles querying users with filter support

Parameters:

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

Returns: Result<RouteHandlerPayload, Error> - Success with users 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 users if no filter provided
• Returns array of users
• Handles database errors gracefully

Usage:

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

const { findUsers } = handlers;

// Use in composition
const userPipeline = compose(findUsers, listTerminator);

---

updateUser

Updates an existing user by ID.

Purpose: Handles updating users with validation and conflict detection

Parameters:

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

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

Payload Requirements:

• Profile ID must be provided in params.requestParams.profileId or context.data.profileId
• params.requestBody must contain user data to update
• context.db must be available for database operations

Key Features:

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

Usage:

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

const { updateUser } = handlers;

// Use in composition
const userPipeline = compose(updateUser, terminator);

---

deleteUser

Deletes a user by ID.

Purpose: Handles safe deletion of users with existence validation

Parameters:

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

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

Payload Requirements:

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

Key Features:

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

Usage:

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

const { deleteUser } = handlers;

// Use in composition
const userPipeline = compose(deleteUser, deleteTerminator);

---

lockUser

Locks a user by setting isLocked to true.

Purpose: Handles user account locking with validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.identityId or context.data.identityId: Identity ID to lock
  • context.db: Database connection

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

Payload Requirements:

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

Key Features:

• Validates userId is provided
• Sets isLocked to true for user account
• Checks if user exists before locking
• Returns lock result on success
• Handles not found and lock failures

Usage:

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

const { lockUser } = handlers;

// Use in composition
const userPipeline = compose(lockUser, lockTerminator);

---

unlockUser

Unlocks a user by setting isLocked to false.

Purpose: Handles user account unlocking with validation

Parameters:

• payload: RouteHandlerPayload - Contains request context and data
  • params.requestParams.identityId or context.data.identityId: Identity ID to unlock
  • context.db: Database connection

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

Payload Requirements:

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

Key Features:

• Validates userId is provided
• Sets isLocked to false for user account
• Checks if user exists before unlocking
• Returns unlock result on success
• Handles not found and unlock failures

Usage:

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

const { unlockUser } = handlers;

// Use in composition
const userPipeline = compose(schema, unlockUser, unlockUserTerminator);

---

🎯 User Terminator Handlers

normalizeUserTerminator

Normalizes user data by removing database-specific fields.

Purpose: Cleans user data for API response

Parameters:

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

Returns: Normalized user object

Payload Requirements:

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

Usage:

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

const { normalizeUserTerminator } = handlers;

// Use in composition
const userPipeline = compose(getUserById, normalizeUserTerminator);

---

normalizeUsersListTerminator

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

Purpose: Cleans users array data for API response

Parameters:

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

Returns: Array of normalized user objects

Payload Requirements:

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

Usage:

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

const { normalizeUsersListTerminator } = handlers;

// Use in composition
const userPipeline = compose(findUsers, normalizeUsersListTerminator);

---

deleteUserTerminator

Terminates user 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.deleteUser: Deletion result from previous handler

Returns: Response object with 204 statusCode

Payload Requirements:

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

Usage:

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

const { deleteUserTerminator } = handlers;

// Use in composition
const userPipeline = compose(deleteUser, deleteUserTerminator);

---

lockUserTerminator

Terminates user locking with proper status code.

Purpose: Formats successful user lock response with 204 status

Parameters:

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

Returns: Response object with 204 statusCode

Payload Requirements:

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

Usage:

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

const { lockUserTerminator } = handlers;

// Use in composition
const userPipeline = compose(lockUser, lockUserTerminator);

---

unlockUserTerminator

Terminates user unlocking with proper status code.

Purpose: Formats successful user unlock response with 204 status

Parameters:

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

Returns: Response object with 204 statusCode

Payload Requirements:

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

Usage:

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

const { unlockUserTerminator } = handlers;

// Use in composition
const userPipeline = compose(schema, unlockUser, unlockUserTerminator);