Opaque types for WebGL

[crobi]

WebGL types are included in the default lib.d.ts. However, most types are defined as empty interfaces, which means that the compiler doesn't catch many WebGL errors.

Consider the following code:

function foo(gl: WebGLRenderingContext, fbo: WebGLFramebuffer) {
  gl.bindFramebuffer(gl.FRAMEBUFFER, fbo); // Correct call
  gl.bindFramebuffer(gl.FRAMEBUFFER, "abc"); // This should be a compile error!

  fbo = gl.createFramebuffer(); // Correct call
  fbo = new WebGLFramebuffer; // This should be a compile error!
}

• The second parameter of gl.bindFramebuffer should be a WebGLFramebuffer object, but passing a string does not emit a compile error or warning.
• The type WebGLFramebuffer can only be constructed via WebGLRenderingContext.createFramebuffer, calling new throws an error at runtime

Ideally, Typescript would know that WebGLFramebuffer, even though it has no public properties, cannot be constructed or converted to any other type.
I assume that this is not easy to specify with structural typing, but having such opaque types could be useful for other libraries as well (e.g., for returning handles).

If that is not possible, can we find a workaround that at least helps catching the above mentioned bugs?

For reference, here's how the above types are currently defined in lib.d.ts:

interface WebGLFramebuffer extends WebGLObject {
}
declare var WebGLFramebuffer: {
    prototype: WebGLFramebuffer;
    new(): WebGLFramebuffer;
}
interface WebGLRenderingContext {
    bindFramebuffer(target: number, framebuffer: WebGLFramebuffer): void;
    // + many other methods
}

[mhegazy]

@crobi you raise two issues, the first about WebGLObject being an empty object, and this should be fixed, either by updating the WebGL definitions or by just adding a constructor property to each of these types, this should do the trick. @zhengbli does your update of the spec take care of this? if not can we add the constructor declaration declaration?

interface WebGLFramebuffer extends WebGLObject {
    constructor: WebGLFramebuffer;
}

the second one is about constructors, most of the DOM elements have constructors though they are not callable. the problem is that instanceof relies on constructors, if we remove the constructors we will need to come up with a new way to make instanceof work. the other option is to have some sort of private constructors that are callable but still exist for instanceof checks. i think this is a more general issue and needs a general solution

[mhegazy]

@crobi as a work around, you can define the constructor in your files, and this should cause the compiler to flag the error as expected.

[mhegazy]

sorry, scrap my original comment, the constructor would not do it, we need something not defined on object, some sort of _brand:any.

[crobi]

the constructor would not do it, we need something not defined on object, some sort of _brand:any.

This crossed my mind as well, but I'm not sure such a workaround would look nice in lib.d.ts. Maybe this is another use case for #202? Structurally, all WebGL objects are identical to the empty interface, but (due to being native browser objects with hidden properties?) nominally they are all distinct types.

the problem is that instanceof relies on constructors, if we remove the constructors we will need to come up with a new way to make instanceof work.

In plain Javascript, instanceof works as expected on WebGL objects (see below). Is there an additional transformation that Typescript performs on instanceof, that would require compile-time information about the constructors?

> gl.createFramebuffer() instanceof WebGLFramebuffer
true

> gl.createFramebuffer() instanceof WebGLTexture
false

> new WebGLFramebuffer
Uncaught TypeError: Illegal constructor

> gl.createFramebuffer()
WebGLFramebuffer {}

[mhegazy]

In plain Javascript, instanceof works as expected on WebGL objects (see below). Is there an additional transformation that Typescript performs on instanceof, that would require compile-time information about the constructors?

No run time transformations. the right operand of instanceof is expected to have a constructor, so we will need to remove this restriction, or add a non-callable constructor.

[weswigham]

@mhegazy A noncallable constructor would be what abstract classes would need as well (both for instanceof and things like passing an abstract class constructor function as a valid type for a dynamic extends clause), so I suspect that would be the more general solution.