> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Transformer

> Request/response transformation middleware for data manipulation.

## Overview

The `transformer` middleware transforms request and response data, enabling format conversion, field mapping, and data manipulation.

Use it when you need:

* API version compatibility
* Field renaming/mapping
* Format conversion

## Installation

```go theme={null}
import "github.com/go-mizu/mizu/middlewares/transformer"
```

## Quick Start

```go theme={null}
app := mizu.New()

// Transform request JSON
app.Use(transformer.Request(func(data map[string]any) map[string]any {
    // Rename field
    data["user_name"] = data["username"]
    delete(data, "username")
    return data
}))
```

## Configuration

### Options

| Option     | Type                                  | Description        |
| ---------- | ------------------------------------- | ------------------ |
| `Request`  | `func(map[string]any) map[string]any` | Transform request  |
| `Response` | `func(map[string]any) map[string]any` | Transform response |

## Examples

### Request Transformation

```go theme={null}
app.Use(transformer.Request(func(data map[string]any) map[string]any {
    // Snake case to camel case
    if v, ok := data["first_name"]; ok {
        data["firstName"] = v
        delete(data, "first_name")
    }
    return data
}))
```

### Response Transformation

```go theme={null}
app.Use(transformer.Response(func(data map[string]any) map[string]any {
    // Add metadata
    return map[string]any{
        "data":    data,
        "version": "2.0",
    }
}))
```

### Field Mapping

```go theme={null}
fieldMap := map[string]string{
    "userName": "username",
    "firstName": "first_name",
    "lastName": "last_name",
}

app.Use(transformer.WithFieldMap(fieldMap))
```

### Version Compatibility

```go theme={null}
// v1 to v2 transformation
app.Use(transformer.Request(func(data map[string]any) map[string]any {
    // v1 had "name", v2 expects "fullName"
    if name, ok := data["name"]; ok {
        data["fullName"] = name
        delete(data, "name")
    }
    return data
}))
```

## API Reference

### Functions

```go theme={null}
// Request creates request transformer
func Request(fn func(map[string]any) map[string]any) mizu.Middleware

// Response creates response transformer
func Response(fn func(map[string]any) map[string]any) mizu.Middleware

// WithFieldMap creates field mapping transformer
func WithFieldMap(fieldMap map[string]string) mizu.Middleware
```

## Technical Details

The transformer middleware provides a flexible architecture for modifying HTTP requests and responses:

### Request Transformation

Request transformers are applied sequentially before the handler executes. Each transformer receives the `*http.Request` object and can modify:

* Headers (add, set, remove)
* URL path and query parameters
* Request body content

The middleware supports multiple request transformers, applied in the order they are registered.

### Response Transformation

Response transformation uses a custom `responseRecorder` that captures:

* HTTP status code (defaults to 200 OK if not set)
* Response headers
* Response body bytes

The recorder intercepts all response writes, allowing transformers to modify the complete response before it's sent to the client. Response transformers are applied sequentially and can modify:

* Status codes (mapping or conditional changes)
* Headers (add, set, remove)
* Body content (transformation or replacement)

### Implementation Details

* **Request transformers** receive `*http.Request` and return an error
* **Response transformers** receive `(statusCode int, headers http.Header, body []byte)` and return `(int, http.Header, []byte, error)`
* The middleware restores the original response writer after capturing to ensure proper cleanup
* Headers from the recorder are copied to the original writer before writing the status and body
* Empty response bodies are handled gracefully

## Best Practices

* Use for API version compatibility
* Keep transformations simple
* Document transformation rules
* Test edge cases thoroughly

## Testing

The transformer middleware includes comprehensive test coverage for all transformation functions:

| Test Case                   | Description                                | Expected Behavior                                               |
| --------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
| `TestNew`                   | Basic middleware initialization            | Middleware works with default empty options                     |
| `TestAddHeader`             | Adding a request header                    | New header is added to request and accessible in handler        |
| `TestSetHeader`             | Setting/overriding a request header        | Existing header value is replaced with new value                |
| `TestRemoveHeader`          | Removing a request header                  | Specified header is deleted from request                        |
| `TestRewritePath`           | URL path rewriting                         | Request path is transformed from old prefix to new prefix       |
| `TestAddQueryParam`         | Adding query parameters                    | New query parameter is added and encoded properly               |
| `TestTransformBody`         | Request body transformation                | Request body is transformed (e.g., uppercase conversion)        |
| `TestAddResponseHeader`     | Adding a response header                   | New header is added to response                                 |
| `TestSetResponseHeader`     | Setting/overriding a response header       | Response header is set to new value, overriding handler's value |
| `TestRemoveResponseHeader`  | Removing a response header                 | Specified header is removed from response                       |
| `TestTransformResponseBody` | Response body transformation               | Response body content is transformed before sending             |
| `TestMapStatusCode`         | Status code mapping                        | HTTP status code is mapped from one value to another            |
| `TestReplaceBody`           | Conditional body replacement               | Response body is replaced based on status code condition        |
| `TestMultipleTransformers`  | Multiple request and response transformers | All transformers are applied in sequence correctly              |

## Related Middlewares

* [version](/middlewares/version) - API versioning
* [envelope](/middlewares/envelope) - Response wrapping
* [filter](/middlewares/filter) - Field filtering