@tahanabavi/typefetch 1.0.3 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # TypeFetch
 
-TypeFetch is a type-safe client for working with APIs, built with TypeScript and Zod. This project allows you to define API contracts and safely use types, while also supporting middlewares, error handling, and response transformation.
+TypeFetch is a type-safe client for working with APIs, built with TypeScript and Zod. This project allows you to define API contracts and safely use types, while also supporting middlewares, error handling, response transformation, mock data, and response wrappers.
 
 ---
 
@@ -12,6 +12,8 @@ TypeFetch is a type-safe client for working with APIs, built with TypeScript and
 - Error handling with the `RichError` class
 - Ability to transform responses using a response transformer
 - Authentication support via token
+- Mock data support for development and testing
+- Response wrapper for consistent API response formats
 
 ---
 
@@ -25,9 +27,39 @@ yarn add @tahanabavi/typefetch
 
 ---
 
+## What's New in v1.1.1
+
+### 🎯 Mock Data Support
+
+- Add mock data to endpoints for development and testing
+- Configurable random delays to simulate network latency
+- Support for both static data and dynamic functions
+- Runtime toggle between mock and real API modes
+
+### 🔄 Response Wrapper
+
+- Consistent API response format handling
+- Automatic validation of wrapped responses
+- Support for success/error response patterns
+- Seamless integration with existing contracts
+
+### 🚀 Enhanced Error Handling
+
+- Better Zod error wrapping and reporting
+- Improved type safety for response wrappers
+
+### 🔧 Token Provider System
+
+- Dynamic token resolution: Tokens resolved at request time, not initialization
+- Universal compatibility: Works seamlessly in both server and client environments
+- Async token providers: Support for asynchronous token retrieval
+  - Multiple token sources: Flexible token sourcing from cookies, context, or external services
+
+---
+
 ## Defining Contracts
 
-Contracts are defined using the `Contracts` and `EndpointDef` types
+Contracts are defined using the `Contracts` and `EndpointDef` types.
 
 ```ts
 import { z } from "zod";
@@ -40,12 +72,16 @@ const contracts = {
       auth: true,
       request: z.object({ id: z.string() }),
       response: z.object({ id: z.string(), name: z.string() }),
+      // Optional mock data
+      mockData: { id: "1", name: "John Doe" },
     },
     createUser: {
       method: "POST",
       path: "/user",
       request: z.object({ name: z.string() }),
       response: z.object({ id: z.string(), name: z.string() }),
+      // Dynamic mock data function
+      mockData: () => ({ id: Math.random().toString(), name: "Dynamic User" }),
     },
   },
 } as const;
@@ -62,6 +98,8 @@ const client = new ApiClient(
   {
     baseUrl: "https://api.example.com",
     token: "your-auth-token",
+    useMockData: true,
+    mockDelay: { min: 100, max: 1000 },
   },
   contracts
 );
@@ -82,7 +120,7 @@ All errors are provided via the `RichError` class. You can define a custom error
 
 ```ts
 client.onError((error: RichError) => {
-  console.error("API Error:", error.message, error.status);
+  console.error("API Error:", error.message, error.status, error.code);
 });
 ```
 
@@ -140,11 +178,61 @@ client.useResponseTransform((data) => {
 
 ---
 
+## Mock Data Features
+
+Static Mock Data:
+
+```ts
+mockData: { id: "1", name: "Static User" }
+```
+
+Dynamic Mock Data:
+
+```ts
+mockData: () => ({ id: Math.random().toString(), name: `User-${Date.now()}` });
+```
+
+Runtime Control:
+
+```ts
+client.setMockMode(true, { min: 100, max: 2000 });
+client.setMockMode(false);
+```
+
+---
+
+## Response Wrapper Features
+
+```ts
+const apiResponseWrapper = (successResponse: z.ZodTypeAny) =>
+  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(apiResponseWrapper);
+```
+
+---
+
 ## Important Notes
 
 - Always call `client.init()` before using endpoints.
 - Types are automatically inferred from Zod, making inputs and outputs type-safe.
 - Middleware execution order: first added middleware runs last, last added middleware runs first.
+- Mock data is used only when `useMockData` is true and mock data is defined.
+- Response wrapper automatically handles success/error patterns.
 
 ---
 
@@ -156,23 +244,50 @@ import { ApiClient, RichError } from "typefetch";
 import { LoggingMiddleware, RetryMiddleware } from "typefetch/middlewares";
 
 const contracts = {
-  post: {
-    getPost: {
+  user: {
+    getUser: {
       method: "GET",
-      path: "/posts/:id",
+      path: "/users/:id",
       auth: true,
       request: z.object({ id: z.string() }),
-      response: z.object({ id: z.string(), title: z.string() }),
+      response: z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.string(),
+      }),
+      mockData: { id: "1", name: "John Doe", email: "john@example.com" },
     },
   },
 } as const;
 
+const apiResponseWrapper = (successResponse: z.ZodTypeAny) =>
+  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(),
+    }),
+  ]);
+
 const client = new ApiClient(
-  { baseUrl: "https://api.example.com", token: "abc123" },
+  {
+    baseUrl: "https://api.example.com",
+    token: "abc123",
+    useMockData: process.env.NODE_ENV === "development",
+  },
   contracts
 );
 
 client.init();
+client.setResponseWrapper(apiResponseWrapper);
 client.use(LoggingMiddleware);
 client.use(RetryMiddleware, { maxRetries: 2 });
 
@@ -183,7 +298,13 @@ client.onError((err: RichError) => {
 const { modules: api } = client;
 
 (async () => {
-  const post = await api.post.getPost({ id: "1" });
-  console.log(post);
+  const user = await api.user.getUser({ id: "1" });
+  console.log(user);
 })();
 ```
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -6,6 +6,7 @@ type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
     auth?: boolean;
     request: TReq;
     response: TRes;
+    mockData?: (() => z.infer<TRes>) | z.infer<TRes>;
 };
 type Contracts = {
     [ModuleName: string]: {
@@ -28,6 +29,7 @@ type EndpointDefZ = EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
 type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
     [K in keyof M]: (input: z.infer<M[K]["request"]>) => Promise<z.infer<M[K]["response"]>>;
 };
+type TokenProvider = () => string | Promise<string>;
 
 declare class RichError extends Error implements ErrorLike {
     status?: number;
@@ -45,17 +47,36 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private middlewares;
     private errorHandler?;
     private responseTransform;
+    private useMockData;
+    private mockDelay;
+    private responseWrapper?;
+    private tokenProvider?;
     private _modules;
     constructor(config: {
         baseUrl: string;
         token?: string;
+        tokenProvider?: TokenProvider;
+        useMockData?: boolean;
+        mockDelay?: {
+            min: number;
+            max: number;
+        };
     }, contracts: C);
     init(): void;
     get modules(): { [M in keyof C]: EndpointMethods<C[M]>; };
     use<T>(middleware: Middleware<T>, options?: T): void;
     onError(handler: (error: E) => void): void;
     useResponseTransform(fn: (data: any) => any): void;
+    setMockMode(enabled: boolean, delay?: {
+        min: number;
+        max: number;
+    }): void;
+    setResponseWrapper(wrapper: (successResponse: z.ZodTypeAny) => z.ZodTypeAny): void;
+    setTokenProvider(provider: TokenProvider): void;
+    getCurrentToken(): Promise<string | undefined>;
     private request;
+    private handleMockRequest;
+    private getRandomDelay;
     private createError;
     private normalizeError;
 }
@@ -83,4 +104,4 @@ type CacheOptions = {
 };
 declare const cacheMiddleware: (options?: CacheOptions) => (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RetryOptions, RichError, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };
+export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
     auth?: boolean;
     request: TReq;
     response: TRes;
+    mockData?: (() => z.infer<TRes>) | z.infer<TRes>;
 };
 type Contracts = {
     [ModuleName: string]: {
@@ -28,6 +29,7 @@ type EndpointDefZ = EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
 type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
     [K in keyof M]: (input: z.infer<M[K]["request"]>) => Promise<z.infer<M[K]["response"]>>;
 };
+type TokenProvider = () => string | Promise<string>;
 
 declare class RichError extends Error implements ErrorLike {
     status?: number;
@@ -45,17 +47,36 @@ declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
     private middlewares;
     private errorHandler?;
     private responseTransform;
+    private useMockData;
+    private mockDelay;
+    private responseWrapper?;
+    private tokenProvider?;
     private _modules;
     constructor(config: {
         baseUrl: string;
         token?: string;
+        tokenProvider?: TokenProvider;
+        useMockData?: boolean;
+        mockDelay?: {
+            min: number;
+            max: number;
+        };
     }, contracts: C);
     init(): void;
     get modules(): { [M in keyof C]: EndpointMethods<C[M]>; };
     use<T>(middleware: Middleware<T>, options?: T): void;
     onError(handler: (error: E) => void): void;
     useResponseTransform(fn: (data: any) => any): void;
+    setMockMode(enabled: boolean, delay?: {
+        min: number;
+        max: number;
+    }): void;
+    setResponseWrapper(wrapper: (successResponse: z.ZodTypeAny) => z.ZodTypeAny): void;
+    setTokenProvider(provider: TokenProvider): void;
+    getCurrentToken(): Promise<string | undefined>;
     private request;
+    private handleMockRequest;
+    private getRandomDelay;
     private createError;
     private normalizeError;
 }
@@ -83,4 +104,4 @@ type CacheOptions = {
 };
 declare const cacheMiddleware: (options?: CacheOptions) => (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RetryOptions, RichError, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };
+export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Middleware, type MiddlewareContext, type MiddlewareNext, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, loggingMiddleware, retryMiddleware };