New encoding for methods described by type maps

[oyvindberg]

As a part of trying to adapt the ST encoding to true literal types this is one of the problems that needs solving, because all the resulting methods are prone to either name or erasure clashes, or they need to receive long, ugly names.

I'm trying out discussion to see if somebody has any ideas for alternative paths forward

given this:

interface Document {
    createElement<K extends keyof HTMLElementTagNameMap>(tagName: K, options?: ElementCreationOptions): HTMLElementTagNameMap[K];
    createElement<K extends keyof HTMLElementDeprecatedTagNameMap>(tagName: K, options?: ElementCreationOptions): HTMLElementDeprecatedTagNameMap[K];
    createElement(tagName: string, options?: ElementCreationOptions): HTMLElement;
}

interface HTMLElementTagNameMap {
    "a": HTMLAnchorElement;
    "abbr": HTMLElement;
    // ...
}
interface HTMLElementDeprecatedTagNameMap {
    "listing": HTMLPreElement;
    "xmp": HTMLPreElement;
}

Now this is generated:

import typings.std.stdStrings.a
import typings.std.stdStrings.abbr

@js.native
trait Document extends js.Object {
  @JSName("createElement")
  def createElement_a(tagName: a): HTMLAnchorElement = js.native
  @JSName("createElement")
  def createElement_a(tagName: a, options: ElementCreationOptions): HTMLAnchorElement = js.native
  @JSName("createElement")
  def createElement_abbr(tagName: abbr): HTMLElement = js.native
  @JSName("createElement")
  def createElement_abbr(tagName: abbr, options: ElementCreationOptions): HTMLElement = js.native
...
}

The new proposal is to generate something like this:

  @js.native
  trait Document extends js.Object {
    def createElement[K1 <: java.lang.String with Singleton, R1](tagName: K1)(implicit X1: Document.CreateElementType[K1, R1]): R1 = js.native
  }

  object Document {
    // some synthetic name
    sealed trait CreateElementType[K, R]

    // only if there is a fallback `string` method defined
    trait CreateElementTypeDefault {
      @inline implicit def default[K <: java.lang.String]: CreateElementType[K, HTMLElement] = null
    }

    object CreateElementType extends CreateElementTypeDefault {
      // HTMLElementDeprecatedTagNameMap
      @inline implicit def listing: CreateElementType["listing", HTMLPreElement] = null
      @inline implicit def xmp: CreateElementType["xmp", HTMLPreElement] = null

      @inline implicit def a: CreateElementType["a", HTMLAnchorElement] = null
      @inline implicit def abbr: CreateElementType["abbr", HTMLElement] = null
  }
}

It can be used like this:

  val doc: NewEncoding.Document = null

  val illegal: HTMLElement = doc.createElement("illegal")
  val applet: HTMLAppletElement = doc.createElement("applet")
  val a: HTMLAnchorElement = doc.createElement("a")
  val xmp: HTMLPreElement = doc.createElement("xmp")

Pros:

• fewer methods generated,
• much smaller changes of name/erasure clash
• user code looks exactly similar to javascript

Cons:

• somewhat more heavy compile
• worse tooling support (auto-complete and so on)
• worse type signatures
• an extra parameter (the implicit) is passed to javascript. in almost all cases it'll be ignored

[Atry]

Why not simply :

@js.native
trait Document extends js.Object {
  def createElement(tagName: "a"): HTMLAnchorElement = js.native
  def createElement(tagName: "a", options: ElementCreationOptions): HTMLAnchorElement = js.native
  def createElement(tagName: "abbr"): HTMLElement = js.native
  def createElement(tagName: "abbr", options: ElementCreationOptions): HTMLElement = js.native
}

[oyvindberg]

Good question, I should absolutely have dedicated a paragraph to it.

The problem is that these methods need different return types in order to not erasure clash.

so if we take your Document trait and add this:

  def createElement(tagName: "article"): HTMLElement = js.native
  def createElement(tagName: "article", options: ElementCreationOptions): HTMLElement = js.native

They will clash with those methods taking "abbr".

So one solution is to translate all naively, group methods by return type, and make the parameters a union of the literal types:

trait Document
  def createElement(tagName: "a"): HTMLAnchorElement = js.native
  def createElement(tagName: "a", options: ElementCreationOptions): HTMLAnchorElement = js.native
  def createElement(tagName: "abbr" | "article"): HTMLElement = js.native
  def createElement(tagName: "abbr" | "article", options: ElementCreationOptions): HTMLElement = js.native

IIRC def createElement(tagName: "abbr" | "article"): HTMLElement will clash with the fallback def createElement(tagName: String): HTMLElement, but those again could be merged into something like def createElement(tagName: /* abbr" | "article" */ String): HTMLElement

So that's at least the main issue. There might be some further complications as well. FTR what I've sketched here is probably a better direction than the monstrosity above. The redeeming quality of the implicit machinery is that it can be done without considering so much environment as most forms of naming and erasure clashes will be avoided

[Atry]

OK, now I understand the motivation of the _a and _abbr suffixes. But how about the stdString? Shall we replace stdString with string literal but still keep the suffixes?

[TheElectronWill]

Bumping into the discussion 👀
It seems to be a good use case for the new @targetName annotation of Scala 3!

import scala.annotation.targetName

@js.native
trait Document extends js.Object {
  @targetName("createElement_article") // Maybe @JSName("createElement") is required too
  def createElement(tagName: "article"): HTMLElement = js.native
  @targetName("createElement_article")
  def createElement(tagName: "article", options: ElementCreationOptions): HTMLElement = js.native

  @targetName("createElement_abbr")
  def createElement(tagName: "abbr"): HTMLElement = js.native
  @targetName("createElement_abbr")
  def createElement(tagName: "abbr", options: ElementCreationOptions): HTMLElement = js.native
}

This way, the compiler will generate createElement_abbrr etc. (which means no erasure clash), but the users' code will use

createElement("article")
createElement("abbr")

[oyvindberg]

Holy shit @TheElectronWill - thanks! That worked beautifully! (and JSName was needed)

See #487

Now the question is what to do with support for Scala 2, heh.