Node 22 Compatibility Design

Goal: Fix fake XHR compatibility for supported Node runtimes (>= 22) by separating Blob, FileReader, and FormData capability checks instead of treating them as one feature set.

Context

PR #218 attempted to address Node 18+/20 compatibility, but it mixed the actual fix with support-policy changes and dependency churn. The supported runtime baseline for this work is Node >= 22, so the design can align with modern Node behavior and CI without preserving Node 16 behavior.

Problem

The current fake XHR implementation in lib/fake-xhr/index.js relies on coarse feature detection:

  • supportsFormData is based on a single global check.
  • supportsBlob is based on constructing a Blob.
  • Tests in lib/fake-xhr/index.test.js read blobs with FileReader, even though current Node exposes Blob without exposing FileReader.

That means blob response behavior and blob tests are coupled to APIs that do not actually need to exist together.

Chosen Approach

Use the minimal compatibility patch:

  • keep production behavior dependency-free unless reproduction proves otherwise;
  • split capability checks by actual API usage;
  • update tests to match supported Node behavior;
  • update CI to supported Node versions only.

This avoids a FormData polyfill unless it is strictly required and avoids repeating the abandoned PR's runtime-policy and lockfile noise.

Architecture

In production code:

  • Blob response support should be gated by Blob support only.
  • FormData header handling should be gated by FormData support only.
  • FileReader should not be part of production blob support unless code directly instantiates it.

In tests:

  • blob-response assertions should use an API available in supported runtimes, preferably Blob.text();
  • any FileReader-specific assertions should be isolated behind a FileReader guard;
  • tests should explicitly cover the supported Node runtime assumptions.

In CI:

  • the workflow should test supported Node versions only, using Node 22+ entries in the test matrix.

Files Expected To Change

  • .github/workflows/main.yml
  • lib/fake-xhr/index.js
  • lib/fake-xhr/blob.js or a replacement helper if the existing helper becomes too narrow
  • lib/fake-xhr/index.test.js
  • package.json only if test/runtime policy updates require it

Validation

  • run targeted mocha tests around fake XHR send/body handling and blob responses;
  • run the full npm test suite on supported Node;
  • confirm CI config reflects Node >= 22.

Out of Scope

  • preserving compatibility with Node 16 or 18;
  • adding broad polyfills by default;
  • unrelated dependency updates or lockfile churn.