Propriedades Opcionais (?) e Modificador readonly no TypeScript
Aprenda a flexibilizar contratos de dados sem abrir mão da segurança estrita: domine a declaração de Propriedades Opcionais (?) para campos facultativos e utilize o modificador readonly para blindar objetos contra mutações acidentais.
📑 Índice do Conteúdo
1. O Desafio da Modelagem: Campos Flexíveis vs. Dados Imutáveis
Na modelagem de entidades do mundo real, dois desafios arquiteturais surgem com frequência:
- Campos Facultativos: Nem todo registro possui todos os dados preenchidos no momento do cadastro (ex: complemento de endereço, telefone secundário, avatar ou observações).
- Imutabilidade Estrutural: Dados de identificação primária (como
id,uuid,cpfou timestamps de criação) jamais devem ser alterados após a instanciação do objeto na memória.
O TypeScript resolve ambos os cenários de forma elegante através do operador de interrogação (?) e do modificador readonly.
2. Propriedades Opcionais (?): Sintaxe e Comportamento
Para indicar que uma propriedade de uma interface ou type não é de fornecimento obrigatório, adicionamos ? logo após o seu nome:
TypeScript
interface PerfilColaborador {
id: number;
nome: string;
cargo: string;
// Propriedades opcionais (Tipo resultante: string | undefined)
telefoneRamal?: string;
avatarUrl?: string;
}
// Objeto criado omitindo os campos opcionais sem nenhum erro:
const desenvolvedor: PerfilColaborador = {
id: 1042,
nome: "Felipe Ramos",
cargo: "Engenheiro Front-End Pleno"
};
// Ao acessar uma propriedade opcional, utilize Optional Chaining (?.) para segurança:
console.log(desenvolvedor.avatarUrl?.toLowerCase()); // undefined (sem quebrar a aplicação!)
3. O Modificador readonly: Imutabilidade Estática
O modificador readonly é prefixado antes do nome da propriedade para proibir qualquer operação de reatribuição após a inicialização do objeto:
TypeScript
interface DocumentoFiscal {
readonly numeroNota: string;
readonly cnpjEmissor: string;
readonly emitidoEm: Date;
valorTotal: number; // Mutável (pode ser recalculado)
}
const nota: DocumentoFiscal = {
numeroNota: "NF-2026-9941",
cnpjEmissor: "12.345.678/0001-90",
emitidoEm: new Date(),
valorTotal: 1500.00
};
// Válido: valorTotal não é readonly
nota.valorTotal = 1650.00;
// ❌ ERRO DE COMPILAÇÃO TS2540:
// Cannot assign to 'numeroNota' because it is a read-only property.
// nota.numeroNota = "NF-OUTRA";
4. Imutabilidade Rasa (Shallow) vs. Imutabilidade Profunda (Deep)
Um detalhe técnico crucial que todo engenheiro sênior deve dominar: o modificador readonly no TypeScript protege apenas a referência direta da propriedade (imutabilidade rasa / shallow immutability).
Se a propriedade for um objeto aninhado ou um array, os métodos de mutação interna ainda poderão ser executados caso o tipo interno não seja também protegido:
TypeScript
interface ConfiguracaoSeguranca {
readonly nivel: string;
// ⚠️ Array mutável internamente:
readonly permissoes: string[];
}
const config: ConfiguracaoSeguranca = {
nivel: "alto",
permissoes: ["leitura", "escrita"]
};
// ❌ Bloqueado pelo compilador (Reatribuição direta):
// config.permissoes = ["total"]; // Erro TS2540!
// ⚠️ PERMITIDO EM RUNTIME (Mutação interna do array):
// config.permissoes.push("exclusao"); // Modifica o array original!
// ✅ SOLUÇÃO PROFISSA (Imutabilidade Profunda):
interface ConfiguracaoBlindada {
readonly nivel: string;
readonly permissoes: readonly string[]; // Array estritamente readonly!
}
const blindada: ConfiguracaoBlindada = {
nivel: "critico",
permissoes: ["leitura"]
};
// ❌ Bloqueado! Método 'push' não existe em 'readonly string[]':
// blindada.permissoes.push("root");
5. O Tipo Utilitário Readonly<T>
Se você já possui uma interface com dezenas de propriedades normais e deseja criar uma versão 100% imutável de todas as propriedades de uma só vez, utilize o utility type nativo Readonly<T>:
TypeScript
interface Cliente {
id: string;
nome: string;
limiteCredito: number;
}
// Transforma id, nome e limiteCredito em readonly automaticamente:
type ClienteCongelado = Readonly<Cliente>;
6. Exemplo Prático Integrado: Conta Bancária e Registro de Transações
Veja como aplicar propriedades opcionais e imutabilidade profunda em um sistema bancário que utiliza o padrão de cópia imutável (Spread Operator):
TypeScript
// 1. Contrato de transação estritamente imutável
interface TransacaoFinanceira {
readonly idTransacao: string;
readonly dataHora: Date;
readonly tipo: "credito" | "debito";
readonly valor: number;
// Campo opcional para metadados ou observações do cliente
observacaoAuditoria?: string;
}
// 2. Contrato de conta corrente
interface ContaCorrente {
readonly numeroConta: string;
readonly titular: string;
readonly saldo: number;
readonly extrato: readonly TransacaoFinanceira[]; // Histórico protegido
}
// 3. Função pura de depósito que retorna um novo estado sem mutação
function processarDeposito(
contaAtual: ContaCorrente,
valorDeposito: number,
motivo?: string
): ContaCorrente {
const novaTransacao: TransacaoFinanceira = {
idTransacao: "TX-" + Math.floor(Math.random() * 100000),
dataHora: new Date(),
tipo: "credito",
valor: valorDeposito,
observacaoAuditoria: motivo
};
// Retorna novo objeto imutável preservando o histórico anterior:
return {
...contaAtual,
saldo: contaAtual.saldo + valorDeposito,
extrato: [...contaAtual.extrato, novaTransacao]
};
}
// 4. Instanciação inicial da conta
const contaMatheus: ContaCorrente = {
numeroConta: "001-44589-2",
titular: "Matheus Silveira",
saldo: 5000.00,
extrato: []
};
const contaAtualizada = processarDeposito(contaMatheus, 1500.00, "Depósito de Bonificação");
console.log(`[CONTA #${contaAtualizada.numeroConta}] Titular: ${contaAtualizada.titular}`);
console.log(`Saldo Anterior: R$ ${contaMatheus.saldo.toFixed(2)} | Novo Saldo: R$ ${contaAtualizada.saldo.toFixed(2)}`);
console.log(`Total de Transações Registradas: ${contaAtualizada.extrato.length}`);
7. Tabela Didática: Modificadores de Propriedades em Interfaces
| Modificador | Sintaxe de Exemplo | Impacto no Compilador | Cenário Recomendado |
|---|---|---|---|
| Propriedade Padrão | campo: Tipo; |
Obrigatório no objeto; valor mutável. | Estados que mudam com frequência (ex: saldo, status). |
| Propriedade Opcional | campo?: Tipo; |
Permite omitir a chave; tipo vira Tipo | undefined. |
Campos facultativos de cadastro (ex: complemento, avatar). |
| Modificador readonly | readonly campo: Tipo; |
Bloqueia reatribuição após a inicialização do objeto. | Identificadores primários (id, UUID, CPF, createdAt). |
| Array Readonly Profundo | readonly lista: readonly Tipo[]; |
Bloqueia reatribuição e proíbe métodos mutáveis (push/pop). | Coleções imutáveis, históricos de logs e extratos contábeis. |
readonly como padrão para campos de identidade e auditoria. Em arquiteturas corporativas e bibliotecas reativas (como React, Redux, Zustand e NestJS), a imutabilidade estática impede que middlewares ou mutações acidentais corrompam o estado da aplicação em produção.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE