node-domexception

node-domexception is a lightweight polyfill that exposes the native DOMException class built into NodeJS, making it available via globalThis without needing to reach into worker_threads or another internal module. It works by intentionally triggering a DOMException through a native atob() call and capturing the resulting error’s constructor, giving consumers the exact same DOMException implementation NodeJS itself uses internally rather than a reimplementation.

The package is widely used as a compatibility shim inside libraries that need to throw spec-compliant DOMException errors (for example, implementations of the Fetch API, Blob, and postMessage-style APIs) while still supporting older NodeJS versions. As of NodeJS 18, DOMException is globally available by default, and the maintainer has marked the package deprecated for users already on Node 18+, recommending they rely on the platform global instead.

What You Get

• Native DOMException access - Captures NodeJS’s real DOMException constructor via a triggered atob() error rather than reimplementing the class from scratch.
• Zero dependencies - A single ~200-byte index.js file with no runtime dependencies to install or audit.
• Legacy error-code support - Includes all of DOMException’s legacy numeric codes (e.g. INUSE_ATTRIBUTE_ERR) for compatibility with older web-platform error-handling code.
• Cross-version compatibility - A v1.x line (using node:worker_threads) supports Node 10.5+, while the current v2.x line supports Node 16+ via global atob.

Common Use Cases

• Polyfilling fetch/Blob/File implementations - Libraries implementing spec-compliant Fetch/Blob/File behavior throw a real DOMException for correct error handling on older Node versions.
• postMessage/structured-clone error handling - Code that needs to check for DataCloneError-style DOMExceptions when working with MessageChannel or similar APIs.
• Cross-platform packages targeting Node <18 - Any package needing the same DOMException behavior in Node as in browsers, without bundling a full reimplementation.
• Conditional polyfilling - Projects that check globalThis.DOMException and only import this package when the native global isn’t already present.

Under The Hood

Architecture The entire package is a single four-line index.js executed for its side effect: it checks whether globalThis.DOMException already exists and, if not, deliberately calls atob(0) with an invalid argument to trigger NodeJS’s own DOMException, then captures err.constructor and assigns it to globalThis.DOMException. There are no layers, modules, or abstractions to speak of — the design intentionally trades architectural sophistication for correctness, since the whole point is to obtain NodeJS’s real internal DOMException class rather than construct a look-alike.

Tech Stack The package has zero runtime dependencies and no build step: package.json declares only an engines.node constraint (>=16 for the current v2.x line, since it depends on globalThis.atob) and points main directly at the unbundled index.js. There is no bundler, transpiler, or type-definitions file, and the repository ships no test runner or CI workflow configuration.

Code Quality No test files exist anywhere in the repository, and there is no linter, formatter, or CI workflow configured beyond a GitHub Sponsors funding file. The single source file is short enough that correctness is easy to verify by reading, but there is no automated verification of the atob-based capture technique across NodeJS versions.

API Design The developer experience is deliberately minimal: consuming code writes a single side-effecting import (import ‘node-domexception’) and gets a global DOMException that behaves identically to the browser and newer-NodeJS version, with no functions, classes, or configuration exposed. This zero-API-surface design is well suited to a stopgap polyfill, though it does mean consumers can’t opt into a namespaced import instead of mutating the global scope.