Registry / http-networking / agent-phin

agent-phin

JSON →
library1.0.4jsnpmunverified

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.

http-networking
npm install agent-phin
github ↗package ↗
INSTALL
IMPORT
SIG · AGENT-PHIN
A
agent-phin
http-networkingjavascriptv1.0.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

phin
✓ const p = require('agent-phin')
✗ import p from '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
✓ const p = require('agent-phin').unpromisified
✗ import { unpromisified } from 'agent-phin'
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
✓ const ppostjson = require('agent-phin').defaults(...)
✗ import { defaults } from 'agent-phin'
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.

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();
Debug
Known issues
gotchaAll 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()`.
affects: >=1.0.0
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`.
affects: >=1.0.0
gotchaWhen 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.
affects: >=1.0.1
gotchaThe 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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: await is only valid in async function
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
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
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.
Upgrade
Version history
1.0.4latest on npm
Audit
Dependencies
https-proxy-agentoptionalUsed for integrating with HTTP/HTTPS proxy servers via a custom agent.
Agent activity
42 hits · last 30 days
node
36
OpenAI (training)
1
Resources
githubhttps://github.com/pxjohnny/agent-phin ↗
packagehttps://www.npmjs.com/package/agent-phin ↗