Transparent HTTP/2 and HTTP/1.1 Client for Node.js

Common errors

• TypeError: Cannot destructure property 'request' of 'require(...)' as it is undefined.

  cause This error typically indicates that `http2-client` was installed or imported incorrectly, or that the Node.js environment has issues resolving the module.
  fix First, ensure `npm install http2-client` was successful. If using a bundler, verify CommonJS modules are correctly handled. If running in an ES module context, consider if `require()` is appropriate or if a different library designed for ESM is needed.

• Error: Protocol "https:" not supported. Expected "http:"

  cause While `http2-client` supports HTTPS, this error might occur if an incorrect `protocol` option is explicitly set in the request options, overriding the automatic detection, or if an older Node.js version with limited HTTPS/ALPN capabilities is used.
  fix Remove explicit `protocol` options if you want the library to automatically handle protocol detection based on the URL. Ensure your Node.js version supports ALPN for HTTPS/2 negotiation (typically Node.js 8.8.1+).

Warnings

• gotcha The package is primarily designed for CommonJS environments. While Node.js itself supports ESM, `http2-client`'s documentation and examples exclusively use `require()`. Attempting direct ES module `import` syntax may lead to runtime errors or require bundler configuration.
  Fix: Ensure your project is configured for CommonJS, or use dynamic `import()` if absolutely necessary within an ESM context, though this is not officially supported by the library.
• gotcha The README states 'All Http2 features are available except push.' Server push is a core HTTP/2 feature that this client explicitly does not support. Applications relying on HTTP/2 server push will need an alternative solution.
  Fix: If HTTP/2 server push is a requirement, consider using Node.js's native `http2` module directly or a different HTTP client library that offers full HTTP/2 feature parity.
• gotcha The description claims 'it's the only http2/https compatible API for clients.' This claim is likely outdated given the evolution of Node.js's native HTTP/2 support, the introduction of `fetch` in Node.js, and other modern HTTP client libraries. Relying on this package as the *only* option might miss more current and actively maintained alternatives.
  Fix: Evaluate modern alternatives like `undici` or Node.js's built-in `fetch` API, which offer robust HTTP/2 support, especially for newer projects, if active development and broader feature sets are crucial.
• gotcha The library automatically falls back to HTTP/1.1 if the Node.js version doesn't support HTTP/2. While convenient, this might mask underlying environment issues or unexpected performance characteristics if HTTP/2 was expected but not achieved.
  Fix: Ensure your Node.js version (typically >=8.8.1 for `http2` module availability) supports HTTP/2 if you intend to use it. Monitor `res.httpVersion` in your callbacks to confirm the protocol used.

Install

• npm install http2-client npm
• yarn add http2-client yarn
• pnpm add http2-client pnpm

Imports

• request
  wrong:

  import { request } from 'http2-client';

  correct:

  const { request } = require('http2-client');

  The library primarily uses CommonJS syntax. Direct ES module imports are not officially supported or documented, potentially leading to errors.
• get
  wrong:

  import get from 'http2-client';

  correct:

  const { get } = require('http2-client');

  Similar to `request`, `get` is a named export. Attempting a default import or ESM named import will fail.
• HttpRequestManager
  wrong:

  new http2Client.HttpRequestManager();

  correct:

  const { HttpRequestManager } = require('http2-client');

  HttpRequestManager is a named export for creating custom request managers with specific defaults and separate caches.

Quickstart

This quickstart demonstrates how to use `http2-client`'s `request` function to make transparent requests to both HTTP/1.1 and HTTP/2 servers using the same API as Node's native `http` module. It prints the URL, status code, and HTTP version for each response.

const { request } = require('http2-client');

const h1Target = 'http://www.example.com/';
const h2Target = 'https://www.google.com/'; // Using google as example.com might not support h2

console.log('Making HTTP/1.1 request...');
const req1 = request(h1Target, (res) => {
    console.log(`\nUrl : ${h1Target}\nStatus : ${res.statusCode}\nHttpVersion : ${res.httpVersion}`);
    res.on('data', () => {}); // Consume response data
    res.on('end', () => console.log('HTTP/1.1 request ended.'));
});
req1.on('error', (e) => console.error(`HTTP/1.1 request error: ${e.message}`));
req1.end();

console.log('\nMaking HTTP/2 request...');
const req2 = request(h2Target, (res) => {
    console.log(`\nUrl : ${h2Target}\nStatus : ${res.statusCode}\nHttpVersion : ${res.httpVersion}`);
    res.on('data', () => {}); // Consume response data
    res.on('end', () => console.log('HTTP/2 request ended.'));
});
req2.on('error', (e) => console.error(`HTTP/2 request error: ${e.message}`));
req2.end();