Synchronous HTTP Request Utility

1.1.4 · abandoned · verified Wed Apr 22

This package provides a synchronous HTTP request utility for Node.js, built on top of `urllib` and utilizing Node.js's `spawnSync` module to achieve blocking I/O. The current stable version is 1.1.4, and it has not been updated in approximately nine years, indicating it is no longer maintained. Its primary function is to perform HTTP requests that halt the Node.js event loop until a response is received, a pattern generally considered an anti-pattern in asynchronous Node.js environments. Key differentiators include its explicit synchronous operation, contrasting with the typically non-blocking nature of Node.js. It explicitly states support only for Node.js v0.11.13+ and does not support features like response streams or custom HTTP agents, limiting its utility for modern applications requiring efficient handling of large data or complex network interactions.

Common errors

```
Error: The 'child_process.spawnSync' API is not available on this Node.js version.
```
cause urllib-sync relies on internal Node.js APIs (like `spawnSync` from `child_process`) that have changed or become incompatible in newer Node.js versions, breaking the package's functionality.

fix This package is incompatible with modern Node.js. Update your application to use asynchronous HTTP clients instead of `urllib-sync`.
```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require('urllib-sync')` in a Node.js environment configured for ECMAScript Modules (ESM) where CommonJS `require` is not directly available.

fix urllib-sync is a CommonJS package. Either refactor your project to use CommonJS modules or migrate your HTTP requests to a modern, ESM-compatible asynchronous library like `node-fetch` or native `fetch`.
```
TypeError: request is not a function (or similar, if trying to call the module directly)
```
cause The package exports an object with a `request` method, not the function directly. If you `require('urllib-sync')` and try to call the result, it will fail.

fix Ensure you are destructuring the `request` function correctly: `const { request } = require('urllib-sync');` or accessing it as a property: `const request = require('urllib-sync').request;`

Warnings

breaking This package explicitly supports only Node.js v0.11.13+. It is incompatible with all modern Node.js versions (v12+ onwards) due to significant changes in Node.js internals and API availability.
Fix: Do not use `urllib-sync` in modern Node.js applications. Prefer native `fetch` (Node.js v18+) or packages like `node-fetch`, `axios`, or the original `urllib` (which is asynchronous) for non-blocking HTTP requests.
gotcha Using synchronous HTTP requests in Node.js will block the entire event loop, making your application unresponsive. This is a severe performance anti-pattern and should be avoided in server-side or long-running applications.
Fix: Always use asynchronous HTTP request libraries (e.g., `fetch`, `axios`, `urllib`'s async methods) to maintain a non-blocking event loop. Refactor code to use `async/await` or Promises.
gotcha The package does not support streams or custom HTTP agents. This limits its use cases, especially for handling large responses efficiently or integrating with proxy/advanced networking setups.
Fix: For stream support or custom agents, you must use an asynchronous HTTP client like `urllib` (the non-sync version), `node-fetch`, or `axios`.
deprecated The package is effectively abandoned, with its last publish nearly a decade ago and no updates to support modern Node.js versions or fix potential vulnerabilities or bugs. Its underlying approach (synchronous HTTP) is generally deprecated in Node.js best practices.
Fix: Migrate to actively maintained asynchronous HTTP clients to ensure security, compatibility, and access to modern features and performance optimizations.

Install

npm install urllib-sync npm
yarn add urllib-sync yarn
pnpm add urllib-sync pnpm

Imports

request

wrong:

import { request } from 'urllib-sync';
// Error: require is not defined in ES module scope

correct:

const { request } = require('urllib-sync');

urllib-sync is a CommonJS module. Attempting to use ESM `import` will result in a runtime error.

request

wrong:

const urllibSync = require('urllib-sync');
urllibSync(); // TypeError: urllibSync is not a function

correct:

const request = require('urllib-sync').request;

The package exports an object with a `request` method, not the method directly as a default export.

Quickstart

This quickstart demonstrates how to make a basic synchronous GET request using `urllib-sync`. It fetches content from a URL and logs the status, headers, and a snippet of the response body. It highlights the blocking nature of the request and provides commented-out examples for POST requests and options.

const { request } = require('urllib-sync');

try {
  console.log('Making a synchronous HTTP request...');
  // This will block the Node.js event loop until the request completes.
  const res = request('https://www.google.com');
  
  console.log(`Status: ${res.status}`);
  console.log('Headers:');
  for (const key in res.headers) {
    console.log(`  ${key}: ${res.headers[key]}`);
  }
  // Note: res.data is a Buffer by default. Convert to string for display.
  console.log(`Body snippet: ${res.data.toString().substring(0, 100)}...`);

  // Example with options (e.g., method, data, timeout)
  // const postData = JSON.stringify({ key: 'value' });
  // const postRes = request('https://httpbin.org/post', {
  //   method: 'POST',
  //   data: postData,
  //   headers: { 'Content-Type': 'application/json' },
  //   timeout: 5000 // In milliseconds
  // });
  // console.log(`POST Status: ${postRes.status}, Body: ${postRes.data.toString()}`);

} catch (error) {
  console.error('Synchronous request failed:', error.message);
}

view raw JSON →