📦 Order Handler Blocks
Order handler blocks provide core business logic functions for order management operations in Nodeblocks applications. These handlers encapsulate common patterns for order database operations, data transformation, and response formatting.
🎯 Overview
Order handler blocks are designed to:
- Encapsulate order business logic in reusable functions
- Handle order database operations with proper error management
- Transform order data between different formats
- Ensure type safety with TypeScript integration
- Support composition with other order blocks
📋 Order Handler Types
Order Async Handlers
Functions that perform asynchronous order operations (database calls, API requests, etc.).
Order Sync Handlers
Functions that perform synchronous order operations (data transformation, validation, etc.).
Order Terminator Handlers
Functions that format and return the final order response.
🔧 Available Order Handlers
createOrder
Creates a new order in the database with validation and entity management.
Purpose: Handles creation of orders with validation and entity management
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with orderId or error
Example Usage:
// Used in composition:
compose(createOrder, terminator);
Key Features:
- Validates request body is present and not empty
- Creates base entity with timestamps and ID
- Inserts order into database
- Returns orderId on success
- Handles database errors gracefully
updateOrder
Updates an existing order by ID with validation and conflict detection.
Purpose: Handles updating orders with validation and conflict detection
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with orderId or error
Example Usage:
// Used in composition:
compose(updateOrder, terminator);
Key Features:
- Validates orderId is provided
- Validates request body is present and not empty
- Updates base entity with timestamps
- Checks if order exists before updating
- Returns orderId on success
- Handles not found and update failures
getOrderById
Retrieves a single order by ID with existence validation.
Purpose: Fetches order data with existence validation
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with orderGroup or error
Example Usage:
// Used in composition:
compose(getOrderById, normalizeTerminator);
Key Features:
- Validates orderId is provided
- Finds order by ID in database
- Returns 404 if order not found
- Returns orderGroup data on success
- Handles database errors gracefully
findOrders
Finds multiple orders with optional filtering support.
Purpose: Handles querying orders with filter support
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with orderGroups array or error
Example Usage:
// Used in composition:
compose(findOrders, listTerminator);
Key Features:
- Accepts optional filter from request query
- Returns all orders if no filter provided
- Returns array of orderGroups
- Handles database errors gracefully
deleteOrder
Deletes an order by ID with safe deletion and existence validation.
Purpose: Handles safe deletion of orders with existence validation
Parameters:
payload: RouteHandlerPayload containing request context and data
Returns: Result<RouteHandlerPayload, Error> - success with deletion flag or error
Example Usage:
// Used in composition:
compose(deleteOrder, deleteTerminator);
Key Features:
- Validates orderId is provided
- Deletes order by ID from database
- Returns 404 if order not found
- Returns deletion confirmation flag
- Handles database errors gracefully
Terminator Handlers
createOrderTerminator
Terminates order creation with proper response formatting.
Purpose: Formats successful order creation response with 201 status
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Formatted response object with data and statusCode
Example Usage:
// Used in composition:
compose(createOrder, createOrderTerminator);
Key Features:
- Throws error if result is error
- Validates orderGroup exists in context
- Removes database _id field
- Returns 201 status code for creation
normalizeOrderTerminator
Normalizes order data by removing database-specific fields.
Purpose: Cleans order data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Normalized order object
Example Usage:
// Used in composition:
compose(getOrderById, normalizeOrderTerminator);
Key Features:
- Throws error if result is error
- Validates orderGroup exists in context
- Removes database _id field
- Returns clean order object
normalizeOrdersListTerminator
Normalizes orders list by removing database-specific fields from each item.
Purpose: Cleans orders array data for API response
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Array of normalized order objects
Example Usage:
// Used in composition:
compose(findOrders, normalizeOrdersListTerminator);
Key Features:
- Throws error if result is error
- Maps over orderGroups array
- Removes database _id field from each order
- Returns array of clean order objects
deleteOrderTerminator
Terminates order deletion with proper status code.
Purpose: Formats successful deletion response with 204 status
Parameters:
result:Result<RouteHandlerPayload, Error>
Returns: Response object with 204 statusCode
Example Usage:
// Used in composition:
compose(deleteOrder, deleteOrderTerminator);
Key Features:
- Throws error if result is error
- Validates deletion flag exists
- Returns 204 status code for successful deletion