@hyperttp/core 1.5.6 → 2.0.0

package/README.md

@@ -1,290 +1,362 @@
-# @hyperttp/core ⚡
+# @hyperttp/core
 
-> High-performance HTTP engine for Node.js and Bun.
+> Protocol-agnostic execution core for client and server communication.
 
-**English** | [Русский](https://github.com/IT-IF-OR/hyperttp-core/tree/main/lang/ru)
+**English** | [Русский](./lang/ru/README.md)
 
+[![CI](https://github.com/IT-IF-OR/hyperttp-core/actions/workflows/ci.yml/badge.svg)](https://github.com/IT-IF-OR/hyperttp-core/actions/workflows/ci.yml)
 [![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)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@hyperttp/core)](https://bundlephobia.com/package/@hyperttp/core)
 [![license](https://img.shields.io/npm/l/@hyperttp/core)](./LICENSE)
 [![typescript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 
----
+## Positioning
 
-## What is @hyperttp/core?
+`@hyperttp/core` is a small orchestration kernel, not another wrapper around `fetch` and not a
+batteries-included HTTP framework. It connects three independent extension points:
 
-**@hyperttp/core** is a low-level, high-performance HTTP engine designed for building fast,
-extensible HTTP clients and SDKs.
+- **Protocols** define communication semantics. A protocol can send through a `HyperSender`,
+  receive through a `HyperReceiver`, or implement both roles as a `HyperProtocol`.
+- **Transports** own physical I/O. The current transport contract executes outgoing requests and can
+  additionally listen for incoming requests.
+- **Plugins** add client request policy and cross-cutting behavior without expanding the core.
 
-It provides:
+The core owns dispatch, lifecycle, plugin execution and resource coordination. REST is included as
+the baseline protocol; additional protocols, optimized transports and higher-level behavior live in
+separate packages.
 
-- ⚡ Optimized request execution pipeline
-- 🔀 Runtime-aware transport abstraction
-- 🔌 Plugin lifecycle hooks
-- 🛡️ Safe request/response handling
-- 📦 Zero runtime dependencies
-
-`@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.
+```text
+Application
+    │
+    ├── Plugins: retry, cache, auth, tracing, metrics, logging, policy
+    │
+ HyperCore
+    │
+    ├── Protocol: prepare → send → parse
+    │              receive → handle → respond
+    │
+    └── Transport: execute (client) / listen (server)
+                   Node.js / Bun / Deno / Browser / custom runtime
+```
 
-> 💡 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.
+This boundary is intentional. New client-side retries, caches, authentication strategies,
+observability tools and other request policies should be plugins. New wire semantics should be
+protocol packages. New I/O implementations should be transport packages.
 
----
+> Looking for a preconfigured HTTP client? Use
+> [`hyperttp`](https://www.npmjs.com/package/hyperttp), which composes the core with application-level
+> plugins and defaults.
 
-## Why @hyperttp/core?
+## Core properties
 
-Unlike the native `fetch()`, HyperCore is designed as an extensible HTTP engine rather than just a request API.
+- Client and server orchestration.
+- Protocol-independent request envelope and universal response shape.
+- Client lifecycle: `prepare → send → parse`.
+- Server lifecycle: `receive → handle → respond`.
+- Per-protocol transport resolution and coordinated transport ownership.
+- Blocking and background client plugin hooks.
+- Runtime-aware transport selection with a browser-safe fetch fallback.
+- Strict TypeScript contracts and module augmentation for typed protocol namespaces.
+- No bundled runtime dependencies.
 
-| Feature                | fetch | @hyperttp/core |
-| ---------------------- | :---: | :------------: |
-| Transport abstraction  |  ❌   |       ✅       |
-| Plugin pipeline        |  ❌   |       ✅       |
-| Request/Response hooks |  ❌   |       ✅       |
-| Custom transports      |  ❌   |       ✅       |
-| Built for SDKs         |  ⚠️   |       ✅       |
-| Safe response cleanup  |  ❌   |       ✅       |
-| Runtime auto-detection |  ❌   |       ✅       |
+## Installation
 
----
+```bash
+npm install @hyperttp/core @hyperttp/types
+```
 
-## Features
+Compatible optimized transports can be installed separately. Ensure the selected transport release
+declares compatibility with `@hyperttp/types@^0.3.0`; older transport releases target the v1 type
+contracts and cannot be installed alongside core 2.0. Without an optional transport package, the
+core uses its built-in `FetchTransport` fallback.
 
-- ⚡ 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
+## Client quick start
 
----
+```ts
+import { HyperCore } from "@hyperttp/core";
 
-## Architecture
+const core = new HyperCore();
 
-```text
-                  hyperttp
-                      │
-                      ▼
-              @hyperttp/core
-                      │
-      ┌───────────────┴───────────────┐
-      │                               │
-      ▼                               ▼
- Transport Layer              Plugin Pipeline
-      │                               │
-      ├── BunTransport                │
-      ├── UndiciTransport             ├── Retry
-      ├── NodeTransport               ├── Cache
-      ├── BrowserTransport            ├── Parser
-      └── Custom Transport            └── Пользовательские плагины
-```
-
----
+const response = await core.rest.get("https://example.com/users", {
+  query: { page: 1 },
+});
 
-## Installation
+console.log(response.status);
+console.log(response.data);
 
-```bash
-npm install @hyperttp/core
+await core.destroy();
 ```
 
-Recommended transports:
+The same request can use the protocol-independent API:
 
-```bash
-# Bun
-npm install @hyperttp/transport-bun
-
-# Node.js
-npm install @hyperttp/transport-undici
+```ts
+const response = await core.send({
+  protocol: "rest",
+  input: {
+    method: "GET",
+    url: "https://example.com/users",
+    query: { page: 1 },
+  },
+});
 ```
 
----
+## Server quick start
 
-## Quick Start
+A transport may also expose `listen()`. `HyperCore` connects it to the receiver side of the selected
+protocol:
 
 ```ts
 import { HyperCore } from "@hyperttp/core";
 
-const http = new HyperCore({
-  network: {
-    baseURL: "https://api.example.com",
-    headers: {
-      "X-App-Version": "1.0.0",
-    },
+const core = new HyperCore();
+
+const server = await core.listen({
+  protocol: "rest",
+  host: "127.0.0.1",
+  port: 3000,
+  handler(request) {
+    return {
+      status: 200,
+      body: {
+        method: request.method,
+        path: request.path,
+      },
+    };
   },
 });
 
-const response = await http.get("/users", {
-  query: {
-    page: 1,
-    limit: 20,
-  },
-});
+// Closes active servers and releases every transport owned by this core.
+await core.destroy();
+```
 
-const users = await response.json();
+Protocols can be client-only, server-only or expose both roles. The current transport contract always
+provides client `execute()` and can additionally provide server `listen()`.
 
-console.log(users);
-```
+## Protocols
 
----
+REST is the only protocol implemented inside the core. External protocol modules are loaded lazily:
 
-## Error Handling
+| Protocol  | Package                        | Namespace                    |
+| --------- | ------------------------------ | ---------------------------- |
+| REST      | built in                       | `core.rest`                  |
+| GraphQL   | `@hyperttp/protocol-graphql`   | `core.graphql`               |
+| gRPC      | `@hyperttp/protocol-grpc`      | `core.grpc`                  |
+| tRPC      | `@hyperttp/protocol-trpc`      | `core.trpc`                  |
+| WebSocket | `@hyperttp/protocol-websocket` | `core.ws` / `core.websocket` |
+| SSE       | `@hyperttp/protocol-sse`       | `core.sse`                   |
+| MQTT      | `@hyperttp/protocol-mqtt`      | `core.mqtt`                  |
 
-```ts
-import { HyperCore, HttpClientError, TimeoutError } from "@hyperttp/core";
+If an optional protocol package is missing, resolution fails with an installation hint instead of
+silently selecting another protocol.
 
-try {
-  const res = await http.get("/users");
+### Protocol roles
 
-  console.log(await res.json());
-} catch (error) {
-  if (TimeoutError.isTimeoutError(error)) {
-    console.error("Request timed out.");
-  }
+A unified protocol module can expose either or both roles:
 
-  if (HttpClientError.isHttpClientError(error)) {
-    console.error(error.statusCode, error.message);
-  }
+```ts
+const protocol = {
+  protocol: "my-protocol",
+  sender: mySender, // optional client role
+  receiver: myReceiver, // optional server role
+};
 
-  throw error;
-}
+core.registerProtocol(protocol);
 ```
 
----
+A sender translates protocol input into a transport request and parses the transport response. A
+receiver translates an incoming transport request into protocol input and serializes the application
+response.
 
-## Streaming
-
-Read a streaming response:
+Protocol packages can extend typed inputs and namespaces through `@hyperttp/types` module
+augmentation:
 
 ```ts
-const response = await http.stream("https://stream.example.com/audio");
+declare module "@hyperttp/types" {
+  interface ProtocolInputMap {
+    "my-protocol": MyProtocolInput;
+  }
 
-const reader = response.body.getReader();
+  interface HyperProtocols {
+    "my-protocol": MyProtocolMethods;
+  }
+}
+```
 
-while (true) {
-  const { done, value } = await reader.read();
+## Transports
 
-  if (done) break;
+A transport describes its client capabilities and optional server capability:
 
-  console.log(value.length);
+```ts
+interface HyperTransport {
+  execute(request: TransportRequest): Promise<TransportResponse>;
+  listen?(options: TransportListenOptions): Promise<TransportServer>;
+  close?(): Promise<void> | void;
+  destroy?(): Promise<void> | void;
 }
 ```
 
-Discard a response body without buffering:
+- `execute()` is the required client role.
+- `listen()` is the optional server role.
+- `protocols` or `supports()` declares protocol capabilities.
+- The core resolves and retains transports per protocol and closes a shared instance only after its
+  last owner releases it.
+
+Runtime selection:
+
+| Runtime        | Preferred package            | Fallback                  |
+| -------------- | ---------------------------- | ------------------------- |
+| Node.js        | `@hyperttp/transport-undici` | built-in `FetchTransport` |
+| Bun            | `@hyperttp/transport-bun`    | built-in `FetchTransport` |
+| Deno           | `@hyperttp/transport-deno`   | built-in `FetchTransport` |
+| Browser / edge | custom transport             | built-in `FetchTransport` |
+
+A transport can also be supplied explicitly:
 
 ```ts
-await http.dump("https://api.example.com/ping");
-```
+import { HyperCore } from "@hyperttp/core";
+import { UndiciTransport } from "@hyperttp/transport-undici";
 
----
+const core = new HyperCore({
+  customTransport: new UndiciTransport(),
+});
+```
 
 ## Plugins
 
-HyperCore exposes request lifecycle hooks that allow intercepting requests, responses and errors.
+Plugins are the intended extension mechanism for client request behavior that does not belong to
+protocol semantics or physical I/O. The current hooks run in the client `send()` lifecycle:
 
 ```ts
-http.use({
-  name: "logger",
-  priority: 10,
-
-  onRequest(req) {
-    req.meta.start = performance.now();
+core.use({
+  name: "request-logger",
+  phase: "DATA",
+  onRequest(request) {
+    console.log("request", request.protocol);
   },
-
-  onResponse(res, req) {
-    const elapsed = performance.now() - (req.meta.start as number);
-
-    console.log(`${req.method} ${req.url} -> ${res.status} (${elapsed.toFixed(2)} ms)`);
+  onResponse(response) {
+    console.log("response", response.status);
   },
-
-  onError(error, req) {
-    console.error(`${req.url}: ${error.message}`);
+  onError(error) {
+    console.error(error);
   },
 });
 ```
 
----
+Hooks:
 
-## Transports
+- `onRequest` can modify a request or return an early response.
+- `onResponse` can inspect or replace a response.
+- `onError` can recover by returning a response.
+- `mode: "background"` detaches response-side work from the blocking path.
+- `enabled(config)` controls registration.
+- `setup(context)` initializes a plugin.
+
+Examples of functionality that belongs in plugins:
 
-HyperCore automatically detects the current runtime, or you can provide your own transport.
+- retries and circuit breakers;
+- caching and request deduplication;
+- authentication and request signing;
+- tracing, metrics and structured logging;
+- rate limiting, concurrency control and scheduling;
+- schema validation and application-specific policies.
 
-| Transport        | Runtime       |
-| ---------------- | ------------- |
-| BunTransport     | Bun           |
-| UndiciTransport  | Node.js       |
-| NodeTransport    | Bun / Node.js |
-| BrowserTransport | Browser       |
-| Custom Transport | Any           |
+## Built-in REST protocol
 
-Example:
+The REST package exposes client and server roles through `RestProtocol`.
 
 ```ts
-import { HyperCore } from "@hyperttp/core";
-import { UndiciTransport } from "@hyperttp/transport-undici";
+const getResponse = await core.rest.get("/users", {
+  query: { page: 1, tag: ["a", "b"] },
+  headers: { accept: "application/json" },
+  timeout: 5_000,
+});
 
-const http = new HyperCore({
-  customTransport: new UndiciTransport(),
+const postResponse = await core.rest.post("/users", {
+  name: "Ada",
 });
+
+const streamResponse = await core.rest.stream("/events");
 ```
 
----
+REST behavior includes:
+
+- query serialization with repeated array parameters;
+- header normalization;
+- JSON serialization for plain object and array request bodies;
+- JSON, text and binary response handling;
+- timeout and user abort propagation;
+- unbuffered stream mode;
+- request decoding and response serialization for the server role.
+
+REST-specific public types are available from `@hyperttp/core/rest`.
+
+## Lifecycle
+
+```ts
+const child = core.extend({ verbose: true }); // shares resolved transport leases
+const isolated = core.create({}); // independent transport lifecycle
+
+await child.destroy();
+await isolated.destroy();
+await core.destroy();
+```
 
-## Performance
+- `extend()` creates a related core and shares existing transport ownership.
+- `create()` creates an independent core and does not inherit `customTransport` by default.
+- `destroy()` is idempotent, closes tracked servers and releases transports.
+- `destroy(false)` requests forced shutdown where the transport supports it.
 
-HyperCore is optimized for sustained high concurrency.
+## Error handling
 
-Recent stress testing:
+```ts
+import { HyperClientError, TimeoutError } from "@hyperttp/core";
 
-- **200,000 requests**
-- **1000 concurrent connections**
-- **120 seconds**
-- **0 request errors**
+try {
+  await core.rest.get("/slow", { timeout: 1_000 });
+} catch (error) {
+  if (TimeoutError.isTimeoutError(error)) {
+    console.error("Request timed out");
+  } else if (HyperClientError.isHyperClientError(error)) {
+    console.error(error.code, error.message);
+  }
+}
+```
 
-Optimizations include:
+## Scope
 
-- minimal allocations
-- object reuse
-- optimized semaphore
-- manual query serialization
-- efficient header normalization
-- zero-dependency core
+The stable core is intentionally limited to:
 
----
+1. protocol registration and dispatch;
+2. transport resolution, sharing and shutdown;
+3. client and server lifecycle orchestration;
+4. plugin execution;
+5. the baseline REST protocol and universal error contracts.
 
-## Ecosystem
+Feature growth should happen through plugins, protocol packages and transport packages. Keeping this
+boundary small makes runtime behavior predictable and allows the core API to stabilize independently
+from the ecosystem around it.
 
-| 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            |
+## Runtime support
 
----
+- Node.js 20 and newer;
+- current stable Bun;
+- current stable Deno;
+- modern browsers and edge runtimes with Fetch and Web Streams.
 
 ## Development
 
 ```bash
-bun install
-
-bun run lint
-bun run typecheck
-bun run test
-bun run build
+npm install
+npm run format:check
+npm run lint
+npm run typecheck
+npm run test
+npm run build
 ```
 
----
+The required order is `lint → typecheck → test → build`. CI also verifies browser bundling, runtime
+smoke tests and installation of the generated npm tarball.
 
 ## License
 

package/defaultConfig.d.ts

@@ -0,0 +1,12 @@
+import type { HyperClientOptions } from "@hyperttp/types";
+/**
+ * @ru Конфигурация по умолчанию универсального ядра.
+ * @en Default configuration for the universal core.
+ */
+export declare const defaultCoreConfig: HyperClientOptions;
+/**
+ * @ru HTTP-конфигурация по умолчанию для HttpSender.
+ * @en Default HTTP configuration for the HttpSender.
+ */
+export declare const defaultHttpConfig: HyperClientOptions;
+//# sourceMappingURL=defaultConfig.d.ts.map

package/defaultConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultConfig.d.ts","sourceRoot":"","sources":["../src/defaultConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,kBAQ/B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,kBAO/B,CAAC"}

package/defaultConfig.js

@@ -0,0 +1,2 @@
+"use strict";export const defaultCoreConfig={retry:{maxRetries:0,baseDelay:100,maxDelay:5e3,jitter:!0},verbose:!1},defaultHttpConfig={retry:{maxRetries:0,baseDelay:100,maxDelay:5e3,jitter:!0}};
+//# sourceMappingURL=defaultConfig.js.map

package/defaultConfig.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/defaultConfig.ts"],
+  "sourcesContent": ["import type { HyperClientOptions } from \"@hyperttp/types\";\n\n/**\n * @ru Конфигурация по умолчанию универсального ядра.\n * @en Default configuration for the universal core.\n */\nexport const defaultCoreConfig: HyperClientOptions = {\n  retry: {\n    maxRetries: 0,\n    baseDelay: 100,\n    maxDelay: 5000,\n    jitter: true,\n  },\n  verbose: false,\n};\n\n/**\n * @ru HTTP-конфигурация по умолчанию для HttpSender.\n * @en Default HTTP configuration for the HttpSender.\n */\nexport const defaultHttpConfig: HyperClientOptions = {\n  retry: {\n    maxRetries: 0,\n    baseDelay: 100,\n    maxDelay: 5000,\n    jitter: true,\n  },\n};\n"],
+  "mappings": "aAMO,aAAM,kBAAwC,CACnD,MAAO,CACL,WAAY,EACZ,UAAW,IACX,SAAU,IACV,OAAQ,IAEV,QAAS,IAOE,kBAAwC,CACnD,MAAO,CACL,WAAY,EACZ,UAAW,IACX,SAAU,IACV,OAAQ",
+  "names": []
+}

package/index.d.ts

@@ -0,0 +1,6 @@
+export { HyperCore } from "./Core/index.js";
+export { HyperClientError, TimeoutError } from "./utils/errors.js";
+export { deepMerge } from "./utils/merge.js";
+export { RestProtocol, RestReceiver, RestSender } from "./protocols/rest/index.js";
+export { KNOWN_PROTOCOLS, resetCachedProtocols, resolveProtocol, resolveReceiver, resolveSender, } from "./protocols/manager.js";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,wBAAwB,CAAC"}

package/index.js

@@ -0,0 +1,2 @@
+"use strict";export{HyperCore}from"./Core/index.js";export{HyperClientError,TimeoutError}from"./utils/errors.js";export{deepMerge}from"./utils/merge.js";export{RestProtocol,RestReceiver,RestSender}from"./protocols/rest/index.js";export{KNOWN_PROTOCOLS,resetCachedProtocols,resolveProtocol,resolveReceiver,resolveSender}from"./protocols/manager.js";
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export { HyperCore } from \"./Core/index.js\";\nexport { HyperClientError, TimeoutError } from \"./utils/errors.js\";\nexport { deepMerge } from \"./utils/merge.js\";\nexport { RestProtocol, RestReceiver, RestSender } from \"./protocols/rest/index.js\";\nexport {\n  KNOWN_PROTOCOLS,\n  resetCachedProtocols,\n  resolveProtocol,\n  resolveReceiver,\n  resolveSender,\n} from \"./protocols/manager.js\";\n"],
+  "mappings": "aAAA,OAAS,cAAiB,kBAC1B,OAAS,iBAAkB,iBAAoB,oBAC/C,OAAS,cAAiB,mBAC1B,OAAS,aAAc,aAAc,eAAkB,4BACvD,OACE,gBACA,qBACA,gBACA,gBACA,kBACK",
+  "names": []
+}