HTTP/HTTPS Agent Resolver

Common errors

• TypeError: getAgent is not a function

  cause Attempting to call the module's default export directly before it has been initialized with options, or incorrectly assuming `require()` directly returns the agent.
  fix The module exports a factory function. First, call the factory with options (e.g., `{ keepAlive: true }`), then use the returned function to get an agent. Correct: `const getAgent = httpHttpsAgent({ keepAlive: true }); const agent = getAgent('https://example.com');`

• ERR_MODULE_NOT_FOUND or Cannot find module 'http-https-agent'

  cause The package is not installed or the import path is incorrect, or a module resolution issue in a mixed ESM/CJS project.
  fix Ensure the package is installed: `npm install http-https-agent`. Verify the import statement: `import httpHttpsAgent from "http-https-agent";` for ESM or `const httpHttpsAgent = require("http-https-agent");` for CommonJS.

• TypeError: Parameter 'url' must be a string.

  cause Providing a non-string or malformed URL to the agent retrieval function.
  fix Ensure the argument passed to the agent retrieval function is a valid URL string, including the protocol (e.g., `'https://example.com'`).

Warnings

• gotcha The package has not been updated in several years (last version 1.0.2). While its core functionality is based on stable Node.js APIs (http.Agent, https.Agent), it might not leverage recent performance improvements, security patches, or new features in Node.js core or related ecosystem libraries.
  Fix: Review the simplicity of the logic and consider implementing a custom solution or a more actively maintained alternative if advanced features or the latest Node.js compatibility are critical.
• gotcha The library does not provide TypeScript declaration files. Users working in TypeScript projects will need to provide their own type definitions (e.g., in a 'd.ts' file) to avoid compilation errors and benefit from type checking.
  Fix: Create a declaration file (e.g., 'http-https-agent.d.ts') with `declare module "http-https-agent" { function httpHttpsAgent(options?: any): (url: string) => import('http').Agent | import('https').Agent; export default httpHttpsAgent; }` or use `@ts-ignore` for quick fixes.
• gotcha The package includes `lodash.startswith` as a dependency. In modern Node.js environments (Node.js 6+), `String.prototype.startsWith` is natively available, making the Lodash dependency potentially unnecessary and adding minor overhead to the bundle size if tree-shaking isn't fully effective.
  Fix: This is an internal dependency of the package; no direct fix is available to the user other than considering alternative libraries if bundle size is a critical concern, or forking the library to remove the dependency.

Install

• npm install http-https-agent npm
• yarn add http-https-agent yarn
• pnpm add http-https-agent pnpm

Imports

• httpHttpsAgent
  wrong:

  const httpHttpsAgent = require('http-https-agent');

  correct:

  import httpHttpsAgent from 'http-https-agent';

  The package uses a default export. For CommonJS, `require('http-https-agent')` directly returns the agent factory function. The 'wrong' entry is included because developers sometimes incorrectly assume named exports or try `require().default` in mixed environments.

Quickstart

Demonstrates how to initialize the agent factory with options and then use the returned function to dynamically obtain an HTTP or HTTPS agent based on the provided URL, confirming their types.

import httpHttpsAgent from 'http-https-agent';
import https from 'https';
import http from 'http';

// Create an agent factory with global options, e.g., keepAlive
const getAgent = httpHttpsAgent({
  keepAlive: true,
  maxSockets: 10,
  timeout: 60000 // 60 seconds
});

// Get an HTTPS agent for an HTTPS URL
const httpsUrl = 'https://jsonplaceholder.typicode.com/posts/1';
const myHttpsAgent = getAgent(httpsUrl);
console.log(`HTTPS Agent created for ${httpsUrl}:`, myHttpsAgent instanceof https.Agent); // Should be true

// Get an HTTP agent for an HTTP URL
const httpUrl = 'http://example.com'; // Note: Many public APIs enforce HTTPS
const myHttpAgent = getAgent(httpUrl);
console.log(`HTTP Agent created for ${httpUrl}:`, myHttpAgent instanceof http.Agent); // Should be true

// Example of using the agent in a request (simplified for demonstration)
https.get({ hostname: 'jsonplaceholder.typicode.com', path: '/posts/1', agent: myHttpsAgent }, (res) => {
  console.log('HTTPS Request status:', res.statusCode);
  res.resume();
}).on('error', (e) => {
  console.error('HTTPS Request error:', e.message);
});