[Web API type definition issue] BufferSource

[BTOdell]

Summary

Current BufferSource definition is too strict

Expected vs. Actual Behavior

Expected:

type BufferSource = ArrayBufferView<ArrayBuffer> | ArrayBuffer;

Actual:

type BufferSource = ArrayBufferView | ArrayBuffer;

I just recently updated from TypeScript 5.8.3 to 5.9.2 and the only typing error was due to a change in the definition of BufferSource.

Code example:

...
if (body instanceof ArrayBuffer || body instanceof Uint8Array) {
    reqOptions.body = body; // Error here that `Uint8Array<ArrayBufferLike>` can't be assigned
}
...

reqOptions.body is defined as: BodyInit.

There doesn't seem to be an easy way to check if the body value is a ArrayBufferView<ArrayBuffer> in order to satisfy the BufferSource definition, since you can't invoke instanceof on a TypeScript definition.

Seeing that this is a recent change, I wonder if it was a mistake?

Playground Link

No response

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

No response

[Renegade334]

It's TypeScript's behaviour towards array buffer views that changed in 5.9 – lib.dom's BufferSource et al. haven't changed. The difference in the behaviour of ArrayBuffer and array buffer views is as detailed in the version 5.9 announcement post.

The web spec mandates that BufferSource, ArrayBufferView etc. are specifically backed by an ArrayBuffer unless flagged as [AllowShared], so the lib.dom types are correct here.

The issue was that eg. Uint8Array<SharedArrayBuffer> was actually considered assignable to Uint8Array<ArrayBuffer> in previous versions of TypeScript due to a definition quirk, so these constraints in lib.dom were never actually applied prior to now.

For external input that needs to be validated, you may need to define some kind of helper predicate like

function isBufferSource(input: unknown): input is BufferSource {
  if (ArrayBuffer.isView(input)) return input.buffer instanceof ArrayBuffer;
  if (input instanceof ArrayBuffer) return true;
  return false;
}

to use in your conditionals.

[BTOdell]

Thank you for the detailed explanation!