agent-phin Node.js HTTP Client

Common errors

• TypeError: await is only valid in async function

  cause Attempting to use `await` with `agent-phin`'s Promise-based API outside of an `async` function.
  fix Declare the function containing `await` as `async function` or handle the returned Promise using `.then()` and `.catch()`.

• ReferenceError: p is not defined

  cause The `agent-phin` module was not correctly imported (e.g., `const p = require('agent-phin')` was omitted or misspelled).
  fix Ensure you have `const p = require('agent-phin');` at the beginning of your script.

• Error: connect ECONNREFUSED 127.0.0.1:8008

  cause The HTTP/HTTPS proxy server specified in the `agent` option (e.g., `http://localhost:8008`) is not running or is unreachable.
  fix Verify that your proxy server is running and accessible at the specified address and port. Check network connectivity, firewall rules, or proxy configuration.

Warnings

• gotcha All Promise-based API calls (the default behavior) must be used within an `async` function or handled with `.then()`/`.catch()` to properly await the response. Failure to do so will result in unhandled promises or incorrect execution flow.
  Fix: Wrap `await p(...)` calls in an `async` function or chain `.then()` and `.catch()` to the Promise returned by `p()`.
• gotcha `agent-phin` is a fork of the original `phin` library, specifically adding HTTP agent support. While it aims for compatibility, developers should be aware of its distinct origin and potential divergences from `phin`'s development path, especially concerning features beyond agent support. Always check the `agent-phin` repository for specific updates.
  Fix: Review the `agent-phin` GitHub repository for specific updates and compatibility notes if migrating from or considering the original `phin`.
• gotcha When using custom `http.Agent` or `https.Agent` instances, especially for KeepAlive, it's crucial to explicitly call `agent.destroy()` when the agent is no longer needed to prevent resource leaks (e.g., open sockets). `agent-phin` itself does not manage agent lifecycle.
  Fix: Ensure `agent.destroy()` is called on your custom agent instance, typically in a `finally` block or when your application is shutting down, to properly close persistent connections.
• gotcha The default import style shown in documentation is CommonJS `require()`. While Node.js supports ESM, directly `import`ing `agent-phin` might require specific setup (e.g., `type: "module"` in `package.json` or bundler configuration) and could lead to `ERR_REQUIRE_ESM` if not handled correctly.
  Fix: For Node.js projects, use `const p = require('agent-phin');`. If you must use ESM `import`, ensure your project is configured for ESM, or consider an intermediary CommonJS wrapper.

Install

• npm install agent-phin npm
• yarn add agent-phin yarn
• pnpm add agent-phin pnpm

Imports

• phin
  wrong:

  import p from 'agent-phin'

  correct:

  const p = require('agent-phin')

  This library primarily exposes a CommonJS module. Use `require` for synchronous import. While ESM compatibility might exist via bundlers, native Node.js ESM `import` is not directly supported without specific configuration or an `esm` wrapper.
• unpromisified
  wrong:

  import { unpromisified } from 'agent-phin'

  correct:

  const p = require('agent-phin').unpromisified

  The `unpromisified` method is a named export from the CommonJS module, providing a callback-based API. It must be accessed as a property of the main `phin` export.
• defaults
  wrong:

  import { defaults } from 'agent-phin'

  correct:

  const ppostjson = require('agent-phin').defaults(...)

  The `defaults` method is a named export for creating pre-configured instances of the `phin` client. Access it as a property of the main `phin` export.

Quickstart

Demonstrates how to make a POST request using `agent-phin` with a `https.Agent` configured for KeepAlive, showcasing its primary differentiating feature for efficient connection management.

const p = require('agent-phin');
const https = require('https');

async function makeRequestWithAgent() {
  // Create a KeepAlive agent to reuse TCP connections
  const keepAliveAgent = new https.Agent({ keepAlive: true });

  try {
    const res = await p({
      url: 'https://httpbin.org/post',
      method: 'POST',
      data: {
        message: 'Hello from agent-phin with KeepAlive!'
      },
      agent: keepAliveAgent, // Pass the custom agent here
      parse: 'json' // Automatically parse the response body as JSON
    });

    console.log('Response status:', res.statusCode);
    console.log('Response body:', res.body);
  } catch (error) {
    console.error('Request failed:', error);
  } finally {
    // It's crucial to destroy the agent when it's no longer needed to prevent resource leaks.
    keepAliveAgent.destroy();
  }
}

makeRequestWithAgent();