# Calculator Module Interface Contract

## Purpose
Defines the interface for the core calculator functionality module that will handle all mathematical operations.

## Interface Definition

### Core Calculator API
```
interface Calculator {
  // Evaluate an arithmetic expression in standard notation
  evaluate(expression: string): number | Error
  
  // Add two numbers
  add(a: number, b: number): number
  
  // Subtract two numbers  
  subtract(a: number, b: number): number
  
  // Multiply two numbers
  multiply(a: number, b: number): number
  
  // Divide two numbers (handles division by zero)
  divide(a: number, b: number): number | Error
  
  // Handle percentage operations
  percentage(value: number, percent: number): number
  
  // Toggle sign of a number
  toggleSign(value: number): number
  
  // Clear the current calculation
  clear(): void
  
  // Get current display value
  getCurrentDisplay(): string
}
```

### RPN Calculator API
```
interface RPNCalculator {
  // Push a number onto the stack
  push(value: number): void
  
  // Pop a number from the stack
  pop(): number | undefined
  
  // Perform an operation on stack values
  operate(operator: string): number | Error
  
  // Clear the entire stack
  clear(): void
  
  // Get current stack state
  getStack(): number[]
  
  // Execute RPN expression (e.g., "3 4 +")
  evaluate(rpnExpression: string): number | Error
}
```

### Validation Requirements
- All operations must return valid numbers or appropriate error objects
- Division by zero must return an Error object
- Expression syntax errors must return Error objects
- Operations must respect JavaScript numeric limits (will return Infinity if exceeded)

### Performance Requirements
- All operations must complete within 100ms
- Evaluation should be efficient to maintain responsive UI

### Error Handling
- Invalid operations return Error objects with descriptive messages
- Overflow conditions return Infinity values
- Underflow conditions return 0 values