"Polyfill" AllowSharedBufferSource (#179)

We need to use our own definition for `AllowSharedBufferSource` (here
called `GPUAllowSharedBufferSource`) because the built-in one in
TypeScript is broken.

Fixes #178

Author: kainino0x

dist/index.d.ts

@@ -6,13 +6,24 @@
 // Manually-written
 // *********************************************************************************************
 
+// AllowSharedBufferSource wasn't introduced until TypeScript 5.2.
+// But it also didn't include SharedArrayBuffer in the union.
+// This broke in ES2024 when ArrayBuffer gained some properties that SharedArrayBuffer didn't.
+// So, we use our own definition for AllowSharedBufferSource.
+
+type GPUAllowSharedBufferSource =
+
+    | BufferSource
+    | SharedArrayBuffer;
+
+// Stronger typing for getContext()
+
 interface HTMLCanvasElement {
   getContext(
     contextId:
       | "webgpu"
   ): GPUCanvasContext | null;
 }
-
 interface OffscreenCanvas {
   getContext(
     contextId:
@@ -21,33 +32,34 @@ interface OffscreenCanvas {
 }
 
 // Defined as an empty interface here to prevent errors when using these types in a worker.
+
 interface HTMLVideoElement {}
 
+// Strict types defined to help developers catch a common class of errors.
+// This interface defines depth as an undefined, which will cause a type check failure if someone
+// attempts to set depth rather than depthOrArrayLayers on a GPUExtent3D (an easy mistake to make.)
+
 type GPUOrigin2DStrict =
 
     | Iterable<GPUIntegerCoordinate>
     | GPUOrigin2DDictStrict;
-
 interface GPUOrigin2DDictStrict
   extends GPUOrigin2DDict {
   /** @deprecated Does not exist for GPUOrigin2D. */
   z?: undefined;
 }
-
 type GPUExtent3DStrict =
 
     | Iterable<GPUIntegerCoordinate>
     | GPUExtent3DDictStrict;
-
-// GPUExtent3DDictStrict is defined to help developers catch a common class of errors.
-// This interface defines depth as an undefined, which will cause a type check failure if someone
-// attempts to set depth rather than depthOrArrayLayers on a GPUExtent3D (an easy mistake to make.)
 interface GPUExtent3DDictStrict
   extends GPUExtent3DDict {
   /** @deprecated The correct name is `depthOrArrayLayers`. */
   depth?: undefined;
 }
 
+// Stronger typing for event listeners.
+
 /** @internal */
 interface __GPUDeviceEventMap {
   uncapturederror: GPUUncapturedErrorEvent;
@@ -2865,7 +2877,7 @@ interface GPUQueue
   writeBuffer(
     buffer: GPUBuffer,
     bufferOffset: GPUSize64,
-    data: AllowSharedBufferSource,
+    data: GPUAllowSharedBufferSource,
     dataOffset?: GPUSize64,
     size?: GPUSize64
   ): undefined;
@@ -2878,7 +2890,7 @@ interface GPUQueue
    */
   writeTexture(
     destination: GPUTexelCopyTextureInfo,
-    data: AllowSharedBufferSource,
+    data: GPUAllowSharedBufferSource,
     dataLayout: GPUTexelCopyBufferLayout,
     size: GPUExtent3DStrict
   ): undefined;

fix-generated-comments.mjs fix-generated.mjsfix-generated-comments.mjs renamed to fix-generated.mjs

@@ -3,6 +3,9 @@ import fs from 'fs';
 async function main() {
   let ts = fs.readFileSync('generated/index.d.ts', { encoding: 'utf-8' });
   ts = ts
+    // Replace broken AllowSharedBufferSource with GPUAllowSharedBufferSource
+    .replace(/AllowSharedBufferSource/g, 'GPUAllowSharedBufferSource')
+
     // convert [[#anchor]] to {@link spec_url}
     // convert [[#anchor|text]] to {@link spec_url|text}
     .replace(/([^#])\[\[([^\[].*?)\]\]/g, '$1{@link https://www.w3.org/TR/webgpu/$2}')

generated/index.d.ts

@@ -2494,7 +2494,7 @@ interface GPUQueue
   writeBuffer(
     buffer: GPUBuffer,
     bufferOffset: GPUSize64,
-    data: AllowSharedBufferSource,
+    data: GPUAllowSharedBufferSource,
     dataOffset?: GPUSize64,
     size?: GPUSize64
   ): undefined;
@@ -2507,7 +2507,7 @@ interface GPUQueue
    */
   writeTexture(
     destination: GPUTexelCopyTextureInfo,
-    data: AllowSharedBufferSource,
+    data: GPUAllowSharedBufferSource,
     dataLayout: GPUTexelCopyBufferLayout,
     size: GPUExtent3D
   ): undefined;

package.json

@@ -11,9 +11,9 @@
     "dist/**/*"
   ],
   "scripts": {
-    "test": "for t in tests/*/ ; do (cd \"$t\" && npm i && npm test); done",
+    "test": "for t in tests/*/ ; do echo \"\\n======== $t ========\" ; (cd \"$t\" && npm i && npm test); done",
     "build-docs": "cd tsdoc-src && npm ci && npm run build",
-    "generate": "bikeshed-to-ts --in ./gpuweb/spec/index.bs --out ./generated/index.d.ts --forceGlobal --nominal && node fix-generated-comments.mjs && prettier -w generated/index.d.ts",
+    "generate": "bikeshed-to-ts --in ./gpuweb/spec/index.bs --out ./generated/index.d.ts --forceGlobal --nominal && node fix-generated.mjs && prettier -w generated/index.d.ts",
     "format": "prettier -w dist/index.d.ts"
   },
   "devDependencies": {

tests/index.ts

@@ -0,0 +1,3 @@
+export function test_writeBuffer(q: GPUQueue, b: GPUBuffer, sab: SharedArrayBuffer) {
+    q.writeBuffer(b, 0, sab);
+}

tests/ts4.6/index.ts

@@ -1,4 +1,4 @@
 {
   "extends": "../tsconfig.json",
-  "include": ["index.ts"]
+  "include": ["../index.ts"]
 }

tests/ts4.6/tsconfig.json

@@ -1,4 +1,4 @@
 {
   "extends": "../tsconfig.json",
-  "include": ["index.ts"]
+  "include": ["../index.ts"]
 }