Overrides for TypeScript definition generation from JSG RTTI

.clang-format

@@ -0,0 +1,7 @@
+WhitespaceSensitiveMacros:
+  # clang format doesn't understand TypeScript, so make sure it doesn't mangle
+  # overrides and additional definitions
+  - JSG_TS_OVERRIDE
+  - JSG_TS_DEFINE
+  - JSG_STRUCT_TS_OVERRIDE
+  - JSG_STRUCT_TS_DEFINE

src/workerd/api/actor-state.h

@@ -42,6 +42,7 @@ class DurableObjectStorageOperations {
     }
 
     JSG_STRUCT(allowConcurrency, noCache);
+    JSG_STRUCT_TS_OVERRIDE(DurableObjectGetOptions); // Rename from DurableObjectStorageOperationsGetOptions
   };
 
   jsg::Promise<jsg::Value> get(
@@ -52,6 +53,7 @@ class DurableObjectStorageOperations {
     jsg::Optional<bool> allowConcurrency;
 
     JSG_STRUCT(allowConcurrency);
+    JSG_STRUCT_TS_OVERRIDE(DurableObjectGetAlarmOptions); // Rename from DurableObjectStorageOperationsGetAlarmOptions
   };
 
   jsg::Promise<kj::Maybe<double>> getAlarm(jsg::Optional<GetAlarmOptions> options, v8::Isolate* isolate);
@@ -74,6 +76,7 @@ class DurableObjectStorageOperations {
     }
 
     JSG_STRUCT(start, startAfter, end, prefix, reverse, limit, allowConcurrency, noCache);
+    JSG_STRUCT_TS_OVERRIDE(DurableObjectListOptions); // Rename from DurableObjectStorageOperationsListOptions
   };
 
   jsg::Promise<jsg::Value> list(jsg::Optional<ListOptions> options, v8::Isolate* isolate);
@@ -91,6 +94,7 @@ class DurableObjectStorageOperations {
     }
 
     JSG_STRUCT(allowConcurrency, allowUnconfirmed, noCache);
+    JSG_STRUCT_TS_OVERRIDE(DurableObjectPutOptions); // Rename from DurableObjectStorageOperationsPutOptions
   };
 
   jsg::Promise<void> put(jsg::Lock& js,
@@ -114,6 +118,7 @@ class DurableObjectStorageOperations {
     }
 
     JSG_STRUCT(allowConcurrency, allowUnconfirmed);
+    JSG_STRUCT_TS_OVERRIDE(DurableObjectSetAlarmOptions); // Rename from DurableObjectStorageOperationsSetAlarmOptions
   };
 
   jsg::Promise<void> setAlarm(kj::Date scheduledTime, jsg::Optional<SetAlarmOptions> options,
@@ -179,6 +184,8 @@ class DurableObjectStorage: public jsg::Object, public DurableObjectStorageOpera
     jsg::Optional<bool> lowPriority;
 
     JSG_STRUCT(asOfTime, lowPriority);
+    JSG_STRUCT_TS_OVERRIDE(type TransactionOptions = never);
+    // Omit from definitions
   };
 
   jsg::Promise<jsg::Value> transaction(jsg::Lock& js,
@@ -200,6 +207,21 @@ class DurableObjectStorage: public jsg::Object, public DurableObjectStorageOpera
     JSG_METHOD(setAlarm);
     JSG_METHOD(deleteAlarm);
     JSG_METHOD(sync);
+
+    JSG_TS_OVERRIDE({
+      get<T = unknown>(key: string, options?: DurableObjectGetOptions): Promise<T | undefined>;
+      get<T = unknown>(keys: string[], options?: DurableObjectGetOptions): Promise<Map<string, T>>;
+
+      list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
+
+      put<T>(key: string, value: T, options?: DurableObjectPutOptions): Promise<void>;
+      put<T>(entries: Record<string, T>, options?: DurableObjectPutOptions): Promise<void>;
+
+      delete(key: string, options?: DurableObjectPutOptions): Promise<boolean>;
+      delete(keys: string[], options?: DurableObjectPutOptions): Promise<number>;
+
+      transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
+    });
   }
 
 protected:
@@ -238,6 +260,21 @@ class DurableObjectTransaction final: public jsg::Object, public DurableObjectSt
     JSG_METHOD(getAlarm);
     JSG_METHOD(setAlarm);
     JSG_METHOD(deleteAlarm);
+
+    JSG_TS_OVERRIDE({
+      get<T = unknown>(key: string, options?: DurableObjectGetOptions): Promise<T | undefined>;
+      get<T = unknown>(keys: string[], options?: DurableObjectGetOptions): Promise<Map<string, T>>;
+
+      list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
+
+      put<T>(key: string, value: T, options?: DurableObjectPutOptions): Promise<void>;
+      put<T>(entries: Record<string, T>, options?: DurableObjectPutOptions): Promise<void>;
+
+      delete(key: string, options?: DurableObjectPutOptions): Promise<boolean>;
+      delete(keys: string[], options?: DurableObjectPutOptions): Promise<number>;
+
+      deleteAll: never;
+    });
   }
 
 protected:
@@ -280,6 +317,8 @@ class ActorState: public jsg::Object {
     JSG_READONLY_INSTANCE_PROPERTY(id, getId);
     JSG_READONLY_INSTANCE_PROPERTY(transient, getTransient);
     JSG_READONLY_INSTANCE_PROPERTY(persistent, getPersistent);
+
+    JSG_TS_OVERRIDE(type ActorState = never);
   }
 
 private:
@@ -311,6 +350,14 @@ class DurableObjectState: public jsg::Object {
     JSG_READONLY_INSTANCE_PROPERTY(id, getId);
     JSG_READONLY_INSTANCE_PROPERTY(storage, getStorage);
     JSG_METHOD(blockConcurrencyWhile);
+
+    JSG_TS_ROOT();
+    JSG_TS_OVERRIDE({
+      readonly id: DurableObjectId;
+      readonly storage: DurableObjectStorage;
+      blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+    });
+    // Make `storage` non-optional
   }
 
 private:

src/workerd/api/actor.h

@@ -85,6 +85,14 @@ class DurableObject: public Fetcher {
 
     JSG_READONLY_INSTANCE_PROPERTY(id, getId);
     JSG_READONLY_INSTANCE_PROPERTY(name, getName);
+
+    JSG_TS_DEFINE(interface DurableObject {
+      fetch(request: Request): Response | Promise<Response>;
+      alarm?(): void | Promise<void>;
+    });
+    JSG_TS_OVERRIDE(DurableObjectStub);
+    // Rename this resource type to DurableObjectStub, and make DurableObject
+    // the interface implemented by users' Durable Object classes.
   }
 
 private:
@@ -132,6 +140,7 @@ class DurableObjectNamespace: public jsg::Object {
     JSG_METHOD(idFromName);
     JSG_METHOD(idFromString);
     JSG_METHOD(get);
+    JSG_TS_ROOT();
   }
 
 private:

src/workerd/api/analytics-engine.h

@@ -58,6 +58,7 @@ class AnalyticsEngine: public jsg::Object {
 
   JSG_RESOURCE_TYPE(AnalyticsEngine) {
     JSG_METHOD(writeDataPoint);
+    JSG_TS_ROOT();
   }
 
 private:

src/workerd/api/basics.h

@@ -182,6 +182,9 @@ class ExtendableEvent: public Event {
 #if !WORKERD_API_BASICS_TEST
     JSG_LAZY_READONLY_INSTANCE_PROPERTY(actorState, getActorState);
 #endif
+
+    JSG_TS_OVERRIDE({ actorState: never });
+    // Omit `actorState` from definitions
   }
 };
 
@@ -307,6 +310,19 @@ class EventTarget: public jsg::Object {
     JSG_METHOD(addEventListener);
     JSG_METHOD(removeEventListener);
     JSG_METHOD(dispatchEvent);
+
+    JSG_TS_DEFINE(
+      type EventListener<EventType extends Event = Event> = (event: EventType) => void;
+      interface EventListenerObject<EventType extends Event = Event> {
+        handleEvent(event: EventType): void;
+      }
+      type EventListenerOrEventListenerObject<EventType extends Event = Event> = EventListener<EventType> | EventListenerObject<EventType>;
+    );
+    JSG_TS_OVERRIDE(<EventMap extends Record<string, Event> = Record<string, Event>> {
+      addEventListener<Type extends keyof EventMap>(type: Type, handler: EventListenerOrEventListenerObject<EventMap[Type]>, options?: EventTargetAddEventListenerOptions | boolean): void;
+      removeEventListener<Type extends keyof EventMap>(type: Type, handler: EventListenerOrEventListenerObject<EventMap[Type]>, options?: EventTargetEventListenerOptions | boolean): void;
+      dispatchEvent(event: EventMap[keyof EventMap]): boolean;
+    });
   }
   JSG_REFLECTION(onEvents);
 

src/workerd/api/cache.h

@@ -68,6 +68,13 @@ class Cache: public jsg::Object {
     JSG_METHOD(put);
     JSG_METHOD(matchAll);
     JSG_METHOD(keys);
+
+    JSG_TS_OVERRIDE({
+      delete(request: RequestInfo, options?: CacheQueryOptions): Promise<boolean>;
+      match(request: RequestInfo, options?: CacheQueryOptions): Promise<Response | undefined>;
+      put(request: RequestInfo, response: Response): Promise<void>;
+    });
+    // Use RequestInfo type alias to allow `URL`s as cache keys
   }
 
 private:

src/workerd/api/crypto.h

@@ -392,6 +392,7 @@ class SubtleCrypto: public jsg::Object {
       jsg::Optional<kj::String> t;
 
       JSG_STRUCT(r, d, t);
+      JSG_STRUCT_TS_OVERRIDE(RsaOtherPrimesInfo); // Rename from SubtleCryptoJsonWebKeyRsaOtherPrimesInfo
     };
 
     // The following fields are defined in Section 3.1 of JSON Web Key (RFC 7517).
@@ -424,6 +425,7 @@ class SubtleCrypto: public jsg::Object {
     jsg::Optional<kj::String> k;
 
     JSG_STRUCT(kty, use, key_ops, alg, ext, crv, x, y, d, n, e, p, q, dp, dq, qi, oth, k);
+    JSG_STRUCT_TS_OVERRIDE(JsonWebKey); // Rename from SubtleCryptoJsonWebKey
   };
 
   using ImportKeyData = kj::OneOf<kj::Array<kj::byte>, JsonWebKey>;
@@ -593,6 +595,8 @@ class DigestStream: public WritableStream {
     } else {
       JSG_READONLY_INSTANCE_PROPERTY(digest, getDigest);
     }
+
+    JSG_TS_OVERRIDE(extends WritableStream<ArrayBuffer | ArrayBufferView>);
   }
 
 private:
@@ -629,6 +633,20 @@ class Crypto: public jsg::Object {
     JSG_METHOD(randomUUID);
 
     JSG_NESTED_TYPE(DigestStream);
+
+    JSG_TS_OVERRIDE({
+      getRandomValues<
+        T extends
+          | Int8Array
+          | Uint8Array
+          | Int16Array
+          | Uint16Array
+          | Int32Array
+          | Uint32Array
+          | BigInt64Array
+          | BigUint64Array
+      >(buffer: T): T;
+    });
   }
 
 private:

src/workerd/api/form-data.h

@@ -96,7 +96,7 @@ class FormData: public jsg::Object {
       jsg::Optional<jsg::Value> thisArg,
       const jsg::TypeHandler<EntryType>& handler);
 
-  JSG_RESOURCE_TYPE(FormData) {
+  JSG_RESOURCE_TYPE(FormData, CompatibilityFlags::Reader flags) {
     JSG_METHOD(append);
     JSG_METHOD_NAMED(delete, delete_);
     JSG_METHOD(get);
@@ -109,6 +109,37 @@ class FormData: public jsg::Object {
 
     JSG_METHOD(forEach);
     JSG_ITERABLE(entries);
+
+    if (flags.getFormDataParserSupportsFiles()) {
+      JSG_TS_OVERRIDE({
+        append(name: string, value: string): void;
+        append(name: string, value: Blob, filename?: string): void;
+
+        set(name: string, value: string): void;
+        set(name: string, value: Blob, filename?: string): void;
+
+        entries(): IterableIterator<[key: string, value: File | string]>;
+        [Symbol.iterator](): IterableIterator<[key: string, value: File | string]>;
+
+        forEach<This = unknown>(callback: (this: This, value: File | string, key: string, parent: FormData) => void, thisArg?: This): void;
+      });
+    } else {
+      JSG_TS_OVERRIDE({
+        get(name: string): string | null;
+        getAll(name: string): string[];
+
+        append(name: string, value: string): void;
+        append(name: string, value: Blob, filename?: string): void;
+
+        set(name: string, value: string): void;
+        set(name: string, value: Blob, filename?: string): void;
+
+        entries(): IterableIterator<[key: string, value: string]>;
+        [Symbol.iterator](): IterableIterator<[key: string, value: string]>;
+
+        forEach<This = unknown>(callback: (this: This, value: string, key: string, parent: FormData) => void, thisArg?: This): void;
+      });
+    }
   }
 
 private: