Local proxies

[granicz]

In an ideal world, proxies (giving JS semantics to .NET APIs) arise "magically" and web developers just use them without worrying about how they came to be. In a less ideal world, one often encounters .NET APIs that don't yet have a proxy and run into the obvious error:

Method name not found in JavaScript compilation: (System.Net.WebUtilities.UrlDecode : System.String -> System.String)

At this point, one can resolve the situation easily by clever shadowing, or using a compiler directive (#if JAVASCRIPT ... ELSE ...) to branch off the problematic part and substitute a web-friendly one. While these mechanisms are straightforward and more than OK for one-off cases, they do litter up the codebase unnecessarily with glue code. And as we usually find, there is always another missing method that needs to be provided...

The WebSharper textbook recommendation, and the most robust solution to fixing the above situation, is to create a proxy. A proxy is implemented as an internal type with an attribute marking the actual type that is to be proxied:

open WebSharper
open WebSharper.JavaScript

[<Proxy(typeof<System.Net.WebUtility>)>]
type internal SystemNetWebUtility =
    static member UrlDecode(s: string) = JS.DecodeURIComponent(s)

When such a proxy is encountered, its metadata is saved into the target assembly, making it possible to use the proxied functionality in consuming projects seamlessly. However, currently, the proxy overload resolution is non-existent: if you need to change or amend an existing proxy, it will result in a compiler error. This then discourages anyone from writing partial proxies.

To provide a more user-friendly experience, this ticket proposes the idea of "local proxies" - proxies that can "fill in holes where needed" in the current project, but not persisted into the metadata of the assembly. Effectively, local proxies don't escape - and one should use them accordingly.

This proposal would then enable writing "local" proxies with the same implementation as above, but for practical purposes, using a different attribute name such as ProxyLocal.

[granicz]

After a few rounds of discussions: instead of ProxyLocal the name InternalProxy was selected for this new attribute. Furthermore, it is still an artifact of the proxying subsystem that at most one internal proxy can be supplied for any given type (in a given project).