@tahanabavi/typefetch 1.0.2 → 1.1.0

package/README.md

@@ -1,17 +1,19 @@
 # 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.
 
 ---
 
 ## Features
 
-* Fully type-safe using TypeScript and Zod
-* Define contracts for modules and endpoints
-* Support for middlewares to add custom behavior before or after requests
-* Error handling with the `RichError` class
-* Ability to transform responses using a response transformer
-* Authentication support via token
+- Fully type-safe using TypeScript and Zod
+- Define contracts for modules and endpoints
+- Support for middlewares to add custom behavior before or after requests
+- 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,32 @@ yarn add @tahanabavi/typefetch
 
 ---
 
+## What's New in v1.1.0
+
+### 🎯 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
+
+---
+
 ## 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 +65,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,14 +91,18 @@ const client = new ApiClient(
   {
     baseUrl: "https://api.example.com",
     token: "your-auth-token",
+    useMockData: true,
+    mockDelay: { min: 100, max: 1000 },
   },
   contracts
 );
 
 client.init();
 
-const user = await client.user.getUser({ id: "123" });
-const newUser = await client.user.createUser({ name: "Taha" });
+const { modules: api } = client;
+
+const user = await api.user.getUser({ id: "123" });
+const newUser = await api.user.createUser({ name: "Taha" });
 ```
 
 ---
@@ -80,7 +113,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);
 });
 ```
 
@@ -91,12 +124,14 @@ client.onError((error: RichError) => {
 You can add custom behavior before or after requests. Middlewares work similarly to Express:
 
 ```ts
-client.use(async (ctx, next, options) => {
-  console.log("Request URL:", ctx.url);
-  const response = await next();
-  console.log("Response status:", response.status);
-  return response;
-});
+client.use(
+  async (ctx: MiddlewareContext, next: MiddlewareNext, options?: any) => {
+    console.log("Request URL:", ctx.url);
+    const response = await next();
+    console.log("Response status:", response.status);
+    return response;
+  }
+);
 ```
 
 ### Built-in Middlewares
@@ -117,10 +152,10 @@ client.use(AuthMiddleware, { refreshToken: () => "your-auth-token" });
 client.use(CacheMiddleware, { ttl: 60 * 1000 });
 ```
 
-* `LoggingMiddleware` – Logs requests and responses
-* `RetryMiddleware` – Retries failed requests
-* `AuthMiddleware` – Automatically adds Authorization headers
-* `CacheMiddleware` – Caches responses to reduce repeated requests
+- `LoggingMiddleware` – Logs requests and responses
+- `RetryMiddleware` – Retries failed requests
+- `AuthMiddleware` – Automatically adds Authorization headers
+- `CacheMiddleware` – Caches responses to reduce repeated requests
 
 ---
 
@@ -136,11 +171,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.
+- 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.
 
 ---
 
@@ -152,23 +237,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 });
 
@@ -176,8 +288,16 @@ client.onError((err: RichError) => {
   console.error("Error:", err.message);
 });
 
+const { modules: api } = client;
+
 (async () => {
-  const post = await client.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

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+
+type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    auth?: boolean;
+    request: TReq;
+    response: TRes;
+    mockData?: (() => z.infer<TRes>) | z.infer<TRes>;
+};
+type Contracts = {
+    [ModuleName: string]: {
+        [EndpointName: string]: EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+    };
+};
+interface MiddlewareContext {
+    url: string;
+    init: RequestInit;
+}
+type MiddlewareNext = () => Promise<Response>;
+type Middleware<Options = any> = (ctx: MiddlewareContext, next: MiddlewareNext, options?: Options) => Promise<Response>;
+type ErrorLike = {
+    message: string;
+    status?: number;
+    code?: string;
+    [key: string]: any;
+};
+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"]>>;
+};
+
+declare class RichError extends Error implements ErrorLike {
+    status?: number;
+    code?: string;
+    title?: string;
+    detail?: string;
+    errors?: Record<string, string[]>;
+    constructor(error: Partial<ErrorLike> & {
+        message: string;
+    });
+}
+declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
+    private config;
+    private contracts;
+    private middlewares;
+    private errorHandler?;
+    private responseTransform;
+    private useMockData;
+    private mockDelay;
+    private responseWrapper?;
+    private _modules;
+    constructor(config: {
+        baseUrl: string;
+        token?: string;
+        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;
+    private request;
+    private handleMockRequest;
+    private getRandomDelay;
+    private createError;
+    private normalizeError;
+}
+
+type LoggingOptions = {
+    logRequest?: boolean;
+    logResponse?: boolean;
+    debug?: boolean;
+};
+declare const loggingMiddleware: Middleware<LoggingOptions>;
+
+type RetryOptions = {
+    maxRetries?: number;
+    delay?: number;
+};
+declare const retryMiddleware: (options?: RetryOptions) => Middleware;
+
+type AuthOptions = {
+    refreshToken?: () => Promise<string>;
+};
+declare const authMiddleware: Middleware<AuthOptions>;
+
+type CacheOptions = {
+    ttl?: number;
+};
+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 };

package/dist/index.d.ts

@@ -1,6 +1,102 @@
-export * from "./types";
-export * from "./client";
-export * from "./middlewares/logging";
-export * from "./middlewares/retry";
-export * from "./middlewares/auth";
-export * from "./middlewares/cache";
+import { z } from 'zod';
+
+type EndpointDef<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny> = {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    path: string;
+    auth?: boolean;
+    request: TReq;
+    response: TRes;
+    mockData?: (() => z.infer<TRes>) | z.infer<TRes>;
+};
+type Contracts = {
+    [ModuleName: string]: {
+        [EndpointName: string]: EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+    };
+};
+interface MiddlewareContext {
+    url: string;
+    init: RequestInit;
+}
+type MiddlewareNext = () => Promise<Response>;
+type Middleware<Options = any> = (ctx: MiddlewareContext, next: MiddlewareNext, options?: Options) => Promise<Response>;
+type ErrorLike = {
+    message: string;
+    status?: number;
+    code?: string;
+    [key: string]: any;
+};
+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"]>>;
+};
+
+declare class RichError extends Error implements ErrorLike {
+    status?: number;
+    code?: string;
+    title?: string;
+    detail?: string;
+    errors?: Record<string, string[]>;
+    constructor(error: Partial<ErrorLike> & {
+        message: string;
+    });
+}
+declare class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
+    private config;
+    private contracts;
+    private middlewares;
+    private errorHandler?;
+    private responseTransform;
+    private useMockData;
+    private mockDelay;
+    private responseWrapper?;
+    private _modules;
+    constructor(config: {
+        baseUrl: string;
+        token?: string;
+        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;
+    private request;
+    private handleMockRequest;
+    private getRandomDelay;
+    private createError;
+    private normalizeError;
+}
+
+type LoggingOptions = {
+    logRequest?: boolean;
+    logResponse?: boolean;
+    debug?: boolean;
+};
+declare const loggingMiddleware: Middleware<LoggingOptions>;
+
+type RetryOptions = {
+    maxRetries?: number;
+    delay?: number;
+};
+declare const retryMiddleware: (options?: RetryOptions) => Middleware;
+
+type AuthOptions = {
+    refreshToken?: () => Promise<string>;
+};
+declare const authMiddleware: Middleware<AuthOptions>;
+
+type CacheOptions = {
+    ttl?: number;
+};
+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 };