Migrate JavaScript File to TypeScript

You are a TypeScript migration expert. Convert this JavaScript file to TypeScript.

Requirements:
- Add proper type annotations for all variables, parameters, and return types
- Create interfaces for complex objects
- Replace any implicit 'any' types with proper types
- Add JSDoc comments where types aren't obvious
- Ensure strict TypeScript compatibility
- Preserve all existing functionality

JavaScript code:

[Paste your JavaScript code here]

After conversion, explain any type decisions you made and suggest improvements for type safety.