GitHub - tc39/proposal-class-static-block: ECMAScript class static initialization blocks (original) (raw)

ECMAScript class static initialization blocks

Class static blocks provide a mechanism to perform additional static initialization during class definition evaluation.

This is not intended as a replacement for public fields, as they provide useful information for static analysis tools and are a valid target for decorators. Rather, this is intended to augment existing use cases and enable new use cases not currently handled by that proposal.

Status

Stage: 4
Champion: Ron Buckton (@rbuckton)

For detailed status of this proposal see TODO, below.

Authors

Motivations

The current proposals for static fields and static private fields provide a mechanism to perform per-field initialization of the static-side of a class during ClassDefinitionEvaluation, however there are some cases that cannot be covered easily. For example, if you need to evaluate statements during initialization (such as try..catch), or set two fields from a single value, you have to perform that logic outside of the class definition.

// without static blocks: class C { static x = ...; static y; static z; }

try { const obj = doSomethingWith(C.x); C.y = obj.y C.z = obj.z; } catch { C.y = ...; C.z = ...; }

// with static blocks: class C { static x = ...; static y; static z; static { try { const obj = doSomethingWith(this.x); this.y = obj.y; this.z = obj.z; } catch { this.y = ...; this.z = ...; } } }

In addition, there are cases where information sharing needs to occur between a class with an instance private field and another class or function declared in the same scope.

Static blocks provide an opportunity to evaluate statements in the context of the current class declaration, with privileged access to private state (be they instance-private or static-private):

let getX;

export class C { #x constructor(x) { this.#x = { data: x }; }

static { // getX has privileged access to #x getX = (obj) => obj.#x; } }

export function readXData(obj) { return getX(obj).data; }

Relation to "Private Declarations"

Proposal: https://github.com/tc39/proposal-private-declarations

The Private Declarations proposal also intends to address the issue of privileged access between two classes, by lifting the private name out of the class declaration and into the enclosing scope. While there is some overlap in that respect, private declarations do not solve the issue of multi-step static initialization without potentially exposing a private name to the outer scope purely for initialization purposes:

// with private declarations private #z; // exposed purely for post-declaration initialization class C { static y; static outer #z; } const obj = ...; C.y = obj.y; C.#z = obj.z;

// with static block class C { static y; static #z; // not exposed outside of class static { const obj = ...; this.y = obj.y; this.#z = obj.z; } }

In addition, Private Declarations expose a private name that potentially allows both read and write access to shared private state when read-only access might be desireable. To work around this with private declarations requires additional complexity (though there is a similar cost for static{} as well):

// with private declarations private #zRead; class C { #z = ...; // only writable inside of the class get #zRead() { return this.#z; } // wrapper needed to ensure read-only access }

// with static let zRead; class C { #z = ...; // only writable inside of the class static { zRead = obj => obj.#z; } // callback needed to ensure read-only access }

In the long run, however, there is nothing that prevents these two proposals from working side-by-side:

private #shared; class C { static outer #shared; static #local; static { const obj = ...; this.#shared = obj.shared; this.#local = obj.local; } } class D { method() { C.#shared; // ok C.#local; // no access } }

Prior Art

Syntax

class C { static { // statements } }

Semantics

Examples

// "friend" access (same module) let A, B; { let friendA;

A = class A { #x;

static {
    friendA = {
      getX(obj) { return obj.#x },
      setX(obj, value) { obj.#x = value }
    };
}

};

B = class B { constructor(a) { const x = friendA.getX(a); // ok friendA.setX(a, x); // ok } }; }

References

TODO

The following is a high-level list of tasks to progress through each stage of the TC39 proposal process:

Stage 1 Entrance Criteria

Stage 2 Entrance Criteria

Stage 3 Entrance Criteria

Stage 4 Entrance Criteria

For up-to-date information on Stage 4 criteria, check: #48