phn

A lightweight http client adapted from phin and centra.

It works great with node and bun and comes with optional support for zstd compression via fzstd.

install

npm i phn

optional: zstd

phn supports zstd compression if fzstd is installed (not included)

npm i phn fzstd

usage

const phn = require("phn");

const res = await phn({
	url: 'https://example.org'
});

options

• url - URL to request
• method - HTTP method, default: GET
• headers - HTTP headers object
• query - Object to be added to url as query string
• data - Request body; json, buffer or object containing form data
• form - object containing form data
• core - options passed on to http(s).request
• parse - parse response body as json or string
• followRedirects - follow redirects if true
• maxRedirects - maximum number of redirects to follow, default: infinite
• stream - return stream as res.stream instead of res.body
• compression - handle compression, accept br, gzip and deflate, also zstd if fzstd package is installed. string overrides accept-encoding header
• timeout - request timeout in milliseconds
• maxBuffer - maximum response buffer size

stream

consume http response as stream

const phn = require("phn");

const stream = await phn({
	url: 'https://example.org/',
	compression: true,
	stream: true,
});

stream.pipe(/* ... */)

custom http(s) options

use a custom agent

const phn = require("phn");
const https = require("https");

const agent = new https.Agent({ keepAlive: true });

await phn({
	url: 'https://example.org/',
	core: { agent },
});

unpromisified

get a classic callback interface

const phn = require("phn").unpromisified;

phn('https://example.org/', (err, res) => {
	if (!err) console.log(res.body);
});

defaults

set options for any subsequent request

const phn = require("phn").defaults({
	method: 'POST',
	parse: 'json',
	timeout: 2000
});

const res = await phn('https://example.org/')

comparison

phn is tiny and comes with no required dependencies.

Package | Size --- | --- phn | slim-fetch | phin | r2 | isomorphic-fetch | needle | undici | got | superagent | axios | request | node-fetch |

license

MIT

acknowledgement

phn is a fork of phin and centra by Ethan Davis.