@bereasoftware/nexa 1.2.0 → 1.3.0

package/README.en.md

@@ -1,4 +1,5 @@
 <p align="center">
+  <img src="assets/Logo.png" alt="Nexa Logo" width="120" height="120" />
   <h1 align="center">@bereasoftware/nexa</h1>
   <p align="center">
     A modern, type-safe HTTP client that combines the power of <code>fetch</code> with the convenience of <code>axios</code> — built on SOLID principles.
@@ -6,15 +7,16 @@
 </p>
 
 <p align="center">
-  <a href="#tests"><img src="https://img.shields.io/badge/Tests-233_passing-brightgreen?style=for-the-badge" alt="Tests" /></a>
-  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-72%25-orange?style=for-the-badge" alt="Coverage" /></a>
+  <a href="#tests"><img src="https://img.shields.io/badge/Tests-213_passing-brightgreen?style=for-the-badge" alt="Tests" /></a>
+  <a href="#test-coverage"><img src="https://img.shields.io/badge/Coverage-See_report-orange?style=for-the-badge" alt="Coverage" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/v/@bereasoftware/nexa?style=for-the-badge" alt="NPM Version" /></a>
   <a href="https://bundlephobia.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/bundlephobia/minzip/@bereasoftware/nexa?label=Bundle&style=for-the-badge" alt="Bundle Size" /></a>
   <a href="https://www.npmjs.com/package/@bereasoftware/nexa"><img src="https://img.shields.io/npm/dm/@bereasoftware/nexa?style=for-the-badge" alt="NPM Downloads" /></a>
   <img src="https://img.shields.io/badge/Node-20%2B-success?style=for-the-badge" alt="Node" />
-  <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/TypeScript-6.x-3178C6?style=for-the-badge" alt="TypeScript" />
   <img src="https://img.shields.io/badge/Dependencies-Zero-brightgreen?style=for-the-badge" alt="Dependencies" />
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License" /></a>
+  <img src="https://img.shields.io/badge/Maintenance-Active-success?style=for-the-badge" alt="Maintenance" />
   <a href="https://github.com/Berea-Soft/nexa"><img src="https://img.shields.io/badge/github-Repository-blue?logo=github&style=for-the-badge" alt="Repository" /></a>
 </p>
 
@@ -23,6 +25,16 @@
 > - 🇪🇸 [Español](README.md)
 > - 🇬🇧 **English** (this file - README.en.md)
 
+> 📖 **Additional documentation:**
+>
+> - [Architecture](ARCHITECTURE.md) — System design
+> - [Design](DESIGN.md) — Philosophy and design decisions
+> - [Security](SECURITY.md) — Security policy
+> - [Contributing](CONTRIBUTING.md) — Contributor guide
+> - [Migration](MIGRATION.md) — From axios/fetch
+> - [Support](SUPPORT.md) — How to get help
+> - [Skills](SKILLS.md) — Project competencies
+
 ---
 
 ## Why Nexa?
@@ -48,14 +60,8 @@
 | Validators & transformers       |   ❌    |   ❌    |    ✅    |
 | Response duration tracking      |   ❌    |   ❌    |    ✅    |
 | Smart response type detection   |   ❌    |   ✅    |    ✅    |
-| Request transformation (transformRequest)   |   ❌    |   ✅    |    ✅    |
-| Credentials policy   |   ✅    |   ✅    |    ✅    |
-| Adapter pattern (mocking/testing)   |   ❌    |   ✅    |    ✅    |
-| Automatic FormData conversion   |   ❌    |   ❌    |    ✅    |
-| Enhanced error context (request/response/config)   |   ❌    |   ✅    |    ✅    |
-| Differentiated timeouts (connection vs response)   |   ❌    |   ❌    |    ✅    |
-| Debug logging (development mode)                   |   ❌    |   ❌    |    ✅    |
 | Tree-shakeable                  |   ✅    |   ❌    |    ✅    |
+| Dev Overlay (dev tools)         |   ❌    |   ❌    |    ✅    |
 
 ---
 
@@ -71,10 +77,6 @@
   - [Path Parameters](#path-parameters)
   - [Query Parameters](#query-parameters)
   - [Auto Body Serialization](#auto-body-serialization)
-  - [Request Transformation (transformRequest)](#request-transformation-transformrequest)
-  - [Credentials Policy](#credentials-policy)
-  - [Adapter Pattern](#adapter-pattern)
-  - [Transport Configuration](#transport-configuration)
   - [Response Types](#response-types)
   - [Timeout](#timeout)
 - [Retry Strategies](#retry-strategies)
@@ -99,15 +101,13 @@
 - [Transformers](#transformers)
 - [Middleware Pipeline](#middleware-pipeline)
 - [Plugin System](#plugin-system)
+- [Dev Overlay](#dev-overlay)
 - [Streaming](#streaming)
 - [Typed Generics](#typed-generics)
 - [Error Handling](#error-handling)
-  - [Enhanced Error Context](#enhanced-error-context)
 - [API Reference](#api-reference)
 - [Build Formats](#build-formats)
 - [Development](#development)
-- [Contributing](#contributing)
-- [Security](#security)
 - [License](#license)
 
 ---
@@ -221,8 +221,6 @@ const client = createHttpClient({
 | `maxConcurrent`       | `number`                      | `0` (unlimited)                          | Max concurrent requests                    |
 | `defaultResponseType` | `ResponseType`                | `'auto'`                                 | Default response parsing strategy          |
 | `defaultHooks`        | `RequestHooks`                | `{}`                                     | Default lifecycle hooks for all requests   |
-| `debug`               | `boolean \| 'verbose'`        | `undefined`                              | Enable debug logging for requests/responses. `true` for basic logs, `'verbose'` for detailed logs. |
-| `logger`              | `(message: string, data?: unknown) => void` | `undefined`                              | Custom logger function. If provided, replaces the default console.log with custom logging. |
 
 ---
 
@@ -305,8 +303,6 @@ Nexa automatically detects and serializes the request body:
 | `ArrayBuffer`      | Passed as-is       | `application/octet-stream`          |
 | `ReadableStream`   | Passed as-is       | `application/octet-stream`          |
 
-When `autoFormData` is enabled (default), objects containing `File` or `Blob` instances are automatically converted to `FormData`. This is useful for uploading files without manually creating `FormData` instances.
-
 ```typescript
 // JSON (automatic)
 await client.post("/users", { name: "John" });
@@ -323,172 +319,6 @@ await client.post(
 );
 ```
 
-### Request Transformation (transformRequest)
-
-Nexa supports request transformation similar to axios's `transformRequest`. You can provide a function or array of functions that transform the request body before serialization. The transformation is applied after interceptors and before serialization.
-
-```typescript
-// Global configuration
-const client = createHttpClient({
-  transformRequest: [(data, headers) => {
-    // Add timestamp to all requests
-    if (data && typeof data === 'object') {
-      return { ...data, timestamp: Date.now() };
-    }
-    return data;
-  }]
-});
-
-// Per-request configuration
-await client.post('/api', { foo: 'bar' }, {
-  transformRequest: [(data) => ({ ...data, extra: 'value' })]
-});
-```
-
-### Credentials Policy
-
-Nexa supports the standard fetch `credentials` option as well as axios-compatible `withCredentials` boolean. This controls whether cookies and other credentials are sent with cross-origin requests.
-
-```typescript
-// Using fetch-style credentials
-await client.get('/api', { credentials: 'include' });
-
-// Using axios-style withCredentials (true = 'include', false = 'same-origin')
-await client.post('/api', data, { withCredentials: true });
-
-// Global configuration
-const client = createHttpClient({
-  credentials: 'same-origin', // Default: 'omit'
-  // or
-  withCredentials: true, // Equivalent to credentials: 'include'
-});
-```
-
-Priority: `credentials` overrides `withCredentials` if both are specified.
-
-### Adapter Pattern
-
-Nexa supports custom adapters for mocking, testing, or integrating with different environments (Cloudflare Workers, Node.js, etc.). The adapter has the same signature as the global `fetch` function.
-
-```typescript
-// Mock adapter for testing
-const mockAdapter = async (input: RequestInfo, init?: RequestInit) => {
-  return new Response(JSON.stringify({ mock: true }), { status: 200 });
-};
-
-// Global adapter
-const client = createHttpClient({
-  adapter: mockAdapter,
-});
-
-// Per-request adapter (overrides global)
-await client.get('/api', { adapter: mockAdapter });
-```
-
-Adapters can be used to intercept requests before they reach the network, enabling easy testing without actual HTTP calls.
-
-### Mocking Utilities (axios-mock-adapter style)
-
-For more sophisticated testing scenarios, Nexa provides a mocking utility similar to `axios-mock-adapter`. This allows you to configure mock responses for specific routes and HTTP methods.
-
-```typescript
-import { createHttpClient } from '@bereasoftware/nexa';
-import { createMockClient } from '@bereasoftware/nexa/testing';
-
-const client = createHttpClient({ baseURL: 'https://api.example.com' });
-const mockClient = createMockClient(client);
-
-// Configure mock responses
-mockClient.onGet('/users').reply(200, [{ id: 1, name: 'John' }]);
-mockClient.onPost('/users').reply(201, { id: 2, name: 'Jane' });
-mockClient.onPut('/users/1').reply(200, { id: 1, name: 'Updated' });
-mockClient.onDelete('/users/1').reply(204);
-
-// Network error simulation
-mockClient.onGet('/error').networkError('Network failure');
-
-// Use the mock-enabled client for requests
-const result = await mockClient.client.get('/users');
-if (result.ok) {
-  console.log(result.value.data); // [{ id: 1, name: 'John' }]
-}
-
-// Advanced: reply once, then fall through
-mockClient.onGet('/once').replyOnce(200, { data: 'first' });
-// Second call to same route will not match (unless passthrough enabled)
-
-// Advanced: function-based responses
-mockClient.onGet('/dynamic').reply((config) => ({
-  status: 200,
-  data: { url: config.url, query: config.query },
-}));
-
-// Reset mock routes between tests
-mockClient.reset();
-```
-
-**Key features:**
-- **Fluent API**: `onGet(url).reply(status, data)` similar to axios-mock-adapter
-- **URL patterns**: Support string exact match or RegExp
-- **Response functions**: Dynamic responses based on request config
-- **Call limits**: `replyOnce()` for one-time mock
-- **Network errors**: Simulate network failures with `networkError()`
-- **Timeout simulation**: `timeout()` method for timeout testing
-- **Passthrough mode**: Optionally forward unmatched requests to real adapter
-- **Base URL support**: Automatically strips baseURL when matching
-
-**Options** for `createMockClient`:
-- `passthrough`: Forward unmatched requests to original adapter (default: `false`)
-- `baseURL`: Base URL to strip when matching routes
-- `delay`: Default delay for all responses (ms)
-
-### Transport Configuration
-
-Nexa supports multiple transport layers for different environments. By default, it uses the global `fetch` API (available in browsers and Node.js 18+). For advanced Node.js scenarios, you can use the native HTTP/1.1 or HTTP/2 modules with keep-alive, connection pooling, and other Node-specific optimizations.
-
-```typescript
-import { createHttpClient } from '@bereasoftware/nexa';
-
-// Use Node.js HTTP/1.1 with keep-alive and connection pooling
-const client = createHttpClient({
-  transport: 'node', // 'fetch' (default), 'node', or 'http2'
-  nodeOptions: {
-    keepAlive: true,
-    maxSockets: 50,
-    maxFreeSockets: 10,
-    maxRequestsPerSocket: 0, // unlimited
-    timeout: 60000,
-  },
-});
-
-// Use HTTP/2 for better performance with multiplexing
-const http2Client = createHttpClient({
-  transport: 'http2',
-  nodeOptions: {
-    http2Settings: {
-      enablePush: false,
-    },
-  },
-});
-
-// Override transport per request
-await client.get('/api', {
-  transport: 'http2',
-  nodeOptions: { keepAlive: true },
-});
-```
-
-**Note:** Node transports (`'node'` and `'http2'`) are only available in Node.js environments. In browsers, they will fall back to `'fetch'` automatically.
-
-**Available options in `nodeOptions`:**
-- `keepAlive` (boolean): Enable keep-alive connections (default: `true`)
-- `maxSockets` (number): Maximum sockets per host (default: `50`)
-- `maxFreeSockets` (number): Maximum free sockets to keep open (default: `10`)
-- `maxRequestsPerSocket` (number): Maximum requests per socket (default: `0` = unlimited)
-- `timeout` (number): Socket timeout in milliseconds (default: `60000`)
-- `http2` (boolean): Deprecated - use `transport: 'http2'` instead
-- `http2Settings` (Record<string, unknown>): HTTP/2 specific settings (only for `transport: 'http2'`)
-
 ### Response Types
 
 Control how the response body is parsed:
@@ -533,66 +363,10 @@ const result = await client.get("/slow-endpoint", { timeout: 5000 });
 // Timeout produces a specific error code
 if (!result.ok && result.error.code === "TIMEOUT") {
   console.log("Request timed out");
+}
 ```
 
-Nexa also supports differentiated timeouts for connection and response phases, going beyond axios/fetch's single timeout. You can specify timeouts as an object:
-
-```typescript
-// Differentiated timeouts
-await client.get('/api', {
-  timeout: {
-    connection: 3000,  // 3 seconds to establish connection
-    response: 10000,   // 10 seconds to receive complete response
-    total: 15000       // Optional total timeout (overrides connection/response)
-  }
-});
-
-// Backward compatibility: number still works (total timeout)
-await client.get('/api', { timeout: 5000 });
-```
-
-Error codes: `TIMEOUT` for connection/total timeouts, `RESPONSE_TIMEOUT` for response phase timeouts.
-
-### Debug Logging
-
-Nexa provides axios-like debug logging for development. Enable it globally or per-request:
-
-```typescript
-// Global debug logging
-const client = createHttpClient({
-  debug: true, // basic logs
-  // debug: 'verbose', // detailed logs
-});
-
-// Per-request override
-await client.get('/api', { debug: 'verbose' });
-```
-
-Logs include request method/URL, response status, duration, errors, retries, and cache hits. With `verbose` mode, you also see transformed requests, interceptor outputs, and response data.
-
-#### Custom Logger
-
-You can provide a custom logger function to redirect logs to your preferred logging system:
-
-```typescript
-const client = createHttpClient({
-  debug: true,
-  logger: (message, data) => {
-    // Send to your logging service
-    myLogger.info(message, data);
-  },
-});
-
-// Request-level logger override
-await client.post('/api', data, { 
-  debug: true,
-  logger: (msg, data) => console.warn(msg, data)
-});
-```
-
-The logger receives two arguments: the log message (prefixed with `[Nexa HTTP]`) and optional data object.
-
----
+---
 
 ## Retry Strategies
 
@@ -607,27 +381,6 @@ const result = await client.get("/unstable-api", {
 // Retries up to 3 times with exponential backoff + jitter
 ```
 
-### Custom Retry Condition
-
-You can provide a custom condition function to decide which errors should be retried:
-
-```typescript
-const result = await client.get('/api', {
-  retry: {
-    maxAttempts: 3,
-    backoffMs: 1000,
-    on: (error) => {
-      // Retry only on network errors or 5xx status
-      return error.code === 'NETWORK_ERROR' || 
-             (error.status >= 500 && error.status < 600) ||
-             error.message.includes('ECONNRESET')
-    }
-  }
-});
-```
-
-The `on` function receives the `HttpErrorDetails` and attempt number, and returns `true` if the request should be retried. If `on` is not provided, the default condition (5xx status, network errors, timeouts) is used.
-
 ### AggressiveRetry
 
 Retries all errors up to max attempts with minimal delay:
@@ -1201,6 +954,120 @@ manager.register(rateLimitPlugin);
 
 ---
 
+## Dev Overlay
+
+Built-in visual development tool for debugging and monitoring HTTP requests in real-time.
+
+```typescript
+import { createHttpClient, createDevOverlay } from "@bereasoftware/nexa";
+
+// Create the Dev Overlay - appears automatically
+const { tracker, ui } = createDevOverlay({
+  position: "bottom-right", // top-right, top-left, bottom-left
+  theme: "dark",
+  maxHistory: 200,
+});
+
+// Pass the tracker to the HTTP client
+const client = createHttpClient({
+  baseURL: "https://api.example.com",
+  devTracker: tracker,
+});
+
+// That's it! All requests will appear in the overlay
+const result = await client.get("/users");
+```
+
+### Features
+
+- **Keyboard toggle** — Press `Ctrl+Shift+N` or `Cmd+Shift+N` to show/hide
+- **Request list** — Shows method, status, URL, duration and badges (cache, retries)
+- **Real-time metrics** — Total requests, average, throughput, success, failed
+- **Search and filter** — Filter by URL, method or status (`Ctrl+F`)
+- **Request detail** — Click any request to see headers, body and timing
+- **Quick retry** — Replays the selected URL with `fetch` for fast verification
+- **Keyboard shortcuts** — `Ctrl+Shift+N` / `Cmd+Shift+N` (toggle), `Escape` (close), `Ctrl+F` / `Cmd+F` (search)
+
+### API
+
+```typescript
+createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevOverlayUI }
+```
+
+**Configuration options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Tracker-level flag you can use to enable or disable the overlay flow in your app |
+| `position` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Overlay position |
+| `theme` | `'dark' \| 'light'` | `'dark'` | Typed visual theme; the current UI is optimized for dark mode |
+| `maxHistory` | `number` | `500` | Maximum requests in history |
+| `keyboardShortcut` | `string` | `'ctrl+shift+n'` | Keyboard shortcut |
+
+**Behavior notes:**
+
+- `createDevOverlay()` is a singleton. Multiple calls reuse the same instance.
+- `theme` is typed as `'dark' | 'light'`, but the current UI is primarily designed for dark mode.
+- The retry button uses direct `fetch()` for quick revalidation; it does not automatically replay interceptors or advanced `HttpClient` configuration.
+
+**Note:** Advanced request options such as `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions`, and `autoFormData` are already typed, but not all of them are fully wired into the main `HttpClient` pipeline in this release.
+
+**UI methods:**
+
+```typescript
+ui.show()   // Show overlay
+ui.hide()    // Hide overlay
+ui.toggle()  // Toggle visibility
+ui.destroy() // Remove the panel from the DOM
+
+tracker.clear()          // Clear history
+tracker.getHistory()      // Get all requests
+tracker.getMetrics()      // Get metrics
+tracker.getConfig()       // Get resolved config
+tracker.onChange((request) => {}) // Listen for new tracked requests
+```
+
+**Module methods:**
+
+```typescript
+getDevOverlay() // Get current { tracker, ui } or null if not created yet
+destroyDevOverlay() // Destroy the current singleton instance
+```
+
+**Exposed data shapes:**
+
+```typescript
+type TrackedRequest = {
+  id: string;
+  method: string;
+  url: string;
+  status?: number;
+  duration: number;
+  timestamp: number;
+  cached: boolean;
+  ok: boolean;
+  code?: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  responseHeaders?: Record<string, string>;
+  retryCount: number;
+};
+
+type DevMetrics = {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  cachedRequests: number;
+  avgDuration: number;
+  maxDuration: number;
+  minDuration: number;
+  requestsPerSecond: number;
+  slowestRequests: TrackedRequest[];
+};
+```
+
+---
+
 ## Streaming
 
 Handle large files and streaming responses:
@@ -1349,22 +1216,6 @@ deferred.reject(new Error("failed"));
 | `MAX_RETRIES`      | All retry attempts exhausted                            |
 | `UNKNOWN_ERROR`    | Unclassified error                                      |
 
-### Enhanced Error Context
-
-Nexa provides rich error context similar to axios, including the original request, response, and configuration in error objects. This makes debugging easier.
-
-```typescript
-const result = await client.get('/api');
-if (!result.ok) {
-  const { request, response, config } = result.error;
-  console.log('Failed request URL:', request?.url);
-  console.log('Response status:', response?.status);
-  console.log('Config timeout:', config?.timeout);
-}
-```
-
-All errors now include `request`, `response` (if available), and `config` properties.
-
 ### HttpError Class
 
 ```typescript
@@ -1474,23 +1325,40 @@ Nexa ships in multiple module formats:
 
 ## Development
 
-### Tests
-
-**205 tests in total**: 88 HTTP Client tests + 69 utilities tests + 24 mock tests + 4 Node adapter tests + 20 additional tests
-
-```bash
-# Run all tests
-npm test
+### Tests
+
+```bash
+# Run all tests
+npm test
 
 # Watch mode
 npm run test:watch
 
 # Coverage report
 npm run test:coverage
+
+# Test UI
+npm run test:ui
 ```
 
 Tests use **Vitest** (globals mode) with BDD style (`describe`/`it`/`expect`).
 
+### Linting & Formatting
+
+```bash
+# Type check
+npm run lint
+
+# Fix style issues
+npm run lint:fix
+
+# Format code
+npm run format
+
+# Check formatting
+npm run format:check
+```
+
 ### Build
 
 ```bash
@@ -1517,57 +1385,33 @@ dist/
   └── types/            (TypeScript .d.ts declarations)
 ```
 
-### Test Coverage
-
-**Overall Coverage: 71.4%** — solid unit test coverage with mock-based HTTP testing
-
-| Component   | Coverage   | Details                           |
-| ----------- | ---------- | --------------------------------- |
-| HTTP Client | **66.7%** | 67.3% branches, 67.0% functions |
-| Types       | **100%**   | Perfect type coverage             |
-| Testing     | **93.7%**  | 85.1% branches, 95.8% functions   |
-| Utils       | **71.8%**  | 66.7% branches, 81.1% functions   |
-
-**HTTP Client** (`test/http-client.test.ts`) — **88 tests**:
-
-- ✓ Core methods: create, GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS (7 tests)
-- ✓ Retry strategies & timeouts (3 tests)
-- ✓ Interceptors & disposal (5 tests)
-- ✓ Caching & validation (4 tests)
-- ✓ Type safety & extensions (3 tests)
-- ✓ Pagination & polling (5 tests)
-- ✓ Response type handling: all 8+ types + auto-detection (13 tests)
-- ✓ Binary content-type detection: image/_, audio/_, video/\*, octet-stream (5 tests)
-- ✓ Body serialization: JSON, null, strings, Blob, URLSearchParams, ArrayBuffer, TypedArray, FormData, ReadableStream (7 tests)
-- ✓ Error normalization: TimeoutError, AbortError, TypeError, unknown, NETWORK_ERROR (5+ tests)
-- ✓ Request management: activeRequests, cancelAll, clearCache (2 tests)
-- ✓ Module exports verification: all 8 export categories (8 tests)
-- ✓ Plugin integration: LoggerPlugin, MetricsPlugin event handlers (7 tests)
-- ✓ Advanced configuration: null body, direct Blob, abort messages (5+ tests)
-
-**Utilities** (`test/utils.test.ts`) \u2014 **69 tests**:
-
-- \u2713 Validators: schema, required fields, type checks (4 tests)
-- \u2713 Transformers: snake↔camel case, flatten, projection, wrapper (5 tests)
-- \u2713 Retry Strategies: Aggressive, Conservative, Circuit Breaker (10 tests)
-- \u2713 Timeout & Retry: withTimeout, retry function (6 tests)
-- \u2713 Cache: CacheStore CRUD, TTL expiry (5 tests)
-- \u2713 Deduplication: RequestDeduplicator sharing, cleanup (3 tests)
-- \u2713 Middleware Pipeline: ordering, next() guard, legacy pipeline (3 tests)
-- \u2713 Cache Middleware: GET caching, POST bypass (2 tests)
-- \u2713 Dedup Middleware: GET dedup, POST bypass (2 tests)
-- \u2713 Typed Generics: TypedResponse, TypedObservable (map/filter), Defer, type guards, branded types (9 tests)
-- \u2713 Plugins: PluginManager, LoggerPlugin, MetricsPlugin, CachePlugin, DedupePlugin (5 tests)\n\n### Coverage Limitations & Realistic Ceiling\n\nUnit test coverage plateaus around **75-80%** due to inherent mock-based testing limitations:\n\n**Why not 95%?**\n- **Streaming features** (~3-5% gap): Download progress tracking uses `ReadableStream.getReader()` which requires real HTTP streams—not mockable with `fetch-mock`\n- **Utility examples** (~5-10% gap): Middleware patterns and reference code are intentionally not exercised in production \n- **Export-only files** (~2-3% gap): `http-client/index.ts` verified via import validation, not unit testable\n\n**Realistic maximums:**\n- Unit tests + mocks: **~80-85%** ceiling (current: 71.4%)\n- Integration tests required: Would reach 90%+ but beyond this project\u2019s scope\n\nThe 71.4% coverage represents comprehensive testing of all **production code paths** that can be reached via HTTP mocks.
+### Benchmark
 
----
+```bash
+# Run performance benchmark
+npm run benchmark
+```
 
-## Contributing
+### Examples
 
-Want to contribute to Nexa? Please read our [contributing guide](CONTRIBUTING.md) and [code of conduct](CODE_OF_CONDUCT.md).
+See the `examples/` folder for usage examples with different frameworks:
 
-## Security
+- `react-example.ts` — Usage with React
+- `vue-example.ts` — Usage with Vue
+- `svelte-example.ts` — Usage with Svelte
+- `node-example.ts` — Usage with Node.js
 
-To report security vulnerabilities, see our [security policy](SECURITY.md).
+### Test Coverage
+
+Generate the latest report locally:
+
+```bash
+npm run test:coverage
+```
+
+Coverage changes as features evolve, so the generated report should be treated as the source of truth instead of hardcoded percentages in the README.
+
+---
 
 ## License