unxhr: XMLHttpRequest Emulation for Node.js

Common errors

• ReferenceError: XMLHttpRequest is not defined

  cause The `XMLHttpRequest` class was not correctly imported or referenced before use.
  fix Ensure you are using `const XMLHttpRequest = require('unxhr').XMLHttpRequest;` and that `XMLHttpRequest` is in scope where you are attempting to instantiate it.

• Error: stdout maxBuffer exceeded. Did you mean to enable the sync option? Running an async process and expecting stdout to be captured. Consider increasing the maxBuffer option.

  cause The HTTP response body exceeded the maximum buffer size allocated for the internal child process communication. This typically happens with large responses in older versions or if `UNXHR_MAX_BUFFER` is set too low.
  fix For `unxhr` v1.2.0 and above, the default `maxBuffer` is 100MB. If you encounter this, increase the buffer size by setting the `UNXHR_MAX_BUFFER` environment variable (e.g., `UNXHR_MAX_BUFFER=200000000` for 200MB).

• Error: Network error or connection refused.

  cause The `onerror` callback was triggered, indicating a network-level issue such as no internet connection, an unreachable host, or a blocked port.
  fix Verify network connectivity, check the target URL/host for correctness, and ensure no firewalls or proxies are blocking the request. Inspect the `onerror` event for more specific details if available.

Warnings

• breaking Synchronous requests using `unxhr` will block the entire Node.js event loop until a response is received. This behavior is inherent to synchronous XHR and can lead to unresponsive applications and performance issues.
  Fix: Prioritize asynchronous requests whenever possible. If synchronous behavior is strictly required, ensure it's used in non-critical paths or dedicated worker threads to minimize impact on the main event loop.
• gotcha Synchronous requests in `unxhr` are known to have issues with properly setting and handling HTTP headers, potentially leading to incorrect request behavior or unexpected server responses.
  Fix: Always use asynchronous requests for scenarios requiring reliable HTTP header manipulation. If synchronous is unavoidable, thoroughly test header transmission.
• gotcha Accessing local files via the `file://` protocol may produce unexpected results or errors, especially when dealing with files that are not encoded in UTF-8. There are known limitations in handling these scenarios.
  Fix: For local file access, prefer Node.js's native `fs` module for reliable and robust file system interactions. Avoid `unxhr` for `file://` protocol access if file encoding or integrity is critical.
• gotcha The `unxhr` implementation is an emulation and does not provide a complete feature set identical to a browser's native `XMLHttpRequest`. Key missing features include certain events (e.g., `abort`), persistence of cookies between requests, and robust XML parsing support.
  Fix: Review the 'Known Issues / Missing Features' section in the package README. For advanced XHR features or a more complete HTTP client, consider using Node.js-native libraries like `node-fetch` or `axios`.

Install

• npm install unxhr npm
• yarn add unxhr yarn
• pnpm add unxhr pnpm

Imports

• XMLHttpRequest
  wrong:

  import { XMLHttpRequest } from 'unxhr';

  correct:

  const XMLHttpRequest = require('unxhr').XMLHttpRequest;

  The primary export is the `XMLHttpRequest` class, typically accessed as a property of the main CommonJS module export. While Node.js supports ESM, `unxhr` is primarily designed for and used with CommonJS `require` syntax.
• XHR instance
  wrong:

  const xhr = unxhr.XMLHttpRequest();

  correct:

  const xhr = new XMLHttpRequest();

  The `XMLHttpRequest` symbol is a constructor and must be instantiated with the `new` keyword, similar to browser-based usage.

Quickstart

Demonstrates basic asynchronous HTTP GET request using `unxhr`'s `XMLHttpRequest` emulation, including event handling for response and errors, wrapped in a Promise.

const XMLHttpRequest = require('unxhr').XMLHttpRequest;

async function makeRequest() {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open('GET', 'https://jsonplaceholder.typicode.com/posts/1', true); // true for async

    xhr.onreadystatechange = () => {
      if (xhr.readyState === 4) {
        if (xhr.status >= 200 && xhr.status < 300) {
          try {
            resolve(JSON.parse(xhr.responseText));
          } catch (e) {
            reject(new Error('Failed to parse JSON response: ' + e.message));
          }
        } else {
          reject(new Error(`Request failed with status ${xhr.status}: ${xhr.statusText}`));
        }
      }
    };

    xhr.onerror = () => {
      reject(new Error('Network error or connection refused.'));
    };

    xhr.send();
  });
}

makeRequest()
  .then(data => console.log('Fetched data:', data))
  .catch(error => console.error('Error during request:', error));

// Example of a synchronous request (use with extreme caution due to blocking nature)
// console.log('\nStarting synchronous request (will block event loop)...');
// const syncXhr = new XMLHttpRequest();
// try {
//   syncXhr.open('GET', 'https://jsonplaceholder.typicode.com/todos/1', false); // false for sync
//   syncXhr.send(null);
//   if (syncXhr.status === 200) {
//     console.log('Synchronous Response:', JSON.parse(syncXhr.responseText));
//   } else {
//     console.error('Synchronous Error:', syncXhr.status, syncXhr.statusText);
//   }
// } catch (e) {
//   console.error('Synchronous Request Failed:', e);
// }
// console.log('Synchronous request finished.');