Decoradores Experimentais em TypeScript: Analisando por Baixo dos Panos

Por que seu TypeScript reclama sobre "decoradores experimentais"?

Você já compilou um projeto TypeScript e viu algo assim no console:

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.

Se sim, você não está sozinho. Esta pergunta no Stack Overflow acumulou milhares de visualizações e dezenas de respostas. Mas a maioria delas sugere apenas "ativar a opção e esquecer". Hoje iremos mais longe: entenderemos o que é o aviso de decoradores experimentais no TypeScript, de onde ele vem, como funciona por baixo dos panos e por que o TypeScript considera os decoradores "experimentais".

O que são decoradores no TypeScript (e por que são experimentais)?

Decoradores são uma ferramenta poderosa de metaprogramação. Eles permitem anotar e modificar classes, métodos, propriedades e parâmetros em tempo de execução. Se você trabalhou com Angular, NestJS ou TypeORM, já os encontrou:

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

Mas eis o problema: o padrão JavaScript para decoradores (proposta TC39) ainda está no estágio Stage 3. Isso significa que a sintaxe e a semântica podem mudar. O TypeScript, sendo um superconjunto do JavaScript, não pode simplesmente "congelar" a implementação — ele oferece suporte experimental para decoradores através da flag experimentalDecorators.

Quando você ativa esta opção, o compilador TypeScript gera código que pode se tornar obsoleto ou quebrar com a atualização do padrão. É por isso que ele avisa honestamente: "Você usa por sua conta e risco".

Como o aviso de decoradores experimentais funciona por baixo dos panos do compilador?

Para entender o aviso, vamos dar uma olhada nos fontes do TypeScript. No arquivo checker.ts (sim, é um arquivo real dentro do compilador) existe a função checkGrammarForDecorator. Quando o parser encontra um decorador, o compilador verifica se a flag experimentalDecorators está definida no tsconfig.json.

Se a flag não estiver definida, ele gera uma mensagem de diagnóstico — o próprio aviso. Não é um erro (o código ainda será compilado), mas o compilador insiste em lembrar: "Ei, você está usando um recurso que pode mudar!".

Aqui está como a lógica simplificada se parece:

// Pseudocódigo da lógica real do 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}

O código de erro 1219 é exatamente o aviso que você vê. E o código 1220 é um aviso semelhante para emitDecoratorMetadata (outra flag experimental, que discutiremos abaixo).

Como desativar o aviso de decoradores experimentais: 3 maneiras

A maneira mais simples é adicionar a flag no tsconfig.json:

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

Se você estiver usando a linha de comando:

tsc --experimentalDecorators

Ou se você não tiver um tsconfig.json, pode passar a flag diretamente:

npx tsc --experimentalDecorators src/index.ts

Depois disso, o aviso desaparecerá. Mas isso é apenas a ponta do iceberg. Vamos entender o que realmente acontece quando você ativa experimentalDecorators.

O que o compilador gera por baixo dos panos?

Quando você escreve um decorador de clas