Streaming HTTP Requests (Substack's hyperquest)

2.1.3 verified Thu Apr 23 auth: no javascript abandoned

Hyperquest is a lightweight, streaming HTTP client for Node.js, last updated to version 2.1.3 approximately eight years ago. It was created by Substack to address fundamental shortcomings in Node.js's native `http` module prior to version 0.12, specifically concerning default idle timeouts (2 minutes) and a restrictive connection pool limit (5 requests). These defaults often led to applications hanging or experiencing unexpected behavior when making multiple concurrent HTTP requests. Hyperquest bypassed these internal Node.js annoyances by treating HTTP requests purely as streaming transports, removing pooling and extending default timeouts significantly. While it offered a streamlined, 'request'-like API, it was designed for raw streaming without buffering or automatic JSON parsing. Given that its core purpose was to mitigate issues resolved in much older Node.js versions (specifically, Node.js 0.12 and later fixed many of these `http` module defaults), the package is now considered abandoned and not suitable for modern Node.js development.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module ... from ... not supported. ↓

cause Attempting to `require()` an ESM module, or (more commonly for this package) attempting to `import` this CJS package into an ESM context.

fix

This error indicates a module system mismatch. Since hyperquest is CommonJS, if you are in an ESM file, you must use

import { createRequire } from 'module'; const require = createRequire(import.meta.url); const hyperquest = require('hyperquest');

. However, consider migrating to a modern, actively maintained HTTP client with native ESM support.

error TypeError: Cannot read properties of undefined (reading 'pipe') ↓

cause The `hyperquest` function was called without a valid URL, or the URL was malformed, causing it to return an undefined or invalid stream object.

fix

Ensure that the hyperquest() function is called with a well-formed URL string. For example: hyperquest('http://example.com/api').

Warnings

breaking The primary issues `hyperquest` was designed to solve (Node.js's default 2-minute idle timeout and 5-connection pooling limit in `http.request`) were largely addressed in Node.js 0.12 and subsequent versions. Using `hyperquest` in modern Node.js (v4.x+) offers little benefit and may introduce compatibility issues or unexpected behavior due to its outdated approach to HTTP streaming. ↓

fix For modern Node.js, rely on the native `http` module, `undici`, `node-fetch`, or `axios`. Configure `agent` options (like `maxSockets`, `keepAlive`, `timeout`) directly on native HTTP agents as needed. For example, use `new http.Agent({ keepAlive: true, maxSockets: Infinity })`.

deprecated The `hyperquest` package is effectively abandoned, with its last npm publication over eight years ago (v2.1.3 in January 2018). It is not maintained, does not receive security updates, and is not compatible with modern Node.js module systems (ESM). ↓

fix Migrate to actively maintained and modern HTTP clients like `undici` (built-in Node.js `fetch`), `node-fetch`, or `axios`. If streaming is critical, explore stream-based solutions within these modern clients or libraries built on top of them.

gotcha `hyperquest` is a CommonJS-only package. Attempting to `import hyperquest from 'hyperquest'` in an ESM module context will result in a runtime error. ↓

fix If used in an ESM project, you must use `require` via `createRequire` from the `module` built-in module: `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const hyperquest = require('hyperquest');`. However, migrating away from `hyperquest` is strongly recommended.

gotcha `hyperquest` provides a raw streaming interface, unlike higher-level libraries such as `request` or `axios` which automatically buffer responses or parse JSON. Users must manually handle stream events (`data`, `end`, `error`) and process chunks. ↓

fix Always attach `data`, `end`, and `error` event handlers to the returned stream. Accumulate data chunks if a complete response body is needed, and parse manually (e.g., `JSON.parse(Buffer.concat(chunks).toString())`) if the content type is JSON.

Install

npm install hyperquest

yarn add hyperquest

pnpm add hyperquest

Imports

hyperquest
wrong
```
import hyperquest from 'hyperquest';
```
correct
```
const hyperquest = require('hyperquest');
```
This package is CommonJS-only and does not support ESM imports directly. It was last published before widespread ESM adoption in Node.js.

Quickstart

Demonstrates a basic streaming GET request using `hyperquest` to a local HTTP server and piping the response to standard output.

const hyperquest = require('hyperquest');
const http = require('http');

// Create a simple HTTP server to test against
const server = http.createServer((req, res) => {
  console.log(`Server received request for: ${req.url}`);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from hyperquest server!');
});

server.listen(8000, () => {
  console.log('Server listening on http://localhost:8000');

  // Make a streaming GET request using hyperquest
  const reqStream = hyperquest('http://localhost:8000');

  reqStream.on('data', (chunk) => {
    process.stdout.write('Client received: ' + chunk.toString());
  });

  reqStream.on('end', () => {
    console.log('\nClient finished receiving data.');
    server.close(); // Close the server after the request is done
  });

  reqStream.on('error', (err) => {
    console.error('Hyperquest error:', err);
    server.close();
  });
});