Skip to main content
Version: 🚧 Canary

📦 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