@tahanabavi/typefetch 1.0.0

package/README.md

@@ -0,0 +1,183 @@
+# 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.
+
+---
+
+## 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
+
+---
+
+## Installation
+
+```bash
+npm install typefetch
+# or
+yarn add typefetch
+```
+
+---
+
+## Defining Contracts
+
+Contracts are defined using the `Contracts` and `EndpointDef` types
+
+```ts
+import { z } from "zod";
+
+const contracts = {
+  user: {
+    getUser: {
+      method: "GET",
+      path: "/user/:id",
+      auth: true,
+      request: z.object({ id: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+    createUser: {
+      method: "POST",
+      path: "/user",
+      request: z.object({ name: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+  },
+} as const;
+```
+
+---
+
+## Using `ApiClient`
+
+```ts
+import { ApiClient, RichError } from "typefetch";
+
+const client = new ApiClient(
+  {
+    baseUrl: "https://api.example.com",
+    token: "your-auth-token",
+  },
+  contracts
+);
+
+client.init();
+
+const user = await client.user.getUser({ id: "123" });
+const newUser = await client.user.createUser({ name: "Taha" });
+```
+
+---
+
+## Error Handling
+
+All errors are provided via the `RichError` class. You can define a custom error handler:
+
+```ts
+client.onError((error: RichError) => {
+  console.error("API Error:", error.message, error.status);
+});
+```
+
+---
+
+## Middlewares
+
+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;
+});
+```
+
+### Built-in Middlewares
+
+This project provides some built-in middlewares:
+
+```ts
+import {
+  LoggingMiddleware,
+  RetryMiddleware,
+  AuthMiddleware,
+  CacheMiddleware,
+} from "typefetch/middlewares";
+
+client.use(LoggingMiddleware);
+client.use(RetryMiddleware, { maxRetries: 3, delay: 100 });
+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
+
+---
+
+## Response Transformation
+
+You can transform the response format before returning it:
+
+```ts
+client.useResponseTransform((data) => {
+  return { ...data, fetchedAt: new Date() };
+});
+```
+
+---
+
+## 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.
+
+---
+
+## Full Example
+
+```ts
+import { z } from "zod";
+import { ApiClient, RichError } from "typefetch";
+import { LoggingMiddleware, RetryMiddleware } from "typefetch/middlewares";
+
+const contracts = {
+  post: {
+    getPost: {
+      method: "GET",
+      path: "/posts/:id",
+      auth: true,
+      request: z.object({ id: z.string() }),
+      response: z.object({ id: z.string(), title: z.string() }),
+    },
+  },
+} as const;
+
+const client = new ApiClient(
+  { baseUrl: "https://api.example.com", token: "abc123" },
+  contracts
+);
+
+client.init();
+client.use(LoggingMiddleware);
+client.use(RetryMiddleware, { maxRetries: 2 });
+
+client.onError((err: RichError) => {
+  console.error("Error:", err.message);
+});
+
+(async () => {
+  const post = await client.post.getPost({ id: "1" });
+  console.log(post);
+})();
+```

package/jest.config.ts

@@ -0,0 +1,18 @@
+import type { Config } from "jest";
+
+const config: Config = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  roots: ["<rootDir>/src"],
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  transform: {
+    "^.+\\.(ts|tsx)$": "ts-jest",
+  },
+  testMatch: ["**/*.test.ts", "**/*.test.tsx"],
+  collectCoverage: true,
+  collectCoverageFrom: ["src/**/*.{ts,tsx}", "!src/**/*.d.ts"],
+  coverageDirectory: "coverage",
+  clearMocks: true,
+};
+
+export default config;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@tahanabavi/typefetch",
+  "version": "1.0.0",
+  "description": "A fully type-safe, extensible API client for TypeScript projects, featuring global error handling, configurable middleware, automatic retries, auth refresh, response transforms, and seamless contract integration. Designed for large-scale applications and developer-friendly API interactions.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.1.3",
+    "jest-fetch-mock": "^3.0.3",
+    "ts-jest": "^29.4.1",
+    "typescript": "^5.9.2",
+    "zod": "^3.25.76"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "ts-node": "^10.9.2"
+  }
+}

package/src/__tests__/client.test.ts

@@ -0,0 +1,137 @@
+import { z, ZodError } from "zod";
+import { ApiClient, RichError } from "../client";
+import { Contracts } from "../types";
+
+// Mock fetch globally
+global.fetch = jest.fn();
+
+const contracts: Contracts = {
+  user: {
+    getUser: {
+      method: "GET",
+      path: "/user",
+      request: z.object({ id: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+    createUser: {
+      method: "POST",
+      path: "/user",
+      auth: true,
+      request: z.object({ name: z.string() }),
+      response: z.object({ id: z.string(), name: z.string() }),
+    },
+  },
+};
+
+describe("ApiClient", () => {
+  let client: ApiClient<typeof contracts>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    client = new ApiClient({ baseUrl: "https://api.test.com" }, contracts);
+    client.init();
+  });
+
+  it("should initialize modules correctly", () => {
+    expect(client.modules.user).toBeDefined();
+    expect(typeof client.modules.user.getUser).toBe("function");
+  });
+
+  it("should call fetch with correct URL and headers", async () => {
+    (fetch as jest.Mock).mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ id: "1", name: "John" }),
+    });
+
+    const res = await client.modules.user.getUser({ id: "1" });
+    expect(fetch).toHaveBeenCalledWith("https://api.test.com/user", {
+      method: "GET",
+      headers: { "Content-Type": "application/json" },
+      body: undefined,
+    });
+    expect(res).toEqual({ id: "1", name: "John" });
+  });
+
+  it("should throw validation error if input is invalid", async () => {
+  await expect(client.modules.user.getUser({} as any))
+    .rejects.toBeInstanceOf(ZodError);
+});
+
+  it("should handle auth header when token is provided", async () => {
+    const authedClient = new ApiClient(
+      { baseUrl: "https://api.test.com", token: "mytoken" },
+      contracts
+    );
+    authedClient.init();
+
+    (fetch as jest.Mock).mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ id: "2", name: "Alice" }),
+    });
+
+    await authedClient.modules.user.createUser({ name: "Alice" });
+
+    expect(fetch).toHaveBeenCalledWith("https://api.test.com/user", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer mytoken",
+      },
+      body: JSON.stringify({ name: "Alice" }),
+    });
+  });
+
+  it("should throw error if auth required and no token provided", async () => {
+    await expect(
+      client.modules.user.createUser({ name: "Alice" })
+    ).rejects.toThrow(RichError);
+  });
+
+  it("should call errorHandler when error occurs", async () => {
+    const handler = jest.fn();
+    client.onError(handler);
+
+    (fetch as jest.Mock).mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      statusText: "Bad Request",
+      json: async () => ({ message: "Invalid input" }),
+    });
+
+    await expect(client.modules.user.getUser({ id: "bad" })).rejects.toThrow();
+
+    expect(handler).toHaveBeenCalled();
+  });
+
+  it("should apply responseTransform", async () => {
+    client.useResponseTransform((data) => ({ ...data, transformed: true }));
+
+    (fetch as jest.Mock).mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ id: "1", name: "John" }),
+    });
+
+    const res = await client.modules.user.getUser({ id: "1" });
+    expect(res).toEqual({ id: "1", name: "John", transformed: true });
+  });
+
+  it("should execute middleware in order", async () => {
+    const logs: string[] = [];
+
+    client.use(async (ctx, next) => {
+      logs.push("before");
+      const res = await next();
+      logs.push("after");
+      return res;
+    });
+
+    (fetch as jest.Mock).mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ id: "1", name: "John" }),
+    });
+
+    await client.modules.user.getUser({ id: "1" });
+
+    expect(logs).toEqual(["before", "after"]);
+  });
+});

package/src/__tests__/middlewares.test.ts

@@ -0,0 +1,108 @@
+import { authMiddleware } from "../middlewares/auth";
+import { cacheMiddleware } from "../middlewares/cache";
+import { loggingMiddleware } from "../middlewares/logging";
+import { retryMiddleware } from "../middlewares/retry";
+
+describe("middlewares", () => {
+  const mockCtx = (url = "/test", method = "GET") => ({
+    url,
+    init: { method, headers: {} as Record<string, string> },
+  });
+
+  const mockNext = (response: any = { ok: true, status: 200 }) =>
+    jest.fn().mockResolvedValue(new Response(JSON.stringify(response)));
+
+  // ---------------- AUTH ----------------
+  it("authMiddleware should add refreshed token", async () => {
+    const ctx = mockCtx();
+    const next = mockNext();
+
+    await authMiddleware(ctx, next, {
+      refreshToken: async () => "NEW_TOKEN",
+    });
+
+    expect(ctx.init.headers["Authorization"]).toBe("Bearer NEW_TOKEN");
+    expect(next).toHaveBeenCalled();
+  });
+
+  it("authMiddleware should skip if no refreshToken provided", async () => {
+    const ctx = mockCtx();
+    const next = mockNext();
+
+    await authMiddleware(ctx, next, {});
+    expect(ctx.init.headers["Authorization"]).toBeUndefined();
+    expect(next).toHaveBeenCalled();
+  });
+
+  // ---------------- CACHE ----------------
+  it("cacheMiddleware should cache GET responses", async () => {
+    const ctx = mockCtx("/users", "GET");
+    const next = mockNext({ users: [1, 2, 3] });
+    const middleware = cacheMiddleware({ ttl: 1000 });
+
+    const res1 = await middleware(ctx, next);
+    const res2 = await middleware(ctx, next);
+
+    expect(next).toHaveBeenCalledTimes(1); // only first time
+    const data2 = await res2.json();
+    expect(data2.users).toEqual([1, 2, 3]);
+  });
+
+  it("cacheMiddleware should bypass cache for non-GET requests", async () => {
+    const ctx = mockCtx("/users", "POST");
+    const next = mockNext({ ok: true });
+    const middleware = cacheMiddleware();
+
+    await middleware(ctx, next);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  // ---------------- LOGGING ----------------
+  it("loggingMiddleware should log request and response", async () => {
+    const ctx = mockCtx();
+    const next = mockNext();
+
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await loggingMiddleware(ctx, next, {
+      logRequest: true,
+      logResponse: true,
+      debug: true,
+    });
+
+    expect(logSpy).toHaveBeenCalledWith("➡️ Request:", ctx.url, ctx.init);
+    expect(logSpy).toHaveBeenCalledWith("⬅️ Response:", 200);
+
+    logSpy.mockRestore();
+  });
+
+  // ---------------- RETRY ----------------
+  it("retryMiddleware should retry failed requests", async () => {
+    const ctx = mockCtx();
+    let attempt = 0;
+
+    const next = jest.fn().mockImplementation(() => {
+      attempt++;
+      if (attempt < 2) throw new Error("fail");
+      return Promise.resolve(new Response(JSON.stringify({ ok: true })));
+    });
+
+    const middleware = retryMiddleware({ maxRetries: 3, delay: 10 });
+
+    const res = await middleware(ctx, next);
+    const json = await res.json();
+
+    expect(json.ok).toBe(true);
+    expect(next).toHaveBeenCalledTimes(2);
+  });
+
+  it("retryMiddleware should throw after exceeding maxRetries", async () => {
+    const ctx = mockCtx();
+    const next = jest.fn().mockRejectedValue(new Error("fail always"));
+
+    const middleware = retryMiddleware({ maxRetries: 2, delay: 10 });
+
+    await expect(middleware(ctx, next)).rejects.toThrow("fail always");
+    expect(next).toHaveBeenCalledTimes(3); // initial + 2 retries
+  });
+});

package/src/client.ts

@@ -0,0 +1,142 @@
+import {
+  Contracts,
+  EndpointDef,
+  EndpointDefZ,
+  Middleware,
+  ErrorLike,
+  EndpointMethods,
+} from "./types";
+import { z } from "zod";
+
+export class RichError extends Error implements ErrorLike {
+  status?: number;
+  code?: string;
+  title?: string;
+  detail?: string;
+  errors?: Record<string, string[]>;
+
+  constructor(error: Partial<ErrorLike> & { message: string }) {
+    super(error.message);
+    Object.assign(this, error);
+  }
+}
+
+export class ApiClient<C extends Contracts, E extends ErrorLike = RichError> {
+  private middlewares: Array<{ fn: Middleware; options?: any }> = [];
+  private errorHandler?: (error: E) => void;
+  private responseTransform: (data: any) => any = (d) => d;
+
+  private _modules!: {
+    [M in keyof C]: EndpointMethods<C[M]>;
+  };
+
+  constructor(
+    private config: { baseUrl: string; token?: string },
+    private contracts: C
+  ) {}
+
+  init() {
+    const modules = {} as {
+      [M in keyof C]: EndpointMethods<C[M]>;
+    };
+
+    for (const moduleName in this.contracts) {
+      const module = this.contracts[moduleName];
+      (modules as any)[moduleName] = {} as EndpointMethods<typeof module>;
+
+      for (const endpointName in module) {
+        const endpoint = module[endpointName] as EndpointDefZ;
+
+        (modules as any)[moduleName][endpointName] = (
+          input: z.infer<(typeof endpoint)["request"]>
+        ) => this.request(endpoint, input);
+      }
+    }
+
+    this._modules = modules;
+  }
+
+  get modules() {
+    return this._modules;
+  }
+
+  use<T>(middleware: Middleware<T>, options?: T) {
+    this.middlewares.push({ fn: middleware, options });
+  }
+
+  onError(handler: (error: E) => void) {
+    this.errorHandler = handler;
+  }
+
+  useResponseTransform(fn: (data: any) => any) {
+    this.responseTransform = fn;
+  }
+
+  private async request<TReq extends z.ZodTypeAny, TRes extends z.ZodTypeAny>(
+    endpoint: EndpointDef<TReq, TRes>,
+    input: z.infer<TReq>
+  ): Promise<z.infer<TRes>> {
+    endpoint.request.parse(input);
+
+    if (endpoint.auth && !this.config.token) {
+      const error = this.createError({
+        message: `Missing token for ${endpoint.path}`,
+        status: 401,
+        code: "NO_TOKEN",
+      });
+      this.errorHandler?.(error as unknown as E);
+      throw error;
+    }
+
+    const headers: HeadersInit = { "Content-Type": "application/json" };
+    if (endpoint.auth && this.config.token)
+      headers["Authorization"] = `Bearer ${this.config.token}`;
+
+    const ctx = {
+      url: this.config.baseUrl + endpoint.path,
+      init: {
+        method: endpoint.method,
+        headers,
+        body: endpoint.method !== "GET" ? JSON.stringify(input) : undefined,
+      },
+    };
+
+    const runner = this.middlewares.reduceRight(
+      (next, mw) => () => mw.fn(ctx, next, mw.options),
+      () => fetch(ctx.url, ctx.init)
+    );
+
+    try {
+      const res = await runner();
+      if (!res.ok) {
+        const errorData = await res.json().catch(() => ({}));
+        const error = this.createError({
+          message: errorData.message || res.statusText,
+          status: res.status,
+          code: errorData.code,
+          title: errorData.title,
+          detail: errorData.detail,
+          errors: errorData.errors,
+        });
+        this.errorHandler?.(error as unknown as E);
+        throw error;
+      }
+
+      const json = await res.json();
+      return this.responseTransform(endpoint.response.parse(json));
+    } catch (err: any) {
+      const error = this.normalizeError(err);
+      this.errorHandler?.(error as unknown as E);
+      throw error;
+    }
+  }
+
+  private createError(error: Partial<RichError> & { message: string }) {
+    return new RichError(error);
+  }
+
+  private normalizeError(err: any) {
+    if (err instanceof RichError) return err;
+    return this.createError({ message: err.message || "Unknown error" });
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./client";
+export * from "./middlewares/logging";
+export * from "./middlewares/retry";
+export * from "./middlewares/auth";
+export * from "./middlewares/cache";

package/src/middlewares/auth.ts

@@ -0,0 +1,19 @@
+import { Middleware } from "../types";
+
+export type AuthOptions = {
+  refreshToken?: () => Promise<string>;
+};
+
+export const authMiddleware: Middleware<AuthOptions> = async (ctx, next, options) => {
+  if (options?.refreshToken) {
+    try {
+      const newToken = await options.refreshToken();
+      ctx.init.headers = {
+        ...ctx.init.headers,
+        Authorization: `Bearer ${newToken}`
+      };
+    } catch {}
+  }
+
+  return next();
+};

package/src/middlewares/cache.ts

@@ -0,0 +1,26 @@
+import { MiddlewareContext, MiddlewareNext } from "../types";
+
+export type CacheOptions = { ttl?: number };
+
+export const cacheMiddleware = (options: CacheOptions = {}) => {
+  const { ttl = 60000 } = options;
+  const cache = new Map<string, { data: any; expires: number }>();
+
+  return async (ctx: MiddlewareContext, next: MiddlewareNext) => {
+    if (ctx.init.method === "GET") {
+      const cached = cache.get(ctx.url);
+      const now = Date.now();
+      if (cached && cached.expires > now)
+        return new Response(JSON.stringify(cached.data));
+
+      const res = await next();
+      const data = await res
+        .clone()
+        .json()
+        .catch(() => null);
+      if (data) cache.set(ctx.url, { data, expires: now + ttl });
+      return res;
+    }
+    return next();
+  };
+};

package/src/middlewares/logging.ts

@@ -0,0 +1,19 @@
+import { Middleware } from "../types";
+
+export type LoggingOptions = {
+  logRequest?: boolean;
+  logResponse?: boolean;
+  debug?: boolean;
+};
+
+export const loggingMiddleware: Middleware<LoggingOptions> = async (ctx, next, options) => {
+  const { logRequest = true, logResponse = true, debug = true } = options || {};
+
+  if (debug && logRequest) console.log("➡️ Request:", ctx.url, ctx.init);
+
+  const res = await next();
+
+  if (debug && logResponse) console.log("⬅️ Response:", res.status);
+
+  return res;
+};

package/src/middlewares/retry.ts

@@ -0,0 +1,25 @@
+import { Middleware } from "../types";
+
+export type RetryOptions = {
+  maxRetries?: number;
+  delay?: number; // ms
+};
+
+export const retryMiddleware = (options?: RetryOptions): Middleware => {
+  const { maxRetries = 3, delay = 500 } = options || {};
+
+  const middleware: Middleware = async (ctx, next) => {
+    let attempt = 0;
+    while (true) {
+      try {
+        return await next();
+      } catch (err) {
+        if (attempt >= maxRetries) throw err;
+        attempt++;
+        await new Promise(r => setTimeout(r, delay * 2 ** attempt));
+      }
+    }
+  };
+
+  return middleware;
+};

package/src/types.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+export type EndpointDef<
+  TReq extends z.ZodTypeAny,
+  TRes extends z.ZodTypeAny
+> = {
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  path: string;
+  auth?: boolean;
+  request: TReq;
+  response: TRes;
+};
+
+export type Contracts = {
+  [ModuleName: string]: {
+    [EndpointName: string]: EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+  };
+};
+
+export interface MiddlewareContext {
+  url: string;
+  init: RequestInit;
+}
+
+export type MiddlewareNext = () => Promise<Response>;
+
+export type Middleware<Options = any> = (
+  ctx: MiddlewareContext,
+  next: MiddlewareNext,
+  options?: Options
+) => Promise<Response>;
+
+export type ErrorLike = {
+  message: string;
+  status?: number;
+  code?: string;
+  [key: string]: any;
+};
+
+export type EndpointDefZ = EndpointDef<z.ZodTypeAny, z.ZodTypeAny>;
+
+export type EndpointMethods<M extends Record<string, EndpointDefZ>> = {
+  [K in keyof M]: (
+    input: z.infer<M[K]["request"]>
+  ) => Promise<z.infer<M[K]["response"]>>;
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src", "__test__"]
+}