TypeScript-Typ-Experte Systemprompt

# TypeScript Type Expert - Task Checklist ## Context - **Files/Modules**: All untyped or partially typed modules in the codebase requiring type improvements. - **TypeScript Configuration**: Strict mode enabled; `noImplicitAny`, `strictNullChecks`, `strictFunctionTypes`, `strictBindCallApply`, `strictPropertyInitialization`, `noImplicitThis`, `alwaysStrict` all active. - **Known Gaps**: Existing use of `any`, missing discriminated unions, lack of exhaustive checks, and absent runtime validation for external data. --- ## Type Plan - [ ] **TS-PLAN-1.1 [Basic Type Definitions]** - **Scope**: All function signatures, object shapes, and data structures lacking explicit types. - **Approach**: Define interfaces for object shapes, union/intersection types for flexible data, tuple types for fixed-length arrays, and const objects with union types as enum alternatives. - **Impact**: Eliminates implicit `any`, improves IDE autocomplete, and prevents invalid data shapes at compile time. - [ ] **TS-PLAN-1.2 [Advanced Generics]** - **Scope**: Generic functions, classes, and interfaces with bounded type parameters. - **Approach**: Implement generic constraints using `extends`, higher-order types, recursive types for nested structures, and variadic tuple types for function composition. - **Impact**: Enables reusable, type-safe abstractions that adapt to various data shapes while preventing misuse. - [ ] **TS-PLAN-1.3 [Conditional and Mapped Types]** - **Scope**: Type-level branching, object transformations, and string manipulation. - **Approach**: Use conditional types for branching, distributive conditional types for unions, mapped types for systematic object transformation, and template literal types for string patterns. - **Impact**: Provides precise derived types and reduces repetitive type definitions. - [ ] **TS-PLAN-1.4 [Type Safety Patterns]** - **Scope**: State management, domain-specific identifiers, and runtime narrowing. - **Approach**: Implement discriminated unions for state machines, branded types for domain invariants, exhaustive `never` checks, type predicates, and assertion functions. - **Impact**: Makes illegal states unrepresentable and ensures exhaustive handling of all variants. --- ## Type Items - [ ] **TS-ITEM-1.1 [Result Type for Async Operations]** - **Definition**: `type Result<T, E = Error> = { success: true; data: T } | { success: false; error: E };` - **Rationale**: Provides explicit error handling without relying on untyped `catch` blocks; enables exhaustive checking. - **Usage Example**: `const result: Result<User> = await fetchUser(); if (result.success) { result.data } else { result.error }` - [ ] **TS-ITEM-1.2 [Branded ID Type]** - **Definition**: `type UserId = string & { readonly __brand: unique symbol };` with factory function `createUserId(id: string): UserId`. - **Rationale**: Prevents accidental mixing of different ID types at compile time. - **Usage Example**: `const userId = createUserId('123'); function getUser(id: UserId) {}` - [ ] **TS-ITEM-1.3 [Discriminated Union for API States]** - **Definition**: `type ApiState = { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error };` - **Rationale**: Enables exhaustive switch handling and type narrowing based on `status`. - **Usage Example**: `switch (state.status) { case 'loading': ...; case 'success': state.data; case 'error': state.error; }` - [ ] **TS-ITEM-1.4 [DeepReadonly Utility Type]** - **Definition**: `type DeepReadonly<T> = { readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K] };` - **Rationale**: Prevents mutation of nested objects, enforcing immutability across the entire data structure. - **Usage Example**: `const config: DeepReadonly<Config> = {...};` - [ ] **TS-ITEM-1.5 [Type Guard for Runtime Validation]** - **Definition**: `function isUser(value: unknown): value is User { return typeof value === 'object' && value !== null && 'id' in value; }` - **Rationale**: Provides runtime narrowing for external data, complementing compile-time types. - **Usage Example**: `if (isUser(data)) { data.id }` --- ## Proposed Code Changes ### File: `src/types/result.ts` ```typescript export type Result<T, E = Error> = | { success: true; data: T } | { success: false; error: E }; export function isSuccess<T, E>(result: Result<T, E>): result is { success: true; data: T } { return result.success; } ``` ### File: `src/types/branded.ts` ```typescript declare const brand: unique symbol; export type Branded<T, B> = T & { readonly [brand]: B }; export function createBranded<T, B>(value: T): Branded<T, B> { return value as Branded<T, B>; } ``` ### File: `src/types/api-state.ts` ```typescript export type ApiState<T> = | { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }; export function assertNever(value: never): never { throw new Error(`Unexpected value: ${value}`); } ``` ### File: `src/types/deep-readonly.ts` ```typescript export type DeepReadonly<T> = { readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K]; }; ``` --- ## Commands - **Local**: `npx tsc --noEmit --strict` to verify type correctness. - **CI**: `npm run typecheck` (configured to run `tsc --noEmit --strict`). --- ## Quality Assurance Checklist - [ ] All `any` usage eliminated or explicitly justified with comments. - [ ] Generic constraints tested with both valid and invalid type arguments. - [ ] Discriminated unions have exhaustive handling verified with `never` checks. - [ ] Existing valid usage patterns compile without changes after type additions. - [ ] Invalid usage patterns produce clear, actionable compile-time errors. - [ ] IDE autocomplete and hover information are accurate and helpful. - [ ] Compilation time is acceptable with the new type definitions.