@rexeus/typeweaver-clients 0.4.1 → 0.5.0

package/README.md

@@ -31,7 +31,8 @@ npm install @rexeus/typeweaver-core
 npx typeweaver generate --input ./api/definitions --output ./api/generated --plugins clients
 ```
 
-More on the CLI in [@rexeus/typeweaver](https://github.com/rexeus/typeweaver/tree/main/packages/cli/README.md#️-cli).
+More on the CLI in
+[@rexeus/typeweaver](https://github.com/rexeus/typeweaver/tree/main/packages/cli/README.md#️-cli).
 
 ## 📂 Generated Output
 
@@ -48,7 +49,8 @@ Resource-specific HTTP clients are generated as `<ResourceName>Client.ts` files,
 
 - **Type-safe HTTP methods** - Method overloads for each operation ensuring compile-time type
   checking
-- **axios based** - Supports all axios features and interceptors by using custom axios instances
+- **fetch based** - Zero dependencies, uses the native fetch API. Supports custom fetch functions
+  for middleware and testing
 - **Response type mapping** - Each response is automatically mapped to the associated response class
   and an instance of the class is returned. This ensures that all responses are in the defined
   format and it is type-safe.
@@ -66,8 +68,8 @@ Resource-specific HTTP clients are generated as `<ResourceName>Client.ts` files,
 import { TodoClient } from "path/to/generated/output";
 
 const client = new TodoClient({
-  axiosInstance: customAxios, // Custom axios instance
-  baseUrl: "https://api.example.com", // Base URL for all requests
+  fetchFn: customFetch, // Custom fetch function (optional, defaults to globalThis.fetch)
+  baseUrl: "https://api.example.com", // Base URL for all requests (required)
   unknownResponseHandling: "throw", // "throw" | "passthrough" for unknown responses
   // -> In "passthrough" mode, the received status code determines if the response is thrown
   isSuccessStatusCode: code => code < 400, // Custom success status code predicate, determines whether the response is successful or should be thrown

package/dist/lib/ApiClient.ts

@@ -5,16 +5,18 @@
  * @generated by @rexeus/typeweaver
  */
 
-import axios, { AxiosError } from "axios";
 import type {
   IHttpHeader,
   IHttpParam,
   IHttpQuery,
   IHttpResponse,
 } from "@rexeus/typeweaver-core";
+import { NetworkError } from "./NetworkError";
+import { PathParameterError } from "./PathParameterError";
 import { RequestCommand } from "./RequestCommand";
+import { ResponseParseError } from "./ResponseParseError";
+import type { NetworkErrorCode } from "./NetworkError";
 import type { ProcessResponseOptions } from "./RequestCommand";
-import type { AxiosHeaderValue, AxiosInstance, AxiosResponse } from "axios";
 
 /**
  * Configuration options for handling unknown responses.
@@ -25,14 +27,25 @@ export type UnknownResponseHandling = "throw" | "passthrough";
  * Configuration options for ApiClient initialization.
  */
 export type ApiClientProps = {
-  /** Custom Axios instance with pre-configured defaults */
-  axiosInstance?: AxiosInstance;
-  /** Base URL for API requests. If not provided, must be set in axiosInstance */
-  baseUrl?: string;
+  /** Custom fetch function for HTTP requests. Defaults to globalThis.fetch */
+  readonly fetchFn?: typeof globalThis.fetch;
+  /** Base URL for API requests */
+  readonly baseUrl: string;
   /** How to handle unknown responses. Defaults to "throw" */
-  unknownResponseHandling?: UnknownResponseHandling;
+  readonly unknownResponseHandling?: UnknownResponseHandling;
   /** Predicate to determine if a status code represents success. Defaults to 2xx status codes */
-  isSuccessStatusCode?: (statusCode: number) => boolean;
+  readonly isSuccessStatusCode?: (statusCode: number) => boolean;
+  /** Request timeout in milliseconds. When set, requests will be aborted after this duration */
+  readonly timeoutMs?: number;
+};
+
+const NETWORK_ERROR_MESSAGES: Readonly<
+  Partial<Record<NetworkErrorCode, string>>
+> = {
+  ECONNREFUSED: "Connection refused",
+  ECONNRESET: "Connection reset by peer",
+  ENOTFOUND: "DNS lookup failed",
+  ETIMEDOUT: "Connection timed out",
 };
 
 /**
@@ -41,49 +54,38 @@ export type ApiClientProps = {
  * This class provides HTTP request execution with:
  * - Automatic path parameter substitution (`:param` style)
  * - Query string building with array support
- * - Header normalization (converts to Header-Case)
  * - Network error handling with specific error messages
  * - Integration with RequestCommand pattern for type safety
  */
 export abstract class ApiClient {
-  /** The Axios instance used for HTTP requests */
-  public readonly axiosInstance: AxiosInstance;
-  /** The base URL for all API requests */
+  private readonly fetchFn: typeof globalThis.fetch;
   public readonly baseUrl: string;
-  /** How to handle unknown responses */
   public readonly unknownResponseHandling: UnknownResponseHandling;
-  /** Predicate to determine if a status code represents success */
   public readonly isSuccessStatusCode: (statusCode: number) => boolean;
+  private readonly timeoutMs: number | undefined;
 
-  /**
-   * Creates a new ApiClient instance.
-   *
-   * @param props - Configuration options
-   * @throws {Error} If no base URL is provided in props or axios instance
-   */
   protected constructor(props: ApiClientProps) {
-    this.axiosInstance = props.axiosInstance ?? axios.create();
+    this.fetchFn = props.fetchFn ?? globalThis.fetch.bind(globalThis);
+    this.baseUrl = props.baseUrl;
 
-    this.baseUrl = props.baseUrl ?? this.axiosInstance.defaults.baseURL ?? "";
     if (!this.baseUrl) {
-      throw new Error(
-        "Base URL must be provided either in axios instance or in constructor"
-      );
+      throw new Error("Base URL must be provided");
+    }
+
+    if (
+      props.timeoutMs !== undefined &&
+      (props.timeoutMs <= 0 || !Number.isFinite(props.timeoutMs))
+    ) {
+      throw new Error("timeoutMs must be a positive finite number");
     }
-    this.axiosInstance.defaults.baseURL = undefined;
 
     this.unknownResponseHandling = props.unknownResponseHandling ?? "throw";
     this.isSuccessStatusCode =
       props.isSuccessStatusCode ??
       ((statusCode: number) => statusCode >= 200 && statusCode < 300);
+    this.timeoutMs = props.timeoutMs;
   }
 
-  /**
-   * Gets the process response options for this client instance.
-   *
-   * @returns The configuration options for processing responses
-   * @protected
-   */
   protected get processResponseOptions(): ProcessResponseOptions {
     return {
       unknownResponseHandling: this.unknownResponseHandling,
@@ -91,79 +93,247 @@ export abstract class ApiClient {
     };
   }
 
-  /**
-   * Executes an HTTP request using the provided command.
-   *
-   * This method:
-   * 1. Substitutes path parameters (e.g., `:id` with actual values)
-   * 2. Builds the complete URL with query parameters
-   * 3. Sends the HTTP request via Axios
-   * 4. Normalizes the response format
-   * 5. Handles network errors with specific error messages
-   *
-   * @param request - The request command containing all HTTP parameters
-   * @returns Promise resolving to the HTTP response
-   * @throws {Error} Network errors with specific messages (connection refused, timeout, etc.)
-   * @protected
-   */
   protected async execute(request: RequestCommand): Promise<IHttpResponse> {
     const { method, path, header, query, param, body } = request;
 
-    const headers = this.createHeader(header);
     const pathWithParam = this.createPath(path, param);
-    const url = this.createUrl(pathWithParam, query);
+    const relativeUrl = this.createUrl(pathWithParam, query);
+    const fullUrl = this.buildFullUrl(relativeUrl);
 
-    try {
-      const response = await this.axiosInstance.request({
-        method,
-        url,
-        data: body,
-        headers,
-      });
-
-      return this.createResponse(response);
-    } catch (error) {
-      if (error instanceof AxiosError) {
-        if (error.response) {
-          return this.createResponse(error.response);
-        }
-
-        // TODO: improve network error handling
-        if (error.code === "ECONNREFUSED") {
-          throw new Error("Network error: Connection refused");
-        }
-        if (error.code === "ECONNRESET") {
-          throw new Error("Network error: Connection reset by peer");
-        }
-        if (error.code === "ENOTFOUND") {
-          throw new Error("Network error: DNS lookup failed");
-        }
-        if (error.code === "ETIMEDOUT") {
-          throw new Error("Network error: Connection timed out");
-        }
+    const response = await this.performFetch(method, fullUrl, {
+      method,
+      headers: this.flattenHeaders(header),
+      body: this.serializeBody(body),
+      signal:
+        this.timeoutMs !== undefined
+          ? AbortSignal.timeout(this.timeoutMs)
+          : undefined,
+    });
 
-        throw new Error("Network error: Unknown error");
-      }
+    return await this.createResponse(response, method, fullUrl);
+  }
 
-      throw new Error(
-        `Network error: ${error instanceof Error ? error.message : String(error)}`
-      );
+  private async performFetch(
+    method: string,
+    url: string,
+    init: RequestInit
+  ): Promise<Response> {
+    try {
+      return await this.fetchFn(url, init);
+    } catch (error) {
+      throw this.createNetworkError(error, method, url);
     }
   }
 
-  private createResponse(response: AxiosResponse): IHttpResponse {
+  private async createResponse(
+    response: Response,
+    method: string,
+    url: string
+  ): Promise<IHttpResponse> {
     const header: IHttpHeader = {};
-    Object.entries(response.headers).forEach(([key, value]) => {
-      this.addMultiValue(header, key, String(value));
+    response.headers.forEach((value, key) => {
+      header[key] = value;
     });
 
+    if (typeof response.headers.getSetCookie === "function") {
+      const cookies = response.headers.getSetCookie();
+      if (cookies.length > 1) {
+        header["set-cookie"] = cookies;
+      }
+    }
+
+    const body = await this.parseResponseBody(response, method, url);
+
     return {
-      body: response.data,
+      body,
       header,
       statusCode: response.status,
     };
   }
 
+  private async readBody<T>(
+    read: () => Promise<T>,
+    response: Response,
+    method: string,
+    url: string
+  ): Promise<T> {
+    try {
+      return await read();
+    } catch (error) {
+      throw new ResponseParseError(
+        `Failed to read response body (${method} ${url})`,
+        response.status,
+        "",
+        { cause: error instanceof Error ? error : undefined }
+      );
+    }
+  }
+
+  private async parseResponseBody(
+    response: Response,
+    method: string,
+    url: string
+  ): Promise<unknown> {
+    if (response.status === 204 || response.status === 304) {
+      return undefined;
+    }
+
+    const contentType = response.headers.get("content-type");
+
+    if (this.isJsonContentType(contentType)) {
+      const text = await this.readBody(
+        () => response.text(),
+        response,
+        method,
+        url
+      );
+      if (!text) return undefined;
+      try {
+        return JSON.parse(text);
+      } catch (parseError) {
+        throw new ResponseParseError(
+          "Failed to parse JSON response",
+          response.status,
+          text.slice(0, 200),
+          {
+            cause: parseError instanceof Error ? parseError : undefined,
+          }
+        );
+      }
+    }
+
+    if (this.isTextContentType(contentType) || !contentType) {
+      const text = await this.readBody(
+        () => response.text(),
+        response,
+        method,
+        url
+      );
+      if (!text) return undefined;
+      return text;
+    }
+
+    return await this.readBody(
+      () => response.arrayBuffer(),
+      response,
+      method,
+      url
+    );
+  }
+
+  private isTextContentType(contentType: string | null): boolean {
+    if (!contentType) return false;
+    return contentType.includes("text/");
+  }
+
+  private createNetworkError(
+    error: unknown,
+    method: string,
+    url: string
+  ): NetworkError {
+    const context = `(${method} ${url})`;
+
+    if (
+      (error instanceof DOMException || error instanceof Error) &&
+      error.name === "TimeoutError"
+    ) {
+      return new NetworkError(
+        `Network error: Request timed out ${context}`,
+        "TIMEOUT",
+        method,
+        url,
+        { cause: error }
+      );
+    }
+
+    if (
+      (error instanceof DOMException || error instanceof Error) &&
+      error.name === "AbortError"
+    ) {
+      return new NetworkError(
+        `Network error: Request aborted ${context}`,
+        "ABORT",
+        method,
+        url,
+        { cause: error }
+      );
+    }
+
+    if (error instanceof TypeError) {
+      const cause = (error as TypeError & { cause?: { code?: string } }).cause;
+      const code = cause?.code;
+
+      if (code && code in NETWORK_ERROR_MESSAGES) {
+        const message = NETWORK_ERROR_MESSAGES[code as NetworkErrorCode];
+        return new NetworkError(
+          `Network error: ${message} ${context}`,
+          code as NetworkErrorCode,
+          method,
+          url,
+          { cause: error }
+        );
+      }
+    }
+
+    return new NetworkError(
+      `Network error: ${error instanceof Error ? error.message : String(error)} ${context}`,
+      "UNKNOWN",
+      method,
+      url,
+      { cause: error }
+    );
+  }
+
+  private flattenHeaders(
+    header: IHttpHeader
+  ): Record<string, string> | undefined {
+    if (header === undefined) return undefined;
+
+    const flattened: Record<string, string> = {};
+    for (const [key, value] of Object.entries(header)) {
+      flattened[key] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return flattened;
+  }
+
+  private serializeBody(
+    body: unknown
+  ): NonNullable<RequestInit["body"]> | undefined {
+    if (body === null || body === undefined) return undefined;
+    if (typeof body === "string") return body;
+    if (this.isNativeBody(body))
+      return body as NonNullable<RequestInit["body"]>;
+    return JSON.stringify(body);
+  }
+
+  private isNativeBody(body: unknown): boolean {
+    return (
+      body instanceof Blob ||
+      body instanceof ArrayBuffer ||
+      body instanceof FormData ||
+      body instanceof URLSearchParams ||
+      body instanceof ReadableStream ||
+      ArrayBuffer.isView(body)
+    );
+  }
+
+  private isJsonContentType(contentType: string | null): boolean {
+    if (!contentType) return false;
+    return (
+      contentType.includes("application/json") || contentType.includes("+json")
+    );
+  }
+
+  private buildFullUrl(relativePath: string): string {
+    const base = this.baseUrl.endsWith("/")
+      ? this.baseUrl.slice(0, -1)
+      : this.baseUrl;
+    const path = relativePath.startsWith("/")
+      ? relativePath
+      : `/${relativePath}`;
+    return `${base}${path}`;
+  }
+
   private createPath(path: string, param?: IHttpParam): string {
     if (!param) {
       return path;
@@ -173,8 +343,10 @@ export abstract class ApiClient {
       const result = acc.replace(`:${key}`, encodeURIComponent(value));
 
       if (result === acc) {
-        throw new Error(
-          `Path parameter '${key}' is not found in path '${path}'`
+        throw new PathParameterError(
+          `Path parameter '${key}' is not found in path '${path}'`,
+          key,
+          path
         );
       }
 
@@ -183,12 +355,9 @@ export abstract class ApiClient {
   }
 
   private createUrl(path: string, query?: IHttpQuery): string {
-    const base = this.baseUrl.replace(/\/+$/, "");
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
     const queryString = this.buildQueryString(query);
-    return queryString
-      ? `${base}${normalizedPath}?${queryString}`
-      : `${base}${normalizedPath}`;
+    return queryString ? `${normalizedPath}?${queryString}` : normalizedPath;
   }
 
   private buildQueryString(query?: IHttpQuery): string {
@@ -213,29 +382,4 @@ export abstract class ApiClient {
     }
     return params.toString();
   }
-
-  private createHeader(header: any): any {
-    return header;
-  }
-
-  private addMultiValue(
-    record: Record<string, string | string[]>,
-    key: string,
-    value: AxiosHeaderValue
-  ): void {
-    const existing = record[key];
-    const preparedValue = Array.isArray(value)
-      ? value.map(String)
-      : [String(value)];
-    if (existing) {
-      if (Array.isArray(existing)) {
-        existing.push(...preparedValue);
-      } else {
-        record[key] = [existing, ...preparedValue];
-      }
-    } else {
-      record[key] =
-        preparedValue.length > 1 ? preparedValue : (preparedValue[0] as string);
-    }
-  }
 }

package/dist/lib/NetworkError.ts

@@ -0,0 +1,39 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+/**
+ * Discriminated error codes for network-level failures.
+ */
+export type NetworkErrorCode =
+  | "TIMEOUT"
+  | "ABORT"
+  | "ECONNREFUSED"
+  | "ECONNRESET"
+  | "ENOTFOUND"
+  | "ETIMEDOUT"
+  | "UNKNOWN";
+
+/**
+ * Typed error for network-level failures during HTTP requests.
+ *
+ * Provides a discriminated `code` property for programmatic error handling
+ * instead of message string parsing. Thrown by ApiClient when the underlying
+ * fetch call fails before receiving a response.
+ */
+export class NetworkError extends Error {
+  public override readonly name = "NetworkError";
+
+  public constructor(
+    message: string,
+    public readonly code: NetworkErrorCode,
+    public readonly method: string,
+    public readonly url: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options);
+  }
+}

package/dist/lib/PathParameterError.ts

@@ -0,0 +1,26 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+/**
+ * Typed error for path parameter substitution failures.
+ *
+ * Thrown when a path parameter key does not match any placeholder in the
+ * URL path pattern. Exposes `paramName` and `path` properties for
+ * programmatic error handling.
+ */
+export class PathParameterError extends Error {
+  public override readonly name = "PathParameterError";
+
+  public constructor(
+    message: string,
+    public readonly paramName: string,
+    public readonly path: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options);
+  }
+}

package/dist/lib/RequestCommand.ts

@@ -47,8 +47,7 @@ export abstract class RequestCommand<
   Param extends IHttpParam = IHttpParam | undefined,
   Query extends IHttpQuery = IHttpQuery | undefined,
   Body extends IHttpBody = IHttpBody | undefined,
-> implements IHttpRequest
-{
+> implements IHttpRequest {
   /** The HTTP method for this request */
   public readonly method!: HttpMethod;
   /** The URL path pattern with parameter placeholders (e.g., '/users/:id') */

package/dist/lib/ResponseParseError.ts

@@ -0,0 +1,26 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+/**
+ * Typed error for response body parsing failures.
+ *
+ * Thrown when a JSON response body cannot be parsed. Provides structured
+ * metadata via `statusCode` and `bodyPreview` properties for diagnostics
+ * without relying on message string parsing.
+ */
+export class ResponseParseError extends Error {
+  public override readonly name = "ResponseParseError";
+
+  public constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly bodyPreview: string,
+    options?: ErrorOptions
+  ) {
+    super(message, options);
+  }
+}

package/dist/lib/index.ts

@@ -6,4 +6,7 @@
  */
 
 export * from "./ApiClient";
+export * from "./NetworkError";
+export * from "./PathParameterError";
 export * from "./RequestCommand";
+export * from "./ResponseParseError";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rexeus/typeweaver-clients",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Generates HTTP clients directly from your API definitions. Powered by Typeweaver 🧵✨",
   "type": "module",
   "sideEffects": false,
@@ -47,22 +47,20 @@
   },
   "homepage": "https://github.com/rexeus/typeweaver#readme",
   "peerDependencies": {
-    "axios": "^1.13.0",
     "zod": "^4.3.0",
-    "@rexeus/typeweaver-core": "^0.4.1",
-    "@rexeus/typeweaver-gen": "^0.4.1"
+    "@rexeus/typeweaver-gen": "^0.5.0",
+    "@rexeus/typeweaver-core": "^0.5.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.7",
-    "axios": "^1.13.2",
     "test-utils": "file:../test-utils",
     "zod": "^4.3.6",
-    "@rexeus/typeweaver-core": "^0.4.1",
-    "@rexeus/typeweaver-gen": "^0.4.1"
+    "@rexeus/typeweaver-core": "^0.5.0",
+    "@rexeus/typeweaver-gen": "^0.5.0"
   },
   "dependencies": {
     "case": "^1.6.3",
-    "@rexeus/typeweaver-zod-to-ts": "^0.4.1"
+    "@rexeus/typeweaver-zod-to-ts": "^0.5.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",