@tahanabavi/typefetch 1.2.2 → 1.4.1

package/README.md

@@ -1,79 +1,127 @@
 # TypeFetch
 
-TypeFetch is a strongly-typed HTTP client built on TypeScript and Zod.
+TypeFetch is a production-grade, strongly-typed HTTP client built on
+**TypeScript** and **Zod**.
 
-You define your API once using Zod schemas, and TypeFetch generates a fully type-safe client with:
+Define your API once using Zod schemas, and TypeFetch generates a fully
+type-safe client with:
 
 - End-to-end type safety
-- Automatic URL handling (path, query, body)
-- Middleware pipeline (logging, retry, cache, auth)
+- Structured request support: `{ path, query, body, headers }`
+- Automatic URL handling (path parameters, query string, JSON body)
+- Middleware pipeline (logging, retry, cache, auth, custom)
+- Built-in retry engine with backoff strategies
+- Timeout & AbortController support
 - Mock mode for development
 - Dynamic token providers
 - Response wrappers for consistent API envelopes
-- Unified error system (RichError)
+- Unified error system (`RichError`)
+- Optional `form-data` body support for file uploads
+- Concurrency-safe request handling
+- Production-grade validation and error normalization
+
+---
 
 ## Installation
 
+```bash
 npm install @tahanabavi/typefetch
-
 # or
-
 yarn add @tahanabavi/typefetch
+```
+
+---
+
+# What's New / Updated
+
+## 1. Advanced Retry Engine
+
+TypeFetch now includes:
+
+- Configurable `maxRetries`
+- Custom `retryCondition`
+- Built-in backoff strategies:
+  - `fixed`
+  - `exponential`
+- Fully normalized retry errors
+
+Example:
 
-## Key Features
+```ts
+client.setRetryConfig({
+  maxRetries: 3,
+  backoff: "exponential",
+  retryCondition: (err) => err.status === 500,
+});
+```
+
+---
+
+## 2. Backoff Strategies
+
+Supported strategies:
 
-1. Type-Safe API Client  
-   Define your API with Zod schemas and get full type safety for request and response types.
+- **fixed** → constant delay
+- **exponential** → 100ms, 200ms, 400ms...
 
-2. Structured Request Support  
-   Each request may contain:
+Backoff is applied automatically between retries.
 
-   - path: URL parameters (fills /users/:id)
-   - query: URL query string ?page=1&limit=10
-   - body: JSON payload for POST/PUT/PATCH
+---
 
-   The client automatically builds URLs and bodies correctly.
+## 3. Timeout & Abort Support
 
-3. Backward Compatibility  
-   If your request schema is flat (z.object({ name: z.string() })), TypeFetch automatically treats it as a simple body payload—no breaking changes.
+Per-request timeout:
 
-4. Middlewares  
-   Middlewares allow modifying requests and responses.
-   Built-in middlewares include:
+```ts
+await api.user.getUser({ path: { id: "123" } }, { timeout: 5000 });
+```
 
-   - loggingMiddleware
-   - retryMiddleware
-   - authMiddleware
-   - cacheMiddleware
+Internally uses `AbortController` for safe cancellation.
 
-5. Token Provider System  
-   Provide tokens dynamically using:
+---
 
-   - token: static auth token
-   - tokenProvider: function or async function returning a token
+## 4. Structured Request Model (Canonical Format)
 
-6. Mock Mode  
-   Provides mock responses based on endpoint.mockData, with configurable fake delays.
+```ts
+z.object({
+  path: z.object({...}).optional(),
+  query: z.object({...}).optional(),
+  body: z.object({...}).optional(),
+  headers: z.record(z.string()).optional(),
+})
+```
 
-7. Response Wrapper  
-   For APIs that wrap responses:
+TypeFetch automatically:
 
-   ```
-   {
-     "success": true,
-     "data": {...},
-     "timestamp": "...",
-     "requestId": "..."
-   }
-   ```
+- Injects path params
+- Builds query string
+- Serializes JSON body
+- Merges headers in priority order:
+  1.  auth
+  2.  endpoint-level headers
+  3.  per-call headers
 
-   TypeFetch unwraps the response automatically.
+---
 
-## Defining API Contracts
+## 5. Backward Compatibility
 
-Example contract definition:
+Flat request schemas still work:
 
+```ts
+z.object({
+  name: z.string(),
+});
 ```
+
+For non-GET requests, the entire object becomes the JSON body.
+
+---
+
+# Defining API Contracts
+
+Example:
+
+```ts
 import { z } from "zod";
 
 const contracts = {
@@ -83,51 +131,30 @@ const contracts = {
       path: "/users/:id",
       auth: true,
       request: z.object({
-        path: z.object({ id: z.string() }).optional(),
-        query: z.object({}).optional(),
-        body: z.never().optional(),
+        path: z.object({ id: z.string() }),
       }),
       response: z.object({
         id: z.string(),
         name: z.string(),
       }),
-      mockData: { id: "1", name: "John Doe" }
     },
-
-    createUser: {
-      method: "POST",
-      path: "/users",
-      auth: true,
-      request: z.object({
-        path: z.object({}).optional(),
-        query: z.object({}).optional(),
-        body: z.object({ name: z.string() }).optional(),
-      }),
-      response: z.object({
-        id: z.string(),
-        name: z.string(),
-      }),
-      mockData: () => ({
-        id: Math.random().toString(36).slice(2),
-        name: "Mock User",
-      }),
-    }
-  }
-};
+  },
+} as const;
 ```
 
-## Using ApiClient
+---
 
-```
+# Using ApiClient
+
+```ts
 import { ApiClient } from "@tahanabavi/typefetch";
 
 const client = new ApiClient(
   {
     baseUrl: "https://api.example.com",
-    tokenProvider: () => "dynamic-token",
-    useMockData: false
+    tokenProvider: async () => "dynamic-token",
   },
-  contracts
+  contracts,
 );
 
 client.init();
@@ -135,89 +162,142 @@ client.init();
 const api = client.modules;
 
 const user = await api.user.getUser({ path: { id: "123" } });
-const created = await api.user.createUser({ body: { name: "Alice" } });
 ```
 
-## Middlewares
+---
 
-Example custom middleware:
+# Middleware System
 
-```
+Middlewares execute in reverse registration order.
+
+## Custom Middleware
+
+```ts
 client.use(async (ctx, next) => {
-  console.log("Request to:", ctx.url);
+  console.log("Request:", ctx.url);
   const res = await next();
   console.log("Response:", res.status);
   return res;
 });
 ```
 
-Built-in middlewares:
+## Built-in Middlewares
 
-```
-import {
-  loggingMiddleware,
-  retryMiddleware,
-  cacheMiddleware,
-  authMiddleware
-} from "@tahanabavi/typefetch/middlewares";
-
-  client.use(loggingMiddleware, { logRequest: true });
-  client.use(retryMiddleware, { maxRetries: 3, delay: 100 });
-  client.use(cacheMiddleware, { ttl: 60000 });
-  client.use(authMiddleware, {
-  refreshToken: async () => "refreshed-token"
-});
-```
+- `loggingMiddleware`
+- `retryMiddleware`
+- `cacheMiddleware`
+- `authMiddleware`
+
+Example:
 
-## Mock Mode
+```ts
+client.use(loggingMiddleware);
+client.use(retryMiddleware, { maxRetries: 3 });
+client.use(cacheMiddleware, { ttl: 60000 });
+client.use(authMiddleware);
 ```
+
+---
+
+# Mock Mode
+
+```ts
 client.setMockMode(true, { min: 200, max: 1000 });
-client.setMockMode(false);
 ```
-## Response Transformation
-```
-client.useResponseTransform((data) => {
-  return {
-    ...data,
-    transformedAt: new Date().toISOString()
-  };
-});
-```
-## Response Wrapper Example
-```
-const wrapper = (successResponse) =>
-z.union([
-  z.object({
-    success: z.literal(true),
-    data: successResponse,
-    timestamp: z.string(),
-    requestId: z.string(),
-  }),
-  z.object({
-    success: z.literal(false),
-    message: z.string(),
-    code: z.number(),
-    timestamp: z.string(),
-    requestId: z.string(),
-  }),
-]);
-
-client.setResponseWrapper(wrapper);
+
+- Returns `mockData` instead of calling network
+- Still applies response validation and wrapper
+
+---
+
+# Response Wrapper
+
+Supports envelope APIs:
+
+```json
+{
+  "success": true,
+  "data": {...},
+  "timestamp": "..."
+}
 ```
-## Error Handling
+
+Example:
+
+```ts
+client.setResponseWrapper(wrapperSchema);
 ```
+
+On failure, throws normalized `RichError`.
+
+---
+
+# Error Handling
+
+All errors are normalized into `RichError`:
+
+- HTTP errors
+- Network failures
+- Validation errors
+- Timeout errors
+- Retry exhaustion
+
+Global handler:
+
+```ts
 client.onError((err) => {
-  console.error("API Error:", err.message, err.status, err.code);
+  console.error(err.message, err.status);
 });
 ```
-## Notes
 
-- Always call client.init() before using client.modules.
-- Middlewares run in reverse registration order.
-- Endpoints requiring auth must have a token or tokenProvider.
+---
+
+# File Uploads (FormData)
+
+Set `bodyType: "form-data"` in endpoint definition.
+
+TypeFetch builds `FormData` automatically.
+
+---
+
+# Concurrency Safety
+
+TypeFetch safely handles parallel requests:
+
+- No shared mutable state issues
+- Independent retry cycles
+- Independent AbortControllers
+
+---
+
+# Production-Grade Test Coverage
+
+The project now includes:
+
+- Validation tests
+- Middleware tests
+- Retry tests
+- Backoff timing tests
+- Timeout & abort tests
+- Concurrency tests
+- Error propagation tests
+- Mock mode tests
+- TokenProvider tests
+- Edge case handling tests
+
+Suitable for publishing as a production SDK.
+
+---
+
+# Notes
+
+- Always call `client.init()` before using modules.
 - All responses are validated via Zod.
-- Backward-compatible request support makes migration safe.
+- Structured request shape is recommended.
+- Retry + Timeout can be combined safely.
+
+---
 
-## License
+# License
 
 MIT