[element-internals] How to get internals in base class and subclass, without leaking it to public

[trusktr]

How does a sub class get the internals? This isn't working:

class Base extends HTMLElement {
  #_
  
  constructor() {
    super()
    this.#_ = this.attachInternals()
  }
}

class MyEl extends Base {
  #_
  
  constructor() {
    super()
    this.#_ = this.attachInternals() // subclass also wants it, but this causes runtime error
  }
}

customElements.define('my-el', MyEl)

document.body.append(document.createElement('my-el')) // ERROR

The error in Chrome is:

Uncaught DOMException: Failed to execute 'attachInternals' on 'HTMLElement': ElementInternals for the specified element was already attached.

The Tc39 ES group thought protected was not a worthy thing to give us. What do we do, how do we keep it within the class hierarchy without leaking to public? Implement a complicated dance?

[trusktr]

Maybe, as long as we're still in construction, attachInternals should return existing internals rather than throwing, effectively making it protected-like? Should it perhaps be called getInternals in that case, instead?

[rniwa]

We need an JavaScript equivalent of "protected" keyword in C++/Java to do this.

[keithamus]

The work-arounds for this, for now, are to either override attachInternals:

class Base extends HTMLElement {
  #internals
  #internalsCalled = false

  constructor() {
    super()
    this.attachInternals()
    this.#internalsCalled = false
  }

  attachInternals() {
    if (this.#internals && !this.#internalsCalled) {
      this.#internalsCalled = true
      return this.#internals
    }
    this.#internals = super.attachInternals()
    this.#internalsCalled = true
    return this.#internals
  }

}

Or to provide some agreed upon interface in your own libraries, like getInternals(), which breaks the privacy contract around attachInternals unless you're able to use TypeScript's protected property in all code.

[trusktr]

@keithamus But in your example, if a subclass of the base class doesn't need the internals (not all end subclasses may need them) then your example leaves the extra call available for the public.

The following is still a problem, isn't it?

customElements.define('my-el', class extends HTMLElement {})
document.createElement('my-el').attachInternals() // returns "internals" to the public. (I had expected an error)

I originally thought that attachInternals could only be called in constructor. It would be enforceable with documet.createElement, but not with new unless the DOM engine can do something special with the JS engine that otherwise normal JS users can't.

And, if attachInternals would be callable only in constructor (otherwise throw), then we could as well rename it to getInternals and allow it to be called any number of times in constructor.

So, if we can't actually guarantee that attachInternals is internal (unless explicitly leaked by an author), why call it attachInternals?

Maybe it should be called attachFeatures or getFeatures because it is clearly public, just throws on any call other than the first (this does not at all guarantee privacy or "internal"ness).

[trusktr]

unless you're able to use TypeScript's protected property in all code.

I'm interested in plain JS semantics because as a library author, I can't guarantee my users will use TypeScript.

[keithamus]

@keithamus But in your example, if a subclass of the base class doesn't need the internals (not all end subclasses may need them) then your example leaves the extra call available for the public.

Right. My example just works around the error condition of calling attachInternals twice while preserving it for later callsites. It doesn't attempt to fix the issue of outside access.

If you know you don't want others to have access to internals and you don't want to call attachInternals yourself, you can disable it using disabledFeatures which means it won't be available for public (or just call it in your constructor anyway).

customElements.define('my-el', class extends HTMLElement {
static get disabledFeatures() { return ['internals']; }
})
document.createElement('my-el').attachInternals() // throws

[calebdwilliams]

You can always save it in a WeakMap and provide some API behind a closure to keep it hidden. It’s not particularly performant but it’s probably the best bet.

Regardless, this is a perfect example of the need for protected class fields in JavaScript.

[bakkot]

Is there something wrong with the obvious approach of explicit communication?

class Base extends HTMLElement {
  #_
  
  constructor(forwardInternals) {
    super()
    let internals = this.attachInternals()
    this.#_ = internals
    forwardInternals?.(internals)
  }
}

class MyEl extends Base {
  #_
  
  constructor() {
    // if you want to be open for further extension, repeat the `forwardInternals` thing in this constructor
    let internals;
    super(int => { internals = int })
    this.#_ = internals
  }
}

[trusktr]

customElements.define('my-el', class extends HTMLElement {
static get disabledFeatures() { return ['internals']; }
})
document.createElement('my-el').attachInternals() // throws

That API seems backwards. Perhaps it should have been this:

customElements.define('my-el', class extends HTMLElement {})
document.createElement('my-el').attachInternals() // throws

customElements.define('my-el', class extends HTMLElement {
  static enabledFeatures = ['internals']
})
document.createElement('my-el').attachInternals() // does not throw

Always avoid double negatives!

But that's tangential anyway. Once the feature is available, protecting it is difficult.

[trusktr]

Related discussion in TC39 ES forum:

https://es.discourse.group/t/protected-has-not-been-given-to-us-w3c-tries-to-make-internal-apis-that-arent-internal/1412

[trusktr]

@bakkot interesting trick. That does indeed keep the internals protected. The only downside is subclasses needing to remember that boilerplate. That subclass constructor should also wire up a callback in case a further subclass needs internals (lots of boilerplate).

And then it gets tricky with class-factory mixins. protected would be nice!

[calebdwilliams]

With bakkot’s trick, that does cause complications calling new Whatever though. Might not be a deal breaker though.

[bakkot]

@trusktr

The only downside is subclasses needing to remember that boilerplate.

Well, if you forget it, you won't get access to the internals, so I don't think there's much risk of that. And if you don't need the internals you don't need to include the boilerplate in your subclass.

---

@calebdwilliams

that does cause complications calling new Whatever though.

What complications do you mean?

[trusktr]

Well, if you forget it, you won't get access to the internals, so I don't think there's much risk of that. And if you don't need the internals you don't need to include the boilerplate in your subclass.

But if you forget it, then a further subclass of your class can't get them either, so you need the boilerplate even if your class doesn't need internals.

[bakkot]

Personally I am inclined to regard it as a good thing that you need to explicitly opt in to be open for extensions which can manipulate internal state, rather than that being the default, but this is a design question which is beyond the scope of this thread.

[rniwa]

F2F resolution: Closing this bug. Each custom element class needs to be designed with subclassing in mind. This is working as intended.

[trusktr]

comment moved to

• A better solution for ElementInternals #1036

[trusktr]

Each custom element class needs to be designed with subclassing in mind. This is working as intended.

This is "working as intended" only because JavaScript doesn't have a "protected" feature. Many people want it.

opt in to be open for extensions which can manipulate internal state

Using protected would count as opting into being open for extensions (by subclasses, while still blocking public access). It's a valid use case, and greatly simplifies class implementations. @bakkot's example is far too cumbersome.

[trusktr]

This thread proposes a "private class field symbols" syntax idea, which would allow "protected" to be possible, and it also explains how this would be useful for features like ElementInternals which proctected would be super useful for:

https://es.discourse.group/t/private-class-field-symbols/2262

To summarize, it would allow people to define elements as follows, making being "open to extension" easier:

const internals = Symbol()

export class BaseElement extends HTMLElement {
  #[internals]

  constructor() {
    super()
    this#[internals] = this.attachInternals()
  }
}

If the subclass was not already getting the internals, that is still problematic because the subclass will still be calling attachInternals and the base class, if it begins to call attachInternals, will start to cause a runtime error.

With this BaseElement example, now a subclass can openly extend by accessing the internals:

import {internals, BaseElement} from 'some-lib'

class SomeElement extends BaseElement {
  method() {
    this#[internals] // use the internals
  }
}

customElements.define('some-el', MyEl) // "finalize" the class (subclasses of SomeElement will need a new name).

Public users will not be able to use the internals:

import {internals} from 'some-lib'

const el = document.querySelector('some-el')
el.method() // ok
el#[internals] // SyntaxError (good!)

The best solution would be, if attachInternals could be updated so that it can be called any number of times (not only once) when inside an custom element constructor call stack. Then subclasses could simply call it, even if a base class doesn't use it yet, and a base class could begin to call it without causing errors. Problems solved.

[trusktr]

if it is not possible to modify the attachInternals() design, then a possibility is to introduce a new getInternals() method with the new behavior of throwing when called anywhere except in an element's constructor call stack.

The best practice would be to stop using attachInternals and start using getInternals. Maybe eventually attachInternals could be deprecated.

This is assuming that the engine can do something special wih new SomeElement to track the constructor call stack. If not, then another option could be that getInternals can only be called when an element is constructed without new, such as with document.createElement().

const el = document.createElement('some-el')
el.getInternals() // always a runtime error.

If you need the constructor, and don't have the name, then

const el = document.createElement(customElements.getName(SomeClass))
el.getInternals() // always a runtime error.

In either example, any constructor in the call stack can call getInternals without a runtime error.

It could be nice if there were a helper for constructing the class without knowing the name, f.e. document.createElement(SomeClass), and this would also ensure that getInternals works.

A subclass could opt into being "open for extension" by using getInternals() instead of attachInternals() (assuming attachInternals would not be deprecated).