darionco / bikeshed-to-ts Goto Github PK

I thought I filed this, but I guess I forgot.

[AllowShared]: https://heycam.github.io/webidl/#AllowShared

[AllowShared] BufferSource should be translated as BufferSource | SharedArrayBuffer.
WebGPU doesn't use it, but also:
[AllowShared] ArrayBuffer should be translated as ArrayBuffer | SharedArrayBuffer.

Currently IDL interfaces with constructors will generate declare vars like:

declare var GPUOutOfMemoryError: {
  prototype: GPUOutOfMemoryError;
  new ();
};

However some compiler settings (such as the ones used in gpuweb/cts) will actually consider new () to return any instead of the apparent usual default GPUOutOfMemoryError (I'm not exactly sure why), causing linter errors. Would be best to write the return type explicitly I think.

declare var GPUOutOfMemoryError: {
  prototype: GPUOutOfMemoryError;
  new (): GPUOutOfMemoryError;
};

Just now I was doing the manual diff between the handwritten and generated types for WebGPU, and realized (toward the end) it is going to end up being somewhat painful when we reorder IDL chunks in the spec, which I expect we will do as we edit the spec.

We could avoid churn by doing some sorting of the top level items, either just alphabetically or by (type, name) tuple (where type is enum, dictionary, interface, etc.)

This code from the WebGPU spec:

interface mixin NavigatorGPU {
    [SameObject] readonly attribute GPU gpu;
};
Navigator includes NavigatorGPU;

generates:

  interface Navigator {
    /**
     * Nominal type branding.
     * https://github.com/microsoft/TypeScript/pull/33038
     * @internal
     */
    readonly __brand: "Navigator";
    readonly gpu: GPU;
  }

but shouldn't make this externally-defined interface suddenly become nominally typed:

  interface Navigator {
    readonly gpu: GPU;
  }

WebIDL sequences are (I think) equivalent to TypeScript Iterables - the WebIDL conversion rules from JS will iterate the value to produce an array. For example:

dictionary GPUBindGroupLayoutDescriptor : GPUObjectDescriptorBase {
    required sequence<GPUBindGroupLayoutEntry> entries;
};

generates:

  interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase {
    entries: Array<GPUBindGroupLayoutEntry>;
  }

but should generate:

  interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase {
    entries: Iterable<GPUBindGroupLayoutEntry>;
  }

declare var for WebIDL interfaces without constructors currently omit the new () definition:

declare var GPUDevice: {
  prototype: GPUDevice;
};

However, this prevents expressions like mydevice instanceof GPUDevice from being valid.
A new () method should be added to the generated var.

Upstream, TypeScript's built-in types would do this:

declare var GPUDevice: {
  prototype: GPUDevice;
  new (): GPUDevice;
};

However, if there is no constructor present in the IDL, then the constructor exists but will always throw. Hence, I think the generator could optionally write:

declare var GPUDevice: {
  prototype: GPUDevice;
  new (): never;
};

to be more precise.

Currently translates as any, but I think it should just be object.

In WebGPU:

interface mixin GPUObjectBase {
    attribute USVString? label;
};

gets translated as

  interface GPUObjectBase {
    label: string;
  }

but it should be:

  interface GPUObjectBase {
    label: string | null;
  }

E.g. for WebGPU's GPURequestAdapterOptions, currently I get:

  interface GPURequestAdapterOptions {
    /**
     * Nominal type branding.
     * https://github.com/microsoft/TypeScript/pull/33038
     * @internal
     */
    readonly __brand: "GPURequestAdapterOptions";
    powerPreference?: GPUPowerPreference;
  }

WebIDL dictionaries are input types; users write them as { object: literals } in TS. So they should not be nominally typed.

In IDL, optional dictionary members can have default values. This can't be expressed in TypeScript, but these defaults are extremely useful for developers to know about. It would be nice if the default values could be appended or prepended into the generated documentation.

Here's an example from TypeScript's lib.dom.d.ts:
https://github.com/microsoft/TypeScript/blob/16031bc429305e5daabf263f208678a6729a161e/lib/lib.dom.d.ts#L6490-L6525

interface HTMLCanvasElement extends HTMLElement {
    // ...
}
declare var HTMLCanvasElement: {
    prototype: HTMLCanvasElement;
    new(): HTMLCanvasElement;
};