Convert JavaScript File to TypeScript

Convert this JavaScript file to TypeScript.

Do:
- Rename to .ts
- Add type annotations for parameters and returns
- Introduce interfaces/types for complex objects
- Use generics where useful
- Enable strict null checks (no implicit any)
- Fix any type errors that appear

Explain any important typing decisions in comments.