@hyperttp/core ⚡

English | Русский

🌐 Language

• 🇺🇸 English
• 🇷🇺 Русский

🔗 Quick Links

• 🏢 Organization: github.com/IT-IF-OR
• 👤 Author: github.com/dirold2
• 📦 npm: npmjs.com/org/hyperttp
• 🚀 High-level client: hyperttp (all plugins pre-wired)

@hyperttp/core is the low-level, high-performance engine of the Hyperttp ecosystem. It provides a thin, optimized HTTP core with an intelligent transport layer and an advanced pipeline-based plugin architecture — the foundation upon which the feature-rich hyperttp client is built.

💡 Looking for a batteries-included client? Install hyperttp instead — it wraps @hyperttp/core with caching, rate limiting, queueing, parsing, and more.

🔥 Key Features

• ⚡ Zero-Overhead Hot Paths: Fast header merging, response mapping, and object creation loops optimized for high-throughput environments. Object pooling for InternalRequest eliminates allocations in the hot path.
• 📍 LRU URL Caching: Built-in string URL parsing cache (up to 512 entries) with automatic eviction to bypass repetitive new URL() overhead.
• 🔀 Intelligent Isomorphism: Automatically switches between optimal underlying transports (Native Bun, Undici, or Node.js native fetch) while maintaining a unified, clean API.
• 🔌 Multi-Stage Hooks & Pipelines: Granular control over the request lifecycle with sorted hook priorities and short-circuit capabilities.
• 🗜️ Transparent Decompression: Automatic out-of-the-box handling of gzip, deflate, and br (Brotli) content-encodings for both standard Uint8Array buffers and ReadableStream data.
• 💎 Prototype Preservation: Safe internal mapping that respects and carries forward custom prototypes passed via request configurations.
• 🦀 Rust-Powered Toolchain: Built and linted with OXC (oxlint + oxfmt) for blazing-fast development cycles.

📦 Ecosystem Packages

🏗️ Architecture & Lifecycle

HyperCore shifts heavy lifting into structured execution pipelines:

┌─────────────────────────────────────────────────────────────────┐
│                         HyperCore                               │
│                                                                 │
│  1. Request Pipeline (onRequest) ─── short-circuit capable      │
│                     │                                           │
│  2. Transport Execution (HyperTransport)                        │
│     ├─ BunTransport (native Bun fetch)                          │
│     ├─ UndiciTransport (Node.js)                                │
│     └─ NodeTransport (global fetch)                             │
│                     │                                           │
│  3. Response Data Pipeline (onResponseData)                     │
│                     │                                           │
│  4. Internal Processing (decompression, mapping)                │
│                     │                                           │
│  5. Response Pipeline (onResponse)                              │
│     ├─ Mutators (sync/async modification)                       │
│     └─ Side Effects (background, non-blocking)                  │
│                     │                                           │
│  6. Error Pipeline (onError) ─── recovery capable               │
└─────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Installation

npm install @hyperttp/core

# Optional: install a specific transport
npm install @hyperttp/transport-bun    # for Bun
npm install @hyperttp/transport-undici # for Node.js

Basic Usage

HyperCore returns HttpResponse<T> objects with full control over the response body:

import { HyperCore } from "@hyperttp/core";

const http = new HyperCore({
  network: {
    userAgent: "MyApp/2.0",
    headers: { "X-Custom-Global": "Hyperttp" },
  },
});

// Returns HttpResponse<T> with full control
const response = await http.get("https://api.example.com/data");
console.log(response.status);
console.log(response.headers);

// Built-in parsing methods
const json = await response.json<User>();
const text = await response.text();
const buffer = await response.arrayBuffer();

// Shortcut methods
const userJson = await http.json<{ name: string }>("/users/123");
const logsText = await http.text("/logs/latest");

// Safely consume/drain a response without allocations
await http.dump("/analytics/ping");

Streaming

// GET Streams
const streamResponse = await http.stream("https://stream.example.com/audio");
const reader = streamResponse.body.getReader();

// POST Streams (e.g., LLM Completions / Audio Pipes)
const chatStream = await http.postStream("/v1/chat/completions", {
  model: "gpt-4",
  stream: true,
});

🔌 Plugin System

Extend HyperCore with custom hooks that integrate into the pipeline:

import { HyperCore } from "@hyperttp/core";

const http = new HyperCore();

http.use({
  name: "performance-logger",
  priority: 100, // Sorted execution priority (higher runs first)
  mode: "background", // Forces onResponse to run as a non-blocking side-effect

  setup: (ctx) => {
    // Fired immediately on registration
    ctx.config.logger?.info?.("Plugin active");
  },

  onRequest: async (req, ctx) => {
    req.meta.startTime = performance.now();
  },

  onResponse: async (res, req, ctx) => {
    const duration = performance.now() - (req.meta.startTime as number);
    console.log(`[${req.method}] ${req.url} -> ${res.status} (${duration.toFixed(2)}ms)`);
  },

  onError: async (error, req, ctx) => {
    console.error(`Request failed to ${req.url}: ${error.message}`);
    // Return a response object here to bypass/recover from the failure
  },
});

Plugin Phases

💡 Need caching, rate limiting, queueing, parsing, and more? Use the hyperttp meta-package — it comes with 8 pre-wired plugins.

🌍 Transports

Hyperttp automatically selects the optimal transport for your runtime:

Custom Transport

Implement your own transport:

import type { HyperTransport, TransportRequest, TransportResponse } from "@hyperttp/types";

class MyCustomTransport implements HyperTransport {
  async execute(req: TransportRequest): Promise<TransportResponse> {
    const response = await fetch(req.url, {
      method: req.method,
      headers: req.headers,
      body: req.body,
      signal: req.signal,
    });

    return {
      status: response.status,
      headers: Object.fromEntries(response.headers),
      body: response.body,
      url: response.url,
    };
  }

  async close(): Promise<void> {
    // Cleanup resources
  }
}

const http = new HyperCore({}, new MyCustomTransport());

🔄 Extending Configuration

Create derived clients with merged configuration via .extend():

// Inherit global pools and layers while changing specific presets
const authenticatedClient = http.extend({
  network: { headers: { Authorization: "Bearer token_abc" } },
});

Graceful Resource Destruction

Always clean up underlying transport configurations, socket pools, and keep-alive timers in microservice tear-downs:

// Performs a graceful or rapid shutdown sequence across transport selectors
await http.destroy(true);

📊 Benchmarks

Test Configuration

Requests        20000
Concurrency     200
Duration        20000
Timeout         60000 ms

To run your own suite:

bun run bench.ts && npx tsx bench.ts

🟦 Bun 1.3.14 — BunTransport

npm install @hyperttp/transport-bun

🟦 Bun 1.3.14 — NodeTransport

🟦 Node.js v24.14.1 — UndiciTransport

npm install @hyperttp/transport-undici

🟦 Node.js v24.14.1 — NodeTransport

📈 Performance Analysis

Key Insights:

• Bun + BunTransport: @hyperttp/core achieves 17.39K RPS — only 14% slower than native bun-fetch (24.34K)
• Node.js + UndiciTransport: @hyperttp/core reaches 11.95K RPS with p99 latency of 26.58ms — virtually identical to native undici (26.23ms)
• Zero Error Rate: 0% errors across all scenarios in all benchmarks
• Memory Efficiency: @hyperttp/core uses ~148-184MB in Bun, less than axios (201MB) and got (165-170MB)

🛠️ Development

This project uses the OXC toolchain for lightning-fast development:

# Install dependencies
bun install

# Type checking
bun run typecheck

# Linting (oxlint — ~8ms)
bun run lint

# Formatting (oxfmt — ~25ms)
bun run format

# Build
bun run build

# Run tests
bun run test

📄 License

MIT

dirold2