Deprecate support for ECMAScript 5.1.

sjrd · sjrd · commit a4cdc6f2d45a · 2025-03-04T08:53:47.000+01:00
That support is the biggest source of alternative code paths and
polyfills in our codebase.

The polyfills and other alternative implementations we need to
support ES 5.1 include:

* `Math.fround` to support `Float` operations (in `CoreJSLib`).
* Other bit manipulation magic for floating-point numbers
  (in `FloatingPointBits`).
* Using dynamic JS `Array`s instead of typed arrays for Scala
  `Array`s of primitive types.
* Using custom Java `Map`s instead of `js.Map`.
* Various implementations of math methods in `jl.Math` (although
  these may come back for a Wasm-only target, along with more of
  them).
* Using run-time generated random property names instead of
  `Symbol`s.
* Very complex code to handle surrogate pairs in `ju.regex.*`.
* (Imperfect) desugaring of `...rest` parameters and `...spread`
  operators.

Moreover, the ES 5.1 output does not even have exactly the same
semantics as later versions:

* JS classes are not true `class`es. Notably, that means they
  cannot extend native ES classes, and they do not inherit static
  members.
* Top-level exports are declared as `var`s instead of `let`s.

10 years after the instruction of ECMAScript 2015, I believe it
is time to deprecate the support for Es 5.1, so that we can
eventually remove it.
diff --git a/linker-interface/shared/src/main/scala/org/scalajs/linker/interface/ESVersion.scala b/linker-interface/shared/src/main/scala/org/scalajs/linker/interface/ESVersion.scala
@@ -30,7 +30,11 @@ final class ESVersion private (val edition: Int, val name: String)
 }
 
 object ESVersion {
-  /** ECMAScrîpt 5.1. */
+  // !!! When we actually remove this, remove the code mentioning it in ClosureLinkerBackend.scala
+  /** ECMAScript 5.1. */
+  @deprecated(
+      "Support for ECMAScript 5.1 is deprecated and will eventually be removed.",
+      since = "1.19.0")
   val ES5_1: ESVersion = new ESVersion(5, "ECMAScript 5.1")
 
   /** ECMAScript 2015 (6th edition). */
diff --git a/linker-interface/shared/src/test/scala/org/scalajs/linker/interface/StandardConfigFingerprintTest.scala b/linker-interface/shared/src/test/scala/org/scalajs/linker/interface/StandardConfigFingerprintTest.scala
@@ -42,7 +42,7 @@ class StandardConfigFingerprintTest {
   @Test
   def noFingerprintCollisionESFeatures(): Unit = {
     val sc1 = StandardConfig().withESFeatures(_.withESVersion(ESVersion.ES2015))
-    val sc2 = StandardConfig().withESFeatures(_.withESVersion(ESVersion.ES5_1))
+    val sc2 = StandardConfig().withESFeatures(_.withESVersion(ESVersion.ES2016))
     assertFingerprintsNotEquals(sc1, sc2)
   }
 
diff --git a/linker/jvm/src/main/scala/org/scalajs/linker/backend/closure/ClosureLinkerBackend.scala b/linker/jvm/src/main/scala/org/scalajs/linker/backend/closure/ClosureLinkerBackend.scala
@@ -78,7 +78,6 @@ final class ClosureLinkerBackend(config: LinkerBackendImpl.Config)
     import ClosureOptions.LanguageMode._
 
     esFeatures.esVersion match {
-      case ESVersion.ES5_1  => ECMASCRIPT5_STRICT
       case ESVersion.ES2015 => ECMASCRIPT_2015
       case ESVersion.ES2016 => ECMASCRIPT_2016
       case ESVersion.ES2017 => ECMASCRIPT_2017
@@ -87,6 +86,10 @@ final class ClosureLinkerBackend(config: LinkerBackendImpl.Config)
       case ESVersion.ES2020 => ECMASCRIPT_2020
       case ESVersion.ES2021 => ECMASCRIPT_2021
 
+      // Test for ESVersion.ES5_1 without triggering the deprecation warning
+      case esVersion if esVersion.edition == 5 =>
+        ECMASCRIPT5_STRICT
+
       case _ =>
         throw new AssertionError(s"Unknown ES version ${esFeatures.esVersion}")
     }
diff --git a/linker/shared/src/test/scala/org/scalajs/linker/AnalyzerTest.scala b/linker/shared/src/test/scala/org/scalajs/linker/AnalyzerTest.scala
@@ -654,6 +654,7 @@ class AnalyzerTest {
     }
   }
 
+  @deprecated("test deprecated features", "forever")
   @Test
   def newTargetWithoutES2015(): AsyncResult = await {
     val classDefs = Seq(

Original file line number	Diff line number	Diff line change
`@@ -42,7 +42,7 @@ class StandardConfigFingerprintTest {`
`42`	`42`	`@Test`
`43`	`43`	`def noFingerprintCollisionESFeatures(): Unit = {`
`44`	`44`	`val sc1 = StandardConfig().withESFeatures(_.withESVersion(ESVersion.ES2015))`
`45`		`- val sc2 = StandardConfig().withESFeatures(_.withESVersion(ESVersion.ES5_1))`
	`45`	`+ val sc2 = StandardConfig().withESFeatures(_.withESVersion(ESVersion.ES2016))`
`46`	`46`	`assertFingerprintsNotEquals(sc1, sc2)`
`47`	`47`	`}`
`48`	`48`
Original file line number	Diff line number	Diff line change
`@@ -654,6 +654,7 @@ class AnalyzerTest {`
`654`	`654`	`}`
`655`	`655`	`}`
`656`	`656`
	`657`	`+ @deprecated("test deprecated features", "forever")`
`657`	`658`	`@Test`
`658`	`659`	`def newTargetWithoutES2015(): AsyncResult = await {`
`659`	`660`	`val classDefs = Seq(`