@rexeus/typeweaver-clients 0.0.2 → 0.0.4

package/README.md

@@ -1,411 +1,136 @@
-# @rexeus/typeweaver-clients
+# 🧵✨ @rexeus/typeweaver-clients
 
-HTTP client generators for TypeWeaver API specifications.
+[![npm version](https://img.shields.io/npm/v/@rexeus/typeweaver-clients.svg)](https://www.npmjs.com/package/@rexeus/typeweaver-clients)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-## Overview
+Typeweaver is a type-safe HTTP API framework built for API-first development with a focus on
+developer experience. Use typeweaver to specify your HTTP APIs in TypeScript and Zod, and generate
+clients, validators, routers, and more ✨
 
-This plugin generates type-safe HTTP API clients from your TypeWeaver API definitions, providing
-end-to-end type safety from API definition to client usage.
+## 📝 Clients Plugin
 
-## Installation
+This plugin generates type-safe HTTP clients from your typeweaver API definitions, providing
+end-to-end type safety. The generated clients use the Command Pattern, where each API request is
+encapsulated as a typed command object that contains all request data and handles response
+processing.
 
-```bash
-npm install @rexeus/typeweaver-clients
-```
-
-**Peer Dependencies:**
+## 📥 Installation
 
 ```bash
-npm install @rexeus/typeweaver-core @rexeus/typeweaver-gen
-```
+# Install the CLI and the plugin as a dev dependency
+npm install -D @rexeus/typeweaver @rexeus/typeweaver-clients
 
-## Usage
+# Install the runtime as a dependency
+npm install @rexeus/typeweaver-core
+```
 
-### CLI
+## 💡 How to use
 
 ```bash
 npx typeweaver generate --input ./api/definitions --output ./api/generated --plugins clients
 ```
 
-### Configuration File
+More on the CLI in [@rexeus/typeweaver](https://github.com/rexeus/typeweaver/tree/main/packages/cli/README.md#️-cli).
 
-```javascript
-// typeweaver.config.js
-export default {
-  input: "./api/definitions",
-  output: "./api/generated",
-  plugins: ["clients"],
-};
-```
-
-## Generated Output
+## 📂 Generated Output
 
-This plugin generates HTTP API clients for each entity in your API definitions.
+For each resource (e.g., `Todo`), the plugin generates a HTTP client. This client can execute
+request commands for all operations of this resource. This plugin generates the following files:
 
-### Example Generated Client
+- `<ResourceName>Client.ts` - e.g. `TodoClient.ts`
+- `<OperationId>RequestCommand.ts` - e.g. `CreateTodoRequestCommand.ts`
 
-For an API definition with a `users` entity, the plugin generates:
+### 📡 Clients
 
-```typescript
-// UsersClient.ts
-import { ApiClient } from "@rexeus/typeweaver-core";
-import { GetUserRequestCommand } from "./GetUserRequest";
-import { GetUserResponseValidator } from "./GetUserResponseValidator";
-// ... other imports
+Resource-specific HTTP clients are generated as `<ResourceName>Client.ts` files, e.g.
+`TodoClient.ts`. Each client extends the `ApiClient` base class and provides:
 
-export class UsersClient extends ApiClient {
-  public send(command: GetUserRequestCommand): Promise<GetUserResponse>;
-  public send(command: CreateUserRequestCommand): Promise<CreateUserResponse>;
-  // ... other overloads
+- **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
+- **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.
+- **Unknown response handling**
+  - Unknown properties are automatically removed from the response. If a response exceeds the
+    definition, it is not rejected directly.
+  - If a response does not match any known format, it will be rejected by default as an
+    `UnknownResponse` instance.
+  - This unknown response handling can be configured. It is also possible for an `UnknownResponse`
+    instance to be created without being thrown.
 
-  public async send(command: unknown): Promise<unknown> {
-    if (command instanceof GetUserRequestCommand) {
-      return this.handleGetUser(command);
-    }
-    if (command instanceof CreateUserRequestCommand) {
-      return this.handleCreateUser(command);
-    }
-    // ... other handlers
-
-    throw new Error(`Unknown command type`);
-  }
-
-  private async handleGetUser(command: GetUserRequestCommand): Promise<GetUserResponse> {
-    const response = await this.makeRequest(command);
-    const validator = new GetUserResponseValidator();
-    return validator.validate(response);
-  }
-
-  // ... other private handlers
-}
-```
-
-## Usage Examples
-
-### Basic Usage
+**Using generated clients**
 
 ```typescript
-import { UsersClient } from "./api/generated/users/UsersClient";
-import { GetUserRequestCommand } from "./api/generated/users/GetUserRequest";
-
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-});
+import { TodoClient } from "path/to/generated/output";
 
-// Type-safe request
-const command = new GetUserRequestCommand({
-  param: { userId: "123" },
-  header: { Authorization: "Bearer token" },
+const client = new TodoClient({
+  axiosInstance: customAxios, // Custom axios instance
+  baseUrl: "https://api.example.com", // Base URL for all requests
+  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
 });
-
-try {
-  // Fully typed response
-  const result = await client.send(command);
-  console.log(result.body.name); // Type-safe access
-} catch (error) {
-  // Typed error handling
-  if (error instanceof UserNotFoundErrorResponse) {
-    console.error("User not found:", error.body.message);
-  }
-}
 ```
 
-### Advanced Configuration
+### ✉️ Request Commands
 
-```typescript
-import { UsersClient } from "./api/generated/users/UsersClient";
+Request commands are generated as `<OperationId>RequestCommand.ts` files, e.g.
+`CreateTodoRequestCommand.ts`. These commands encapsulate all request data and provide:
 
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-  timeout: 5000,
-  headers: {
-    "User-Agent": "MyApp/1.0",
-  },
-  // Custom axios config
-  axios: {
-    validateStatus: status => status < 500,
-  },
-});
-```
+- **Type-safe construction** - Constructor enforces correct request structure
+- **Complete request encapsulation** - Contains method, path, headers, query parameters, and body
+- **Response processing** - Transform raw HTTP responses into typed response objects of the correct
+  response class
 
-### Error Handling
+### Basic Usage
 
 ```typescript
 import {
-  UsersClient,
-  GetUserRequestCommand,
-  UserNotFoundErrorResponse,
+  TodoClient,
+  CreateTodoRequestCommand,
+  CreateTodoSuccessResponse,
+  OtherSuccessResponse,
   ValidationErrorResponse,
-} from "./api/generated";
-
-const client = new UsersClient({ baseURL: "https://api.example.com" });
+  InternalServerErrorResponse,
+} from "path/to/generated/output";
 
-try {
-  const result = await client.send(
-    new GetUserRequestCommand({
-      param: { userId: "invalid-id" },
-    })
-  );
-} catch (error) {
-  // Type-safe error handling
-  if (error instanceof UserNotFoundErrorResponse) {
-    console.error(`User not found: ${error.body.message}`);
-  } else if (error instanceof ValidationErrorResponse) {
-    console.error("Validation failed:", error.body.issues);
-  } else {
-    console.error("Unexpected error:", error);
-  }
-}
-```
-
-## Client Features
-
-### Type Safety
-
-- **Request Commands** - Fully typed request objects
-- **Response Types** - Typed response interfaces
-- **Error Types** - Typed error response classes
-- **Parameter Validation** - Runtime validation via Zod
-
-### Method Overloading
-
-Each client provides method overloads for perfect type inference:
-
-```typescript
-// Each command type gets its own overload
-client.send(getUserCommand); // Returns GetUserResponse
-client.send(createUserCommand); // Returns CreateUserResponse
-```
-
-### Automatic Validation
-
-- **Request validation** - Commands validate input data
-- **Response validation** - Responses validated against schemas
-- **Error parsing** - HTTP errors mapped to typed error classes
-
-### Framework Integration
-
-Works with any HTTP client framework (uses Axios by default):
-
-```typescript
-// Custom HTTP adapter
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-  httpAdapter: new FetchAdapter(), // Custom adapter
+const client = new TodoClient({
+  baseUrl: "https://api.example.com",
 });
-```
-
-## Request Commands
-
-### Command Structure
 
-Generated request commands encapsulate all request data:
-
-```typescript
-import { GetUserRequestCommand } from "./GetUserRequest";
-
-const command = new GetUserRequestCommand({
-  param: { userId: "123" }, // Path parameters
-  query: { include: ["posts"] }, // Query parameters
-  header: { Authorization: "Bearer token" }, // Headers
-  body: { name: "John Doe" }, // Request body
+const command = new CreateTodoRequestCommand({
+  header: { Authorization: "Bearer token" },
+  body: { title: "New Todo", status: "PENDING" },
 });
-```
-
-### Command Validation
 
-Commands validate input data at construction time:
-
-```typescript
 try {
-  const command = new GetUserRequestCommand({
-    param: { userId: "invalid-uuid" }, // Will throw validation error
-  });
-} catch (error) {
-  console.error("Invalid command:", error.issues);
-}
-```
-
-## Response Handling
+  const response = await client.send(command);
 
-### Success Responses
+  // If there is only one success response,
+  // you can directly access the response like:
+  console.log("Success:", response.body);
 
-```typescript
-const result = await client.send(command);
-
-// Typed access to response data
-console.log(result.statusCode); // HTTP status code
-console.log(result.header); // Response headers
-console.log(result.body.id); // Response body (fully typed)
-```
-
-### Error Responses
-
-```typescript
-try {
-  const result = await client.send(command);
-} catch (error) {
-  if (error instanceof UserNotFoundErrorResponse) {
-    // Specific error type
-    console.log(error.statusCode); // 404
-    console.log(error.body.message); // "User not found"
+  // If there are multiple success responses, you can check the instance like:
+  if (response instanceof CreateTodoSuccessResponse) {
+    console.log("Todo created successfully:", response.body);
   }
-}
-```
-
-## Plugin Architecture
-
-This plugin extends the TypeWeaver plugin system:
-
-```typescript
-import { BasePlugin, type GeneratorContext } from "@rexeus/typeweaver-gen";
-
-export default class ClientsPlugin extends BasePlugin {
-  public name = "clients";
-
-  public override generate(context: GeneratorContext): void {
-    // Generates API clients for each entity
+  if (response instanceof OtherSuccessResponse) {
+    // ... Handle "OtherSuccessResponse"
   }
-}
-```
-
-## Best Practices
-
-### Client Configuration
-
-```typescript
-// Environment-specific configuration
-const client = new UsersClient({
-  baseURL: process.env.API_BASE_URL,
-  timeout: parseInt(process.env.API_TIMEOUT || "5000"),
-  headers: {
-    "User-Agent": `${process.env.APP_NAME}/${process.env.APP_VERSION}`,
-  },
-});
-```
-
-### Error Handling Strategy
-
-```typescript
-// Centralized error handling
-async function handleApiCall<T>(operation: () => Promise<T>): Promise<T> {
-  try {
-    return await operation();
-  } catch (error) {
-    if (error instanceof ValidationErrorResponse) {
-      // Log validation issues
-      logger.warn("Validation error:", error.body.issues);
-    } else if (error instanceof UnauthorizedErrorResponse) {
-      // Handle auth errors
-      redirectToLogin();
-    }
-    throw error;
+  // ...
+} catch (error) {
+  if (error instanceof ValidationErrorResponse) {
+    // Handle validation errors
   }
-}
-
-// Usage
-const result = await handleApiCall(() =>
-  client.send(new GetUserRequestCommand({ param: { userId: "123" } }))
-);
-```
-
-### Testing
-
-```typescript
-// Mock clients for testing
-import { UsersClient } from "./api/generated";
-
-// Mock the client
-jest.mock("./api/generated/users/UsersClient");
-
-const mockClient = new UsersClient() as jest.Mocked<UsersClient>;
-mockClient.send.mockResolvedValue({
-  statusCode: 200,
-  body: { id: "123", name: "Test User" },
-});
-```
-
-## Integration Examples
-
-### React Hook
-
-```typescript
-import { useState, useEffect } from "react";
-import { UsersClient, GetUserRequestCommand } from "./api/generated";
-
-const client = new UsersClient({ baseURL: "https://api.example.com" });
-
-export function useUser(userId: string) {
-  const [user, setUser] = useState(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState(null);
-
-  useEffect(() => {
-    async function fetchUser() {
-      try {
-        setLoading(true);
-        const result = await client.send(
-          new GetUserRequestCommand({
-            param: { userId },
-          })
-        );
-        setUser(result.body);
-      } catch (err) {
-        setError(err);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchUser();
-  }, [userId]);
-
-  return { user, loading, error };
-}
-```
-
-### Node.js Service
-
-```typescript
-import { UsersClient, CreateUserRequestCommand } from "./api/generated";
-
-export class UserService {
-  private client = new UsersClient({
-    baseURL: process.env.API_BASE_URL,
-  });
-
-  async createUser(userData: CreateUserRequest["body"]) {
-    const command = new CreateUserRequestCommand({
-      body: userData,
-      header: {
-        Authorization: `Bearer ${process.env.API_TOKEN}`,
-      },
-    });
-
-    return await this.client.send(command);
+  if (error instanceof InternalServerErrorResponse) {
+    // Handle internal server errors
   }
+  // ... Handle other errors
 }
 ```
 
-## Troubleshooting
-
-### Common Issues
-
-**Import errors**: Ensure all TypeWeaver plugins are installed **Type errors**: Regenerate code
-after API definition changes **Runtime errors**: Check that server API matches generated client
-expectations
-
-### Debug Mode
-
-Enable verbose logging:
-
-```typescript
-const client = new UsersClient({
-  baseURL: "https://api.example.com",
-  debug: true, // Enable debug logging
-});
-```
-
-## License
+## 📄 License
 
-ISC © Dennis Wentzien 2025
+Apache 2.0 © Dennis Wentzien 2025