# PipeTransform

**Kind:** Interface

**Source:** [`packages/common/interfaces/features/pipe-transform.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/common/interfaces/features/pipe-transform.interface.ts#L37)

**Part of:** [Common](subsystem-packages-common)

Interface describing implementation of a pipe.

`PipeTransform` defines the contract for pipes that transform or validate incoming values before they reach a route handler or other consumer. Implementations receive the raw value and argument metadata, then return a transformed value or throw an exception when validation fails.

## Diagram

```mermaid
graph LR
  A[Incoming request value] --> B[PipeTransform.transform]
  C[ArgumentMetadata] --> B
  B -->|Valid / transformed value| D[Route handler parameter]
  B -->|Validation error| E[Exception response]
```

## Usage

```ts
import {
  ArgumentMetadata,
  BadRequestException,
  PipeTransform,
} from '@nestjs/common';

export class ParsePositiveIntPipe implements PipeTransform<string, number> {
  transform(value: string, metadata: ArgumentMetadata): number {
    const parsedValue = Number(value);

    if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
      throw new BadRequestException(
        `${metadata.data ?? 'value'} must be a positive integer`,
      );
    }

    return parsedValue;
  }
}

// Example route usage:
// @Get(':id')
// findOne(@Param('id', ParsePositiveIntPipe) id: number) {
//   return this.usersService.findOne(id);
// }
```

## AI Coding Instructions

- Implement `transform(value, metadata)` and return the value type expected by the consuming handler.
- Use `ArgumentMetadata` to tailor validation behavior or error messages based on the parameter source and name.
- Throw framework HTTP exceptions, such as `BadRequestException`, for invalid input instead of returning invalid or partially transformed values.
- Keep pipes focused on input transformation and validation; delegate business rules and persistence checks to services.
- Ensure asynchronous pipes return a `Promise` and are registered where the value is bound, such as route parameters, request bodies, or global pipe configuration.

## Used by

30 references from 30 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

### Imported by (30)

- `ParamProperties` — `packages/core/router/router-execution-context.ts`:50
- `UserByIdPipe` — `integration/hello-world/src/hello/users/user-by-id.pipe.ts`:4
- `UserByIdPipe` — `integration/hello-world/src/host/users/user-by-id.pipe.ts`:4
- `UserByIdPipe` — `integration/hello-world/src/host-array/users/user-by-id.pipe.ts`:4
- `UserByIdPipe` — `integration/inspector/src/circular-hello/users/user-by-id.pipe.ts`:4
- `ParseIntPipe` — `integration/inspector/src/common/pipes/parse-int.pipe.ts`:8
- `UserByIdPipe` — `integration/scopes/src/circular-hello/users/user-by-id.pipe.ts`:4
- `UserByIdPipe` — `integration/scopes/src/circular-transient/users/user-by-id.pipe.ts`:8

…and 22 more.