[Web API type definition issue] GPUBufferUsage

[ccouzens]

Summary

Unclear on how GPUBufferUsage namespace types should be automated as not in BCD

Expected vs. Actual Behavior

Expected: GPUBufferUsage in Typescript 6.0.2
Actual:

src/renderers/webGPU.ts:73:14 - error TS2304: Cannot find name 'GPUBufferUsage'.

73       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
                ~~~~~~~~~~~~~~

src/renderers/webGPU.ts:73:39 - error TS2304: Cannot find name 'GPUBufferUsage'.

73       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
                                         ~~~~~~~~~~~~~~

Playground Link

https://www.typescriptlang.org/play/?#code/OIBQqgQgrgZjCmAnMBnAhgc3gOgMoBUB5AJQEFgBRIA

Browser Support

• This API is supported in at least two major browser engines (not two Chromium-based browsers).

Have Tried The Latest Releases

• This issue applies to the latest release of TypeScript.
• This issue applies to the latest release of @types/web.

Additional Context

The namespace is documented here.

It is well supported by Firefox (excluding some platforms), Chrome, Safari.

I understand from the contributor documentation that https://github.com/mdn/browser-compat-data drives this repo:

If conditions are not fulfilled but you think MDN is wrong, please file an issue at https://github.com/mdn/browser-compat-data/issues/. The type will be automatically added in a few weeks when MDN fixes their data.

However https://github.com/mdn/browser-compat-data/blob/v7.3.10/docs/data-guidelines/api.md#namespaces calls out GPUBufferUsage as deliberately undocumented:

The GPUBufferUsage namespace only contains constants, which should not be documented in BCD; thus, the GPUBufferUsage namespace should not be documented.

What is the process for contributing a type that BCD deliberately omits?

[Bashamega]

Hello @ccouzens
For contributing a type that BCD deliberately omits you can add it to the gpu.kdl file

[ccouzens]

Here's my WIP PR

#2469

For contributing a type that BCD deliberately omits you can add it to the gpu.kdl file

I did this initially, but I believe I've found a better way. The issues with that approach was it incorrectly added the types to audio worklets and nothing of the type synchronised from the web IDL definitions.

[saschanaz]

https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/api.md#namespaces

Namespaces in Web IDL are similar to interfaces. A namespace should only be documented in BCD if it contains properties or functions that would normally be documented. For example, the console namespace contains many functions, so it should be documented in BCD. The GPUBufferUsage namespace only contains constants, which should not be documented in BCD; thus, the GPUBufferUsage namespace should not be documented.

I... uh... why 🤔

But yes we can override this on our own.

[ccouzens]

Thanks @saschanaz

I've got a pr to enable building the types. There were additional changes beyond not ignoring it

https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/2469/changes

It depends on type changes to webidl2, which is why the build currently fails
DefinitelyTyped/DefinitelyTyped#74872

[ccouzens]

The PR to fix this is now ready #2469