http-call

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/http-call/dist/index.js not supported.

  cause Attempting to use `require()` to load `http-call` in an environment where it's treated as an ES Module, typically in a CommonJS context.
  fix If your project is ES Module-based, use `import { HTTP } from 'http-call'`. If your project is CommonJS, ensure your bundler/TypeScript configuration is correctly set up to consume dual-package formats, or ensure you are on a Node.js version that properly handles CJS-importing-ESM interop (typically Node.js 12.20+ or 14.13+ with `--experimental-json-modules` flag, though general CJS `require` of ESM is still a hard error without dynamic `import()`). The most reliable fix is to migrate to ESM if possible or use dynamic imports.

• TypeError: HTTP.get is not a function

  cause This usually indicates incorrect destructuring of the import or attempting to call a method on an undefined or improperly imported object.
  fix Ensure you are correctly destructuring `HTTP` from the module: `import { HTTP } from 'http-call'` or `const { HTTP } = require('http-call')`. If it's still failing, check if another package named `http-call` is accidentally being imported or if the installation is corrupted.

• TS2345: Argument of type 'string' is not assignable to parameter of type 'number | undefined'.

  cause When using TypeScript, providing a non-numeric value to the `timeout` option (or other configuration options expecting specific types) will cause a type error.
  fix Ensure all options passed to `HTTP` methods or the configuration object conform to the expected TypeScript types. For `timeout`, provide a `number` representing milliseconds or `0` for no timeout: `await HTTP.get(url, { timeout: 5000 })`.

Warnings

• gotcha Starting with v5.4.0, `http-call` introduced a default timeout for requests. Previously, requests might have waited indefinitely. This change can affect applications that relied on long-running or unbounded HTTP requests, potentially causing unexpected timeouts.
  Fix: Review your application's network call expectations. If a longer or infinite timeout is required, explicitly set the `timeout` option in your request configuration: `HTTP.get('/slow-api', { timeout: 60000 })` for 60 seconds or `timeout: 0` for no timeout.
• gotcha While `http-call` supports both CommonJS (`require`) and ES Modules (`import`), mixing them incorrectly in a single project can lead to `ERR_REQUIRE_ESM` errors. Node.js's module resolution for interop can be complex.
  Fix: Standardize on a single module system across your application. For new projects, prefer ES Modules (set `"type": "module"` in `package.json`). If using CommonJS, ensure all imported packages are compatible or use dynamic `await import()` for ESM-only dependencies.
• gotcha The library primarily operates on `Promise`s. While this is standard for modern JavaScript, improperly handling asynchronous operations (e.g., forgetting `await` or `.catch()`) can lead to unhandled promise rejections or incorrect control flow, especially when integrating with older callback-based code.
  Fix: Always use `await` with `HTTP` calls within an `async` function, or chain `.then()` and `.catch()` appropriately to handle both successful responses and errors. Ensure all asynchronous code paths are robustly handled to prevent unexpected application crashes.

Install

• npm install http-call npm
• yarn add http-call yarn
• pnpm add http-call pnpm

Imports

• HTTP
  wrong:

  const { HTTP } = require('http-call')

  correct:

  import { HTTP } from 'http-call'

  Use ESM `import` for modern Node.js projects with `type: "module"` in `package.json` or `.mjs` files. The library provides dual CJS/ESM support.
• HTTP (CommonJS)
  wrong:

  import { HTTP } from 'http-call'

  correct:

  const { HTTP } = require('http-call')

  Use CommonJS `require` for older Node.js projects or environments without ESM support. Attempting to `require` an ESM module will result in `ERR_REQUIRE_ESM`.
• HTTP (TypeScript with generics)
  wrong:

  import { HTTP } from 'http-call';
  // Incorrect: Type not specified
  const { body: user } = await HTTP.get('/users/me')

  correct:

  import { HTTP } from 'http-call';
  
  interface User { id: string; email: string; name: string; }

  For TypeScript, leverage generics to strongly type the response body, enhancing type safety and developer experience. The library ships with built-in type declarations.

Quickstart

This quickstart demonstrates how to make a GET request to the GitHub API, handling authentication, automatic JSON parsing, and TypeScript type inference for the response body. It includes error handling and shows how to use environment variables for sensitive data.

import { HTTP } from 'http-call';

interface GitHubUser {
  login: string;
  id: number;
  node_id: string;
  avatar_url: string;
  name: string;
  email: string | null;
  bio: string | null;
}

async function getGitHubUser(username: string): Promise<GitHubUser> {
  try {
    const token = process.env.GITHUB_TOKEN ?? ''; // Use environment variable for auth
    if (!token) {
      console.warn('GITHUB_TOKEN environment variable is not set. Requests may be unauthenticated or rate-limited.');
    }

    const { body: user } = await HTTP.get<GitHubUser>(`https://api.github.com/users/${username}`, {
      headers: { authorization: token ? `token ${token}` : '' }
    });
    console.log(`Successfully fetched user ${user.name || user.login}. ID: ${user.id}, Bio: ${user.bio || 'N/A'}`);
    return user;
  } catch (error: any) {
    console.error(`Error fetching GitHub user ${username}:`, error.message);
    throw error;
  }
}

// Example usage:
(async () => {
  try {
    const myUser = await getGitHubUser('octocat');
    console.log('GitHub User Details:', myUser);
  } catch (e) {
    // Error handled in getGitHubUser
  }
  try {
    // Example with a non-existent user to demonstrate error handling
    await getGitHubUser('nonexistentuser12345');
  } catch (e) {
    // Expected error, already logged
  }
})();