@rexeus/typeweaver-clients 0.0.1

package/dist/lib/ApiClient.ts

@@ -0,0 +1,189 @@
+import type {
+  IHttpQuery,
+  IHttpParam,
+  IHttpHeader,
+  IHttpResponse,
+} from "@rexeus/typeweaver-core";
+import { RequestCommand } from "./RequestCommand";
+import axios, {
+  AxiosError,
+  type AxiosInstance,
+  type AxiosResponse,
+} from "axios";
+import Case from "case";
+
+/**
+ * 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;
+};
+
+/**
+ * Abstract base class for type-safe API clients.
+ *
+ * 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 */
+  public readonly baseUrl: string;
+
+  /**
+   * 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.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"
+      );
+    }
+  }
+
+  /**
+   * 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);
+
+    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");
+        }
+
+        throw new Error("Network error: Unknown error");
+      }
+
+      throw new Error(`Network error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private createResponse(response: AxiosResponse): IHttpResponse {
+    const header: IHttpHeader = Object.entries(response.headers).reduce(
+      (acc, [key, value]) => {
+        if (!value) {
+          return acc;
+        }
+
+        const lowerCaseKey = key.toLowerCase();
+        const headerCaseKey = Case.header(lowerCaseKey);
+
+        return {
+          ...acc,
+          [headerCaseKey]: value,
+          [lowerCaseKey]: value,
+        };
+      },
+      {}
+    );
+
+    return {
+      body: response.data,
+      header,
+      statusCode: response.status,
+    };
+  }
+
+  private createPath(path: string, param?: IHttpParam): string {
+    if (!param) {
+      return path;
+    }
+
+    return Object.entries(param).reduce((acc, [key, value]) => {
+      const result = acc.replace(`:${key}`, value);
+
+      if (result === acc) {
+        throw new Error(
+          `Path parameter '${key}' is not found in path '${path}'`
+        );
+      }
+
+      return result;
+    }, path);
+  }
+
+  private addQuery(url: URL, query?: IHttpQuery): void {
+    if (!query) {
+      return;
+    }
+
+    const searchParams = url.searchParams;
+    for (const [key, value] of Object.entries(query)) {
+      if (!Array.isArray(value)) {
+        searchParams.append(key, value);
+        continue;
+      }
+
+      for (const item of value) {
+        searchParams.append(key, item);
+      }
+    }
+  }
+
+  private createUrl(path: string, query?: IHttpQuery): string {
+    const url = new URL(path, this.baseUrl);
+
+    this.addQuery(url, query);
+
+    return url.toString();
+  }
+
+  private createHeader(header: any): any {
+    return header;
+  }
+}

package/dist/lib/RequestCommand.ts

@@ -0,0 +1,61 @@
+import {
+  type HttpMethod,
+  type IHttpRequest,
+  type IHttpHeader,
+  type IHttpParam,
+  type IHttpQuery,
+  type IHttpBody,
+  type IHttpResponse,
+  HttpResponse,
+} from "@rexeus/typeweaver-core";
+
+/**
+ * Abstract base class for type-safe API request commands.
+ *
+ * This class represents a command pattern for HTTP requests, providing:
+ * - Type-safe request parameters (headers, path params, query, body)
+ * - Response processing abstraction
+ * - Integration with ApiClient for execution
+ *
+ * Implementations should:
+ * 1. Set all readonly properties in the constructor
+ * 2. Implement processResponse to handle response transformation
+ *
+ * @template Header - The HTTP header type
+ * @template Param - The path parameter type
+ * @template Query - The query string parameter type
+ * @template Body - The request body type
+ */
+export abstract class RequestCommand<
+  Header extends IHttpHeader = IHttpHeader | undefined,
+  Param extends IHttpParam = IHttpParam | undefined,
+  Query extends IHttpQuery = IHttpQuery | undefined,
+  Body extends IHttpBody = IHttpBody | undefined,
+> implements IHttpRequest
+{
+  /** The HTTP method for this request */
+  public readonly method!: HttpMethod;
+  /** The URL path pattern with parameter placeholders (e.g., '/users/:id') */
+  public readonly path!: string;
+  /** HTTP headers to send with the request */
+  public readonly header!: Header;
+  /** Path parameters to substitute in the URL */
+  public readonly param!: Param;
+  /** Query string parameters */
+  public readonly query!: Query;
+  /** Request body data */
+  public readonly body!: Body;
+
+  /**
+   * Processes the raw HTTP response into a typed response object.
+   *
+   * This method should handle:
+   * - Response validation
+   * - Data transformation
+   * - Error response handling
+   *
+   * @param response - The raw HTTP response from the server
+   * @returns The processed, type-safe response object
+   */
+  public abstract processResponse(response: IHttpResponse): HttpResponse;
+}

package/dist/lib/index.ts

@@ -0,0 +1,2 @@
+export * from "./ApiClient";
+export * from "./RequestCommand";

package/dist/templates/Client.ejs

@@ -0,0 +1,39 @@
+import { ApiClient, type ApiClientProps } from "../lib/clients";
+<% for (const operation of operations) { %>
+import { <%= operation.operationId %>RequestCommand, type Successful<%= operation.operationId %>Response } from "<%= operation.requestFile %>";
+<% } %>
+
+export type <%= pascalCaseEntityName %>RequestCommands =
+<% for (const operation of operations) { %>
+    | <%= operation.operationId %>RequestCommand
+<% } %>;
+
+export type Successful<%= pascalCaseEntityName %>Responses =
+<% for (const operation of operations) { %>
+    | Successful<%= operation.operationId %>Response
+<% } %>;
+
+
+export class <%= pascalCaseEntityName %>Client extends ApiClient {
+    public constructor(props: ApiClientProps) {
+        super(props);
+    }
+
+    <% for (const operation of operations) { %>
+    public async send(command: <%= operation.operationId %>RequestCommand): Promise<Successful<%= operation.operationId %>Response>;
+    <% } %>
+    public async send(command: <%= pascalCaseEntityName %>RequestCommands): Promise<Successful<%= pascalCaseEntityName %>Responses> {
+        const response = await this.execute(command);
+
+        switch (true) {
+        <% for (const operation of operations) { %>
+            case command instanceof <%= operation.operationId %>RequestCommand: {
+                return command.processResponse(response);
+            }
+        <% } %>
+            default: {
+                throw new Error("Command is not supported");
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rexeus/typeweaver-clients",
+  "version": "0.0.1",
+  "description": "HTTP client generator for TypeWeaver API framework",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "api",
+    "spec",
+    "definition",
+    "typescript",
+    "zod",
+    "generator",
+    "typeweaver"
+  ],
+  "author": "Dennis Wentzien <dw@rexeus.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rexeus/typeweaver.git",
+    "directory": "packages/clients"
+  },
+  "bugs": {
+    "url": "https://github.com/rexeus/typeweaver/issues"
+  },
+  "homepage": "https://github.com/rexeus/typeweaver#readme",
+  "peerDependencies": {
+    "axios": "^1.7.0"
+  },
+  "devDependencies": {
+    "case": "^1.6.3",
+    "axios": "^1.9.0",
+    "@rexeus/typeweaver-core": "0.0.1",
+    "@rexeus/typeweaver-gen": "0.0.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "build": "pkgroll --clean-dist && cp -r ./src/templates ./dist/templates && cp -r ./src/lib ./dist/lib",
+    "preversion": "npm run build"
+  }
+}