Requisition HTTP Client

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `import requisition` in an ES module context.
  fix Change `import req from 'requisition';` to `const req = require('requisition');`.

• TypeError: (0 , requisition__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

  cause This error occurs in a bundler environment (like Webpack) when `requisition` (a CJS module) is imported as a default ESM import, and the bundler tries to resolve a non-existent default export.
  fix Ensure your bundler is configured to correctly handle CommonJS modules, or preferably, use `require('requisition')` if possible. Best to migrate to a modern, ESM-compatible HTTP client.

• Error: socket hang up

  cause The remote server closed the connection prematurely, often due to a server-side error, proxy issues, or the request taking too long without proper timeout handling.
  fix Increase the request timeout using `.timeout(ms)` or investigate server-side logs for the remote service. Check for network connectivity or proxy configuration issues. Ensure the server is not closing the connection due to malformed requests.

• Error: connect ECONNREFUSED

  cause The client could not establish a connection to the server, typically because the server is not running, is on a different port, or a firewall is blocking the connection.
  fix Verify that the target server is running and accessible at the specified URL and port. Check firewall settings on both client and server machines.

Warnings

• breaking The package is explicitly CommonJS (CJS) only, with its last update in June 2017. It does not support ES modules (ESM) natively, and attempting `import requisition` will result in `ERR_REQUIRE_ESM` errors in modern Node.js projects configured for ESM.
  Fix: Use CommonJS `const req = require('requisition');` or consider migrating to a modern HTTP client that supports ESM like `node-fetch` or `axios`.
• gotcha Requisition is an abandoned package, last updated almost seven years ago. This means it lacks support for modern Node.js features, HTTP/2 or HTTP/3, and may contain unpatched security vulnerabilities or rely on outdated internal dependencies.
  Fix: Avoid using in new projects. For existing projects, consider a migration plan to a actively maintained HTTP client to ensure security, performance, and compatibility with current Node.js ecosystems.
• gotcha Error handling with `async/await` in older Node.js versions (which this package targets) might be less robust for unhandled promise rejections compared to modern environments. Always wrap `await` calls in `try...catch` blocks.
  Fix: Explicitly use `try...catch` for all `await` expressions to gracefully handle network errors, timeouts, and HTTP response errors. Ensure you consume response bodies (e.g., `await res.json()`, `res.dump()`) even on error to prevent resource leaks.
• gotcha The `.cookie()` method for setting cookies uses `cookie.serialize()`, but the response's `.cookies` property provides parsed cookies. Manual handling of cookie string parsing/serializing might be needed for complex scenarios or specific server requirements.
  Fix: Thoroughly test cookie handling to ensure compatibility with your target server. For more advanced cookie management, consider external libraries or manual header manipulation if `.cookie()` doesn't meet needs.

Install

• npm install requisition npm
• yarn add requisition yarn
• pnpm add requisition pnpm

Imports

• req
  wrong:

  import req from 'requisition';

  correct:

  const req = require('requisition');

  Requisition is a CommonJS-only package. Attempting to use `import` syntax will result in an `ERR_REQUIRE_ESM` error in modern Node.js environments.
• request
  wrong:

  import { request } from 'requisition';

  correct:

  const request = require('requisition');

  The primary export is a function, often aliased as `request` or `req`, which initiates an HTTP request chain. Named imports are not supported.
• Request
  wrong:

  import { Request } from 'requisition';

  correct:

  const Request = require('requisition');
  // Request is the function itself, not a class or named export

  There is no `Request` class or named export. The README sometimes refers to the `request` function as 'Request' in its API documentation, which can be confusing. The default export is a function to create a new request.

Quickstart

This quickstart demonstrates how to make a GET request to fetch user data, parse a JSON response, handle different HTTP statuses, and conditionally save a related file to disk, all using `async/await` with `requisition`.

const req = require('requisition');

async function fetchAndSaveUser(userId) {
  try {
    console.log(`Fetching user ${userId}...`);
    const userResponse = await req(`/users/${userId}.json`);

    if (userResponse.status !== 200) {
      console.error(`Error fetching user ${userId}: Status ${userResponse.status}`);
      await userResponse.dump(); // Consume unhandled body to prevent memory leaks
      return;
    }

    const userData = await userResponse.json();
    console.log(`User ${userId} data:`, userData);

    // Example: Save an image if the user had one (hypothetical)
    if (userData.profileImage) {
      console.log(`Fetching profile image for user ${userId}...`);
      const imageResponse = await req(userData.profileImage);
      if (imageResponse.status === 200) {
        const savedPath = await imageResponse.saveTo(`/tmp/user_${userId}_profile.png`);
        console.log(`Profile image saved to: ${savedPath}`);
      } else {
        console.warn(`Could not fetch profile image for user ${userId}: Status ${imageResponse.status}`);
        await imageResponse.dump();
      }
    }

  } catch (error) {
    console.error('An error occurred during the request:', error.message);
  }
}

// To run this example, you'd need a simple local server
// For demonstration purposes, assume '/users/123.json' and '/users/123/image.png' exist

// Example usage (in an async IIFE or main function):
(async () => {
  await fetchAndSaveUser(123);
  await fetchAndSaveUser(456);
})();