An polyfill for DOM Events and related APIs, extracted from Node.js, for use in WinterCG runtimes
npm install dom-events-wintercg
A polyfill for DOM Events and related APIs:
- AbortController
- AbortSignal
- CustomEvent
- DOMException
- Event
- EventTarget
Implementation extracted from the Node.js codebase as of 10th March 2024 (version 21.7.1, I believe). Some simplified internals extracted from readable-stream.
To clarify, this project is not affiliated with WinterCG (i.e. is not an official work). It merely implements part of the WinterCG Common Minimum API proposal.
Install this npm package as follows, depending on which package manager you're using.
- npm:
``sh`
npm install --save dom-events-wintercg
- Yarn:
`sh`
yarn add dom-events-wintercg
- pnpm:
`sh`
pnpm add dom-events-wintercg
- Bun:
`sh`
bun add dom-events-wintercg
- Deno: No need to install. Just add the npm: specifier when importing.
Run this polyfill in your app's entrypoint file so that it fills in the APIs as early as possible in the app lifecycle.
`js
import { polyfill } from 'dom-events-wintercg';
polyfill(globalThis);
// All implemented APIs will now be available in global scope
const eventTarget = new EventTarget();
const event = new Event('click', {});
eventTarget.addEventListener('click', (event) => {
console.log(Fired "${event.type}" event!, event);`
});
eventTarget.dispatchEvent(event, 'abc');
And for TypeScript typings, add the DOM lib in tsconfig.json:
`js`
{
"compilerOptions": {
"lib": ["DOM"],
// ...
}
}
Here, we import from the npm package each time we want to use an API, rather than polyfilling globally.
`js
import { Event, EventTarget } from 'dom-events-wintercg';
const eventTarget = new EventTarget();
const event = new Event('click', {});
eventTarget.addEventListener('click', (event) => {
console.log(Fired "${event.type}" event!, event);`
});
eventTarget.dispatchEvent(event, 'abc');
Some limited TypeScript typings will be inferred from the library's JavaScript source code, but if you'd rather use the lib.dom.d.ts typings built into TypeScript (which I would recommend), then:
1. Add the DOM lib in tsconfig.json:
`js`
{
"compilerOptions": {
"lib": ["DOM"],
// ...
}
}
2. Do this little dance:
`ts
import {
Event as EventImpl,
EventTarget as EventTargetImpl,
} from 'dom-events-wintercg';
// Redeclare the implementation using the types from lib.dom.d.ts
const Event = EventImpl as unknown as Event;
const EventTarget = EventTargetImpl as unknown as EventTarget;
const eventTarget = new EventTarget();
const event = new Event('click', {});
eventTarget.addEventListener('click', (event) => {
console.log(Fired "${event.type}" event!, event);`
});
eventTarget.dispatchEvent(event, 'abc');
This is my best-effort attempt to document usage with a bundler. These instructions are untested, so please open a PR if you find they need tweaking!
In all cases, you can set up TypeScript typings via adding the DOM lib to your tsconfig.json:
`js`
{
"compilerOptions": {
"lib": ["DOM"],
// ...
}
}
Below, I'll describe for each bundler how to integrate this package into your bundle.
#### Webpack 5
This configuration ensures that all the implemented APIs are available from global scope:
`js`
const webpackConfig = {
plugins: [
new webpack.ProvidePlugin({
AbortController: ['dom-events-wintercg', 'AbortController'],
AbortSignal: ['dom-events-wintercg', 'AbortSignal'],
CustomEvent: ['dom-events-wintercg', 'CustomEvent'],
DOMException: ['dom-events-wintercg', 'DOMException'],
Event: ['dom-events-wintercg', 'Event'],
EventTarget: ['dom-events-wintercg', 'EventTarget'],
}),
],
};
Additionally, you can polyfill _some of_ the Node.js events module (e.g. to use a Node.js library in a browser app) as follows. ⚠️ Be warned that while this package implements CustomEvent, Event, and EventTarget, it does not implement _all_ the APIs in the Node.js events module. For example, it does not implement EventEmitter.
`diff`
const webpackConfig = {
+ resolve: {
+ fallback: {
+ events: require.resolve('dom-events-wintercg'),
+ },
+ },
plugins: [
new webpack.ProvidePlugin({
AbortController: ['dom-events-wintercg', 'AbortController'],
AbortSignal: ['dom-events-wintercg', 'AbortSignal'],
CustomEvent: ['dom-events-wintercg', 'CustomEvent'],
DOMException: ['dom-events-wintercg', 'DOMException'],
Event: ['dom-events-wintercg', 'Event'],
EventTarget: ['dom-events-wintercg', 'EventTarget'],
}),
],
};
This polyfill relies on a few language features.
Your JS engine/runtime must support the following APIs (this is a non-exhaustive list):
- At least ES6. I'm not sure exactly what this repo makes use of, but technically the linter allows up to ES2022.
- Private properties
- FinalizationRegistry
- globalThis
- WeakMap
- WeakSet
- WeakRef
- Basic ESM (import and export)
Some of the features of this polyfill are optional, and will fail gracefully if your JS engine/runtime lacks support for the underlying APIs.
AbortSignal.timeout() support requires the following APIs:
If missing, AbortSignal.timeout() will throw an Error with code ERR_METHOD_NOT_IMPLEMENTED when called.
Beyond the differences explained in the Node.js SDK docs, see this excellent article from NearForm about how they first brought EventTarget to Node.js, which covers some of the compromises they had to make in the implementation. In particular, there is no concept of bubbling or capturing, and event.preventDefault()` is a bit useless, as it never has a "default action" to prevent.
This library, being runtime-agnostic, does nothing to keep the event loop alive for Worker event listeners. See the Node.js internals for how they implemented that.