Decoradores experimentales en TypeScript: analizando bajo el capó

¿Por qué tu TypeScript grita sobre «decoradores experimentales»?

¿Alguna vez has ejecutado la compilación de un proyecto TypeScript y has visto en la consola algo como:

Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option in your 'tsconfig.json' or '--experimentalDecorators' to remove this warning.

Si es así, no estás solo. Esta pregunta en Stack Overflow ha acumulado miles de visitas y decenas de respuestas. Pero la mayoría de ellas simplemente sugieren «activar la opción y olvidarse». Hoy iremos más allá: entenderemos qué es la advertencia de decoradores experimentales en TypeScript, de dónde viene, cómo funciona bajo el capó y por qué TypeScript considera los decoradores como «experimentales».

¿Qué son los decoradores en TypeScript (y por qué son experimentales)?

Los decoradores son una poderosa herramienta de metaprogramación. Permiten anotar y modificar clases, métodos, propiedades y parámetros en tiempo de ejecución. Si has trabajado con Angular, NestJS o TypeORM, ya te has encontrado con ellos:

@Component({\n  selector: 'app-root',\n  templateUrl: './app.component.html'\n})\nclass AppComponent {}

Pero aquí está el problema: el estándar de JavaScript para decoradores (propuesta TC39) todavía se encuentra en la etapa Stage 3. Esto significa que la sintaxis y la semántica pueden cambiar. TypeScript, al ser un superconjunto de JavaScript, no puede simplemente «congelar» la implementación; ofrece soporte experimental para decoradores a través de la bandera experimentalDecorators.

Cuando activas esta opción, el compilador de TypeScript genera código que podría quedar obsoleto o romperse al actualizar el estándar. Por eso advierte honestamente: «Lo usas bajo tu propio riesgo».

¿Cómo funciona la advertencia de decoradores experimentales bajo el capó del compilador?

Para entender la advertencia, echemos un vistazo al código fuente de TypeScript. En el archivo checker.ts (sí, es un archivo real dentro del compilador) hay una función llamada checkGrammarForDecorator. Cuando el analizador encuentra un decorador, el compilador verifica si la bandera experimentalDecorators está configurada en tsconfig.json.

Si la bandera no está configurada, genera un mensaje de diagnóstico: esa misma advertencia. No es un error (el código igual se compilará), pero el compilador insiste en recordarte: «¡Oye, estás usando una característica que podría cambiar!».

Así es como se ve la lógica simplificada:

// Pseudocódigo de la lógica real de TypeScript\nfunction checkDecoratorUsage(decorator: Decorator, options: CompilerOptions) {\n  if (!options.experimentalDecorators) {\n    reportDiagnostic({\n      code: 1219,\n      message: "Experimental support for decorators is a feature that is subject to change in a future release..."\n    });\n  }\n}

El código de error 1219 es exactamente la advertencia que ves. Y el código 1220 es una advertencia similar para emitDecoratorMetadata (otra bandera experimental de la que hablaremos más adelante).

Cómo desactivar la advertencia de decoradores experimentales: 3 formas

La forma más sencilla es agregar la bandera en tsconfig.json:

{\n  "compilerOptions": {\n    "experimentalDecorators": true\n  }\n}

Si usas la línea de comandos:

tsc --experimentalDecorators

O si no tienes un tsconfig.json, puedes pasar la bandera directamente:

npx tsc --experimentalDecorators src/index.ts

Después de esto, la advertencia desaparecerá. Pero esto es solo la punta del iceberg. Analicemos qué sucede realmente cuando activas experimentalDecorators.

¿Qué genera el compilador bajo el capó?

Cuando escribes un decorador de cla