Private fields

What it is and why it exists

A private field is a class element whose name starts with #, such as #balance. The same syntax can declare private methods, getters, setters, and static members. These elements give classes a language-enforced encapsulation boundary, instead of treating an _balance naming convention as access control.

A private name can appear only inside the class body that declares it. If account.#balance appears outside that class, the whole script gets a SyntaxError during parsing, so an outer try...catch can’t catch it. account['#balance'] is valid syntax, but it accesses an ordinary public property named "#balance", not the private field.

You meet private elements in classes that maintain invariants, such as a balance that changes only after amount validation or a cache index that callers must not replace. A private boundary also lets an implementation change its internal representation without changing the public API. It isn’t encryption, authorization, or secret storage, however; the class can still expose the value, and it doesn’t constrain debuggers or an attacker already running code in the process.

Private fields fit state wholly owned by one class. If a framework must enumerate the fields, a generic serializer must copy them, or subclasses need direct extension access, ordinary properties with an explicit public contract may fit better. Decide who can read and mutate the state before choosing the syntax.

How it works

When the class definition is parsed, the engine establishes a lexical set of private names. Every #name must resolve to a declaration in the current class body; a same-named string or Symbol can’t stand in for it. This static relationship makes a misspelled private name fail before the code runs.

When an instance is created, the class installs its private elements on the object. For a later object.#name access, the engine first performs a private brand check: the receiver must have gone through that class’s initialization. The check doesn’t depend on instanceof, the constructor’s name, or the shape of the prototype, so an object with matching public properties can’t fake it.

Declaration and initialization

A private field must be declared in the class body. It can be initialized at the declaration, or it can receive undefined before the constructor assigns it. Field initializers run in source order. An earlier initializer can read fields already initialized, but it can’t read a later private field that hasn’t been installed yet.

Instance fields belong to individual instances; static fields belong to the class constructor that defines them. Private methods and accessors use the same lexical access restriction. delete this.#name is a syntax error; represent absence by assigning undefined, null, or a domain-specific sentinel.

Brands and receivers

A private access checks the actual object on the left side of the expression. A class method can read a private field from another instance of the same class because the access code remains inside the declaring class and the other instance carries the same brand. Call that method without its instance, and this becomes undefined or another object, causing a TypeError at the private access.

Inside the declaring class, #name in value checks whether an object has the matching brand. It doesn’t search the prototype chain, and it isn’t the same as '#name' in value. A right-hand side that is null or another non-object still causes a TypeError, so a check that accepts unknown input should reject those values first.

Private elements aren’t properties

Ordinary properties have string or Symbol keys and descriptors such as writable, enumerable, and configurable. Private elements aren’t part of that property model, so Object.keys(), Reflect.ownKeys(), Object.getOwnPropertyDescriptors(), and for...in can’t see them. Object spread, Object.assign(), and JSON.stringify() don’t automatically copy or output them either.

That invisibility prevents accidental exposure, but it doesn’t protect a mutable object referenced by a field. If a public getter returns a private array directly, callers can still mutate that same array. Real encapsulation depends on whether the public API returns a read-only view, a suitable copy, or selected data; the # token alone is insufficient.

Examples

These four examples cover basic encapsulation, brand checks, proxy receivers, and static-private inheritance. Every output below comes from running the corresponding file locally with Node 24.14.0.

Maintaining a balance through a public API

Wallet lets only integer cent amounts enter its state and uses toJSON() to choose what becomes public. Reflection sees only ordinary properties, so this instance has no enumerable own keys.

#cents didn’t enter the JSON merely because it was hidden from enumeration. The balance appears because toJSON() explicitly returns it; without that method, the instance would serialize as {}. Serialization is a public API decision, not an automatic property of a private field.

The validation method is private too. Callers can change the balance only through the constructor and deposit(), keeping the “cent amount must be a non-negative integer” invariant in one place. Any other public method that writes the balance must still apply the same validation.

Checking brands and separating same-named fields

Privacy is scoped to a class declaration, not to the spelling of a name. GuestPass can declare #code again; it is a separate element from AccessPass’s #code.

class AccessPass {
  #code;

  constructor(code) {
    this.#code = code;
  }

  static hasBrand(value) {
    return typeof value === 'object' && value !== null && #code in value;
  }

  readCodeOf(other) {
    return other.#code;
  }
}

class GuestPass extends AccessPass {
  #code = 'lobby';

  codes() {
    return [this.readCodeOf(this), this.#code].join(',');
  }
}

const first = new AccessPass('A-17');
const second = new AccessPass('B-42');
const guest = new GuestPass('G-07');

console.log(AccessPass.hasBrand(first));
console.log(AccessPass.hasBrand({ code: 'A-17' }));
console.log(first.readCodeOf(second));
console.log(guest.codes());

true
false
B-42
G-07,lobby

first can read second, showing that the privacy is class-level rather than “this instance only.” An object literal with the same string value doesn’t have the AccessPass brand. A brand check normally isn’t complete input validation; it says only that the object went through that class’s initialization.

A derived instance receives the base private elements while super() runs, so inherited base methods can read the base #code. Source inside GuestPass still can’t refer directly to the base private name. A #code written in the derived class body resolves only to the derived declaration.

A proxy doesn’t transfer the private brand

After a Proxy wraps a target, the default receiver of a method call is the proxy. The proxy can forward an ordinary property read, but it doesn’t inherit the target object’s private brand.

class Meter {
  #value = 0;

  add(step) {
    this.#value += step;
    return this.#value;
  }

  read() {
    return this.#value;
  }

  static hasBrand(value) {
    return #value in value;
  }
}

const target = new Meter();
const directProxy = new Proxy(target, {});

try {
  directProxy.add(1);
} catch (error) {
  console.log(`direct proxy: ${error.name}`);
}

const boundProxy = new Proxy(target, {
  get(targetObject, property) {
    const value = Reflect.get(targetObject, property, targetObject);
    return typeof value === 'function' ? value.bind(targetObject) : value;
  },
});

console.log(boundProxy.add(2));
console.log(Meter.hasBrand(target), Meter.hasBrand(boundProxy));

direct proxy: TypeError
2
true false

The bound wrapper makes the method run on target, so this example works, but it hasn’t copied the brand to the proxy. This generic get trap may also create a new bound function on every read and change method identity. Production code usually benefits from explicit forwarding methods for the operations that need proxying instead of assuming a wrapper is fully transparent.

The same failure occurs with a detached method, such as passing meter.add directly to a callback API. Pass (step) => meter.add(step), or bind the receiver once when registering. Tests must use the real callback path; a direct meter.add(1) test won’t expose the problem.

Static private fields belong to the declaring class

A public static method is inherited by derived classes, but a base static private field doesn’t become the derived class’s own private field. With polymorphic this.#next, the receiver selected by the caller affects the brand check.

class IdSource {
  static #next = 100;

  static takeViaThis() {
    return this.#next++;
  }

  static takeFromBase() {
    return IdSource.#next++;
  }
}

class RegionalSource extends IdSource {
  static #next = 900;

  static takeRegional() {
    return this.#next++;
  }
}

console.log(IdSource.takeViaThis());
try {
  RegionalSource.takeViaThis();
} catch (error) {
  console.log(`derived receiver: ${error.name}`);
}
console.log(RegionalSource.takeFromBase());
console.log(RegionalSource.takeRegional());

100
derived receiver: TypeError
101
900

Inside RegionalSource.takeViaThis(), this is the derived constructor, which lacks the base class’s static private brand. It doesn’t matter that the derived class also declares a #next: the private name in the base method is lexically bound to the declaration in IdSource.

If the counter must be shared across the inheritance hierarchy, the base method should explicitly use IdSource.#next and accept that this part isn’t polymorphic. If each derived class needs an independent counter, use a public registry or let each class implement the method. One private name can’t express both ownership models.

Pitfalls

Putting a syntax error inside try...catch

Fix: test behavior through the class’s public methods. If you really need to verify illegal syntax, pass a source string to an isolated parser or the Function constructor and assert that compilation fails; don’t place the illegal expression directly in the current file.

Returning a private mutable object

Fix: return a projection, iterator, or copy of the depth required by the API contract. If element objects are mutable too, copying only the outer array isn’t enough. State which levels may be shared and test the mutation paths.

Assuming a subclass has direct access

Fix: when a base class deliberately provides an extension point, expose a narrowly scoped public or controlled method. Decide whether static state belongs to the base class or to each derived class, then choose an explicit base name, a public registry, or a per-class implementation.

Losing the method receiver

Fix: use an explicit arrow wrapper at the API boundary, or bind the method once. Design proxy forwarding one operation at a time and test method identity, getters, setters, and private access instead of checking only one ordinary property read.

Treating freezing and cloning as private-state operations

Fix: enforce immutability through the class’s public mutation interface. For persistence or cross-thread transfer, define an explicit data format and reconstruction function, then test the round trip. A successful return from a generic object utility doesn’t mean it copied a complete class instance.

Further reading

• ECMAScript language specification: field definitions
• MDN: private elements
• V8: private brand checks
• MDN: Proxy