geek-calc/specs/001-build-a-single/contracts/calculator-contract.md

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