import type {FindGlobalInstanceType} from './find-global-type.d.ts'; /** The global `EventTarget` instance type, or `never` when the lib has no DOM or Node.js types. */ type EventTargetInstance = FindGlobalInstanceType<'EventTarget'>; /** The global `Event` instance type, or `never` when the lib has no DOM or Node.js types. */ type EventInstance = FindGlobalInstanceType<'Event'>; /** The options of `addEventListener`, including its `boolean` shorthand. */ type AddListenerOptions = Parameters[2]; /** The options of `removeEventListener`, including its `boolean` shorthand. */ type RemoveListenerOptions = Parameters[2]; /** A listener for one event: a function or an object with a `handleEvent` function. `handleEvent` is a function-typed property rather than a method, so a handler cannot narrow the event type. This matches the function listener form. */ type EventListenerFor = ((this: Target, event: EventValue) => void) | {handleEvent: (event: EventValue) => void}; /** A stricter version of [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) that maps event names to event types. Use-cases: - Add types to an `EventTarget` from a library without changing its runtime code. - Type an instance of a class that extends `EventTarget`. - Type an event target built on the DOM API in a browser, Node.js, Deno, or Bun. `EventMap` values are event types, like the values in `WindowEventMap` or `HTMLElementEventMap`. For an event without data, use `Event`. The event map is constrained to the global `Event` type, so it requires the DOM types or the Node.js types. @example ``` import type {StrictEventTarget} from 'type-fest'; type AppEvents = { save: CustomEvent<{id: string}>; close: Event; }; const target: StrictEventTarget = new EventTarget(); target.addEventListener('save', event => { const {id} = event.detail; //=> string }); // @ts-expect-error `unknown` is not an event name. target.addEventListener('unknown', null); target.dispatchEvent(new CustomEvent('save', {detail: {id: 'abc'}})); ``` Declare the target as `StrictEventTarget`, then assign or cast the real `EventTarget` to it. The methods are declared structurally, so no runtime code is needed. A class cannot extend the type directly, because it has no runtime value. Cast the `EventTarget` constructor instead: @example ``` import type {StrictEventTarget} from 'type-fest'; type CounterEvents = { change: CustomEvent<{count: number}>; }; class Counter extends (EventTarget as new () => StrictEventTarget) { count = 0; increment(): void { this.count++; this.dispatchEvent(new CustomEvent('change', {detail: {count: this.count}})); } } const counter = new Counter(); counter.addEventListener('change', event => { const {count} = event.detail; //=> number }); ``` Note: `dispatchEvent` checks the event type, not the event name, because the type of `CustomEvent` does not include its event name. It also cannot check that a `detail` is present, because the constructor takes the detail type from the map. When a mapped value is a wider type, like `Event`, any event of that type is accepted, including one whose name is not in the map. In a map with several events, an event can carry the detail type of a different event. @category Improved Built-in */ export type StrictEventTarget> = { addEventListener( type: Name, listener: EventListenerFor, EventMap[Name]> | null, options?: AddListenerOptions ): void; removeEventListener( type: Name, listener: EventListenerFor, EventMap[Name]> | null, options?: RemoveListenerOptions ): void; dispatchEvent(event: EventMap[keyof EventMap]): boolean; }; export {};