⚙️ Chat Handlers

Chat handlers 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 handlers 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