JS Predefined Entities

The JS engine has a simulated DOM. Each of the entries in this DOM are referred to as entities, and are handled by the engine differently than standard literal values. Unlike other values and objects that are defined within the AST tree, entities are pre-populated with values. They--by default--cannot be modified. A wide array of properties and characteristics can be given to entities to allow them to dynamically and predictably interact with the rest of the JS engine.

GLOBAL_ENTITIES

GLOBAL_ENTITIES is the object which holds the "global scope" of entities. When the JS engine cannot find an identifier in the global scope of the current program's execution, it looks in this dict for the identifier being queried for.

Each entity is itself dict, with each key being a property.

Entities in GLOBAL_ENTITIES are not copied when they are referenced, meaning that any unintended changes to the internal state of a global entity anywhere in the engine will result in a change across all other global entities of that type.

Properties

Properties are keys on the entity dicts.

Key	Value
dangerous	bool: True throws a warning when encountered. string: A warning is thrown with the string as the message lambda: Prototype: (a=ast argument list, t=traverser._traverse_node, e=error bundle) Lambdas should return a bool or string, to be evaluated as the dangerous value.
dangerous_on_read	bool: True throws a warning when encountered. string: A warning is thrown with the string as the message lambda: Prototype: (t=traverser._traverse_node, e=error bundle) Lambdas should return a bool or string, to be evaluated as the dangerous value.
readonly	bool: False allows the entity to be the l-value of an assignment*.
overwriteable	Should not be used in GLOBAL_ENTITIES bool: True defines instances of the entity as aliases.
return	lambda: Prototype: (wrapper=ast node, arguments=ast argument list, t=traverser) Lambdas should return a JSWrapper object that is returned when the entity is called as a function.
value	dict: Keys are member names, values are the members' entity dicts. lambda: Prototype: (t=traverser) Lambdas should return an entity dict that the current entity is evaluated to.
xpcom_wildcard	Special purpose; makes entity a recursive lazy object.
xpcom_map	Special purpose; defines a function which maps to an entity defining an XPCOM interface. lambda: No Prototype Lambdas should return a dict defining the XPCOM interface associated with the current entity.
literal	lambda: (t=traverser) Lambdas should return a JSWrapper object that should be returned when the object is simplified to its literal value.
context**	string: "content" or "chrome"; Denotes which context the object and its derivatives run in.

* Even as the l-value, the entity will not be re-assigned globally.

** This may only be available on certain branches.