Private methods and getter/setters for ES6 classes
Clone or download
littledan Merge pull request #52 from tc39/private-brands
Editorial: Phrase private methods as brands, not fields
Latest commit 59bcc6a Dec 12, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis.yml Travis auto-deployment Dec 26, 2017
DETAILS.md Create DETAILS.md Jul 21, 2017
README.md Proposal status Oct 11, 2018
deploy.sh Skip CI if no key Jan 2, 2018
github_deploy_key.enc Travis auto-deployment Dec 26, 2017
package.json Travis auto-deployment Dec 26, 2017
spec.html Editorial: Phrase private methods as brands, not fields Dec 12, 2018

README.md

Private methods and getter/setters for JavaScript classes

Daniel Ehrenberg

Stage 3

Keeping state and behavior private to a class lets library authors present a clear, stable interface, while changing their code over time behind the scenes. The class fields proposal provides private fields for classes and instances, and this proposal builds on that by adding private methods and accessors (getter/setters) to JavaScript. With this proposal, any class element can be private.

For discussion about semantic details, see DETAILS.md. This document focuses more on the end user experience and intuition.

A guiding example: Custom elements with classes

To define a counter widget which increments when clicked, you can define the following with ES2015:

class Counter extends HTMLElement {
  get x() { return this.xValue; }
  set x(value) {
    this.xValue = value; 
    window.requestAnimationFrame(this.render.bind(this));
  }

  clicked() {
    this.x++;
  }

  constructor() {
    super();
    this.onclick = this.clicked.bind(this);
    this.xValue = 0;
  }

  connectedCallback() { this.render(); }

  render() {
    this.textContent = this.x.toString();
  }
}
window.customElements.define('num-counter', Counter);

Field declarations

With the class fields proposal, the above example can be written as

class Counter extends HTMLElement {
  xValue = 0;

  get x() { return this.xValue; }
  set x(value) {
    this.xValue = value; 
    window.requestAnimationFrame(this.render.bind(this));
  }

  clicked() {
    this.x++;
    window.requestAnimationFrame(this.render.bind(this));
  }

  constructor() {
    super();
    this.onclick = this.clicked.bind(this);
  }

  connectedCallback() { this.render(); }

  render() {
    this.textContent = this.x.toString();
  }
}
window.customElements.define('num-counter', Counter);

In the above example, you can see a field declared with the syntax x = 0. You can also declare a field without an initializer as x. By declaring fields up-front, class definitions become more self-documenting; instances go through fewer state transitions, as declared fields are always present.

Private methods and fields

The above example has some implementation details exposed to the world that might be better kept internal. Using ESnext private fields and methods, the definition can be refined to:

class Counter extends HTMLElement {
  #xValue = 0;

  get #x() { return #xValue; }
  set #x(value) {
    this.#xValue = value; 
    window.requestAnimationFrame(this.#render.bind(this));
  }

  #clicked() {
    this.#x++;
  }

  constructor() {
    super();
    this.onclick = this.#clicked.bind(this);
  }

  connectedCallback() { this.#render(); }

  #render() {
    this.textContent = this.#x.toString();
  }
}
window.customElements.define('num-counter', Counter);

To make methods, getter/setters or fields private, just give them a name starting with #.

With all of its implementation kept internal to the class, this custom element can present an interface which is basically just like a built-in HTML element. Users of the custom element don't have the power to mess around with any of its internals.

Note that this proposal provides private fields and methods only as declared up-front in a field declaration; private fields cannot be created later, ad-hoc, through assigning to them, the way that normal properties can. You also can't declare private fields or methods in object literals; for example, if you implement your class based on object literals, or adding individual methods to the prototype, or using a class framework, you cannot use private methods, fields or accessors.

Relationship to other proposals

Decorators aren't part of this proposal, but it's designed to allow decorators to work on top of it. See unified class features for an explanation of how they would work together.

This proposal adds only private instance methods, omitting private static methods, which are under consideration in the static class features proposal.

Status

Consensus in TC39

This proposal reached Stage 3 in September 2017. Since that time, there has been extensive thought and lengthy discussion about various alternatives, including:

In considering each proposal, TC39 delegates looked deeply into the motivation, JS developer feedback, and the implications on the future of the language design. In the end, this thought process and continued community engagement led to renewed consensus on the proposal in this repository. Based on that consensus, implementations are moving forward on this proposal.

Implementations

Several implementations are under development:

Activity welcome in this repository

You are encouraged to file issues and PRs this repository to

  • Ask questions about the proposal, how the syntax works, what the semantics mean, etc.
  • Propose and discuss small syntactic or semantic tweaks, especially those motivated by experience implementing or using the proposal.
  • Develop improved documentation, sample code, and other ways to introduce programmers at all levels to this feature.

If you have any additional ideas on how to improve JavaScript, see ecma262's CONTRIBUTING.md for how to get involved.