Go language binding for Web IDL

Not affiliated with Go, Google, W3C, or WHATWG.

2. Go binding

1. You should use Go 1.11 modules when developing Go Web IDL bindings. That means go mod init and not GOPATH.

2. Try to group things based on which specification they are a part of. This helps segement the vast collection of browser APIs into develop-able chunks.

3. Put everything on one level. Don’t nest things in sub-packages; put it all on the root. Some developers will want to import . "github.com/octocat/go-fetch" to make Fetch() and all associated things top-level.

4. The Window, WorkerGlobalScope, etc. interfaces are all ✨special since they are global interfaces. Anything that would be defined as a method on Window or other global scope interface should be defined directly at the top level of the Go package instead of as methods on a Window struct/interface. You should also omit the Window and other global interfaces from the types that you define. Think of Window as an invisible package-level interface instead of a concrete type.

5. Many Web IDL definitions (particularily in HTML Standard) will make reference to "the global document" or "the current window". There is no "current window" in a typical Go program. You should try to follow the spirit if not the letter of these definitions.

partial interface Window {
  undefined alert(DOMString message);
};

func Alert(message string) {
  // ...
}

2.1. Names

Remember: to be exported from a package a Go name must start with an uppercase letter.

Use your own best judgement to split the words and PascalCase-ify them to make them conform to the Go convention. Note that initialisms should be all-caps.

For const & static members of interfaces, use the interface name followed by the member name.

For Web IDL constructors use New followed by the interface name.

2.2. Go type mapping

Can’t find a Web IDL type defined in this section? Add it yourself or open an issue. ❤️

The following list of types doesn’t require much explaining.

2.2.1. Restricted float and double

Reminder: the unrestricted double type means that the value can be NaN, +Infinity, or -Infinity. The counterpart is the plain old double type which cannot be NaN, +Infinity, or -Infinity.

Web IDL float values in Go are represented as Go float32 values. Web IDL double values in Go are represented as Go float64 values.

Implementers should panic() if their input Go float32 or float64 value is NaN, +Infinity, or -Infinity when the Web IDL signature uses a restricted float or double type.

partial interface Window {
  double add(double a, double b);
  unrestricted double addUnrestricted(unrestricted double a, unrestricted double b);
};

func Add(a, b float64) float64 {
  if math.IsNaN(a) || math.IsInf(a, 0) { panic("a is not a double") }
  if math.IsNaN(b) || math.IsInf(b, 0) { panic("b is not a double") }
  return a + b
}
func AddUnrestricted(a, b float64) float64 {
  return a + b
}

2.2.2. undefined

In function return position undefined should be omitted from the Go function signature.

interface Storage {
  setter undefined setItem(DOMString name, DOMString value);
  // ...
};

type Storage interface {
  SetItem(name string, value string)
}

**When used in sequence<undefined>** or other places where a type is required use struct{}.

interface A {
  sequence<undefined> doThing();
};

type A interface {
  DoThing() []struct{}
}

When part of a type union treat it like a nullable ? type.

interface CustomElementRegistry {
  (CustomElementConstructor or undefined) get(DOMString name);
  // ...
};
callback CustomElementConstructor = HTMLElement ();

type CustomElementRegistry interface {
  // CustomElementConstructor is a nil-able type.
  Get(name string) CustomElementConstructor
}
type CustomElementConstructor = func() HTMLElement

2.2.3. USVString

The USVString type corresponds to scalar value strings. Depending on the context, these can be treated as sequences of either 16-bit unsigned integer code units or scalar values.

func DoThing(v string) {
  if !utf8.Valid(v) { panic("v is not a well-formed UTF-8 string") }
}

2.2.4. object

object is similar to any but it **cannot be null or a primitive**. In Go-land that means it’s like any just with a panic() check to make sure it’s not nil or a string|int|bool|etc... type.

func DoThing(v any) {
  if v == nil || reflect.ValueOf(v).Kind() < reflect.Array {
    panic("v is not object type")
  }
}

2.2.5. symbol

Not yet defined.

2.2.6. Interface types

To support downcasting (Node 👉 HTMLAnchorElement) easily Web IDL types are represented as Go interface instead of struct. Each Web IDL interface type should have a corresponding Go interface type. Unless it’s Window or another global interface, in which case it should be omitted and all its members should go in the package scope.

interface Node : EventTarget {
  readonly attribute DOMString nodeName;
};
interface Window {
  undefined alert(DOMString message);
};

type Node interface {
  EventTarget
  NodeName() string
}
func Alert(message string) {}

element, err := document.QuerySelector("audio")
// This won't work
audio := element.(*HTMLAudioElement)
// So how do you convert element (which is *Element) into an *HTMLAudioElement?

element, err := document.QuerySelector("audio")
// This is how you do it
audio := element.(HTMLAudioElement)

Interface constructors are pulled out into a New___() function where you fill in the blank with the interface name. For example the Request interface has a constructor NewRequest(). For interfaces without a constructor you should omit this New___() function. Treat interface constructors as though they were their own Window function and apply all the same union, overload, and optional rules.

[Exposed=(Window,Worker)]
interface Headers {
  constructor(optional HeadersInit init);
  // ...
};

func NewHeaders() Headers {}
func NewHeadersInit(init any) Headers {}

2.2.6.1. interface mixin

Mixins are used by Web IDL to define a set of functions implemented by multiple interfaces. The best example of this is the Body mixin which defines arrayBuffer, text, and json on Request and Response objects.

In Go, that just corrolates to an embedded interface!

interface mixin Body {
  readonly attribute boolean bodyUsed;
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  // ...
};
Request includes Body;
Response includes Body;

type Body interface {
  BodyUsed() bool
  ArrayBuffer() func() ([]byte, error)
  // ...
}
type Request interface {
  Body
}
type Response interface {
  Body
}

2.2.7. Callback interface types

// Both of these work!
globalThis.addEventListener("load", { handleEvent: () => console.log("handleEvent") })
globalThis.addEventListener("load", () => console.log("function"))

Treat callback interfaces as though they were just a union type of the function signature and an unnamed interface with that single method defined. Practically, this means that callback interfaces are represented as any.

You should provide a same-name type TheCallbackInterface func(...)... type as well as an interface type with the suffix Object like type TheCallbackInterfaceObject interface {...}.

interface Thing {
  undefined addEventListener(listener EventListener);
};
callback interface EventListener {
  undefined handleEvent(Event event);
};

type EventListener func(event Event)
type EventListenerObject interface {
  HandleEvent(event Event)
}

func (e *thingImpl) AddEventListener(listener any) {
  if b, ok := a.(EventListenerObject); ok {
    // Can use like this:
    b.HandleEvent(event)
  } else if b, ok := a.(EventListener); ok {
    // Can use like this:
    b(event)
  } else {
    panic("listener is not an EventListener or EventListenerObject")
  }
}

2.2.8. Dictionary types

Web IDL interfaces map quite well to Go struct. The biggest obstacle here is optional struct fields. Since Go doesn’t have a Rust Option<T> or a Java null-able primitive (Integer, Double, String) objects it means we need to use something else. The most Go-like way of doing things is with nil-able types. For interfaces this is no sweat: interfaces are always nil-able. For primitives it means passing by *string instead of string.

func ptr[T any](v T) *T {
  return &v
}

func DoThing(v *string) {}

func main() {
  // Doesn't work 😢
  // DoThing(&"hello ptr magic!")

  // Works! 😄
  DoThing(ptr("hello ptr magic!"))
}

dictionary ResponseInit {
  unsigned short status = 200;
  ByteString statusText = "";
  HeadersInit headers;
};

type ResponseInit struct {
  Status *uint16
  StatusText *string
  Headers any
}

Dictionaries that extend other dictionaries should be completely flattened into a single struct. This is more ergonomic from a consumer’s perspective since all the fields are flattened one level deep instead of being nested.

dictionary AddEventListenerOptions : EventListenerOptions {
  boolean passive = false;
  boolean once = false;
};
dictionary EventListenerOptions {
  boolean capture = false;
};

type AddEventListenerOptions struct {
  EventListenerOptions // 👈 Embedded struct!
  Passive *bool
  Once *bool
}
type EventListenerOptions struct {
  Capture *bool
}

// 🤷‍♀️ Not ideal.
AddEventListener("click", listener, AddEventListenerOptions{
  EventListenerOptions: EventListenerOptions{
    Capture: ptr(true),
  },
  Passive: ptr(true),
  Once: ptr(true),
})

// 👍 Better.
AddEventListener("click", listener, AddEventListenerOptions{
  Capture: ptr(true),
  Passive: ptr(true),
  Once: ptr(true),
})

I’m open to being wrong about nested structs being bad. Give me your experience! Maybe embedded structs are better.

2.2.9. Enumeration types

Todo

2.2.10. Callback function types

Use a type TheType func(...)... newtype.

callback TheCallback = long (long a, long b);

type TheCallback func(a int32, b int32) int32

func useTheCallback(cb TheCallback) {
  fmt.Printf("Result: %d", cb(1, 2))
}

func main() {
  useTheCallback(func(a int32, b int32) int32 {
    return a + b
  })
}

2.2.11. Nullable types

Nullable types become nil-able types in Go. All Web IDL interface types should be nil-able by default since all Go interface types are nil-able. Go primitives like string, int32, etc. can all be made nil-able through a pointer. Go structs can be made nil-able through a pointer as well.

partial interface Window {
  undefined doThing(DOMString? message);
};

func DoThing(message *string) {
  fmt.Println(message)
}

2.2.12. Sequences

For now Web IDL sequences are analagous to Array<T> types. Each sequence<T> type can be exactly mapped into a Go []T slice.

In the future iterables might be accepted.

partial interface Window {
  undefined doThing(sequence<DOMString> items);
};

func DoThing(items []string) {
  for i, v := range items {
    fmt.Printf("item %d: %s", i, v)
  }
}

2.2.13. Records

record<K, V> maps to map[K]V in Go.

partial interface Window {
  undefined doThing(record<DOMString, long> things);
};

func DoThing(things map[string]int32) {
  for k, v := range things {
    fmt.Println(k, v)
  }
}

So far all use-cases for record<K, V> have been unordered so to Go random map[K]V ordering is OK.

2.2.14. Promise types

Promises are a bit tricky in Go. Unlike <-chan T, a Promise<T> can be await-ed multiple times and will always spit out the same cached value. What this means is that just <-chan T isn’t enough to represent a Promise<T> in Go. It falls apart specifically when you have a static Promise<T> that you want to await multiple times like ready.

Instead, the solution is to use a getter function. The current idiom that seems favored by Go is to *return something with a .Wait() method* and then call that to "await" the function’s result.

partial interface Window {
  Promise<Response> fetch();
};

func Fetch() interface{Wait() (Response, error)} {
  // ...
}

An infalliable promise is a promise that never errors. These are extremely rare in Web APIs since most things that are async call system-level operations that can often fail for arbitrary reasons. If you see a Promise<T> in Web IDL it’s almost always a Promise<T> which should be a interface { Wait() (T, error) } in Go.

partial interface ServiceWorkerContainer {
  readonly attribute Promise<ServiceWorkerRegistration> ready;
};

type ServiceWorkerContainer interface {
  Ready() interface{ Wait() ServiceWorkerRegistration }
}

In all cases the returned object should support being called concurrently. sync.* friends handle this for you.

The work that the operation is doing should be done in a go func(){}() Go-routine in an async fashion. The Promise<T> exposes the result to the caller.

2.2.15. Union

Web IDL union types are represented as any in Go. Then at runtime they are if b, ok := a.(T); ok {} checked to see if they fit the union terminal types. There’s no recursion for union types that contain union types; all of said types must be individually checked for at runtime using type conversion checks.

You should provide a stub type UnionType = any type alias (not a newtype) with a documentation comment outlining which values are accepted in the union.

typedef (DOMString or long) TheUnion;
partial interface Window {
  undefined doThing(TheUnion u);
};

type TheUnion any
func DoThing(u TheUnion) {
  if uString, ok := u.(string); ok {
    fmt.Println("got string")
  } else if uInt32, ok := u.(int32); ok {
    fmt.Println("got int32")
  } else {
    panic("not string|int32")
  }
}

func main() {
  DoThing("wasd") // will panic!
  DoThing(1) // will panic!

  var myVariable TheUnion = "qwerty"
  // ☝ This has a type of TheUnion, not string.

  // ✅
  _ = myVariable.(TheUnion)

  // ❌
  _ = myVariable.(string)
}

2.2.16. Buffer source types

An ArrayBuffer needs to support [AllowResizable] so it’s represented in Go as a bytes.Buffer. SharedArrayBuffer is a bit trickier. There’s no concurrent bytes.Buffer in the Go standard library (that I know of) so for now it’s just bytes.Buffer with the note that it should be used with caution.

partial interface Window {
  Float64Array doThing(ArrayBuffer b);
};

func DoThing(b *bytes.Buffer) []float64 {
  return unsafe.Slice((*float64)(unsafe.Pointer(&b.Bytes()[0])), len(b.Bytes())/unsafe.Sizeof(float64(0)))
}

A DataView is roughly equivalent to a []byte and can then be used with other encoding functions to use and mutate the slice’s contents.

2.2.17. Frozen arrays

Use a normal Go slice and just make sure you emphasize that it’s intended to be immutable.

2.2.18. Observable arrays

This is fairly rare. adoptedStyleSheets is one case where I know this is used. Don’t know how to model this in Go.

2.3. Extended attributes

-tags=coi might be something that happens in the future to disable cross-origin isolated features by default.

2.3.1. [PutForwards]

[Exposed=Window]
interface Name {
  attribute DOMString full;
  attribute DOMString family;
  attribute DOMString given;
};

[Exposed=Window]
interface Person {
  [PutForwards=full] readonly attribute Name name;
  attribute unsigned short age;
};

var p = getPerson();           // Obtain an instance of Person.

p.name = 'John Citizen';       // This statement...
p.name.full = 'John Citizen';  // ...has the same behavior as this one.

Since this attribute can only be applied on readonly attributes, the port to Go is simple: delegate the setter of the parent attribute to the specified child attribute. There’s no union type or any type deduction.

[Exposed=Window]
interface Name {
  attribute DOMString full;
  attribute DOMString family;
  attribute DOMString given;
};

[Exposed=Window]
interface Person {
  [PutForwards=full] readonly attribute Name name;
  attribute unsigned short age;
};

type Name interface {
  Full() string
  SetFull(v string)
  Family() string
  SetFamily(v string)
  Given() string
  SetGiven(v string)
  isName()
}

type Person interface {
  Name() Name
  SetName(v string)
  Age() uint16
  SetAge(v uint16)
  isPerson()
}

// ✅ The getter stays the same as always. This is a readonly property.
func (p *personImpl) Name() Name {
  return p.name
}

// 👇 We delegate to the p.name.SetFull() just like [PutForwards=full] said!
func (p *personImpl) SetName(v string) {
  p.name.SetFull(v)
}

This attribute is used in ElementCSSInlineStyle/style.

2.4. Legacy extended attributes

2.5. Overloads

Normally Web IDL overloads would be routed under a single JavaScript function. In Go the overload convention is different; you define overloads as separate functions with slightly different names. The naming convention for these extra functions usually focuses either on a type like Match vs MatchString or a named parameter like Split vs SplitAfterN.

The convention that this standard has adopted is to use TODO

2.6. Interfaces

TODO

2.6.1. Constants

TODO

2.6.2. Attributes

2.6.3. Stringifiers

2.6.4. Iterable declarations

2.6.5. Asynchronous iterable declarations

2.6.6. Maplike declarations

2.6.7. Setlike declarations

2.7. Namespaces

2.8. Exceptions