💬 Chat Handler Blocks

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

---

🎯 Overview

Chat handler blocks are designed to:

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

---

📋 Chat Handler Types

Channel Handlers

Functions that perform channel-related operations (creation, retrieval, updates, deletion).

Message Handlers

Functions that perform message-related operations (sending, retrieving, updating, deleting).

Subscription Handlers

Functions that perform subscription-related operations (managing user subscriptions to channels).

Terminator Handlers

Functions that format and return the final chat response.

---

🔧 Available Chat Handlers

📺 Channel Handlers

Core Channel Operations

createChatChannel

Creates a new chat channel in the database with validation and entity management.

Purpose: Handles creation of chat channels with validation and entity management

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with channelId or error

Example Usage:

// Used in composition:
compose(createChatChannel, terminator);

Key Features:

• Validates request body presence
• Creates base entity with metadata
• Returns channel ID on success
• Handles database insertion errors

getChatChannelById

Retrieves a single channel by ID with existence validation.

Purpose: Fetches channel data with existence validation

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with channel or error

Example Usage:

// Used in composition:
compose(getChatChannelById, normalizeTerminator);

Key Features:

• Validates channel ID presence
• Checks channel existence
• Returns full channel object
• Handles database query errors

findChatChannels

Finds multiple channels with optional filtering.

Purpose: Handles querying channels with filter support

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with channels array or error

Example Usage:

// Used in composition:
compose(findChatChannels, listTerminator);

Key Features:

• Accepts optional filter parameters
• Returns all channels if no filter provided
• Supports complex MongoDB queries
• Handles database query errors

updateChatChannel

Updates an existing channel by ID with validation and conflict detection.

Purpose: Handles updating channels with validation and conflict detection

Parameters:

• payload: RouteHandlerPayload containing request context and data

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

Example Usage:

// Used in composition:
compose(updateChatChannel, terminator);

Key Features:

• Validates channel ID and request body
• Checks channel existence before update
• Updates base entity metadata
• Returns update operation result

deleteChatChannel

Deletes a channel by ID with safe deletion and existence validation.

Purpose: Handles safe deletion of channels with existence validation

Parameters:

• payload: RouteHandlerPayload containing request context and data

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

Example Usage:

// Used in composition:
compose(deleteChatChannel, deleteTerminator);

Key Features:

• Validates channel ID presence
• Checks channel existence before deletion
• Returns deletion operation result
• Handles database deletion errors

Channel Terminator Functions

createChatChannelTerminator

Terminates channel creation with proper response formatting.

Purpose: Formats successful channel creation response with 201 status

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Formatted response object with data and statusCode

Example Usage:

// Used in composition:
compose(createChatChannel, createChatChannelTerminator);

Key Features:

• Returns 201 status code for successful creation
• Removes database-specific fields
• Returns formatted channel data

normalizeChatChannelTerminator

Normalizes channel data by removing database-specific fields.

Purpose: Cleans channel data for API response

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Normalized channel object

Example Usage:

// Used in composition:
compose(getChatChannelById, normalizeChatChannelTerminator);

Key Features:

• Removes _id field from channel
• Throws error if channel not found
• Returns clean channel object

normalizeChatChannelsListTerminator

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

Purpose: Cleans channels array data for API response with validation

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Array of normalized channel objects

Example Usage:

// Used in composition:
compose(findChatChannels, normalizeChatChannelsListTerminator);

Key Features:

• Removes _id field from all channels
• Validates channels array existence
• Maps over channels array
• Returns clean channels array

deleteChatChannelTerminator

Terminates channel deletion with proper status code.

Purpose: Formats successful deletion response with 204 status

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Response object with 204 statusCode

Example Usage:

// Used in composition:
compose(deleteChatChannel, deleteChatChannelTerminator);

Key Features:

• Returns 204 status code for successful deletion
• Validates deletion operation result
• Throws error if deletion failed

---

💬 Message Handlers

Core Message Operations

createChatMessage

Creates a new chat message in the database.

Purpose: Handles creation of chat messages with validation and entity management

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with messageId or error

Example Usage:

// Used in route composition:
const createMessageRoute = withRoute({
  handler: compose(createChatMessage, nextHandler)
});

Key Features:

• Validates request body presence
• Creates base entity with metadata
• Returns message ID on success
• Handles database insertion errors

getChatMessageById

Retrieves a chat message by its ID from the database.

Purpose: Fetches message data with existence validation

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with chatMessage or error

Example Usage:

// Used in route composition:
const getMessageRoute = withRoute({
  handler: compose(getChatMessageById, nextHandler)
});

Key Features:

• Validates message ID presence
• Checks message existence
• Returns full message object
• Handles database query errors

findChatMessages

Finds chat messages in the database using optional filter criteria.

Purpose: Handles querying messages with filter support and sorting

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with chatMessages array or error

Example Usage:

// Used in route composition:
const findMessagesRoute = withRoute({
  handler: compose(findChatMessages, nextHandler)
});

Key Features:

• Accepts optional filter parameters
• Sorts messages by creation date (newest first)
• Returns all messages if no filter provided
• Supports complex MongoDB queries

updateChatMessage

Updates an existing chat message in the database.

Purpose: Handles updating messages with validation and conflict detection

Parameters:

• payload: RouteHandlerPayload containing request context and data

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

Example Usage:

// Used in route composition:
const updateMessageRoute = withRoute({
  handler: compose(updateChatMessage, nextHandler)
});

Key Features:

• Validates message ID and request body
• Checks message existence before update
• Updates base entity metadata
• Returns update operation result

deleteChatMessage

Deletes a chat message from the database by its ID.

Purpose: Handles safe deletion of messages with existence validation

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with delete result or error

Example Usage:

// Used in route composition:
const deleteMessageRoute = withRoute({
  handler: compose(deleteChatMessage, nextHandler)
});

Key Features:

• Validates message ID presence
• Checks message existence before deletion
• Returns deletion operation result
• Handles database deletion errors

Message Terminator Functions

createChatMessageTerminator

Formats chat message creation response for API response.

Purpose: Formats successful message creation response with 201 status

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Object with formatted chat message data and 201 status code

Example Usage:

// Used in route composition:
const createMessageRoute = withRoute({
  handler: compose(createChatMessage, lift(createChatMessageTerminator))
});

Key Features:

• Returns 201 status code for successful creation
• Removes database-specific fields
• Returns formatted message data

normalizeChatMessageTerminator

Normalizes single chat message data for API response.

Purpose: Cleans message data for API response

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Normalized chat message object without _id field

Example Usage:

// Used in route composition:
const getMessageRoute = withRoute({
  handler: compose(getChatMessageById, lift(normalizeChatMessageTerminator))
});

Key Features:

• Removes _id field from message
• Throws error if message not found
• Returns clean message object

normalizeChatMessagesListTerminator

Normalizes chat messages list data for API response.

Purpose: Cleans messages array data for API response

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Array of normalized chat message objects without _id fields

Example Usage:

// Used in route composition:
const findMessagesRoute = withRoute({
  handler: compose(findChatMessages, lift(normalizeChatMessagesListTerminator))
});

Key Features:

• Removes _id field from all messages
• Validates messages array existence
• Maps over messages array
• Returns clean messages array

deleteChatMessageTerminator

Formats chat message deletion response for API response.

Purpose: Formats successful deletion response with 204 status

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Object with 204 status code indicating successful deletion

Example Usage:

// Used in route composition:
const deleteMessageRoute = withRoute({
  handler: compose(deleteChatMessage, lift(deleteChatMessageTerminator))
});

Key Features:

• Returns 204 status code for successful deletion
• Validates deletion operation result
• Throws error if deletion failed

---

🔔 Subscription Handlers

Core Subscription Operations

createChatSubscription

Creates a new subscription in the database.

Purpose: Handles creation of chat subscriptions with validation and entity management

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with subscriptionId or error

Example Usage:

// Used in composition:
compose(createChatSubscription, terminator);

Key Features:

• Validates request body presence
• Creates base entity with metadata
• Returns subscription ID on success
• Handles database insertion errors

getChatSubscriptionById

Retrieves a single subscription by ID.

Purpose: Fetches subscription data with existence validation

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with subscription or error

Example Usage:

// Used in composition:
compose(getChatSubscriptionById, normalizeTerminator);

Key Features:

• Validates subscription ID presence
• Checks subscription existence
• Returns full subscription object
• Handles database query errors

findChatSubscriptions

Finds multiple subscriptions with optional filtering.

Purpose: Handles querying subscriptions with filter support

Parameters:

• payload: RouteHandlerPayload containing request context and data

Returns: Result<RouteHandlerPayload, Error> - success with subscriptions array or error

Example Usage:

// Used in composition:
compose(findChatSubscriptions, listTerminator);

Key Features:

• Accepts optional filter parameters
• Returns all subscriptions if no filter provided
• Supports complex MongoDB queries
• Handles database query errors

deleteChatSubscription

Deletes a subscription by ID.

Purpose: Handles safe deletion of subscriptions with existence validation

Parameters:

• payload: RouteHandlerPayload containing request context and data

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

Example Usage:

// Used in composition:
compose(deleteChatSubscription, deleteTerminator);

Key Features:

• Validates subscription ID presence
• Checks subscription existence before deletion
• Returns deletion operation result
• Handles database deletion errors

Subscription Terminator Functions

createChatSubscriptionTerminator

Terminates subscription creation with proper response formatting.

Purpose: Formats successful subscription creation response with 201 status

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Formatted response object with data and statusCode

Example Usage:

// Used in composition:
compose(createChatSubscription, createChatSubscriptionTerminator);

Key Features:

• Returns 201 status code for successful creation
• Removes database-specific fields
• Returns formatted subscription data

normalizeChatSubscriptionTerminator

Normalizes subscription data by removing database-specific fields.

Purpose: Cleans subscription data for API response

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Normalized subscription object

Example Usage:

// Used in composition:
compose(getChatSubscriptionById, normalizeChatSubscriptionTerminator);

Key Features:

• Removes _id field from subscription
• Throws error if subscription not found
• Returns clean subscription object

normalizeChatSubscriptionsListTerminator

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

Purpose: Cleans subscriptions array data for API response with validation

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Array of normalized subscription objects

Example Usage:

// Used in composition:
compose(findChatSubscriptions, normalizeChatSubscriptionsListTerminator);

Key Features:

• Removes _id field from all subscriptions
• Validates subscriptions array existence
• Maps over subscriptions array
• Returns clean subscriptions array

deleteChatSubscriptionTerminator

Terminates subscription deletion with proper status code.

Purpose: Formats successful deletion response with 204 status

Parameters:

• result: Result containing RouteHandlerPayload or Error

Returns: Response object with 204 statusCode

Example Usage:

// Used in composition:
compose(deleteChatSubscription, deleteChatSubscriptionTerminator);

Key Features:

• Returns 204 status code for successful deletion
• Validates deletion operation result
• Throws error if deletion failed