Code Documentation with JSDoc

Add comprehensive JSDoc documentation to this code:

```typescript
[PASTE_YOUR_CODE]
```

For each function/method, add:
- **@description** — what it does (one sentence)
- **@param** — each parameter with type and description
- **@returns** — return type and what it represents
- **@throws** — any exceptions with conditions
- **@example** — one realistic usage example

For each interface/type:
- **@description** — purpose of this type
- **Property descriptions** — inline comment for non-obvious fields

For each class:
- **@description** — responsibility and when to use it
- **@example** — basic instantiation and usage

Rules:
- Don't state the obvious (skip "name - the name of the user")
- Focus on WHY and WHEN, not just WHAT
- Include edge cases in descriptions ("returns null if user not found")
- Use `@see` to link related functions
- Keep examples realistic, not contrived

Return the fully documented code.