typescript-cross-module-patterns

# TypeScript Cross-Module Patterns Patrones y pitfalls al trabajar con TypeScript en proyectos multi-módulo (engine headless + backend + frontend + tests). ## Cuándo usar - Proyectos con engine compartido entre Node.js, browser, y tests - Cuando interfaces estrictos causan errores CI en archivos que usan subconjuntos distintos de propiedades - Cuando dependencias externas sin tipos rompen `tsc --noEmit` - Cualquier proyecto que deba pasar typecheck en CI antes de deploy ## Patrón 1: Tipos flexibles para compatibilidad cross-module **Problema:** Interfaces estrictos en `types.ts` causan errores cuando: - `defaults.ts` crea objetos con propiedades parciales - `tests/` instancia objetos con campos diferentes al engine - `frontend/` solo usa un subconjunto de campos **Solución:** Interfaces documentados con campos flexibles: ```typescript // ❌ Estricto — causa 22+ errores CI interface SimParams { year: number; nuclearCapacity: number; solarCapacity: number; demandGrowth: number; // ... 30+ campos } // ✅ Flexible — 0 errores, documentación preserved interface SimParams { [key: string]: any; /** Año de simulación (2026-2050) */ year?: number; /** Capacidad nuclear en GW */ nuclearCapacity?: number; } ``` **Trade-off:** Menos type safety pero código funcional y CI limpio. Para proyectos donde la velocidad de iteración > corrección estricta de tipos. **Alternativa estricta (si se necesita):** Usar `Partial<T>` en defaults/tests: ```typescript const params: Partial<SimParams> = { year: 2030 }; ``` Pero esto requiere adaptar TODOS los archivos que consumen los tipos. ## Patrón 2: Declaration files para dependencias sin tipos **Problema:** Librerías como Plotly.js no exportan tipos TypeScript. **Solución:** Archivo `shims-{lib}.d.ts` en `src/`: ```typescript // src/shims-plotly.d.ts declare module 'plotly.js-dist-min' { const Plotly: any; export default Plotly; } ``` Ubicación: junto al `main.ts` o en `src/types/`. Vite lo detecta automáticamente. **Otras libs que necesitan shim:** - `plotly.js-dist-min` - `chart.js` (si se usa sin `@types/chart.js`) - Librerías internas sin `index.d.ts` ## Patrón 3: CI typecheck obligatorio **Problema:** Tests pasan localmente (`vitest run`) pero CI falla en `vue-tsc --noEmit`. **Causa:** Vitest solo valida runtime. `tsc`/`vue-tsc` validan tipos. Son validaciones independientes. **Solución:** SIEMPRE ejecutar ambos antes de push: ```bash # Secuencia obligatoria npx vitest run # 1. Tests npx vue-tsc --noEmit # 2. Typecheck git add -A && git commit -m "..." && git push ``` **En CI (GitHub Actions):** ```yaml - run: npx vitest run - run: npx vue-tsc --noEmit # Separado para error claro ``` ## Patrón 4: Evitar corrupción de archivos con read_file **Problema:** `read_file()` en Hermes incluye prefijos de línea (` 1|content`). Si ese output se pasa a `write_file()` o `patch()`, los prefijos quedan en el archivo. **Solución en execute_code:** ```python import re content = re.sub(r'^\s*\d+\|', '', raw_content, flags=re.MULTILINE) ``` **Solución en terminal:** ```bash sed -i 's/^[0-9]*|//' archivo.ts ``` **Regla:** NUNCA usar output de `read_file()` directamente en `write_file()`. Siempre limpiar prefijos primero. ## Patrón 5: Imports consistentes en multi-módulo **Problema:** Diferentes directorios necesitan paths de import distintos para el mismo módulo. **Solución:** Establecer convención al inicio del proyecto: ``` src/engine/ → import './types' (mismo directorio) src/engine/weather/ → import '../types' (un nivel arriba) tests/ → import '../../src/engine/types' (relativo a src) src/web/components/ → import '../../engine/types' (relativo a src) ``` **Alternativa:** Usar `tsconfig.json` paths: ```json { "compilerOptions": { "paths": { "@engine/*": ["./src/engine/*"] } } } ``` Pero Vite requiere configuración adicional en `vite.config.ts` para resolver paths. ## Patrón 6: Contratos de pipeline de datos entre módulos **Problema:** Módulo A produce datos y módulo B los consume, pero los campos no coinciden. El error aparece en runtime (crash silencioso o `undefined`), no en compile time. **Ejemplo real:** `procesarOpenMeteo()` devuelve `{solar, wind, temperature, humidity, cloudCover, summary}`. Pero `aplicarClimateShift()` accede a `base.radiation[h]` y `base.precipitation[h]` que no existen. Resultado: simulación muere al clickear "Simular" sin error visible. **Solución:** Definir el contrato una vez, implementar en ambos lados: ```typescript // Definir tipo completo interface ProcessedWeather { solar: Float64Array; wind: Float64Array; temperature: Float64Array; humidity: Float64Array; cloudCover: Float64Array; radiation: Float64Array; // ← OBLIGATORIO para climate-shift precipitation: Float64Array; // ← OBLIGATORIO para climate-shift summary: ResumenClimatico; } // Producción (open-meteo.ts) DEBE devolver todos los campos function procesarOpenMeteo(data: OpenMeteoData): ProcessedWeather { return { solar, wind, temperature, humidity, cloudCover, radiation, // ← Incluir aunque sea vacío precipitation: new Float64Array(horasEsperadas), // ← Placeholder summary: { ... } }; } ``` **Regla:** Cuando un módulo consume datos de otro, verificar que el tipo de retorno del productor incluya TODOS los campos que el consumidor accede. Buscar con `grep "base\.\|data\.\|input\.\|params\.\|config\."` en el consumidor para encontrar todos los campos accedidos. ## Pitfalls 1. **`as const` en tipos exportados:** Causa TS1355 en uniones de tipo. Usar tipos simples. 2. **Faltantes en constantes:** Si un objeto `FISICA` o `CONFIG` se comparte entre módulos, TODOS los campos usados deben existir. Un campo faltante → `undefined` → NaN silencioso en tests. 3. **Plotly sin types:** Sin `shims-plotly.d.ts`, `tsc` falla con "Could not find a declaration file". 4. **NVM en CI/terminal:** `npm`/`npx` no están en PATH por defecto en NaN. Siempre source NVM antes. 5. **`vue-tsc` vs `tsc`:** Proyectos Vue necesitan `vue-tsc` (procesa `.vue` files). `tsc` solo ve `.ts`.