Fix scala-js#3685: Rename js.special.globalThis to fileLevelThis.

sjrd · sjrd · commit e6db0ff7b85a · 2019-06-14T14:49:12.000+02:00
As ECMAScript is about to receive a new global variable called
`globalThis`, that is not equivalent to our
`js.special.globalThis`, we need to rename the latter.
diff --git a/library/src/main/scala/scala/scalajs/js/special/package.scala b/library/src/main/scala/scala/scalajs/js/special/package.scala
@@ -41,17 +41,56 @@ package object special {
   def delete(obj: scala.Any, key: scala.Any): Unit =
     throw new java.lang.Error("stub")
 
-  /** The value of the global JavaScript `this`.
+  /** The value of the JavaScript `this` at the top-level of the generated
+   *  file.
    *
    *  This returns the value that would be obtained by writing `this` at the
-   *  top-level of the JavaScript file generated by Scala.js. In most
-   *  JavaScript environments, this is equivalent to the *global object*, but
-   *  it is not necessarily the case. For example, on Node.js, `this` is the
-   *  object representing the `exports` of the current module.
+   *  top-level of the JavaScript file generated by Scala.js. In scripts, this
+   *  is equivalent to the *global object*, but in other environments, it is
+   *  not necessarily the case. For example, in CommonJS modules on Node.js,
+   *  `this` is the object representing the `exports` of the current module,
+   *  and it is `undefined` in ECMAScript modules.
    *
    *  Using this value should be rare, and mostly limited to writing code
    *  detecting what the global object is. For example, a typical detection
-   *  code looks like:
+   *  code--in case we do not need to worry of ES modules--looks like:
+   *  {{{
+   *  val globalObject = {
+   *    import js.Dynamic.{global => g}
+   *    if (js.typeOf(g.global) != "undefined" && (g.global.Object eq g.Object)) {
+   *      // Node.js environment detected
+   *      g.global
+   *    } else {
+   *      // In all other well-known environment, we can use the global `this`
+   *      js.special.fileLevelThis
+   *    }
+   *  }
+   *  }}}
+   *  Note that the above code is not comprehensive, as there can be JavaScript
+   *  environments where the global object cannot be fetched neither through
+   *  `global` nor `this`. If your code needs to run in such an environment, it
+   *  is up to you to use an appropriate detection procedure.
+   */
+  @inline
+  def fileLevelThis: scala.Any =
+    scala.scalajs.runtime.linkingInfo.globalThis
+
+  /** The value of the JavaScript `this` at the top-level of the generated
+   *  file.
+   *
+   *  *Deprecated*: this value does not correspond to JavaScript's
+   *  `globalThis` value. Use `fileLevelThis` instead.
+   *
+   *  This returns the value that would be obtained by writing `this` at the
+   *  top-level of the JavaScript file generated by Scala.js. In scripts, this
+   *  is equivalent to the *global object*, but in other environments, it is
+   *  not necessarily the case. For example, in CommonJS modules on Node.js,
+   *  `this` is the object representing the `exports` of the current module,
+   *  and it is `undefined` in ECMAScript modules.
+   *
+   *  Using this value should be rare, and mostly limited to writing code
+   *  detecting what the global object is. For example, a typical detection
+   *  code--in case we do not need to worry of ES modules--looks like:
    *  {{{
    *  val globalObject = {
    *    import js.Dynamic.{global => g}
@@ -69,9 +108,13 @@ package object special {
    *  `global` nor `this`. If your code needs to run in such an environment, it
    *  is up to you to use an appropriate detection procedure.
    */
+  @deprecated(
+      "Does not correspond to JavaScript's globalThis. " +
+      "Use fileLevelThis instead.",
+      "0.6.29")
   @inline
   def globalThis: scala.Any =
-    scala.scalajs.runtime.linkingInfo.globalThis
+    fileLevelThis
 
   /** Exact equivalent of the `debugger` keyword of JavaScript.
    *
diff --git a/test-suite/js/src/test/scala/org/scalajs/testsuite/jsinterop/SpecialTest.scala b/test-suite/js/src/test/scala/org/scalajs/testsuite/jsinterop/SpecialTest.scala
@@ -60,9 +60,9 @@ class SpecialTest {
     js.special.delete(a[js.Object]("foo"), kh.key)
   }
 
-  // js.special.globalThis
+  // js.special.fileLevelThis
 
-  @Test def globalThis_can_be_used_to_detect_the_global_object(): Unit = {
+  @Test def fileLevelThis_can_be_used_to_detect_the_global_object(): Unit = {
     val globalObject = {
       import js.Dynamic.{global => g}
       // We've got to use selectDynamic explicitly not to crash Scala 2.10
@@ -72,13 +72,19 @@ class SpecialTest {
         g.selectDynamic("global")
       } else {
         // In all other well-known environment, we can use the global `this`
-        js.special.globalThis
+        js.special.fileLevelThis
       }
     }
 
     assertSame(js.Dynamic.global, globalObject)
   }
 
+  // js.special.globalThis (deprecated)
+
+  @Test def globalThis_is_fileLevelThis(): Unit = {
+    assertSame(js.special.fileLevelThis, js.special.globalThis)
+  }
+
   // js.special.debugger
 
   @Test def should_support_debugger_statements_through_the_whole_pipeline_issue_1402(): Unit = {
