Modificadores de acesso em TypeScript: public, private, protected

O TypeScript tem três modificadores de acesso para membros de classe: public (o padrão), protected e private. Eles controlam onde um membro pode ser usado, e o compilador aponta qualquer acesso feito do lugar errado.

class Employee {
    public name: string;          // anywhere (public is the default)
    protected salary: number;     // this class and subclasses
    private ssn: string;          // this class only

    constructor(name: string, salary: number, ssn: string) {
        this.name = name;
        this.salary = salary;
        this.ssn = ssn;
    }

    maskedSsn(): string {
        return "***-**-" + this.ssn.slice(-4); // fine: inside the class
    }
}

const e = new Employee("Ada", 5000, "123-45-6789");
console.log(e.name, e.maskedSsn()); // Ada ***-**-6789

// @ts-expect-error: Property 'ssn' is private and only accessible within class 'Employee'.
console.log(e.ssn);

A última linha é um erro de compilação, mas veja o que ela imprimiu quando rodou mesmo assim: 123-45-6789. Esse é o fato mais importante desta página, e a seção sobre private o explica.

O que cada modificador permite

Os modificadores funcionam em campos, métodos, getters e setters, construtores e parameter properties (constructor(private id: string)). Escrever public é opcional, e muitas bases de código o omitem.

private é uma verificação de tempo de compilação

O TypeScript apaga o private junto com o resto dos tipos. A classe compilada tem uma propriedade comum, então tudo o que não passa pelo verificador de tipos a enxerga: quem chama em JavaScript puro, JSON.stringify, Object.keys e até a notação de colchetes do próprio TypeScript, permitida de propósito como válvula de escape.

class Session {
    private token = "abc123";
    userId = 7;
}

const s = new Session();
console.log(s["token"]);           // abc123: bracket access skips the check
console.log(Object.keys(s));       // [ 'token', 'userId' ]
console.log(JSON.stringify(s));    // {"token":"abc123","userId":7}

Isso está certo para o que o private se propõe: dizer a outros desenvolvedores (e ao seu editor) que um membro é um detalhe de implementação. Ele não é uma barreira de segurança, e um campo private vai acabar em logs e em respostas JSON, a menos que você mesmo o remova.

Campos #private: aplicados em tempo de execução

O JavaScript tem os próprios campos privados, escritos com #. A engine os aplica: fora da classe, obj.#field nem é sintaxe válida, e o campo não aparece em Object.keys, JSON.stringify nem console.log.

class Session {
    #token = "abc123";
    userId = 7;

    constructor(token: string) {
        this.#token = token;
    }

    matches(t: string): boolean {
        return this.#token === t;
    }

    static isSession(x: object): boolean {
        return #token in x; // brand check: was x made by this class?
    }
}

const s = new Session("xyz");
console.log(s.matches("xyz"));     // true
console.log(Object.keys(s));       // [ 'userId' ]
console.log(JSON.stringify(s));    // {"userId":7}
console.log(s);                    // Session { userId: 7 }
console.log(Session.isSession(s), Session.isSession({ userId: 7 })); // true false

Escrever s.#token fora da classe gera o erro TS18013 (Property '#token' is not accessible outside class 'Session' because it has a private identifier) e, diferente do caso do private, também não há como contornar isso em tempo de execução. Veja campos privados em JavaScript para as regras de tempo de execução.

private vs #private: qual usar

Use #private quando os dados precisam continuar privados em tempo de execução (tokens, estado interno que os usuários de uma biblioteca não podem mexer) ou quando você quer que o JSON.stringify os deixe de fora. Use private quando o objetivo é só uma API pública limpa, quando um framework precisa ler o campo por reflexão ou para seguir o estilo existente de uma base de código. Não combine os dois: private #x gera o erro TS18010 (An accessibility modifier cannot be used with a private identifier).

protected e subclasses

Um membro protected fica disponível dentro da classe e em qualquer classe que a estenda, mas não em instâncias vistas de fora.

class Shape {
    protected sides: number;

    constructor(sides: number) {
        this.sides = sides;
    }
}

class Polygon extends Shape {
    describe(): string {
        return `${this.sides} sides`; // fine: subclass
    }
}

const hex = new Polygon(6);
console.log(hex.describe()); // 6 sides

// @ts-expect-error: Property 'sides' is protected and only accessible within class 'Shape' and its subclasses.
console.log(hex.sides); // 6: like private, protected is not enforced at runtime

Uma regra surpreende as pessoas. Dentro de Polygon, você pode ler sides no this ou em outro Polygon, mas não em um Shape simples recebido como parâmetro: other.sides com other: Shape gera o erro TS2446 (Property 'sides' is protected and only accessible through an instance of class 'Polygon'. This is an instance of class 'Shape'.). Uma subclasse só pode alcançar membros protected de objetos que pertencem ao seu próprio ramo da hierarquia.

Uma subclasse pode tornar público um membro protected redeclarando-o, mas não pode tornar protected ou private um membro público. Redeclare-o com um inicializador (public override sides = 6) ou só como tipo (declare public sides: number). Um public sides: number; sem mais nada é rejeitado com TS2564 e TS2612, porque com os class fields modernos ele reiniciaria o valor herdado para undefined depois que super() retornasse.

readonly

O readonly bloqueia a reatribuição depois da construção. O campo pode ser definido na declaração ou no construtor; qualquer atribuição posterior gera o erro TS2540.

class Order {
    readonly id: string;
    readonly items: string[] = [];

    constructor(id: string) {
        this.id = id; // allowed: inside the constructor
    }
}

const order = new Order("A-17");
order.items.push("book"); // allowed: readonly is shallow
console.log(order);       // Order { id: 'A-17', items: [ 'book' ] }

// @ts-expect-error: Cannot assign to 'id' because it is a read-only property.
order.id = "B-1";
console.log(order.id);    // B-1: nothing stops it at runtime

Dois limites aparecem aqui. O readonly é raso: o array não pode ser substituído, mas o conteúdo dele pode mudar (tipe como readonly string[] para bloquear o push). E, como o private, ele desaparece em tempo de execução, então a atribuição que o compilador rejeitou rodou mesmo assim. Para um valor que não pode mudar em tempo de execução, use Object.freeze ou um getter sem setter. A página sobre readonly trata de Readonly<T> e arrays readonly.

O readonly se combina com os modificadores de acesso: private readonly cache = new Map<string, number>() é um padrão comum para um campo interno que nunca é reatribuído.

Erros comuns

• Tratar o private como segurança. Ele some em tempo de execução. Use #field para dados que precisam ficar escondidos, e nunca mande um objeto com segredos direto para o JSON.stringify.
• Escrever public em todo lugar. É o padrão; acrescentá-lo não muda nada.
• Usar protected para tudo o que é "interno". Se nenhuma subclasse precisa, o private mantém a superfície menor.
• Esperar que o readonly congele dados aninhados. Ele só impede a reatribuição da própria propriedade.