Propriedades Opcionais e readonly no TypeScript Guia
⚡ Curso de TypeScript • Web-ZoneWare

Propriedades Opcionais (?) e Modificador readonly no TypeScript

Lição 12 de 50

Propriedades Opcionais (?) e Modificador readonly no TypeScript

⚡ Módulo 2 • Aula 12 de 50

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.

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, cpf ou 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:

propriedades-opcionais.ts
TypeScript
TypeScript 18 linhas
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:

readonly-basico.ts
TypeScript
TypeScript 20 linhas
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:

shallow-vs-deep-readonly.ts
TypeScript
TypeScript 30 linhas
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>:

utility-readonly.ts
TypeScript
TypeScript 8 linhas
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):

conta-bancaria-imutavel.ts
TypeScript
TypeScript 53 linhas
// 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}`);
Execute e teste códigos interativos na ferramenta oficial do portal:
Abrir no Playground IDE →

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.
💡

Dica Pro de Engenharia Web-ZoneWare: Adote o modificador 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.

🚀

Próximo Passo Prático: Com interfaces, métodos, herança e modificadores dominados, na Lição 13 vamos responder à dúvida mais clássica do ecossistema: A Batalha Definitiva: type versus interface — quando usar cada um?.

🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima