Backend API Specification: Calculation Engine

Overview

Endpoint to evaluate calculated test formulas and return computed values with proper rounding and error handling.

Endpoint

POST /api/calculate/evaluate

Request Body

{
  // The formula expression using test codes as variables
  // Example: "CHOL - HDL - (TG/5)"
  formula: string;
  
  // Map of test codes to their current numeric values
  // Example: { "CHOL": 180, "HDL": 45, "TG": 150 }
  values: Record<string, number>;
  
  // Decimal precision for rounding (0-6)
  // Default: 2
  decimal?: number;
}

Response Body

Success (200)

{
  status: "success";
  data: {
    // The computed result value
    result: number;
    
    // The result rounded to specified decimal places
    resultRounded: number;
    
    // Formula that was evaluated (for verification)
    evaluatedFormula: string;
  }
}

Error (400/422)

{
  status: "error";
  message: string;
  error: {
    // Error type for frontend handling
    type: "MISSING_VALUE" | "INVALID_EXPRESSION" | "DIVISION_BY_ZERO" | "SYNTAX_ERROR";
    
    // Missing variable names if applicable
    missingVars?: string[];
    
    // Position of syntax error if applicable
    position?: number;
  }
}

Formula Syntax

Supported Operators

Arithmetic: +, -, *, /, ^ (power)
Parentheses: ( ) for grouping
Functions: abs(), round(), floor(), ceil(), min(), max(), sqrt()

Variable Names

Test codes are used as variable names directly
Case-sensitive (CHOL ≠ chol)
Must match exactly (word boundaries)

Examples

Simple subtraction:

Formula: "CHOL - HDL"
Values: { "CHOL": 180, "HDL": 45 }
Result: 135

Complex with division:

Formula: "CHOL - HDL - (TG/5)"
Values: { "CHOL": 180, "HDL": 45, "TG": 150 }
Result: 105

With decimal rounding:

Formula: "(HGB * MCV) / 100"
Values: { "HGB": 14.2, "MCV": 87.5 }
Decimal: 2
Result: 12.43

Validation Rules

Missing Values: If any variable in formula is not provided in values, return MISSING_VALUE error
Division by Zero: Return DIVISION_BY_ZERO error if encountered
Invalid Syntax: Return SYNTAX_ERROR with position if formula cannot be parsed
Non-numeric Values: Return MISSING_VALUE if any value is not a valid number

Batch Endpoint (Optional)

For efficiency when recalculating multiple CALC tests:

POST /api/calculate/evaluate-batch

// Request
{
  calculations: [
    {
      testSiteId: number;
      formula: string;
      values: Record<string, number>;
      decimal?: number;
    }
  ]
}

// Response
{
  status: "success";
  data: {
    results: [
      {
        testSiteId: number;
        result: number;
        resultRounded: number;
        error?: {
          type: string;
          message: string;
        }
      }
    ]
  }
}

Frontend Integration

The frontend will:

Build dependency graph from test definitions
Detect when member test values change
Call this API to compute dependent CALC tests
Update UI with computed values
Mark CALC tests as changedByAutoCalc for save tracking

Security Considerations

Never use eval() or similar unsafe evaluation
Use a proper expression parser (mathjs, muparser, or custom parser)
Sanitize/validate formula input before parsing
Limit computation time to prevent DoS

3.4 KiB Raw Blame History