react-native-fetch-client 0.1.0 → 0.1.2-Beta

package/README.md

@@ -1,12 +1,13 @@
 # react-native-fetch-client
 
 > **A high-performance, Fetch-native HTTP client for TypeScript & JavaScript (React Native, Expo, modern browsers, and Node.js).**  
-> Zero runtime dependencies • Dual ESM & CJS • In-flight Request Deduplication • Response Caching • Auth Mutex • Offline Queue • Streaming Progress
+> Zero runtime dependencies • Dual ESM & CJS • In-flight Request Deduplication • Response Caching & SWR • Auth Mutex • Offline Queue • Streaming Progress
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![TypeScript & JavaScript](https://img.shields.io/badge/Languages-TypeScript%20%7C%20JavaScript-blue)](https://www.typescriptlang.org/)
 [![Runtime Dependencies](https://img.shields.io/badge/Dependencies-0-success.svg)](package.json)
 [![Tests: 186 passing](https://img.shields.io/badge/Tests-186%20Passing-brightgreen.svg)](test)
+[![Expo & React Native](https://img.shields.io/badge/React%20Native-Bridgeless%20%26%20New%20Arch%20Ready-success.svg)](https://reactnative.dev)
 
 ---
 
@@ -14,51 +15,52 @@
 
 For in-depth explanations, execution pipeline flows, and implementation guides, explore the dedicated documentation suite:
 
-* 🏛️ **[Architecture & Execution Pipeline Flow](./docs/architecture-flow.md)** — Step-by-step trace through the 16-stage request pipeline.
-* 🛠️ **[Core Features & Usage Guide](./docs/core-features-guide.md)** — Client setup, HTTP methods, path params, form encoding, safe requests, and unwrap.
-* ⚡ **[Caching & Stale-While-Revalidate](./docs/caching-and-swr.md)** — In-memory LRU, persistent storage adapters (MMKV/AsyncStorage), ETag/304, and SWR.
-* 🛡️ **[Resilience, Retries & Offline Queue](./docs/resilience-and-offline.md)** — Exponential backoff, jitter, circuit breakers, concurrency throttling, and offline replay.
-* 🤖 **[Streaming, AI & File Uploads](./docs/streaming-and-uploads.md)** — SSE & AI LLM token streams, WHATWG streams, file uploads, and upload/download progress.
-* 🔑 **[Authentication & Security](./docs/auth-and-security.md)** — Bearer presets, single-flight 401 refresh mutex, token rotation, and header redaction.
-* 🔄 **[Auto-Pagination Helper](./docs/auto-pagination.md)** — Traversal strategies (`page`, `offset`, `cursor`, `linkHeader`) and async generator streaming.
-* 🧪 **[Testing & Mock Adapter Guide](./docs/testing-and-mocking.md)** — Declarative unit testing (`createMockAdapter`), route stubbing, and call assertions.
+* 🏛️ **[Architecture & Execution Pipeline Flow](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/architecture-flow.md)** — Step-by-step trace through the 16-stage request pipeline.
+* 🛠️ **[Core Features & Usage Guide](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/core-features-guide.md)** — Client setup, HTTP methods, path params, form encoding, safe requests, and unwrap.
+* ⚡ **[Caching & Stale-While-Revalidate](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/caching-and-swr.md)** — In-memory LRU, persistent storage adapters (MMKV/AsyncStorage), ETag/304, and SWR.
+* 🛡️ **[Resilience, Retries & Offline Queue](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/resilience-and-offline.md)** — Exponential backoff, jitter, circuit breakers, concurrency throttling, and offline replay.
+* 🤖 **[Streaming, AI & File Uploads](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/streaming-and-uploads.md)** — SSE & AI LLM token streams, WHATWG streams, file uploads, and upload/download progress.
+* 🔑 **[Authentication & Security](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/auth-and-security.md)** — Bearer presets, single-flight 401 refresh mutex, token rotation, and header redaction.
+* 🔄 **[Auto-Pagination Helper](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/auto-pagination.md)** — Traversal strategies (`page`, `offset`, `cursor`, `linkHeader`) and async generator streaming.
+* 🧪 **[Testing & Mock Adapter Guide](https://github.com/arunkumarArjun/react-native-fetch-client/blob/main/docs/testing-and-mocking.md)** — Declarative unit testing (`createMockAdapter`), route stubbing, and call assertions.
 
 ---
 
 ## Table of Contents
 
 - [Why react-native-fetch-client?](#why-react-native-fetch-client)
+- [Feature Comparison](#feature-comparison)
 - [Installation](#installation)
-- [Developer Documentation Guides](#-developer-documentation-guides)
 - [Quick Start (TypeScript & JavaScript)](#quick-start)
   - [TypeScript (ESM)](#1-typescript-esm)
   - [JavaScript (ES Modules - `import`)](#2-javascript-es-modules---import)
   - [JavaScript (CommonJS - `require`)](#3-javascript-commonjs---require)
 - [HTTP Methods & Shorthands](#http-methods--shorthands)
+- [Go/Rust-Style Safe Requests (`api.safe.*`)](#gorust-style-safe-requests-apisafe)
 - [Standard Schema Validation (`schema`)](#standard-schema-validation-schema)
 - [Auto-Pagination Helper (`api.paginate`)](#auto-pagination-helper-apipaginate)
 - [Native AI & SSE Streaming (`api.stream`)](#native-ai--sse-streaming-apistream)
-- [Go/Rust-Style Safe Requests (`api.safe.*`)](#gorust-style-safe-requests-apisafe)
+- [Declarative Testing Mock Adapter (`createMockAdapter`)](#declarative-testing-mock-adapter-createmockadapter)
+- [Response Caching, SWR & Persistent Storage](#response-caching-swr--persistent-storage)
+  - [In-Memory LRU Cache](#1-in-memory-lru-cache)
+  - [Persistent Storage (MMKV / AsyncStorage)](#2-persistent-storage-adapter-storage)
+  - [Stale-While-Revalidate (SWR)](#3-stale-while-revalidate-swr)
+  - [RFC 7234 Conditional Validation (ETag & 304)](#4-rfc-7234-conditional-validation-etag--304)
 - [Client Concurrency Throttler (`maxConcurrentRequests`)](#client-concurrency-throttler-maxconcurrentrequests)
 - [Circuit Breaker Pattern (`circuitBreaker`)](#circuit-breaker-pattern-circuitbreaker)
-- [RFC 7234 Conditional Caching (`ETag` & `304 Not Modified`)](#rfc-7234-conditional-caching-etag--304-not-modified)
-- [Persistent Storage Response Cache (`storage`)](#persistent-storage-response-cache-storage)
-- [Stale-While-Revalidate (`strategy: 'stale-while-revalidate'`)](#stale-while-revalidate-strategy-stale-while-revalidate)
-- [Declarative Testing Mock Adapter (`createMockAdapter`)](#declarative-testing-mock-adapter-createmockadapter)
-- [Path Parameter Interpolation (`pathParams`)](#path-parameter-interpolation-pathparams)
+- [In-Flight Request Deduplication (`dedup`)](#in-flight-request-deduplication-dedup)
+- [Resilient Retry Engine (`retry`)](#resilient-retry-engine-retry)
+- [Auth & Token Refresh Mutex (`auth`)](#auth--token-refresh-mutex-auth)
 - [Bearer Token Preset (`bearerToken`)](#bearer-token-preset-bearertoken)
+- [Path Parameter Interpolation (`pathParams`)](#path-parameter-interpolation-pathparams)
 - [File Upload Helper (`api.upload`)](#file-upload-helper-apiupload)
+- [Upload & Download Progress](#upload--download-progress)
+- [Offline Request Queue (`createOfflineQueue`)](#offline-request-queue-createofflinequeue)
 - [Response Unwrapping (`unwrap: true`)](#response-unwrapping-unwrap-true)
 - [Diagnostic Debug Logger (`debug: true`)](#diagnostic-debug-logger-debug-true)
-- [In-Flight Request Deduplication](#in-flight-request-deduplication)
-- [Response Caching (LRU)](#response-caching-lru)
-- [Resilient Retry Engine](#resilient-retry-engine)
-- [Auth & Token Refresh Mutex](#auth--token-refresh-mutex)
-- [Upload & Download Progress](#upload--download-progress)
-- [Offline Request Queue](#offline-request-queue)
 - [Node.js Enterprise Proxies & Dispatcher](#nodejs-enterprise-proxies--dispatcher)
 - [Migration Guide (From Axios)](#migration-guide-from-axios)
-- [Testing Locally with Your Team](#testing-locally-with-your-team)
+- [License](#license)
 
 ---
 
@@ -70,14 +72,33 @@ Traditional HTTP clients like Axios were built over a decade ago around browser
 
 1. **Zero Production Dependencies (`dependencies: {}`)**: Eliminates supply-chain risks, CVE vulnerabilities, and `node_modules` bloat.
 2. **First-Class TypeScript & Pure JavaScript**: Strict TypeScript generics plus full CommonJS (`require`) and ES Module (`import`) support.
-3. **Native Multi-Runtime**: 100% compliant with WHATWG standards (`fetch`, `ReadableStream`, `AbortController`). Identical behavior across React Native, Expo, iOS, Android, modern browsers, Bun, and Node.js 18+.
+3. **Native Multi-Runtime**: 100% compliant with WHATWG standards (`fetch`, `ReadableStream`, `AbortController`). Identical behavior across React Native (New Architecture & Bridgeless), Expo, iOS, Android, modern browsers, Bun, and Node.js 18+.
 4. **Single-Flight Auth Mutex**: Solves the classic race condition where parallel requests fail on 401s and trigger multiple refresh token calls.
 5. **In-Flight Deduplication**: Coalesces concurrent identical `GET` requests into a single network flight with partial cancellation safety.
-6. **Mutation-Aware LRU Cache**: Automatically invalidates cached GET routes whenever a POST/PUT/PATCH/DELETE mutation succeeds.
+6. **Mutation-Aware LRU Cache & SWR**: Delivers 0ms instant cached data with background revalidation, and automatically invalidates cached GET routes whenever a mutation succeeds.
 7. **Persistent Offline Queue**: Queues mutations offline and replays them sequentially with RFC-standard `Idempotency-Key` headers when reconnected.
 
 ---
 
+## Feature Comparison
+
+| Feature | `react-native-fetch-client` | Axios (`axios`) | Ky (`ky`) | Native Fetch |
+| :--- | :---: | :---: | :---: | :---: |
+| **Runtime Dependencies** | **0 (Zero)** | ~4-6 | **0** | **0** |
+| **React Native New Architecture** | ✅ Native Bridgeless | ⚠️ Legacy XHR | ⚠️ Needs Polyfills | ✅ Native |
+| **Single-Flight 401 Auth Mutex** | ✅ Built-in | ❌ Manual Code | ❌ None | ❌ None |
+| **SWR Caching Strategy (0ms)** | ✅ Built-in | ❌ Needs Plugin | ❌ None | ❌ None |
+| **Persistent Storage (MMKV / Storage)** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
+| **In-Flight Request Deduplication** | ✅ Built-in | ❌ Needs Plugin | ❌ None | ❌ None |
+| **Circuit Breaker** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
+| **Auto-Pagination Helper** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
+| **Declarative Mock Adapter** | ✅ Built-in | ❌ Separate Pkg | ❌ None | ❌ None |
+| **Go/Rust Safe Requests (`api.safe`)** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
+| **Standard Schema / Zod Validation** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
+| **Offline Mutation Queue** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
+
+---
+
 ## Installation
 
 ```bash
@@ -214,156 +235,27 @@ const res = await api.request({
 
 ---
 
-## Request Configuration
+## Go/Rust-Style Safe Requests (`api.safe.*`)
 
-Options can be specified globally in `createClient(config)` or overridden per-request:
+Eliminate `try/catch` boilerplate. The `api.safe.*` namespace returns clean `[data, error]` result tuples where exactly one value is populated:
 
 ```typescript
-const config = {
-  baseURL: 'https://api.example.com',
-  timeout: 10000,                       // Timeout in ms (0 = disabled)
-  headers: { 'Accept': 'application/json' },
-  params: { page: 1, limit: 20 },       // Query parameters: ?page=1&limit=20
-  responseType: 'json',                 // 'json' | 'text' | 'blob' | 'arrayBuffer' | 'none'
-  credentials: 'same-origin',           // 'same-origin' | 'include' | 'omit'
-  redirect: 'follow',                   // 'follow' | 'manual' | 'error'
-  formUrlEncoded: false,                // Serializes plain objects to URL-encoded form
-  signal: controller.signal,            // Caller cancellation signal
-  onDownloadProgress: (event) => {},    // Streaming download callback
-  onUploadProgress: (event) => {},      // Outgoing upload progress callback
-  retry: { attempts: 3 },               // Retry policy
-  cache: { enabled: true, ttl: 30000 }, // Response cache
-  dedup: { enabled: true },             // In-flight request deduplication
-  auth: { skip: true },                 // Bypass token injection for public routes
-  dispatcher: customAgent,              // Undici ProxyAgent (Node.js proxies)
-};
-```
-
----
-
-## Response Structure
-
-Every successful call resolves to an `HttpResponse` object:
-
-```javascript
-const response = await api.get('/users');
-
-console.log(response.data);       // Parsed response body (JSON, text, or Blob)
-console.log(response.status);     // HTTP status code (e.g. 200)
-console.log(response.statusText); // HTTP status text (e.g. "OK")
-console.log(response.headers);    // Lowercased response headers object
-console.log(response.cached);     // true if returned from local LRU cache
-console.log(response.fromDedup);  // true if shared via concurrent in-flight flight
-console.log(response.config);     // Resolved configuration used for request
-console.log(response.request);    // Native WHATWG Request object
-```
-
----
-
-## Error Handling
-
-Errors thrown by `react-native-fetch-client` are typed subclasses of `FetchNativeError`. Type guard functions are exported for safe discrimination:
+const [user, error] = await api.safe.get<User>('/users/123');
 
-#### TypeScript:
-```typescript
-import {
-  isHttpError,
-  isNetworkError,
-  isTimeoutError,
-  isCancelError,
-  isRetryExhaustedError,
-} from 'react-native-fetch-client';
-
-try {
-  await api.get('/orders');
-} catch (err: unknown) {
-  if (isHttpError(err)) {
-    // Non-2xx response from the server (e.g. 400, 404, 500)
-    console.error(`HTTP ${err.status}:`, err.data);
-    console.error('Headers:', err.headers);
-  } else if (isTimeoutError(err)) {
-    // Request timed out past config.timeout
-    console.error(`Timed out after ${err.timeoutMs}ms`);
-  } else if (isCancelError(err)) {
-    // Request was aborted by caller via AbortController
-    console.warn('Request canceled by caller');
-  } else if (isRetryExhaustedError(err)) {
-    // Retried N times and all attempts failed
-    console.error(`Failed after ${err.attempts} attempts. Last error:`, err.lastError);
-  } else if (isNetworkError(err)) {
-    // Offline, DNS resolution failure, or TCP connection reset
-    console.error('Network connection error:', err.message);
-  }
+if (error) {
+  console.error(`Request failed (${error.code}):`, error.message);
+  return;
 }
-```
 
-#### JavaScript:
-```javascript
-const { isHttpError, isTimeoutError, isCancelError } = require('react-native-fetch-client');
-
-try {
-  await api.get('/orders');
-} catch (err) {
-  if (isHttpError(err)) {
-    console.error('Server returned HTTP', err.status, err.data);
-  } else if (isTimeoutError(err)) {
-    console.error('Request timed out!');
-  } else if (isCancelError(err)) {
-    console.warn('Request was aborted.');
-  } else {
-    console.error('Network or system error:', err.message);
-  }
-}
-```
-
----
-
-## Interceptors
-
-Interceptors allow you to transform outgoing requests or inspect/recover from responses:
-
-```javascript
-// 1. Add Request Interceptor
-const reqId = api.interceptors.request.use(
-  (config) => {
-    config.headers = {
-      ...config.headers,
-      'X-Client-Platform': 'mobile',
-    };
-    return config;
-  },
-  (error) => Promise.reject(error)
-);
-
-// 2. Add Response Interceptor
-const resId = api.interceptors.response.use(
-  (response) => {
-    return response;
-  },
-  async (error) => {
-    if (error.status === 403) {
-      console.warn('Forbidden! Redirecting to permissions page...');
-    }
-    return Promise.reject(error);
-  }
-);
-
-// 3. Eject Interceptors
-api.interceptors.request.eject(reqId);
-api.interceptors.response.eject(resId);
-
-// 4. Clear all interceptors
-api.interceptors.request.clear();
+// Guaranteed non-null and fully typed!
+console.log('User loaded:', user.name);
 ```
 
 ---
 
 ## Standard Schema Validation (`schema`)
 
-Validate and parse incoming response payloads directly at runtime with **zero dependencies**. `react-native-fetch-client` uses duck-typing to seamlessly support:
-- [Standard Schema v1 (`~standard`)](https://standardschema.dev/) (Zod 3.24+, Valibot, ArkType)
-- Zod-like schemas (`.parse()`, `.safeParse()`)
-- Plain validation functions `(data) => T`
+Validate response payloads at runtime using the **Standard Schema v1** specification, Zod, Valibot, or custom validation functions:
 
 ```typescript
 import { z } from 'zod';
@@ -374,188 +266,216 @@ const UserSchema = z.object({
   email: z.string().email(),
 });
 
-// Throws ValidationError if response payload does not conform to the schema:
-const response = await api.get('/user/me', {
+// Throws ValidationError with detailed issue paths if schema fails:
+const res = await api.get('/users/1', {
   schema: UserSchema,
 });
 
-console.log(response.data.email); // Fully typed and runtime-validated!
+console.log(res.data.email);
 ```
 
 ---
 
-## Native AI & SSE Streaming (`api.stream`)
+## Auto-Pagination Helper (`api.paginate`)
 
-Stream Server-Sent Events (SSE) or chunked LLM completions line-by-line using standard WHATWG `ReadableStream` and `AsyncGenerator`:
+Traverse multi-page APIs seamlessly using async generators (`for await`) or collect all pages into an array in one call:
 
 ```typescript
-// Connects to SSE endpoint with Accept: text/event-stream
-for await (const chunk of api.stream('/v1/chat/completions', {
-  method: 'POST',
-  body: { model: 'gpt-4o', stream: true, messages: [{ role: 'user', content: 'Hello!' }] },
+// 1. Stream items individually with for-await (Memory efficient!)
+for await (const user of api.paginate<User>('/users', {
+  pagination: { type: 'page', pageParam: 'page', pageSize: 20 },
 })) {
-  console.log(`Event: ${chunk.event}, Data: ${chunk.data}`);
+  console.log(user.name);
 }
+
+// 2. Fetch all pages and flatten into an array:
+const allPosts = await api.paginate.all<Post>('/posts', {
+  pagination: { type: 'page', pageParam: '_page', limitParam: '_limit', limit: 10 },
+});
+console.log(`Fetched ${allPosts.length} posts across all pages!`);
 ```
 
+Supports 4 pagination strategies: `page`, `offset`, `cursor`, and RFC 5988/8288 standard `Link` headers.
+
 ---
 
-## Go/Rust-Style Safe Requests (`api.safe.*`)
+## Native AI & SSE Streaming (`api.stream`)
 
-Eliminate `try/catch` boilerplate. The `api.safe.*` namespace returns clean `[data, error]` result tuples:
+Consume Server-Sent Events (SSE) and AI LLM token streams (OpenAI, Anthropic, Gemini, Ollama) using native async generators:
 
 ```typescript
-const [user, error] = await api.safe.get<User>('/users/123');
+const eventStream = api.stream('/chat/completions', {
+  method: 'POST',
+  body: {
+    model: 'gpt-4o',
+    stream: true,
+    messages: [{ role: 'user', content: 'Hello!' }],
+  },
+});
 
-if (error) {
-  console.error(`Request failed (${error.code}):`, error.message);
-  return;
+for await (const chunk of eventStream) {
+  if (chunk.data === '[DONE]') break;
+  const parsed = JSON.parse(chunk.data);
+  process.stdout.write(parsed.choices[0]?.delta?.content ?? '');
 }
-
-console.log('User loaded:', user.name);
 ```
 
 ---
 
-## Client Concurrency Throttler (`maxConcurrentRequests`)
+## Declarative Testing Mock Adapter (`createMockAdapter`)
 
-Cap the maximum number of simultaneous in-flight sockets across your entire application to avoid browser connection limits (HTTP/1.1 6-socket bottleneck) or mobile network congestion:
+Zero-dependency unit testing for your network calls. Stub routes, simulate network timeouts or offline errors, and assert call history:
 
 ```typescript
-const api = createClient({
-  baseURL: 'https://api.example.com',
-  maxConcurrentRequests: 4, // Max 4 concurrent sockets; excess wait in FIFO queue
-});
+import { createClient, createMockAdapter } from 'react-native-fetch-client';
+
+const api = createClient({ baseURL: 'https://api.example.com' });
+const mock = createMockAdapter(api);
+
+// 1. Mock a route
+mock.onGet('/users/active').reply(200, [{ id: 1, name: 'Alice' }]);
+
+// 2. Simulate errors
+mock.onPost('/billing/charge').replyWithTimeout();
+
+// 3. Test & assert history
+const res = await api.get('/users/active');
+expect(res.data).toEqual([{ id: 1, name: 'Alice' }]);
+expect(mock.history.get).toHaveLength(1);
+
+// Clean up
+mock.restore();
 ```
 
 ---
 
-## Circuit Breaker Pattern (`circuitBreaker`)
+## Response Caching, SWR & Persistent Storage
 
-Prevent cascading outages when upstream microservices experience downtime. Automatically fails fast locally when consecutive errors exceed a configured threshold:
+A complete multi-tier caching engine with in-memory LRU, persistent disk storage, Stale-While-Revalidate (SWR), and RFC 7234 conditional validation.
 
+### 1. In-Memory LRU Cache
 ```typescript
 const api = createClient({
   baseURL: 'https://api.example.com',
-  circuitBreaker: {
+  cache: {
     enabled: true,
-    failureThreshold: 5,   // Trip to OPEN after 5 consecutive 5xx/network failures
-    resetTimeoutMs: 30000, // Probe in HALF_OPEN state after 30 seconds
+    defaultTtl: 60000,          // Cache responses for 60 seconds
+    maxSize: 100,               // Maximum 100 items in memory (LRU eviction)
+    allowAuthenticated: false,  // Prevents leaking user-specific data across accounts
   },
 });
-```
 
----
+// Initial request hits network; second request returns in ~0ms:
+const r1 = await api.get('/products');
+const r2 = await api.get('/products');
+console.log(r2.cached); // true
 
-## RFC 7234 Conditional Caching (`ETag` & `304 Not Modified`)
+// Automatic Invalidation on Mutation:
+// Executing POST, PUT, PATCH, or DELETE automatically purges matching cached paths!
+await api.post('/products', { name: 'New Item' });
+```
 
-Automatically stores `ETag` and `Last-Modified` headers. On subsequent requests, sends `If-None-Match` and `If-Modified-Since`. When the server returns `304 Not Modified`, reuses the cached response body while updating response headers:
+### 2. Persistent Storage Adapter (`storage`)
+Plug directly into high-speed mobile storage (MMKV or AsyncStorage) so cached responses survive app restarts:
 
 ```typescript
+import { MMKV } from 'react-native-mmkv';
+
+const mmkv = new MMKV({ id: 'http-cache' });
+
 const api = createClient({
   baseURL: 'https://api.example.com',
   cache: {
     enabled: true,
-    etag: true, // Enables conditional 304 validation
+    storage: {
+      getItem: (key) => mmkv.getString(key) ?? null,
+      setItem: (key, value) => mmkv.set(key, value),
+      removeItem: (key) => mmkv.delete(key),
+    },
+    defaultTtl: 300_000, // 5 minutes
   },
 });
-```
-
----
 
-## Path Parameter Interpolation (`pathParams`)
+// Instant cache hit on cold app boots (0ms latency):
+const res = await api.get('/user/profile');
+```
 
-Interpolate Express-style (`:param`) and OpenAPI-style (`{param}`) route variables with automated URI encoding:
+### 3. Stale-While-Revalidate (SWR)
+Return cached data instantly (**0ms latency**, `cached: true, stale: true`) to keep the UI responsive, while quietly fetching the latest data from the network in the background:
 
 ```typescript
-await api.get('/orgs/:orgId/projects/{projectId}/items/:itemId', {
-  pathParams: {
-    orgId: 'team-acme',
-    projectId: 'proj-123',
-    itemId: 'item#456', // Auto-encoded to item%23456
+const res = await api.get('/dashboard/stats', {
+  cache: {
+    strategy: 'stale-while-revalidate',
+    onRevalidated: (freshResponse) => {
+      console.log('Background sync complete! Updated data:', freshResponse.data);
+      updateUI(freshResponse.data);
+    },
   },
 });
+
+console.log(res.stale); // true (Served immediately without network lag!)
 ```
 
----
-
-## Bearer Token Preset (`bearerToken`)
-
-Avoid manual interceptors for token attachment. Pass a static string or an asynchronous token getter:
+### 4. RFC 7234 Conditional Validation (`ETag` & `304`)
+Automatically stores `ETag` and `Last-Modified` headers. On subsequent requests, sends `If-None-Match`. When the server returns `304 Not Modified`, reuses the cached response body while updating headers:
 
 ```typescript
 const api = createClient({
   baseURL: 'https://api.example.com',
-  bearerToken: async () => await secureStorage.getItem('access_token'),
-});
-```
-
----
-
-## File Upload Helper (`api.upload`)
-
-Upload files, Blobs, ArrayBuffers, or FormDatas with automatic boundary resolution and upload progress:
-
-```typescript
-const avatarFile = fileInput.files[0];
-
-const response = await api.upload('/users/avatar', avatarFile, {
-  fieldName: 'avatar',
-  fileName: 'photo.jpg',
-  extraFields: { userId: 123 },
-  onUploadProgress: (evt) => {
-    console.log(`Upload progress: ${Math.round((evt.progress ?? 0) * 100)}%`);
+  cache: {
+    enabled: true,
+    etag: true, // Enables conditional 304 validation
   },
 });
 ```
 
 ---
 
-## Response Unwrapping (`unwrap: true`)
+## Client Concurrency Throttler (`maxConcurrentRequests`)
 
-Directly return `response.data` instead of the full envelope:
+Cap the maximum number of simultaneous in-flight sockets across your application to avoid mobile network congestion or connection bottlenecks:
 
 ```typescript
-// Per-request unwrap:
-const users = await api.get('/users', { unwrap: true });
-
-// Or configure client-level unwrap:
-const api = createClient({ unwrap: true });
-const users = await api.get('/users'); // directly returns parsed data
+const api = createClient({
+  baseURL: 'https://api.example.com',
+  maxConcurrentRequests: 4, // Max 4 concurrent sockets; excess wait in FIFO queue
+});
 ```
 
 ---
 
-## Diagnostic Debug Logger (`debug: true`)
+## Circuit Breaker Pattern (`circuitBreaker`)
 
-Log outgoing requests with execution durations, status codes, and automatically redacted authentication tokens:
+Prevent cascading outages when upstream services experience downtime. Automatically fails fast locally when consecutive errors exceed a configured threshold:
 
 ```typescript
 const api = createClient({
   baseURL: 'https://api.example.com',
-  debug: true, // or custom logger callback: (entry) => sendToDatadog(entry)
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 5,   // Trip to OPEN after 5 consecutive failures
+    resetTimeoutMs: 30000, // Probe in HALF_OPEN state after 30 seconds
+  },
 });
 ```
 
 ---
 
-## In-Flight Request Deduplication
-
+## In-Flight Request Deduplication (`dedup`)
 
-When multiple UI components mount simultaneously and request the exact same endpoint (e.g. `GET /api/me`), standard clients fire multiple HTTP requests over the wire. 
+Coalesces concurrent identical `GET` requests into **one single flight**, preventing duplicate calls when multiple UI components mount simultaneously:
 
-`react-native-fetch-client` coalesces them into **one single flight**:
-
-```javascript
+```typescript
 const api = createClient({
   baseURL: 'https://api.example.com',
   dedup: {
-    enabled: true,               // Enable in-flight deduplication
-    methods: ['GET', 'HEAD'],    // Methods eligible for deduplication
+    enabled: true,
+    methods: ['GET', 'HEAD'],
   },
 });
 
-// Fire 3 simultaneous calls
+// Fire 3 simultaneous calls: exactly 1 network socket is opened!
 const [user1, user2, user3] = await Promise.all([
   api.get('/users/1'),
   api.get('/users/1'),
@@ -567,80 +487,41 @@ console.log(user2.fromDedup); // true  (Subscribed to in-flight flight)
 console.log(user3.fromDedup); // true  (Subscribed to in-flight flight)
 ```
 
-> **Partial Cancellation Safety**: If `user2` calls `controller.abort()`, the underlying socket is **not** aborted; `user1` and `user3` still resolve normally.
-
 ---
 
-## Response Caching (LRU)
-
-Built-in in-memory LRU cache with automatic mutation invalidation and deep-clone immutability:
-
-```javascript
-const api = createClient({
-  baseURL: 'https://api.example.com',
-  cache: {
-    enabled: true,
-    defaultTtl: 60000,          // Cache responses for 60 seconds
-    maxSize: 100,               // Maximum 100 items in memory (LRU eviction)
-    allowAuthenticated: false,  // Prevents leaking user-specific data across accounts
-  },
-});
-
-// 1. Initial request (hits live network)
-const r1 = await api.get('/products');
-console.log(r1.cached); // false
-
-// 2. Subsequent request within 60s (returns from RAM in ~0ms)
-const r2 = await api.get('/products');
-console.log(r2.cached); // true
-
-// 3. Automatic Invalidation on Mutation:
-// Executing POST, PUT, PATCH, or DELETE automatically purges matching cached paths!
-await api.post('/products', { name: 'New Item' });
-
-// 4. Next GET fetches fresh data from server
-const r3 = await api.get('/products');
-console.log(r3.cached); // false
-```
-
----
-
-## Resilient Retry Engine
+## Resilient Retry Engine (`retry`)
 
 Automatically retries transient network errors and 5xx gateway errors with exponential backoff, full jitter, and RFC `Retry-After` header parsing:
 
-```javascript
+```typescript
 const api = createClient({
   baseURL: 'https://api.example.com',
   retry: {
     attempts: 3,                   // Maximum 3 retry attempts
     delay: 500,                    // Initial backoff delay: 500ms
     maxDelay: 10000,               // Cap delay at 10 seconds
-    backoff: 'exponential',        // 'exponential' | 'linear' | 'constant'
+    backoff: 'exponential',        // 'exponential' | 'linear'
     jitter: true,                  // Applies full jitter to prevent thundering herds
-    statusCodes: [408, 429, 500, 502, 503, 504],
+    retryOn: [408, 429, 500, 502, 503, 504],
+    respectRetryAfter: true,       // Respects Retry-After response header
   },
 });
 ```
 
-> **RFC Retry-After**: If the server responds with `429 Too Many Requests` and a header `Retry-After: 5` or `Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`, the client automatically pauses for the specified duration before retrying.
-
 ---
 
-## Auth & Token Refresh Mutex
+## Auth & Token Refresh Mutex (`auth`)
 
-Solves race conditions when multiple parallel requests receive 401s on expired access tokens:
+Solves the race condition where parallel requests fail on 401s and trigger multiple refresh token calls simultaneously:
 
-```javascript
+```typescript
 let currentAccessToken = 'initial_token';
 
 const api = createClient({
   baseURL: 'https://api.example.com',
+  bearerToken: () => currentAccessToken,
   auth: {
-    // 1. Returns current token (called before each request)
-    getToken: () => currentAccessToken,
-
-    // 2. Single-flight mutex refresh callback:
+    // Single-flight mutex refresh callback:
     // If 10 requests fail with 401 simultaneously, refreshToken is called EXACTLY ONCE.
     // The other 9 requests wait, then replay with the new token.
     refreshToken: async () => {
@@ -649,68 +530,107 @@ const api = createClient({
       currentAccessToken = data.access_token;
       return currentAccessToken;
     },
-
+    refreshOn: [401],
+    refreshExcludeUrls: ['/oauth/refresh', '/auth/login'],
     headerName: 'Authorization',
-    tokenType: 'Bearer',
+    tokenPrefix: 'Bearer ',
   },
 });
 ```
 
 ---
 
-## Upload & Download Progress
+## Bearer Token Preset (`bearerToken`)
 
-Monitor real-time progress for both uploads and downloads:
+Avoid manual interceptors for token attachment. Pass a static string or an asynchronous token getter:
+
+```typescript
+const api = createClient({
+  baseURL: 'https://api.example.com',
+  bearerToken: async () => await secureStorage.getItem('access_token'),
+});
+```
 
-### 1. Upload Progress (`onUploadProgress`)
+---
 
-```javascript
-const fileBlob = new Blob(['sample data'], { type: 'text/plain' });
+## Path Parameter Interpolation (`pathParams`)
 
-await api.post('/upload', fileBlob, {
-  onUploadProgress: (event) => {
-    const percent = Math.round((event.loaded / event.total) * 100);
-    console.log(`Uploaded ${event.loaded} / ${event.total} bytes (${percent}%)`);
+Interpolate Express-style (`:param`) and OpenAPI-style (`{param}`) route variables with automated URI encoding:
+
+```typescript
+await api.get('/orgs/:orgId/projects/{projectId}/items/:itemId', {
+  pathParams: {
+    orgId: 'team-acme',
+    projectId: 'proj-123',
+    itemId: 'item#456', // Auto-encoded to item%23456
+  },
+});
+```
+
+---
+
+## File Upload Helper (`api.upload`)
+
+Upload files, Blobs, ArrayBuffers, or FormDatas with automatic boundary resolution:
+
+```typescript
+const avatarFile = fileInput.files[0];
+
+const response = await api.upload('/users/avatar', avatarFile, {
+  fieldName: 'avatar',
+  fileName: 'photo.jpg',
+  additionalFields: { userId: 123 },
+  onUploadProgress: (evt) => {
+    console.log(`Upload progress: ${evt.percent}%`);
   },
 });
 ```
 
-### 2. Streaming Download Progress (`onDownloadProgress`)
+---
 
-Uses WHATWG `ReadableStream` to stream chunks without buffering the whole response in memory:
+## Upload & Download Progress
 
-```javascript
+Monitor real-time progress for both uploads and downloads:
+
+```typescript
+// 1. Upload Progress
+await api.post('/upload', fileBlob, {
+  onUploadProgress: (event) => {
+    console.log(`Uploaded ${event.loaded} / ${event.total} bytes (${event.percent}%)`);
+  },
+});
+
+// 2. Download Progress
 await api.get('/downloads/big-file.zip', {
   responseType: 'blob',
   onDownloadProgress: (event) => {
-    console.log(`Received chunk: ${event.bytes} bytes. Total loaded: ${event.loaded} bytes`);
+    console.log(`Downloaded ${event.loaded} / ${event.total} bytes (${event.percent}%)`);
   },
 });
 ```
 
 ---
 
-## Offline Request Queue
+## Offline Request Queue (`createOfflineQueue`)
 
 Queue mutations when the device is offline and replay them deterministically when connectivity returns:
 
-```javascript
-const { createClient, createOfflineQueue, MemoryStorageAdapter } = require('react-native-fetch-client');
+```typescript
+import { createClient, createOfflineQueue, MemoryStorageAdapter } from 'react-native-fetch-client';
 
 const api = createClient({ baseURL: 'https://api.example.com' });
 
-// Initialize queue with any storage engine (AsyncStorage, localStorage, IndexedDB)
 const queue = createOfflineQueue({
   client: api,
-  storage: new MemoryStorageAdapter(), // Or custom AsyncStorage adapter
-  maxQueueSize: 100,                   // Cap at 100 queued items
-  maxAttempts: 5,                      // Drop poison-pills after 5 attempts
-  idempotencyHeader: 'Idempotency-Key',// Automatically attaches UUID idempotency key
+  storage: new MemoryStorageAdapter(), // Or MMKV / AsyncStorage adapter
+  maxQueueSize: 100,
+  maxAttempts: 5,
+  idempotencyHeader: 'Idempotency-Key', // Automatically attaches UUID idempotency key
   onReplaySuccess: (req) => {
     console.log(`Synced offline mutation: ${req.method} ${req.url}`);
   },
   onPermanentFailure: (req, err) => {
-    console.error(`Mutation failed permanently: ${req.url}`, err.message);
+    console.error(`Mutation failed permanently: ${req.url}`, err);
   },
 });
 
@@ -726,13 +646,39 @@ const summary = await queue.process();
 console.log(`Replay complete: ${summary.succeeded} succeeded, ${summary.remaining} remaining.`);
 ```
 
-> **Financial Endpoint Guardrail**: Requests targeting `/pay`, `/checkout`, `/orders`, `/charge`, or `/billing` are strictly rejected from offline queuing by default to prevent unexpected delayed charges.
+---
+
+## Response Unwrapping (`unwrap: true`)
+
+Directly return `response.data` instead of the full envelope:
+
+```typescript
+// Per-request unwrap:
+const users = await api.get('/users', { unwrap: true });
+
+// Or configure client-level unwrap:
+const api = createClient({ unwrap: true });
+const users = await api.get('/users'); // directly returns parsed data
+```
+
+---
+
+## Diagnostic Debug Logger (`debug: true`)
+
+Log outgoing requests with execution durations, status codes, and automatically redacted authentication tokens:
+
+```typescript
+const api = createClient({
+  baseURL: 'https://api.example.com',
+  debug: true, // or custom logger callback: (entry) => sendToTelemetry(entry)
+});
+```
 
 ---
 
 ## Node.js Enterprise Proxies & Dispatcher
 
-In Node.js 18+ environments, pass an Undici `ProxyAgent` to route requests through corporate forward proxies or custom mTLS agents:
+In Node.js 18+ environments, pass an Undici `ProxyAgent` to route requests through corporate forward proxies:
 
 ```javascript
 const { ProxyAgent } = require('undici');
@@ -759,49 +705,10 @@ Switching from Axios takes only a few minutes. Most method signatures are identi
 | `axios.isAxiosError(err)` | `isHttpError(err)` or `isFetchNativeError(err)` | Type-safe guards |
 | `axios-retry` (plugin) | `client = createClient({ retry: {...} })` | Built-in |
 | `axios-cache-interceptor` (plugin) | `client = createClient({ cache: {...} })` | Built-in |
-
----
-
-## Testing Locally with Your Team
-
-To test this library within your team before publishing to public npm:
-
-### Option 1: Pack as a Local `.tgz` Tarball
-```bash
-# In react-native-fetch-client:
-npm run build
-npm pack
-# Generates react-native-fetch-client-0.1.0.tgz
-```
-Share `react-native-fetch-client-0.1.0.tgz` with your teammate. In their project, they install:
-```bash
-npm install ./path/to/react-native-fetch-client-0.1.0.tgz
-```
-
-### Option 2: Local `npm link`
-```bash
-# In react-native-fetch-client:
-npm link
-
-# In teammate's project:
-npm link react-native-fetch-client
-```
-
----
-
-## Verification & Quality Gates
-
-The codebase enforces strict quality checks:
-
-```bash
-npm run typecheck      # Strict TypeScript check (0 errors)
-npm test               # 13 Vitest suites, 143 unit/integration tests (0 failures)
-npm run lint           # ESLint 10 verification
-npm run build          # Dual ESM & CJS build via tsup
-```
+| `axios-mock-adapter` (package) | `mock = createMockAdapter(client)` | Built-in |
 
 ---
 
 ## License
 
-[MIT](LICENSE) © 2026
+[MIT](LICENSE) © 2026 Arunkumar Arjunan

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "react-native-fetch-client",
-  "version": "0.1.0",
+  "version": "0.1.2-Beta",
   "description": "A lightweight, Fetch-native HTTP client for TypeScript, React Native, Expo, browsers, and Node.js",
-  "author": "",
+  "author": "Arunkumar Arjunan",
   "license": "MIT",
+  "sideEffects": false,
   "keywords": [
     "fetch",
     "http",
@@ -16,11 +17,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/OWNER/react-native-fetch-client.git"
+    "url": "git+https://github.com/arunkumarArjun/react-native-fetch-client.git"
   },
-  "homepage": "https://github.com/OWNER/react-native-fetch-client#readme",
+  "homepage": "https://github.com/arunkumarArjun/react-native-fetch-client#readme",
   "bugs": {
-    "url": "https://github.com/OWNER/react-native-fetch-client/issues"
+    "url": "https://github.com/arunkumarArjun/react-native-fetch-client/issues"
   },
 
   "engines": {