A equipe do TypeScript lançou uma nova flag de compilador na versão 6.0 – --noPropertyAccessFromIndexSignature. Quando habilitada, o compilador recusa o acesso via notação de ponto a propriedades que vêm de uma assinatura de índice (index signature), forçando os desenvolvedores a usar a notação de colchetes e expondo possíveis valores undefined em tempo de compilação, em vez de em produção.

Por que a flag é importante

No JavaScript, objetos frequentemente servem como dicionários, e o TypeScript permite tipar tais estruturas com uma assinatura de índice, por exemplo, Record<string, T>. A linguagem trata obj.key e obj["key"] como intercambiáveis, então o compilador assume que a propriedade existe mesmo quando a chave só é conhecida em tempo de execução. Essa suposição silenciosa é a origem de muitos erros: um código que acessa obj.missingProp compila normalmente, é executado e então falha porque o valor é undefined.

A notação de ponto carrega uma garantia implícita – ela diz aos leitores e ao verificador de tipos que a propriedade está definitivamente presente. A notação de colchetes, por outro lado, sinaliza incerteza – a chave pode estar ausente e o resultado pode ser undefined. A flag --noPropertyAccessFromIndexSignature impõe essa distinção visual e semântica, transformando uma classe de erros de tempo de execução em diagnósticos de tempo de compilação.

Como a flag funciona

Quando a flag é ativada, qualquer expressão que acesse uma propriedade por meio de uma assinatura de índice usando notação de ponto é marcada como um erro. O código deve ser reescrito para usar colchetes:

// Before
const name = userData.name;          // OK even if "name" is not in the index

// After enabling the flag
const name = userData["name"];       // Error unless brackets are used

O compilador então aplica as mesmas regras de tratamento de undefined que já utiliza para o acesso por colchetes. Se --noUncheckedIndexedAccess também estiver habilitada, o tipo de userData["name"] torna-se T | undefined, forçando o desenvolvedor a verificar o caso de ausência.

Passos práticos de migração

  1. Habilite a flag no tsconfig.json:

    {
  "compilerOptions": {
    "noPropertyAccessFromIndexSignature": true
  }
}

  2. Execute o verificador de tipos. Todos os acessos via notação de ponto a chaves de assinatura de índice aparecerão como erros.

  3. Substitua pontos por colchetes. A mudança é mecânica; ela não afeta o desempenho em tempo de execução.

  4. Trate os tipos undefined resultantes. Adicione coalescência nula (nullish coalescing), encadeamento opcional (optional chaining) ou verificações explícitas onde for necessário.

  5. Considere combinar com --noUncheckedIndexedAccess para obter a rede de segurança mais robusta. Juntas, elas garantem que qualquer acesso estilo dicionário seja tratado como potencialmente ausente.

Quando manter propriedades explícitas

Se um campo faz parte de um contrato de API estável, declare-o como uma propriedade explícita em vez de depender de uma assinatura de índice. Propriedades explícitas continuam permitindo a notação de ponto, preservando a garantia de que o campo sempre estará presente (dentro do que o sistema de tipos pode verificar). Reserve assinaturas de índice para dados verdadeiramente dinâmicos, onde as chaves não são conhecidas antecipadamente.

Contraponto: verbosidade adicional

Algumas equipes podem achar o excesso de colchetes barulhento, especialmente em bases de código que utilizam intensamente objetos flexíveis. A flag impõe uma disciplina mais rigorosa que pode exigir uma refatoração considerável em projetos legados. Nesses casos, a flag pode ser introduzida incrementalmente, talvez limitada a novos módulos, enquanto o restante da base de código adota o padrão ao longo do tempo.

O que observar a seguir

A flag faz parte de um movimento mais amplo no TypeScript 6.0 em direção a uma segurança de tipos mais rigorosa. Versões futuras podem introduzir verificações adicionais em torno de object spread, optional chaining ou uso de any inferido. Ficar de olho no roadmap do TypeScript ajudará as equipes a decidir quando adotar o próximo conjunto de recursos de segurança sem interromper os cronogramas de entrega.

Resumo: Habilitar --noPropertyAccessFromIndexSignature torna explícita no código a distinção entre “esta propriedade é garantida” e “esta propriedade pode estar ausente”, capturando toda uma classe de bugs antes que cheguem à produção. Transformar uma falha silenciosa em tempo de execução em um erro em tempo de compilação é uma pequena mudança com um impacto desproporcional na confiabilidade.