🤖 Merge PR DefinitelyTyped#72883 node: add DOM CustomEvent to v20/v22 by @Renegade334

Author: Renegade334

types/aws-lambda/aws-lambda-tests.ts

@@ -107,16 +107,16 @@ context.succeed(str, anyObj);
 context.fail(error);
 context.fail(str);
 
-interface CustomEvent {
+interface CustomTEvent {
     eventString: string;
     eventBool: boolean;
 }
-interface CustomResult {
+interface CustomTResult {
     resultString: string;
     resultBool?: boolean | undefined;
 }
-type CustomHandler = AWSLambda.Handler<CustomEvent, CustomResult>;
-type CustomCallback = AWSLambda.Callback<CustomResult>;
+type CustomHandler = AWSLambda.Handler<CustomTEvent, CustomTResult>;
+type CustomCallback = AWSLambda.Callback<CustomTResult>;
 
 // Untyped handlers should work
 const untypedAsyncHandler: AWSLambda.Handler = async (event, context, cb) => {
@@ -161,13 +161,13 @@ const unsafeAsyncHandler: CustomHandler = async (event, context, cb) => {
 
 // Test safe old style still works
 const typedCallbackHandler: CustomHandler = (event, context, cb) => {
-    // $ExpectType CustomEvent
+    // $ExpectType CustomTEvent
     event;
     str = event.eventString;
     // $ExpectType Context
     context;
     str = context.functionName;
-    // $ExpectType Callback<CustomResult>
+    // $ExpectType Callback<CustomTResult>
     cb;
     cb();
     cb(null);
@@ -181,11 +181,11 @@ const typedCallbackHandler: CustomHandler = (event, context, cb) => {
 
 // Test preferred new type
 const typedAsyncHandler: CustomHandler = async (event, context, cb) => {
-    // $ExpectType CustomEvent
+    // $ExpectType CustomTEvent
     event;
     // $ExpectType Context
     context;
-    // $ExpectType Callback<CustomResult>
+    // $ExpectType Callback<CustomTResult>
     cb;
     // Can still use callback
     cb(null, { resultString: str });
@@ -197,7 +197,7 @@ const badTypedAsyncHandler: CustomHandler = async (event, context, cb) => ({ res
 
 // Test using untyped Callback type still works.
 const mixedUntypedCallbackTypedHandler: CustomHandler = (
-    event: CustomEvent,
+    event: CustomTEvent,
     context: AWSLambda.Context,
     cb: AWSLambda.Callback,
 ) => {};

types/node/dom-events.d.ts

@@ -1,95 +1,68 @@
-export {}; // Don't export anything!
+// Make this a module
+export {};
 
-//// DOM-like Events
-// NB: The Event / EventTarget / EventListener implementations below were copied
-// from lib.dom.d.ts, then edited to reflect Node's documentation at
-// https://nodejs.org/api/events.html#class-eventtarget.
-// Please read that link to understand important implementation differences.
+// Conditional type aliases, which are later merged into the global scope.
+// Will either be empty if the relevant web library is already present, or the @types/node definition otherwise.
 
-// This conditional type will be the existing global Event in a browser, or
-// the copy below in a Node environment.
-type __Event = typeof globalThis extends { onmessage: any; Event: any } ? {}
-    : {
-        /** This is not used in Node.js and is provided purely for completeness. */
-        readonly bubbles: boolean;
-        /** Alias for event.stopPropagation(). This is not used in Node.js and is provided purely for completeness. */
-        cancelBubble: () => void;
-        /** True if the event was created with the cancelable option */
-        readonly cancelable: boolean;
-        /** This is not used in Node.js and is provided purely for completeness. */
-        readonly composed: boolean;
-        /** Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness. */
-        composedPath(): [EventTarget?];
-        /** Alias for event.target. */
-        readonly currentTarget: EventTarget | null;
-        /** Is true if cancelable is true and event.preventDefault() has been called. */
-        readonly defaultPrevented: boolean;
-        /** This is not used in Node.js and is provided purely for completeness. */
-        readonly eventPhase: 0 | 2;
-        /** The `AbortSignal` "abort" event is emitted with `isTrusted` set to `true`. The value is `false` in all other cases. */
-        readonly isTrusted: boolean;
-        /** Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. */
-        preventDefault(): void;
-        /** This is not used in Node.js and is provided purely for completeness. */
-        returnValue: boolean;
-        /** Alias for event.target. */
-        readonly srcElement: EventTarget | null;
-        /** Stops the invocation of event listeners after the current one completes. */
-        stopImmediatePropagation(): void;
-        /** This is not used in Node.js and is provided purely for completeness. */
-        stopPropagation(): void;
-        /** The `EventTarget` dispatching the event */
-        readonly target: EventTarget | null;
-        /** The millisecond timestamp when the Event object was created. */
-        readonly timeStamp: number;
-        /** Returns the type of event, e.g. "click", "hashchange", or "submit". */
-        readonly type: string;
-    };
+type __Event = typeof globalThis extends { onmessage: any } ? {} : Event;
+interface Event {
+    readonly bubbles: boolean;
+    cancelBubble: boolean;
+    readonly cancelable: boolean;
+    readonly composed: boolean;
+    composedPath(): [EventTarget?];
+    readonly currentTarget: EventTarget | null;
+    readonly defaultPrevented: boolean;
+    readonly eventPhase: 0 | 2;
+    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+    readonly isTrusted: boolean;
+    preventDefault(): void;
+    readonly returnValue: boolean;
+    readonly srcElement: EventTarget | null;
+    stopImmediatePropagation(): void;
+    stopPropagation(): void;
+    readonly target: EventTarget | null;
+    readonly timeStamp: number;
+    readonly type: string;
+}
 
-// See comment above explaining conditional type
-type __EventTarget = typeof globalThis extends { onmessage: any; EventTarget: any } ? {}
-    : {
-        /**
-         * Adds a new handler for the `type` event. Any given `listener` is added only once per `type` and per `capture` option value.
-         *
-         * If the `once` option is true, the `listener` is removed after the next time a `type` event is dispatched.
-         *
-         * The `capture` option is not used by Node.js in any functional way other than tracking registered event listeners per the `EventTarget` specification.
-         * Specifically, the `capture` option is used as part of the key when registering a `listener`.
-         * Any individual `listener` may be added once with `capture = false`, and once with `capture = true`.
-         */
-        addEventListener(
-            type: string,
-            listener: EventListener | EventListenerObject,
-            options?: AddEventListenerOptions | boolean,
-        ): void;
-        /** Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. */
-        dispatchEvent(event: Event): boolean;
-        /** Removes the event listener in target's event listener list with the same type, callback, and options. */
-        removeEventListener(
-            type: string,
-            listener: EventListener | EventListenerObject,
-            options?: EventListenerOptions | boolean,
-        ): void;
-    };
+type __CustomEvent<T = any> = typeof globalThis extends { onmessage: any } ? {} : CustomEvent<T>;
+interface CustomEvent<T = any> extends Event {
+    readonly detail: T;
+}
+
+type __EventTarget = typeof globalThis extends { onmessage: any } ? {} : EventTarget;
+interface EventTarget {
+    addEventListener(
+        type: string,
+        listener: EventListener | EventListenerObject,
+        options?: AddEventListenerOptions | boolean,
+    ): void;
+    dispatchEvent(event: Event): boolean;
+    removeEventListener(
+        type: string,
+        listener: EventListener | EventListenerObject,
+        options?: EventListenerOptions | boolean,
+    ): void;
+}
 
 interface EventInit {
     bubbles?: boolean;
     cancelable?: boolean;
     composed?: boolean;
 }
 
+interface CustomEventInit<T = any> extends EventInit {
+    detail?: T;
+}
+
 interface EventListenerOptions {
-    /** Not directly used by Node.js. Added for API completeness. Default: `false`. */
     capture?: boolean;
 }
 
 interface AddEventListenerOptions extends EventListenerOptions {
-    /** When `true`, the listener is automatically removed when it is first invoked. Default: `false`. */
     once?: boolean;
-    /** When `true`, serves as a hint that the listener will not call the `Event` object's `preventDefault()` method. Default: false. */
     passive?: boolean;
-    /** The listener will be removed when the given AbortSignal object's `abort()` method is called. */
     signal?: AbortSignal;
 }
 
@@ -101,24 +74,26 @@ interface EventListenerObject {
     handleEvent(object: Event): void;
 }
 
-import {} from "events"; // Make this an ambient declaration
+// Merge conditional interfaces into global scope, and conditionally declare global constructors.
 declare global {
-    /** An event which takes place in the DOM. */
     interface Event extends __Event {}
     var Event: typeof globalThis extends { onmessage: any; Event: infer T } ? T
         : {
-            prototype: __Event;
-            new(type: string, eventInitDict?: EventInit): __Event;
+            prototype: Event;
+            new(type: string, eventInitDict?: EventInit): Event;
+        };
+
+    interface CustomEvent<T = any> extends __CustomEvent<T> {}
+    var CustomEvent: typeof globalThis extends { onmessage: any; CustomEvent: infer T } ? T
+        : {
+            prototype: CustomEvent;
+            new<T>(type: string, eventInitDict?: CustomEventInit<T>): CustomEvent<T>;
         };
 
-    /**
-     * EventTarget is a DOM interface implemented by objects that can
-     * receive events and may have listeners for them.
-     */
     interface EventTarget extends __EventTarget {}
     var EventTarget: typeof globalThis extends { onmessage: any; EventTarget: infer T } ? T
         : {
-            prototype: __EventTarget;
-            new(): __EventTarget;
+            prototype: EventTarget;
+            new(): EventTarget;
         };
 }

types/node/test/events-dom.ts

@@ -1,20 +1,15 @@
-//// Test global event interfaces
-
 {
-    const e: Event = new Event("");
-    e.preventDefault();
-    // @ts-expect-error - ensure constructor does not return a constructor
-    new e();
-
     // Node's "DOM-like" Event differs from the real DOM in a few key aspects
-    // $ExpectType boolean
-    e.cancelBubble;
-    e.composedPath();
+    const evt = new Event("");
+    // $ExpectType EventTarget
+    evt.composedPath()[1];
     // $ExpectType number
-    e.eventPhase;
+    evt.eventPhase;
+
+    const ce = new CustomEvent("", { detail: "" });
+    // $ExpectType string
+    ce.detail;
 
     const et: EventTarget = new EventTarget();
     et.addEventListener("", () => {}, { passive: true });
-    // @ts-expect-error - ensure constructor does not return a constructor
-    new et();
 }

types/node/test/events-non-dom.ts

@@ -1,19 +1,15 @@
-//// Test global event interfaces
-
 {
     // Some event properties differ from DOM types
-    const evt = new Event("fake");
-    evt.cancelBubble();
+    const evt = new Event("");
     // @ts-expect-error
-    evt.composedPath[2];
+    evt.composedPath[1];
     // $ExpectType 0 | 2
     evt.eventPhase;
 
-    // @ts-expect-error - ensure constructor does not return a constructor
-    new evt();
+    const ce = new CustomEvent("", { detail: "" });
+    // $ExpectType string
+    ce.detail;
 
     const et: EventTarget = new EventTarget();
     et.addEventListener("", () => {}, { passive: true });
-    // @ts-expect-error - ensure constructor does not return a constructor
-    new et();
 }