@hyperttp/core 1.5.4 → 1.5.6

package/README.md

@@ -1,6 +1,8 @@
 # @hyperttp/core ⚡
 
-> English | [Русский](https://github.com/IT-IF-OR/hyperttp-core/tree/main/lang/ru)
+> High-performance HTTP engine for Node.js and Bun.
+
+**English** | [Русский](https://github.com/IT-IF-OR/hyperttp-core/tree/main/lang/ru)
 
 [![npm version](https://img.shields.io/npm/v/@hyperttp/core)](https://www.npmjs.com/package/@hyperttp/core)
 [![npm downloads](https://img.shields.io/npm/dm/@hyperttp/core)](https://www.npmjs.com/package/@hyperttp/core)
@@ -10,410 +12,280 @@
 
 ---
 
-## 🌐 Language
-
-- 🇺🇸 English
-- 🇷🇺 [Русский](https://github.com/IT-IF-OR/hyperttp-core/tree/main/lang/ru)
-
----
+## What is @hyperttp/core?
 
-## 🔗 Quick Links
+**@hyperttp/core** is a low-level, high-performance HTTP engine designed for building fast,
+extensible HTTP clients and SDKs.
 
-- 🏢 **Organization:** [github.com/IT-IF-OR](https://github.com/IT-IF-OR)
-- 👤 **Author:** [github.com/dirold2](https://github.com/dirold2)
-- 📦 **npm:** [npmjs.com/org/hyperttp](https://www.npmjs.com/org/hyperttp)
-- 🚀 **High-level client:** [`hyperttp`](https://www.npmjs.com/package/hyperttp) (all plugins pre-wired)
+It provides:
 
----
+- ⚡ Optimized request execution pipeline
+- 🔀 Runtime-aware transport abstraction
+- 🔌 Plugin lifecycle hooks
+- 🛡️ Safe request/response handling
+- 📦 Zero runtime dependencies
 
-**@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`](https://www.npmjs.com/package/hyperttp) client is built.
+`@hyperttp/core` is the foundation that powers **hyperttp**,
+but it can also be used directly to build custom HTTP clients, SDKs, API wrappers and internal tooling.
 
-> 💡 **Looking for a batteries-included client?** Install [`hyperttp`](https://www.npmjs.com/package/hyperttp) instead — it wraps `@hyperttp/core` with caching, rate limiting, queueing, parsing, and more.
+> 💡 Looking for a batteries-included client?
+>
+> Use **[`hyperttp`](https://www.npmjs.com/package/hyperttp)** — it ships with retries, caching,
+> parsing, rate limiting and other plugins already configured.
 
 ---
 
-## 🔥 Key Features
+## Why @hyperttp/core?
 
-- **⚡ 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.
-- **🛡️ Security Hardening:** Response body size limiting (`maxResponseBytes`), CRLF injection prevention in headers, SSL certificate validation enforcement, and concurrent request throttling (`maxConcurrent`).
-- **📦 Tiny Footprint:** ~30.7 KB raw / ~9.6 KB gzip after minification — no unnecessary dependencies.
-- **🦀 Rust-Powered Toolchain:** Built and linted with OXC (`oxlint` + `oxfmt`) for blazing-fast development cycles.
+Unlike the native `fetch()`, HyperCore is designed as an extensible HTTP engine rather than just a request API.
 
----
-
-## 📦 Ecosystem Packages
-
-| Package                                                                                  | Description                                  | Repository                                                      |
-| ---------------------------------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------- |
-| **`@hyperttp/core`** (you are here)                                                      | Low-level core with transport pipeline       | [GitHub](https://github.com/IT-IF-OR/hyperttp-core)             |
-| [`@hyperttp/types`](https://www.npmjs.com/package/@hyperttp/types)                       | Shared TypeScript type definitions           | [GitHub](https://github.com/dirold2/hyperttp-types)             |
-| [`@hyperttp/transport-bun`](https://www.npmjs.com/package/@hyperttp/transport-bun)       | Native Bun transport                         | [GitHub](https://github.com/IT-IF-OR/hyperttp-transport-bun)    |
-| [`@hyperttp/transport-undici`](https://www.npmjs.com/package/@hyperttp/transport-undici) | Undici transport for Node.js                 | [GitHub](https://github.com/IT-IF-OR/hyperttp-transport-undici) |
-| [`hyperttp`](https://www.npmjs.com/package/hyperttp)                                     | High-level client with all plugins pre-wired | [GitHub](https://github.com/dirold2/hyperttp)                   |
+| Feature                | fetch | @hyperttp/core |
+| ---------------------- | :---: | :------------: |
+| Transport abstraction  |  ❌   |       ✅       |
+| Plugin pipeline        |  ❌   |       ✅       |
+| Request/Response hooks |  ❌   |       ✅       |
+| Custom transports      |  ❌   |       ✅       |
+| Built for SDKs         |  ⚠️   |       ✅       |
+| Safe response cleanup  |  ❌   |       ✅       |
+| Runtime auto-detection |  ❌   |       ✅       |
 
 ---
 
-## 🏗️ Architecture & Lifecycle
+## Features
+
+- ⚡ Optimized hot paths with minimal allocations
+- 🚀 Fast manual query string serialization
+- 🔀 Automatic runtime transport selection
+- 🔌 Extensible plugin system
+- 🧠 Request/response lifecycle hooks
+- 🛡️ Protection against Prototype Pollution
+- 🛡️ CRLF header validation
+- 🛡️ Safe `ArrayBuffer` handling
+- 📦 Zero runtime dependencies
+- 🌊 Native stream support
+- 🧹 Automatic resource cleanup
+- 📈 Designed for high concurrency
 
-`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               │
-└─────────────────────────────────────────────────────────────────┘
+## Architecture
+
+```text
+                  hyperttp
+                      │
+                      ▼
+              @hyperttp/core
+                      │
+      ┌───────────────┴───────────────┐
+      │                               │
+      ▼                               ▼
+ Transport Layer              Plugin Pipeline
+      │                               │
+      ├── BunTransport                │
+      ├── UndiciTransport             ├── Retry
+      ├── NodeTransport               ├── Cache
+      ├── BrowserTransport            ├── Parser
+      └── Custom Transport            └── Пользовательские плагины
 ```
 
 ---
 
-## 🚀 Quick Start
-
-### Installation
+## Installation
 
 ```bash
 npm install @hyperttp/core
+```
+
+Recommended transports:
+
+```bash
+# Bun
+npm install @hyperttp/transport-bun
 
-# Optional: install a specific transport
-npm install @hyperttp/transport-bun    # for Bun
-npm install @hyperttp/transport-undici # for Node.js
+# Node.js
+npm install @hyperttp/transport-undici
 ```
 
-### Basic Usage
+---
 
-`HyperCore` returns `HttpResponse<T>` objects with full control over the response body:
+## Quick Start
 
-```typescript
+```ts
 import { HyperCore } from "@hyperttp/core";
 
 const http = new HyperCore({
   network: {
-    userAgent: "MyApp/2.0",
-    headers: { "X-Custom-Global": "Hyperttp" },
+    baseURL: "https://api.example.com",
+    headers: {
+      "X-App-Version": "1.0.0",
+    },
   },
 });
 
-// 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
+const response = await http.get("/users", {
+  query: {
+    page: 1,
+    limit: 20,
+  },
+});
 
-```typescript
-// GET Streams
-const streamResponse = await http.stream("https://stream.example.com/audio");
-const reader = streamResponse.body.getReader();
+const users = await response.json();
 
-// POST Streams (e.g., LLM Completions / Audio Pipes)
-const chatStream = await http.postStream("/v1/chat/completions", {
-  model: "gpt-4",
-  stream: true,
-});
+console.log(users);
 ```
 
 ---
 
-## 🔌 Plugin System
+## Error Handling
 
-Extend `HyperCore` with custom hooks that integrate into the pipeline:
+```ts
+import { HyperCore, HttpClientError, TimeoutError } from "@hyperttp/core";
 
-```typescript
-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");
-  },
+try {
+  const res = await http.get("/users");
 
-  onRequest: async (req, ctx) => {
-    req.meta.startTime = performance.now();
-  },
+  console.log(await res.json());
+} catch (error) {
+  if (TimeoutError.isTimeoutError(error)) {
+    console.error("Request timed out.");
+  }
 
-  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)`);
-  },
+  if (HttpClientError.isHttpClientError(error)) {
+    console.error(error.statusCode, error.message);
+  }
 
-  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
-  },
-});
+  throw error;
+}
 ```
 
-### Plugin Phases
-
-| Phase       | Hook             | Description                                             |
-| ----------- | ---------------- | ------------------------------------------------------- |
-| **REQUEST** | `onRequest`      | Intercepts before execution. Supports short-circuiting. |
-| **DATA**    | `onResponseData` | Transforms raw transport responses before mapping.      |
-| **FORMAT**  | `onResponse`     | Modifies client-facing responses.                       |
-| **ERROR**   | `onError`        | Catches and recovers from errors.                       |
-
-> 💡 **Need caching, rate limiting, queueing, parsing, and more?** Use the [`hyperttp`](https://www.npmjs.com/package/hyperttp) meta-package — it comes with 8 pre-wired plugins.
-
 ---
 
-## 🌍 Transports
+## Streaming
 
-Hyperttp automatically selects the optimal transport for your runtime:
+Read a streaming response:
 
-| Transport           | Runtime           | Installation                             |
-| ------------------- | ----------------- | ---------------------------------------- |
-| **BunTransport**    | Bun               | `npm install @hyperttp/transport-bun`    |
-| **UndiciTransport** | Node.js           | `npm install @hyperttp/transport-undici` |
-| **NodeTransport**   | Node.js / Browser | Built-in (uses global `fetch`)           |
+```ts
+const response = await http.stream("https://stream.example.com/audio");
 
-### Custom Transport
+const reader = response.body.getReader();
 
-Implement your own transport:
+while (true) {
+  const { done, value } = await reader.read();
 
-```typescript
-import type { HyperTransport, TransportRequest, TransportResponse } from "@hyperttp/types";
+  if (done) break;
 
-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
-  }
+  console.log(value.length);
 }
+```
+
+Discard a response body without buffering:
 
-const http = new HyperCore({}, new MyCustomTransport());
+```ts
+await http.dump("https://api.example.com/ping");
 ```
 
 ---
 
-## 🛡️ Security
+## Plugins
 
-@hyperttp/core includes several hardening mechanisms built into the core pipeline:
+HyperCore exposes request lifecycle hooks that allow intercepting requests, responses and errors.
 
-| Protection | Mechanism | Default |
-|---|---|---|
-| **SSL Validation** | `rejectUnauthorized` enforced via `https.Agent` in NodeTransport | `true` |
-| **Response Size Limit** | `maxResponseBytes` — streaming transform aborts oversized responses | unlimited (0) |
-| **CRLF Injection** | `\r\n` stripped from all header values in `appendHeader()` | always on |
-| **Concurrency Throttle** | `maxConcurrent` — semaphore gates transport execution | unlimited (0) |
-| **Transport Whitelist** | only explicitly registered packages can be loaded dynamically | strict |
-| **Prototype Pollution** | all internal maps use `Object.create(null)` | always on |
+```ts
+http.use({
+  name: "logger",
+  priority: 10,
 
-Configurable via `HyperCore` constructor:
+  onRequest(req) {
+    req.meta.start = performance.now();
+  },
 
-```typescript
-const http = new HyperCore({
-  network: {
-    maxResponseBytes: 10 * 1024 * 1024,   // 10 MB limit
-    maxConcurrent: 50,                    // max 50 in-flight requests
-    rejectUnauthorized: true,
+  onResponse(res, req) {
+    const elapsed = performance.now() - (req.meta.start as number);
+
+    console.log(`${req.method} ${req.url} -> ${res.status} (${elapsed.toFixed(2)} ms)`);
+  },
+
+  onError(error, req) {
+    console.error(`${req.url}: ${error.message}`);
   },
 });
 ```
 
 ---
 
-## 🔄 Extending Configuration
+## Transports
 
-Create derived clients with merged configuration via `.extend()`:
+HyperCore automatically detects the current runtime, or you can provide your own transport.
 
-```typescript
-// Inherit global pools and layers while changing specific presets
-const authenticatedClient = http.extend({
-  network: { headers: { Authorization: "Bearer token_abc" } },
-});
-```
+| Transport        | Runtime       |
+| ---------------- | ------------- |
+| BunTransport     | Bun           |
+| UndiciTransport  | Node.js       |
+| NodeTransport    | Bun / Node.js |
+| BrowserTransport | Browser       |
+| Custom Transport | Any           |
 
-### Graceful Resource Destruction
+Example:
 
-Always clean up underlying transport configurations, socket pools, and keep-alive timers in microservice tear-downs:
+```ts
+import { HyperCore } from "@hyperttp/core";
+import { UndiciTransport } from "@hyperttp/transport-undici";
 
-```typescript
-// Performs a graceful or rapid shutdown sequence across transport selectors
-await http.destroy(true);
+const http = new HyperCore({
+  customTransport: new UndiciTransport(),
+});
 ```
 
 ---
 
-## 📊 Benchmarks
+## Performance
 
-### Test Configuration
+HyperCore is optimized for sustained high concurrency.
 
-```txt
-Requests        20000
-Concurrency     200
-Duration        20000
-Timeout         60000 ms
-```
+Recent stress testing:
 
-To run your own suite:
+- **200,000 requests**
+- **1000 concurrent connections**
+- **120 seconds**
+- **0 request errors**
 
-```bash
-bun run bench.ts && npx tsx bench.ts
-```
+Optimizations include:
 
-## 🟦 Bun 1.3.14 — BunTransport
+- minimal allocations
+- object reuse
+- optimized semaphore
+- manual query serialization
+- efficient header normalization
+- zero-dependency core
 
-```bash
-npm install @hyperttp/transport-bun
-```
-
-| Rank | Client             | RPS        | Avg          | p50          | p90          | p99          | Errors |
-| ---- | ------------------ | ---------- | ------------ | ------------ | ------------ | ------------ | ------ |
-| 🥇 1 | bun-fetch          | 24.34K     | 8.18 ms      | 8.50 ms      | 10.62 ms     | 14.10 ms     | 0      |
-| 🥈 2 | node-fetch         | 21.58K     | 9.23 ms      | 9.39 ms      | 12.86 ms     | 14.72 ms     | 0      |
-| 🥉 3 | undici             | 20.28K     | 9.83 ms      | 10.12 ms     | 13.80 ms     | 15.35 ms     | 0      |
-| 4    | **@hyperttp/core** | **17.39K** | **11.46 ms** | **12.94 ms** | **15.53 ms** | **16.66 ms** | 0      |
-| 5    | ky                 | 12.80K     | 15.58 ms     | 13.95 ms     | 20.62 ms     | 22.77 ms     | 0      |
-| 6    | request            | 8.31K      | 24.00 ms     | 23.43 ms     | 29.54 ms     | 32.82 ms     | 0      |
-| 7    | superagent         | 7.96K      | 25.09 ms     | 24.95 ms     | 26.85 ms     | 28.46 ms     | 0      |
-| 8    | axios              | 6.19K      | 32.21 ms     | 31.93 ms     | 34.15 ms     | 39.09 ms     | 0      |
-| 9    | got                | 5.13K      | 38.94 ms     | 30.99 ms     | 58.61 ms     | 63.14 ms     | 0      |
-
-## 🟦 Bun 1.3.14 — NodeTransport
-
-| Rank | Client             | RPS        | Avg          | p50          | p90          | p99          | Errors |
-| ---- | ------------------ | ---------- | ------------ | ------------ | ------------ | ------------ | ------ |
-| 🥇 1 | bun-fetch          | 23.94K     | 8.32 ms      | 8.63 ms      | 10.64 ms     | 13.77 ms     | 0      |
-| 🥈 2 | node-fetch         | 21.71K     | 9.18 ms      | 9.35 ms      | 12.58 ms     | 14.40 ms     | 0      |
-| 🥉 3 | undici             | 20.22K     | 9.86 ms      | 10.15 ms     | 13.65 ms     | 15.41 ms     | 0      |
-| 4    | **@hyperttp/core** | **17.80K** | **11.20 ms** | **12.38 ms** | **15.20 ms** | **17.29 ms** | 0      |
-| 5    | ky                 | 12.78K     | 15.63 ms     | 13.92 ms     | 20.59 ms     | 23.70 ms     | 0      |
-| 6    | request            | 8.20K      | 24.31 ms     | 23.62 ms     | 29.13 ms     | 34.53 ms     | 0      |
-| 7    | superagent         | 8.06K      | 24.79 ms     | 24.79 ms     | 27.26 ms     | 29.52 ms     | 0      |
-| 8    | axios              | 6.28K      | 31.72 ms     | 31.81 ms     | 33.53 ms     | 35.65 ms     | 0      |
-| 9    | got                | 5.17K      | 38.56 ms     | 30.85 ms     | 58.12 ms     | 61.60 ms     | 0      |
-
-## 🟦 Node.js v24.14.1 — UndiciTransport
+---
 
-```bash
-npm install @hyperttp/transport-undici
-```
+## Ecosystem
 
-| Rank | Client             | RPS        | Avg          | p50          | p90          | p99          | Errors |
-| ---- | ------------------ | ---------- | ------------ | ------------ | ------------ | ------------ | ------ |
-| 🥇 1 | undici             | 13.84K     | 14.41 ms     | 13.54 ms     | 15.39 ms     | 26.23 ms     | 0      |
-| 🥈 2 | **@hyperttp/core** | **11.95K** | **16.68 ms** | **14.90 ms** | **17.04 ms** | **26.58 ms** | 0      |
-| 3    | bun-fetch          | 7.89K      | 25.26 ms     | 23.04 ms     | 33.86 ms     | 39.14 ms     | 0      |
-| 4    | request            | 6.99K      | 28.58 ms     | 27.19 ms     | 34.91 ms     | 39.22 ms     | 0      |
-| 5    | ky                 | 5.97K      | 33.42 ms     | 30.05 ms     | 41.58 ms     | 64.01 ms     | 0      |
-| 6    | axios              | 4.71K      | 42.39 ms     | 40.65 ms     | 48.48 ms     | 56.20 ms     | 0      |
-| 7    | node-fetch         | 4.43K      | 45.03 ms     | 42.18 ms     | 53.61 ms     | 65.02 ms     | 0      |
-| 8    | got                | 4.20K      | 47.51 ms     | 45.20 ms     | 55.32 ms     | 67.58 ms     | 0      |
-| 9    | superagent         | 3.18K      | 62.66 ms     | 61.13 ms     | 70.10 ms     | 75.46 ms     | 0      |
-
-## 🟦 Node.js v24.14.1 — NodeTransport
-
-| Rank | Client             | RPS       | Avg          | p50          | p90          | p99          | Errors |
-| ---- | ------------------ | --------- | ------------ | ------------ | ------------ | ------------ | ------ |
-| 🥇 1 | undici             | 15.45K    | 12.91 ms     | 12.68 ms     | 13.69 ms     | 16.96 ms     | 0      |
-| 🥈 2 | bun-fetch          | 8.31K     | 24.00 ms     | 22.34 ms     | 30.38 ms     | 36.20 ms     | 0      |
-| 🥉 3 | request            | 7.34K     | 27.14 ms     | 26.27 ms     | 30.96 ms     | 34.91 ms     | 0      |
-| 4    | **@hyperttp/core** | **7.23K** | **27.58 ms** | **25.68 ms** | **33.76 ms** | **42.75 ms** | 0      |
-| 5    | ky                 | 6.41K     | 31.14 ms     | 28.43 ms     | 37.55 ms     | 61.30 ms     | 0      |
-| 6    | axios              | 4.87K     | 40.96 ms     | 39.70 ms     | 45.47 ms     | 56.43 ms     | 0      |
-| 7    | node-fetch         | 4.62K     | 43.15 ms     | 41.12 ms     | 49.25 ms     | 64.28 ms     | 0      |
-| 8    | got                | 4.58K     | 43.63 ms     | 41.57 ms     | 48.48 ms     | 65.02 ms     | 0      |
-| 9    | superagent         | 3.32K     | 60.11 ms     | 59.08 ms     | 66.02 ms     | 71.26 ms     | 0      |
-
-### 📈 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)
+| Package                      | Description              |
+| ---------------------------- | ------------------------ |
+| `hyperttp`                   | Ready-to-use HTTP client |
+| `@hyperttp/core`             | HTTP engine              |
+| `@hyperttp/parser`           | Response parsing         |
+| `@hyperttp/cache`            | Cache utilities          |
+| `@hyperttp/transport-undici` | Undici transport         |
+| `@hyperttp/transport-bun`    | Bun transport            |
 
 ---
 
-## 🛠️ Development
-
-This project uses the OXC toolchain for lightning-fast development:
+## Development
 
 ```bash
-# 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 typecheck
 bun run test
+bun run build
 ```
 
 ---
 
-## 📄 License
+## License
 
 MIT
-
----
-
-<p align="center">
-  <a href="https://github.com/dirold2">dirold2</a>
-</p>

package/{Core → dist/Core}/HyperCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HyperCore.d.ts","sourceRoot":"","sources":["../../src/Core/HyperCore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HyperCore.d.ts","sourceRoot":"","sources":["../../src/Core/HyperCore.ts"],"names":[],"mappings":"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"}

package/dist/Core/HyperCore.js

@@ -0,0 +1,2 @@
+"use strict";import{defaultConfig as h}from"../defaultConfig.js";import{mapResponseFast as g,mapStreamFast as x,recycleResponse as p}from"../utils/response.js";import{TransportManager as E}from"../transports/manager.js";import{createPipelines as k,executeErrorPipeline as q,executeRequestPipeline as M,executeResponsePipeline as y,executeResponseDataPipeline as T,insertHookSorted as u}from"../utils/pipeline.js";import{normalizeHeaders as b,normalizeBodyForTransport as S}from"../utils/normalize.js";import{calcDelay as R,shouldRetry as D,drainBody as C}from"../utils/retryUtils.js";import{TimeoutError as O}from"../utils/errors.js";import{RequestBuilder as A}from"./RequestBuilder.js";const w=l=>new Promise(t=>setTimeout(t,l)),H=64;class z{current=0;max;queue;capacity;head=0;tail=0;size=0;constructor(t,e=1024){this.max=t,this.capacity=e;const s=[];s.length=e,this.queue=s}tryAcquire(){return this.current<this.max?(this.current++,!0):!1}acquire(){return this.current<this.max?(this.current++,Promise.resolve()):new Promise(t=>{this.size===this.capacity&&this.grow(),this.queue[this.tail]=t,this.tail=(this.tail+1)%this.capacity,this.size++})}release(){if(this.size>0){const t=this.queue[this.head];this.queue[this.head]=void 0,this.head=(this.head+1)%this.capacity,this.size--,t()}else this.current--}grow(){const t=this.capacity,e=t*2,s=[];s.length=e;for(let i=0;i<this.size;i++)s[i]=this.queue[(this.head+i)%t];this.queue=s,this.capacity=e,this.head=0,this.tail=this.size}}export class HyperCore{config;transportManager;transportReady;defaultHeaders;pluginCtx;pipelines=k();requestBuilder=new A;requestPool=[];semaphore=null;hasRequestPlugins=!1;hasResponseDataPlugins=!1;hasResponsePlugins=!1;hasErrorPlugins=!1;_cachedMaxRetries;_cachedRetryOpts;constructor(t=h,e){this.config={...h,...t,network:{...h.network,...t.network,stealth:t.network?.stealth||h.network?.stealth?Object.assign({},h.network?.stealth,t.network?.stealth):void 0}},this.transportManager=new E(this.config,e),this.transportReady=this.transportManager.getSync()?Promise.resolve(this.transportManager.getSync()):this.transportManager.ensure(),this.defaultHeaders=b({Accept:"application/json, text/plain, */*","Accept-Encoding":"gzip, deflate, br","User-Agent":this.config.network?.userAgent??"Hyperttp/2.0",...this.config.network?.headers});const s=this.config.network?.maxConcurrent;this.semaphore=s!=null&&s>0?new z(s):null,this._cachedRetryOpts=this.config.retry??{},this._cachedMaxRetries=this._cachedRetryOpts.maxRetries??0,this.pluginCtx={config:this.config,core:this}}async getTransportName(){return(this.transportManager.transport??await this.transportManager.get()).constructor.name}async dispatch(t){const e=this._cachedRetryOpts,s=this._cachedMaxRetries;for(let i=0;;i++)try{if(this.hasRequestPlugins){const n=M(this.pipelines.request,t,this.pluginCtx),m=n instanceof Promise?await n:n;if(m!=null)return this.recycleRequest(t),m}t.body!=null&&(t.body=S(t.body,t.headers));const r=this.transportManager.transport??this.transportManager.getSync()??await this.transportReady;let a=!1;if(this.semaphore&&(a=this.semaphore.tryAcquire(),a||await this.semaphore.acquire(),a=!0),t.signal?.aborted)throw t.signal.reason??new DOMException("Aborted","AbortError");let o;const c=t.meta,d=!!c.timings,P=d?performance.now():0;try{o=await r.execute(t)}finally{a&&this.semaphore?.release()}if(d&&(c.timings.networkMs=performance.now()-P),i<s&&D(o.status,e)){await C(o.body),await w(R(i,e));continue}if(this.hasResponseDataPlugins){const n=T(this.pipelines.responseData,o,this.pluginCtx);o=n instanceof Promise?await n:n}const f=c.responseType==="stream"?x(o):g(o);if(this.hasResponsePlugins){const n=y(this.pipelines.responseMutators,this.pipelines.responseSideEffects,f,t,this.pluginCtx,this.config.logger);n instanceof Promise&&await n}return this.recycleRequest(t),f}catch(r){if(r instanceof Error&&(r.name==="AbortError"||r.name==="TimeoutError")){if(t.signal&&t.signal.isTimeout){const a=this.config.network?.timeout??0;return this.handleDispatchError(new O(t.url,a),t)}return this.handleDispatchError(r,t)}if(i<s&&!t.signal?.aborted){await w(R(i,e));continue}return this.handleDispatchError(r,t)}}use(t){if(!(t.enabled?t.enabled(this.config):!0))return this;t.setup?.(this.pluginCtx);const s=t.priority??0,i={name:t.name,priority:s,run:null};if(t.onRequest&&(u(this.pipelines.request,{name:i.name,priority:i.priority,run:t.onRequest}),this.hasRequestPlugins=!0),t.onResponse){const r=t.mode==="background"?this.pipelines.responseSideEffects:this.pipelines.responseMutators;u(r,{name:i.name,priority:i.priority,run:t.onResponse}),this.hasResponsePlugins=!0}return t.onResponseData&&(u(this.pipelines.responseData,{name:i.name,priority:i.priority,run:t.onResponseData}),this.hasResponseDataPlugins=!0),t.onError&&(u(this.pipelines.error,{name:i.name,priority:i.priority,run:t.onError}),this.hasErrorPlugins=!0),this}get(t,e){return typeof t=="string"&&t!==""&&!e&&!this.hasRequestPlugins&&!this.hasResponsePlugins&&!this.hasResponseDataPlugins&&!this.hasErrorPlugins&&this._cachedMaxRetries===0?this.fastGet(t):this.dispatch(this.acquireReq("GET",t,void 0,e))}async fastGet(t){const e=this.requestBuilder.resolveUrl(t,this.config.baseURL);let s=!1;this.semaphore&&(s=this.semaphore.tryAcquire(),s||(await this.semaphore.acquire(),s=!0));const i=this.transportManager.transport??this.transportManager.getSync()??await this.transportReady;try{if(typeof i.fastRequest=="function")return await i.fastRequest(e,"GET",this.defaultHeaders);const r=await i.execute({method:"GET",url:e,headers:this.defaultHeaders,body:void 0,signal:void 0,stealth:this.config.network?.stealth});return g(r)}finally{s&&this.semaphore?.release()}}post(t,e,s){return this.dispatch(this.acquireReq("POST",t,e,s))}put(t,e,s){return this.dispatch(this.acquireReq("PUT",t,e,s))}patch(t,e,s){return this.dispatch(this.acquireReq("PATCH",t,e,s))}delete(t,e){return this.dispatch(this.acquireReq("DELETE",t,void 0,e))}options(t,e,s){return this.dispatch(this.acquireReq("OPTIONS",t,e,s))}head(t,e){return this.dispatch(this.acquireReq("HEAD",t,void 0,e))}stream(t,e){return this.dispatch(this.acquireReq("GET",t,void 0,e))}postStream(t,e,s){return this.dispatch(this.acquireReq("POST",t,e,s))}extend(t){const e={...this.config};for(const s in t)Object.prototype.hasOwnProperty.call(t,s)&&(s==="network"&&t.network?e.network={...this.config.network,...t.network,stealth:t.network.stealth||this.config.network?.stealth?{...this.config.network?.stealth,...t.network.stealth}:void 0}:e[s]=t[s]);return new HyperCore(e,this.transportManager.transport??void 0)}create(t){return this.extend(t)}destroy(t=!0){return this.transportManager.destroy(t)}json(t,e){return this.shortcut(t,e).then(s=>{const i=s.json?s.json():Promise.reject(new Error("json() not supported"));return p(s),i})}text(t,e){return this.shortcut(t,e).then(s=>{const i=s.text?s.text():Promise.reject(new Error("text() not supported"));return p(s),i})}dump(t,e){return this.shortcut(t,e).then(s=>{const i=s.dump?s.dump():Promise.resolve();return p(s),i})}async handleDispatchError(t,e){try{if(this.hasErrorPlugins){const s=await q(this.pipelines.error,t,e,this.pluginCtx);if(s!=null){if(this.hasResponsePlugins){const i=y(this.pipelines.responseMutators,this.pipelines.responseSideEffects,s,e,this.pluginCtx,this.config.logger);i instanceof Promise&&await i}return s}}throw t}finally{this.recycleRequest(e)}}acquireReq(t,e,s,i,r){const a=this.requestPool.pop();return this.requestBuilder.build(t,e,s,i,r,this.defaultHeaders,this.config,a)}recycleRequest(t){if(this.requestPool.length<H){t.method="GET",t.url="",t.headers=this.defaultHeaders,t.body=void 0,t.signal=void 0,t.stealth=void 0;const e=t.meta;e&&(e.responseType=void 0,typeof e.cleanupSignal=="function"&&(e.cleanupSignal(),e.cleanupSignal=void 0),e.timings&&(e.timings.networkMs=void 0)),this.requestPool.push(t)}}shortcut(t,e){const s=typeof t=="string"?"GET":t.method??"GET";return this.dispatch(this.acquireReq(s,t,void 0,e))}}
+//# sourceMappingURL=HyperCore.js.map