Mirrors NativeScript/ios#452 — the follow-up to #2026 promised there ("a follow-up PR will introduce DOMException and upgrade these plus AbortSignal's reasons"): DOMException and CustomEvent, both behind the lazy-global tier.

DOMException

New lazy builtin dom-exception.js (Web IDL §4.3), byte-identical with the iOS copy:

• Class grafted onto Error.prototype — instanceof Error holds and Error.prototype.toString renders name: message — with name/message/code as branded, enumerable prototype accessors (private fields double as the Web IDL brand check), the full legacy code table, the 25 constants on interface object and prototype, @@toStringTag, and stack capture.
• Placed by LazyGlobals on first read; until then nothing runs or allocates.

Internal require tier

Sibling builtins construct DOMExceptions lazily via a new internal-only specifier tier: kRegistry rows flagged internalOnly resolve through the require builtins receive and nowhere else — the module system refuses them (GetModule guard for ES imports; the CommonJS path was already prefix-gated by IsBuiltinScheme), and a canary test pins that app code cannot name them. This is the Node internal-module idiom the js README had planned.

All five existing stand-in throw sites now produce real DOMExceptions, with the builtin required at first throw so a clean path never runs it:

• abort-signal.js — default abort ("AbortError") and timeout ("TimeoutError") reasons
• performance.js — SyntaxError / InvalidModificationError failures
• structured-clone.js — transfer-list DataCloneError
• base64.js — atob/btoa InvalidCharacterError
• StructuredSerialization.cpp — the native serializer's DataCloneError, built through the same exports cache (the name-patched-Error shape kept as a teardown fallback)

internals parameter removed

With the tier in place, the interim internals object (introduced with AbortSignal in #2025) had exactly two users left, and both moved into events.js's exports behind internal/events (kListenerChanged for abort-signal's GC accounting, setListenerErrorReporter for error-events). The builtin wrapper is back to Node's five parameters (exports, require, module, binding, primordials), and a consumer resolves the capability explicitly at the require — a cache hit for consumers of eager producers, an on-demand run otherwise — so it can never observe a missing key the way the shared object allowed.

CustomEvent

Defined in events.js next to the Event it extends (same ES5 idiom), exported rather than installed: Events::Init now runs the file through BuiltinLoader::GetExports and reads the backing EventTarget from the exports bag, so the lazy CustomEvent row is a cache hit — only the placement is deferred.

Not implemented

The spec's [Serializable] slot for DOMException: structuredClone/worker postMessage go through v8::ValueSerializer, which has no hook for a plain JS class, so a DOMException inside a cloned graph degrades like any custom Error subclass.

Tests

• Shared suites (NativeScript/common-runtime-tests-app@9cc46c0, submodule bumped, wired into mainpage.js): self-gating DOMException and CustomEvent suites that skip with a visible pending spec where the APIs are absent, plus integration specs — gated per collaborating API — asserting AbortSignal reasons, atob failures and structuredClone failures are real DOMExceptions.
• Unguarded canaries in testRuntimeImplementedAPIs.js so this runtime regressing the globals fails instead of skipping, plus the app-code-cannot-require-internal pin.
• Full suite (runtestsAndVerifyResults, arm64 API 33): 1203 specs, 0 failures.

Summary by CodeRabbit

• New Features

  • Added standards-compatible DOMException support, including legacy properties and error codes.
  • Added CustomEvent support with read-only event details.
  • Improved abort, encoding, performance, and structured-cloning errors to use appropriate DOMException types.

• Documentation

  • Updated runtime documentation to describe DOMException behavior and structured-cloning errors.

• Tests

  • Added coverage verifying DOMException and CustomEvent availability, inheritance, and error behavior.