clean-typescriptlisted

# Clean TypeScript We use **TypeScript as a correctness and clarity tool**, not as ceremony. Types should reduce bugs and cognitive load. ## Type Philosophy - **PREFER** explicit, readable types over clever or overly generic ones - **AVOID** `any` and unsafe type assertions - Use `unknown` instead of `any` when necessary - Let TypeScript infer types when inference is clear and stable ## Types & Interfaces - **PREFER** `type` aliases for most use cases - Use `interface` primarily for public, extendable object shapes - Keep types small, composable, and well-named ## Functions & APIs - **PREFER** explicit return types for public functions - Avoid function overloads unless they meaningfully improve the API - Keep function signatures simple and predictable ## Nullability & Safety - Handle `null` and `undefined` explicitly - **DO NOT** rely on non-null assertions (`!`) except as a last resort - Prefer narrowing via control flow and guards ## Enums & Constants - **AVOID** `enum` - **PREFER** union types or `as const` objects - Keep runtime output predictable and minimal ## Error Handling - Type errors and error states explicitly - Prefer result objects or typed errors over throwing where appropriate - Do not hide failure modes behind broad types ## General Principles - Types should explain intent - If a type is hard to understand, it’s probably wrong - Favor maintainability over theoretical completeness