ExplicitJSClasses

This phase makes all JS classes explicit (their definitions and references to them).

This phase is the equivalent of the two phases ExplicitInnerJS and ExplicitLocalJS from Scala 2. It performs the following transformations:

(A) For every inner JS class Inner in a class or trait Outer, create a field Outer.Inner$jsclass to hold the JS class value of Inner. (B) For every exposed object Inner in a static owner Outer, create an explicit exposed getter Outer.Inner$jsobject. (C) For every local JS class Local, create a local val Local$jsclass to hold the JS class value of Local. (D) Desugar calls like x.isInstanceOf[C] into js.special.instanceof(x, js.constructorOf[C]) when C is a nested JS class. (E) Wrap every new C call and super[C] reference of a nested JS class C with withContextualJSClassValue(js.constructorOf[C], ...). (F) Desugar calls to js.constructorOf[C] (including those generated by the previous transformations) into either runtime.constructorOf or access to the $jsclass fields/vals. (G) Adjust the NoInits flag of traits: - for JS traits, always add the flag - for Scala trait that contain a JS class, remove the flag

Note that in this comment, and more largely in this phase, by "class" we mean only classes. traits and objects are not implied.

(A) Inner$jsclass fields

Roughly, for every inner JS class of the form:

class Outer {
  class Inner extends ParentJSClass
}

this phase creates a field Inner$jsclass in Outer to hold the JS class value for Inner. The rhs of that field is a call to a magic method, used to retain information that the back-end will need.

class Outer {
  <synthetic> val Inner$jsclass: AnyRef =
    createJSClass(classOf[Inner], js.constructorOf[ParentJSClass])

  class Inner extends ParentJSClass
}

These fields will be read by code generated in step (F).

A $jsclass field is also generated for classes declared inside static JS objects. Indeed, even though those classes have a unique, globally accessible class value, that class value needs to be exposed as a field of the enclosing object. In those cases, the rhs of the field is a direct call to js.constructorOf[Inner], which becomes runtime.constructorOf(classOf[Inner]).

For the following input:

object Outer extends js.Object {
  class InnerClass extends ParentJSClass
}

this phase will generate

object Outer extends js.Object {
  @ExposedJSMember @JSName("InnerClass")
  val InnerClass$jsclass: AnyRef = runtime.constructorOf(classOf[InnerClass])
}

The $jsclass fields must also be added to outer classes and traits coming from separate compilation, therefore this phase is an InfoTransform.

(B) Inner$jsobject exposed getters

For modules declared inside static JS objects, we generate an explicit exposed getter as well. For non-static objects, dotc already generates a getter with the @ExposedJSMember annotation, so we do not need to do anything. But for static objects, it doesn't, so we have to do it ourselves here.

For the following input:

object Outer extends js.Object {
  object InnerObject extends ParentJSClass
}

this phase will generate

object Outer extends js.Object {
  @ExposedJSMember @JSName("InnerObject")
  def InnerObject$jsobject: AnyRef = InnerObject
}

(C) Local$jsclass vals and vars

Similarly to how step (A) creates explicit fields in the enclosing templates of inner JS classes and traits to hold the JS class values, this phase creates local vals for local JS classes in the enclosing statement list.

For every local JS class of the form:

def outer() = {
  class Local extends ParentJSClass
}

this phase creates a local val Local$jslass in the body of outer() to hold the JS class value for Local. The rhs of that val is a call to a magic method, used to retain information that the back-end will need:

• A reified reference to class Local, in the form of a classOf
• An explicit reference to the super JS class value, i.e., the desugaring of js.constructorOf[ParentJSClass]
• An array of fake new expressions for all overloaded constructors.

The latter will be augmented by LambdaLift with the appropriate actual parameters for the captures of Local, which will be needed by the back-end. In code, this looks like:

def outer() = {
  class Local extends ParentJSClass
  val Local$jsclass: AnyRef = createLocalJSClass(
      classOf[Local],
      js.constructorOf[ParentJSClass],
      ???)
}

The third argument ??? is a placeholder, which will be filled in by AddLocalJSFakeNews with fake new invocations for the all the constructors of Local. We cannot do it at this phase because that would require inventing sound type arguments for the type parameters of Local out of thin air.

If the body of Local references itself, then the val Local$jsclass is instead declared as a var to work around the cyclic dependency:

def outer() = {
  var Local$jsclass: AnyRef = null
  class Local extends ParentJSClass {
    def newLocal = new Local // self-reference
  }
  Local$jsclass = createLocalJSClass(...)
}

(D) Insertion of withContextualJSClassValue calls

For any nested JS class C, this phase performs the following transformations:

• new C[...Ts](...args) desugars into withContextualJSClassValue(js.constructorOf[C], new C[...Ts](...args)), so that the back-end receives a reified reference to the JS class value.
• In the same spirit, for D extends C, D.super[C].m[...Ts](...args) desugars into withContextualJSClassValue(js.constructorOf[C], D.super[C].m[...Ts](...args)).

For any nested JS object, their (only) instantiation point of the form new O$() is rewritten as withContextualJSClassValue(js.constructorOf[ParentClassOfO], new O$()), so that the back-end receives a reified reference to the parent class of O.

A similar treatment is applied on anonymous JS classes, which basically define something very similar to an object, although without their own JS class.

(E) Desugar x.isInstanceOf[C] for nested JS classes

They are desugared into js.special.instanceof(x, js.constructorOf[C]).

(F) Desugar js.constructorOf[C]

Finally, this phase rewrites all calls to js.constructorOf[C], including the ones generated by the previous steps. The transformation depends on the nature of C:

• If C is a statically accessible class, desugar to runtime.constructorOf(classOf[C]) so that the reified symbol survives erasure and reaches the back-end.
• If C is an inner JS class, it must be of the form path.D for some pair (path, D), and we desugar it to path.D$jsclass, using the field created by step (A) (it is an error if C is of the form Enclosing#D).
• If C is a local JS class, desugar to C$jsclass, using the local val created by step (C).