Skip to main content
Version: 0.7.0 (Previous)

⚙️ Order Handlers

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