{"id":17145,"library":"agent-phin","title":"agent-phin Node.js HTTP Client","description":"agent-phin is an ultra-lightweight Node.js HTTP client, forked from the popular phin library, specifically designed to add robust HTTP agent support. It is currently at version 1.0.4 and appears to maintain a release cadence tied to the introduction of specific features, such as the agent support in v1.0.1. Its primary differentiator is its minimal footprint, being significantly smaller than many common HTTP clients like request, axios, or node-fetch, while still providing essential features like POST requests, JSON parsing, and configurable timeouts. The key addition over the original phin is the native capability to utilize custom `http.Agent` or `https.Agent` instances, enabling features like connection pooling (KeepAlive) or proxy integration via libraries like `https-proxy-agent`. It supports both Promise-based and unpromisified (callback-style) API calls, catering to different asynchronous programming preferences in Node.js environments.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/pxjohnny/agent-phin","tags":["javascript","http","https","request","fetch","ajax","url","uri"],"install":[{"cmd":"npm install agent-phin","lang":"bash","label":"npm"},{"cmd":"yarn add agent-phin","lang":"bash","label":"yarn"},{"cmd":"pnpm add agent-phin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for integrating with HTTP/HTTPS proxy servers via a custom agent.","package":"https-proxy-agent","optional":true}],"imports":[{"note":"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.","wrong":"import p from 'agent-phin'","symbol":"phin","correct":"const p = require('agent-phin')"},{"note":"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.","wrong":"import { unpromisified } from 'agent-phin'","symbol":"unpromisified","correct":"const p = require('agent-phin').unpromisified"},{"note":"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.","wrong":"import { defaults } from 'agent-phin'","symbol":"defaults","correct":"const ppostjson = require('agent-phin').defaults(...)"}],"quickstart":{"code":"const p = require('agent-phin');\nconst https = require('https');\n\nasync function makeRequestWithAgent() {\n  // Create a KeepAlive agent to reuse TCP connections\n  const keepAliveAgent = new https.Agent({ keepAlive: true });\n\n  try {\n    const res = await p({\n      url: 'https://httpbin.org/post',\n      method: 'POST',\n      data: {\n        message: 'Hello from agent-phin with KeepAlive!'\n      },\n      agent: keepAliveAgent, // Pass the custom agent here\n      parse: 'json' // Automatically parse the response body as JSON\n    });\n\n    console.log('Response status:', res.statusCode);\n    console.log('Response body:', res.body);\n  } catch (error) {\n    console.error('Request failed:', error);\n  } finally {\n    // It's crucial to destroy the agent when it's no longer needed to prevent resource leaks.\n    keepAliveAgent.destroy();\n  }\n}\n\nmakeRequestWithAgent();","lang":"javascript","description":"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."},"warnings":[{"fix":"Wrap `await p(...)` calls in an `async` function or chain `.then()` and `.catch()` to the Promise returned by `p()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the `agent-phin` GitHub repository for specific updates and compatibility notes if migrating from or considering the original `phin`.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Declare the function containing `await` as `async function` or handle the returned Promise using `.then()` and `.catch()`.","cause":"Attempting to use `await` with `agent-phin`'s Promise-based API outside of an `async` function.","error":"TypeError: await is only valid in async function"},{"fix":"Ensure you have `const p = require('agent-phin');` at the beginning of your script.","cause":"The `agent-phin` module was not correctly imported (e.g., `const p = require('agent-phin')` was omitted or misspelled).","error":"ReferenceError: p is not defined"},{"fix":"Verify that your proxy server is running and accessible at the specified address and port. Check network connectivity, firewall rules, or proxy configuration.","cause":"The HTTP/HTTPS proxy server specified in the `agent` option (e.g., `http://localhost:8008`) is not running or is unreachable.","error":"Error: connect ECONNREFUSED 127.0.0.1:8008"}],"ecosystem":"npm","meta_description":null}