Function overloading to support common web APIs

Read the overload proposal in this issue alongside the linked discussion in #331 and the distinguishability work in #724. The issue does not name implementation files or tests, so first locate where component function names and validation rules are defined. Done means overload sets can be represented and validated for distinguishability as described, including the stated char rule.

Web APIs can be overloaded such that the behavior you get is different depending on the number of arguments you provide. This is similar to unions (#724), but distinct. Having just one cannot express all the behavior of the other.

This has been discussed previous at least here. Filing a dedicated issue with a concrete proposal.

Examples

CanvasRenderingContext2D.fill

One example is CanvasRenderingContext2D.fill. One overload takes a Path2D and the other does not.

undefined fill(optional CanvasFillRule fillRule = "nonzero");
undefined fill(Path2D path, optional CanvasFillRule fillRule = "nonzero");

Right now you can't import it twice because they have the same name and so you'd break strongly-unique import names.

You could emulate this with anonymous unions (#724) with:

fill: func(a: option<union<path2d, canvas-fill-rule>>, b: option<canvas-fill-rule>);

(Note: the option goes outside the union because of union rules)

This sort of works but is not ergonomic and also allows passing the invalid none, some(canvas-fill-rule) parameter configuration.

CanvasDrawImage.drawImage

CanvasDrawImage.drawImage is harder.

undefined drawImage(CanvasImageSource image, double dx, double dy);
undefined drawImage(CanvasImageSource image, double dx, double dy, double dw, double dh);
undefined drawImage(CanvasImageSource image, double sx, double sy, double sw, double sh,
                                             double dx, double dy, double dw, double dh);

The names of arguments change (and conflict) in the different overloads. The best you can do is:

draw-image: func(
  a: canvas-image-source,
  dxOrSx: f64, dyOrSy: f64,
  dwOrSw: option<f64>, dwOrSw: option<f64>,
  otherDx: option<f64>, otherDy: option<f64>,
  otherDw: option<f64>, otherDh: option<f64>,
);

This one also has the problem that you can pass invalid amounts of optional parameters.

document.open

Another interesting case is returning different results based off of parameter overloading.

Document    open(optional DOMString unused1, optional DOMString unused2);
WindowProxy? open(USVString url, DOMString name, DOMString features);

You could express this as returning an anonymous union, but then you lose some information.

Emulating variadics

Web API's also have variadic functions. This is technically a separate feature, but you can get pretty far with overloading by hand-unrolling the variadic to common lengths. This could potentially be a stop-gap so that we skip variadics for a while (or indefinitely).

For example:

namespace console {
  undefined log(any... data);
}

You could unroll the variadic to be a set of 8 overloads [0-8). You still have to deal with any but that's a different problem.

Proposal

The idea is a new plainname attribute [overload]name.suffix (e.g. [overload]console-log.0) that relaxes the strong-uniqueness rules to allow an 'overload set' and then strengthens validation rules so that everything within an 'overload set' is distinguishable.

The goal is that:

1. Languages without overloading can just represent them normally and append the suffix (e.g. console_log_0) to get a unique name.
2. Languages with static overloading (C++/C#/Swift) can represent them as an overloaded set of functions that the compiler statically dispatches on.
3. Languages with dynamic overloading (JS/Python) can represent them as a single function that does dynamic type tests to dispatch to an overload.

The guest languages are still responsible for overload resolution. At the component AST level (and ABI) these are all still separate functions and the guest language needs to pick which to call. The validation rules just ensure that each language can perform the dispatch without ambiguity.

We'd define an overload set to be a group of component function's with plainname that are strongly unique if you ignore the [overload] and its .suffix. I think we'd want to disallow overloads on [get] and [set], but allow them with [static] and [constructor].

Between any two functions in an overload set we'd need to enforce that either:

1. they have different length of parameters
2. there is some parameter which is distinguishable (building off of #724)

If these two are met, the overload set should be representable in a variety of languages as a native overload set.

For dynamic languages, the analysis of distinguishability in #724 should apply (e.g. WebIDL handles overloads and unions with the same mechanism).

The new requirement on distinguishability would be static overloading in languages like C++/C#/Swift. From basic research it appears the #724 rules for distinguishability work, with the one addition that char should be considered both string-like and numeric-like (JS converts char to String while C++ treats it as a scalar).