Registry / http-networking / unxhr

unxhr

JSON →
library1.2.0jsnpmunverified

`unxhr` is a Node.js library that provides an emulation of the browser's native `XMLHttpRequest` object, enabling both synchronous and asynchronous HTTP requests within Node.js environments. Currently at version 1.2.0, its release cadence is moderate, with recent updates primarily focused on bug fixes and infrastructure improvements. The project is a fork of the original `XMLHttpRequest` package, specifically developed to achieve compliance with the XMLHttpRequest Level 2 specifications. Key differentiators include its complete lack of external dependencies, support for standard HTTP methods (GET, POST, PUT, DELETE), handling of binary data through JavaScript typed arrays, automatic redirection following, and limited support for the `file://` protocol. It serves as a bridge for codebases that expect browser-like XHR behavior in a Node.js context, despite some inherent limitations compared to a full browser implementation.

http-networking
npm install unxhr
github ↗package ↗
INSTALL
IMPORT
SIG · UNXHR
U
unxhr
http-networkingjavascriptv1.2.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

XMLHttpRequest
✓ const XMLHttpRequest = require('unxhr').XMLHttpRequest;
✗ import { XMLHttpRequest } from 'unxhr';
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
✓ const xhr = new XMLHttpRequest();
✗ const xhr = unxhr.XMLHttpRequest();
The `XMLHttpRequest` symbol is a constructor and must be instantiated with the `new` keyword, similar to browser-based usage.

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.');
Debug
Known issues
breakingSynchronous 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.
affects: >=1.0.0
gotchaSynchronous 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.
affects: >=1.0.0
gotchaAccessing 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.
affects: >=1.0.0
gotchaThe `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`.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: XMLHttpRequest is not defined
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.
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.
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.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
githubhttps://github.com/mogztter/unxhr ↗
packagehttps://www.npmjs.com/package/unxhr ↗
unxhr — npm install unxhr · libregistry