dotty.tools.dotc.transform.sjs

Adds fake calls to the constructors of local JS classes in calls to createLocalJSClass.

Given a call of the form

scala.scalajs.runtime.createLocalJSClass(classOf[C], jsClassValue, ???)

this phase fills in the ??? with an array of calls to the constructors of C, like

[ new C(), new C(???, ???) : Object ]

If the class C has an outer pointer, as determined by the ExplicitOuter phase, the calls to the constructor insert a reference to the outer instance:

[ new C(Enclosing.this), new C(Enclosing.this, ???, ???) : Object ]

The LambdaLift phase will further expand those constructor calls with values for captures. The back-end will extract the values of the outer pointer and/or the captures to introduce them as JS class captures.

Since we need to insert fake new C() calls, this scheme does not work for abstract local classes. We therefore reject them as implementation restriction in PrepJSInterop.

This phase complements ExplicitJSClasses. The latter cannot create the fake new invocations because that would require inventing sound type arguments for the class' type parameters in order not to break Ycheck.

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).

Utilities for JS exports handling.

Additional extensions for Symbols that are only relevant for Scala.js.

Generates JUnit bootstrapper objects for Scala.js.

On the JVM, JUnit uses run-time reflection to list and invoke JUnit-related methods. They are identified by annotations such as @Test, @Before, etc. In Scala.js, there is no such reflection for methods and annotations, so a different strategy is used: this phase performs the necessary inspections at compile-time, and generates a so-called bootstrapper object where all those metadata have been reified.

With an example: given the following JUnit test class:

class MyTest {
  @Before def myBefore(): Unit = ...
  @Before def otherBefore(): Unit = ...

  @Test def syncTest(): Unit = ...
  @Test def asyncTest(): Future[Try[Unit]] = ...

  @Ignore @Test def ignoredTest(): Unit = ...
}

object MyTest {
  @AfterClass def myAfterClass(): Unit = ...
}

this phase generates the following bootstrapper module class:

object MyTest$scalajs$junit$bootstrapper extends Object with Bootstrapper {
  def beforeClass(): Unit = {
    // nothing, since there is no @BeforeClass method in object MyTest
  }

  def afterClass(): Unit = {
    MyTest.myAfterClass()
  }

  def before(instance: Object): Unit = {
    // typically 0 or 1, but also support 2 or more
    instance.asInstanceOf[MyTest].myBefore()
    instance.asInstanceOf[MyTest].otherBefore()
  }

  def after(instance: Object): Unit = {
    // nothing, since there is no @After method in class MyTest
  }

  def tests(): Array[TestMetadata] = Array(
    new TestMetadata("syncTest", false, new org.junit.Test()),
    new TestMetadata("asyncTest", false, new org.junit.Test()),
    new TestMetadata("ignoredTest", true, new org.junit.Test()),
  )

  def invokeTest(instance: Object, name: String): Future[Unit] = {
    val castInstance: MyTest = instance.asInstanceOf[MyTest]
    if ("syncTest".equals(name))
      Future.successful(scala.util.Success(castInstance.syncTest()))
    else if ("asyncTest".equals(name))
      castInstance.asyncTest() // asyncTest() already returns a Future[Try[Unit]]
    else if ("ignoredTest".equals(name))
      Future.successful(scala.util.Success(castInstance.ignoredTest()))
    else
      throw new NoSuchMethodException(name)
  }

  def newInstance(): Object = new MyTest()
}

Note that the support for test methods returning Futures is specific to Scala.js, and not advertised as a public feature. It is necessary to test some things in Scala.js itself, but outside users should use a testing framework with official asynchronous support instead.

Because Booststrapper is annotated with @EnableReflectiveInstantiation, the run-time implementation of JUnit for Scala.js can load the bootstrapper module using scala.scalajs.reflect.Reflect, and then use the methods of Bootstrapper, which are implemented in the bootstrapper object, to perform test discovery and invocation.

TODO At the moment, this phase does not handle @Test annotations with parameters, notably the expected exception class. This should be handled at some point in the future.

A macro transform that runs after typer and before pickler to perform additional Scala.js-specific checks and transformations necessary for interoperability with JavaScript.

It performs the following functions:

• Sanity checks for the js.Any hierarchy
• Annotate subclasses of js.Any to be treated specially
• Create JSExport methods: Dummy methods that are propagated through the whole compiler chain to mark exports. This allows exports to have the same semantics than methods.

This is the equivalent of PrepJSInterop in Scala 2, minus the handling of scala.Enumeration.

The reason for making this a macro transform is that some functions (in particular all the checks that behave differently depending on properties of classes in the enclosing class chain) are naturally top-down and don't lend themselves to the bottom-up approach of a mini phase.

In addition, the addition of export forwarders must be done before pickling to be signature-compatible with scalac, and there are only macro transforms before pickling.