[JS] What to do with [[identifiers]], _internal properties and methods_ of JS objects?

[teoli2003]

The problem

JavaScript objects have what are called internal properties and accessors. These are values and functions stored on a JavaScript object, but, unlike regular properties and functions, these entities cannot be read, set, or called by any code outside the code of the engine itself.

In the specification, they are present all over the place, and on MDN, we find quite a few mentions of them. We recognize them as they are enclosed between two sets of brackets, like [[prototype]], [[value]], or [[set]].

The problem is the following: these mentions are information that comes out of the spec, this is not something that web developers directly deal with. At first sight, it looks like something we should bury and not display to web devs. On the other side, if authors have used them here or there (and this is not recent!), it means they are solving a problem: maybe they are more precise and succinct, and maybe they are needed to describe complex interactions.

The current situation is not good: we use these notations here or there without really explaining them, making it hard for a lot readers. We should find a solution that allows readers to naturally understand the docs (either by explaining better the internal properties when used or by hiding them).

Right now, I don't what is the best direction to take.

What questions do we want to answer in this discussion?

With this discussion, I have three objectives:

1. Understand why we use them sometimes on MDN.
2. What do we want to do with them in the future (more of them, them differently, or never?).
3. A brief plan about how to reach the ideal situation.

To help us make pertinent proposals, here is some extra information.

What does the spec say?

There are two kinds of them: internal methods and internal slots.

The actual semantics of objects, in ECMAScript, are specified via algorithms called internal methods. Each object in an ECMAScript engine is associated with a set of internal methods that defines its runtime behaviour. These internal methods are not part of the ECMAScript language. They are defined by this specification purely for expository purposes. However, each object within an implementation of ECMAScript must behave as specified by the internal methods associated with it. The exact manner in which this is accomplished is determined by the implementation.

Internal method names are polymorphic. This means that different object values may perform different algorithms when a common internal method name is invoked upon them. That actual object upon which an internal method is invoked is the “target” of the invocation. If, at runtime, the implementation of an algorithm attempts to use an internal method of an object that the object does not support, a TypeError exception is thrown.

Internal slots correspond to internal state that is associated with objects and used by various ECMAScript specification algorithms. Internal slots are not object properties and they are not inherited.

(spec)

How often are they used on MDN today?

Internal prop or accessor	Usage (total/pages)	Significant links	Meaning	In Spec
[[Prototype]]	68 / 17		Internal slot containing the prototype of an object, or null.	Yes
[[Get]]	4 / 4	1 2 3 4	The getter associated with the object.	Yes
[[Set]]	4 / 4	1 2 3 4	The setter associated with the object.	Yes
[[foo]]	2 / 2	1 2	The two occurrences are in comments in a code snippet that uses the double bracket notation seemingly to list propeties (and so not really à propos)	No
[[Construct]]	2 / 2	1 2	Internal method mandatory for constructors. Creates an object. Invoked via the new operator or a super() call.	Yes
[[Call]]	4 / 3	1 2 3	Internal method mandatory for functions (and constructors). Executes code associated with this object. Invoked via a function call expression.	Yes
[[TimeValue]]	1 / 1	1	Explain that toString()is an abstract method that can only be used on Date objects as they need a [[TimeValue]] internal slot. This doesn't seems to be true in ES2018 and the current draft.	No
[[Put]]	2 / 2	1 2	Two occurrences to control as this is unclear and not in the spec (anymore?)	No
[[DefineProperty]]	2 / 2	1 2	Called [[DefineOwnProperty]]. Internal function for all objects called to create or alter an own property of the object.	Yes
[[Define]]	2 / 1	1	Likely an erroneous abbreviation of [[DefineOwnProperty]].	No
[[OwnPropertyKeys]]	1 / 1	1	Internal slot for all objects with the list of own properties.	Yes
[[Key]]	1 / 1	1	Global internal structure: the global symbol registry, a map of symbols associated with a key.	Yes
[[symbol]]	1 / 1	1	Internal slot of the global symbol registry, a map of symbols associated with a key.	Yes
[[PromiseStatus]]	2 / 1	1	Called [[PromiseState]]. An internal slot containing the status of the promise, a state machine: pending, fullfilled, or rejected. Note: This state machine is described on MDN, but doesn't use the notation [[PromiseState]]…	Yes
[[PromiseValue]]	2 / 1	1	Called [[PromiseResult]]. An internal slot with the value with which the promise has been fulfilled or rejected, if any. Note: Both [[PromiseResult]] and [[PromiseState]] are used on MDN only in a code comment about what should be displayed on the console. This comment is outdated and doesn't describe what Chrome or Firefox dev tools does (and they display different texts).	Yes
[[VarNames]]	2 / 1	1	Global internal structure. A list of string names bound by functions, generators, and var declaration in global code	Yes
[[BoundThis]], [[BoundTargetFunction]], [[BoundArguments]]	2 / 1	1	The 3 internal slots of a bound function exotic object. Note: On MDN, these 3 values are used to paraphrase what implementations do behind the scene.	Yes
[[Multiline]]	1 / 1	1	An internal slot of RegExp, a boolean storing if the multiline (/m) flag is set or not. Note: On MDN, this appears as part of a citation of the spec.	Yes

cc/ @hamishwillee @Rumyra @wbamberg @sideshowbarker @Josh-Cena @schalkneethling

[teoli2003]

While researching to understand and describe the problem, it looked to me that the usage of this notation is uncommon, complex to understand, and not needed.

TL;DR;

We should not use the [[identifier]] notation on MDN at all.

(With the exception of pages with the specification as their topic, like a page about How to document a new JavaScript feature).

Reasoning

• Most of the time, an entity described by the notation is used at a single place on MDN. Introducing a notation for a single usage complexifies the documentation.
• The notation is not understood by most developers.
• Like for Web APIs' mixins, there is no guarantee of stability: naming can change, and there is no process in place to update this.
• The identifiers are invisible to developers.
• There is no explanation of such notation on the web, outside the EcmaScript spec (and even there, there isn't a true explanation)
• The sections using them are not very clear and would benefit from a rewrite to be easier to understand.

Plan

1. Update the pages using them so we get rid of them. Eventually uniformizing some wordings.
2. Write a page about How to write documentation for a new JS feature to guide authors not to use them.

[Josh-Cena]

IMO—they are quite unavoidable in certain places.

For example, when you say "the method is defined on constructor's prototype", does that mean constructor.__proto__, or constructor.prototype? In the case you are referring to the former, it's really bad notation because __proto__ accessors are deprecated; but otherwise there's no way to refer to [[Prototype]]. Object.getPrototypeOf(constructor) is definitely too verbose to be illustrative. That's why [[Prototype]] is used extensively on the https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain page, because there's really no other non-ambiguous notation.

Also, [[Define]] (yes, short for [[DefineOwnProperty]] but it's quite common AFAICT) and [[Set]] are not directly accessed, but their semantics are exposed by assignments and Object.defineProperty, and they can be hooked into by setters and property descriptors. For example, when we document class fields, the knowledge that it uses [[Define]] may be gibberish to average readers, but to those that do understand, it has much, much further implications than "it doesn't invoke setters" (e.g. its interaction with writability and configurability), and this single piece of information is worth 5 paragraphs.

(The consequence of avoiding [[Define]] is some dangerously misleading text, like "They are added to the class constructor at the time of class evaluation using Object.defineProperty()." How should I understand that? Does that mean if I overwrite Object.defineProperty I overwrite how class fields are defined as well?)

This is more personal, but I still want to share it: the first time I started reading MDN systematically (i.e. not as a lookup tool for random APIs) was when I was implementing a klass—an API that tries to mimic every single behavior of JS classes. As such I needed to know every single aspect of the language's behavior, but which was surprisingly lacking on MDN. Of course 99% of our readers would not need to know what happens when you use class fields with a property already defined as non-configurable, but for those that do want to know, do we want to explain it in such a roundabout way than simply stating "it uses [[Define]]", which saves me 1 precious minute reading through the explanation and code examples?

Can we instead create a page under JS references > misc like "Exotic objects and internal slots", where we document these internal slots, and then everywhere we use them, we link to this page? There are other interesting behaviors with internal slots, e.g. you cannot do new Proxy(new Map), because the proxy cannot get access to the map's [[MapData]] internal slot.

[Josh-Cena]

I agree. I've started with mdn/content#18461 — we can gradually remove these.

[teoli2003]

I agree; let's start by removing the case where we are in agreement. For the other cases (I think there are two of them), we can look at them later.

[Rumyra]

I agree; let's start by removing the case where we are in agreement. For the other cases (I think there are two of them), we can look at them later.

This sounds like a good way to move forward :)

It looks like the ones up for discussion are:

• [[Define]]
• [[Set]]
• [[Prototype]]
• Possibly [[Call]]

[teoli2003]

Not sure for [[Set]], but we may have [[Put]] instead.

[Josh-Cena]

[[Put]] is ES5—it predates [[Set]]. So yes, [[Define]] (or [[DefineOwnProperty]] to be exact), [[Set]], and [[Prototype]] are my "yes"; [[Call]] and [[Construct]] are my "maybe".

[Josh-Cena]

After mdn/content#18461 and mdn/content#18476, we have gotten rid of some pointless references. @teoli2003 Maybe you can update that table? I think the rest are more debatable. (The proxy ones are tricky—they are not very critical, but I suspect people who read these pages have a fair chance of understanding the notation anyway.)