skip to content

In a NestJS 12 handler whose parameters carry pipes, in what order do global, controller, route and parameter pipes run?

level: middleimportance: should knowfreq 38%

answer

  1. one chain per argument
  2. outer scopes before the parameter's own
  3. last parameter starts first
  4. the handler waits for every argument

basics

~20 s

Each argument passes through global pipes, then controller and route @UsePipes() pipes, then its own parameter pipes. Across arguments Nest starts with the last parameter and ends with the first, and calls the handler only once every argument resolves.

solid answer

~40 s

For every pipeable argument (`@Body()`, `@Param()`, `@Query()` and the like), Nest runs one chain: the global pipes, the controller's `@UsePipes()` pipes, the route's `@UsePipes()` pipes, then the pipes passed to that parameter's decorator, each receiving the previous pipe's output. Pipes listed in one `@UsePipes()` run first in, first out. Across parameters the docs state that the last parameter is processed first and the first parameter last, so with synchronous pipes the global tier finishes for every argument before the controller tier starts. A consequence worth knowing: a global pipe sees the raw extracted value, so on `@Param('id', ParseIntPipe)` it still gets the string, and the handler is called only after all arguments are resolved.

code

typescript · 17 lines
typescript
// main.ts
app.useGlobalPipes(new TrimStringsPipe());

// reports.controller.ts
@UsePipes(AuditPipe)
@Controller('reports')
export class ReportsController {
  @UsePipes(NormalizePipe)
  @Patch(':id')
  update(
    @Body() body: UpdateReportDto,
    @Param('id', ParseIntPipe) id: number,
    @Query('dryRun', ParseBoolPipe) dryRun: boolean,
  ) {
    return { id, dryRun, body };
  }
}

go deeper

for a junior

Remember that a parameter's own pipe, such as ParseIntPipe in @Param('id', ParseIntPipe), runs after any global, controller or route pipes.

for a middle

Walk through the chain one argument gets, explain FIFO inside @UsePipes(), and state the documented last-parameter-first rule with its example.

for a senior

Explain why a global pipe sees raw strings, why error messages depend on parameter order, and why async pipes on different arguments may interleave.

for a principal

Keep pipes argument-local in team conventions: no pipe that depends on another argument, and a clear rule for which tier owns conversion versus validation.

## One chain per argument In **NestJS**, a **pipe** is a class implementing `PipeTransform` whose `transform(value, metadata)` returns the value the handler will receive, or throws. Pipes can be bound at four levels: - **Global**: `app.useGlobalPipes()` or an `APP_PIPE` provider. - **Controller**: `@UsePipes()` on the controller class. - **Route**: `@UsePipes()` on the handler method. - **Parameter**: passed straight to a parameter decorator, as in `@Param('id', ParseIntPipe)` or `@Body(new ValidationPipe())`. For each argument the handler receives from a pipeable decorator, Nest concatenates these into one list, **global, controller, route, then parameter**, and runs it in sequence: each pipe's output becomes the next pipe's input. Within one `@UsePipes(A, B)` call the order is **first in, first out**: `A` runs before `B`. ## Across parameters: last to first The request-lifecycle page states a rule that surprises most people: when several parameters have pipes, **the last parameter is processed first and the first parameter last**, and this applies to controller-level and route-level pipes as well as parameter pipes. This follows from how TypeScript applies parameter decorators, from the last parameter to the first, which is the order Nest's parameter metadata ends up in. For `update(@Body() body, @Param('id', ParseIntPipe) id, @Query('dryRun', ParseBoolPipe) dryRun)` with a global, a controller and a route pipe, the docs' model gives: 1. The global pipe for `dryRun`, then `id`, then `body`. 2. The controller pipe for `dryRun`, then `id`, then `body`. 3. The route pipe for `dryRun`, then `id`, then `body`. 4. `ParseBoolPipe` for `dryRun`, then `ParseIntPipe` for `id`; `body` has no parameter pipe. 5. The handler, with all three arguments. ## What the source adds In the v12.1.2 source, the router resolves the arguments with `Promise.all` over the parameter list, and each argument's chain is awaited pipe by pipe. Two precise statements follow: - **Within one argument the order is strict**: global, controller, route, parameter, every time. - **Across arguments the order is the start order, not a barrier.** With synchronous pipes the tiers line up exactly as the docs describe. If a pipe is asynchronous and awaits real work for one argument, the other arguments' chains carry on, so a later tier can run for `id` before an earlier tier has finished for `dryRun`. The handler is called only once every argument has resolved; if any chain throws, the handler is not called and the exception travels back through the interceptors to the exception filters. ## Practical consequences | Situation | What happens | |---|---| | Global pipe plus `@Param('id', ParseIntPipe)` | The global pipe receives the raw string; `ParseIntPipe` converts it afterwards | | Two pipes in one `@UsePipes(A, B)` | `A` transforms first, `B` receives `A`'s output | | A parameter pipe throws | The handler is not called; the interceptors see the error | | Two async pipes on different parameters | Their work can interleave; neither may depend on the other having finished | - A global pipe written to validate numbers will not see numbers for route parameters that rely on `ParseIntPipe`, because the parameter pipe runs after it. - A pipe must not depend on another argument's pipe having run: pipes receive one argument and its `ArgumentMetadata` (such as `type`, `metatype` and `data`), never the other arguments. - A parameter pipe is the last word on its argument: whatever a global or route pipe did to the value, the parameter's own pipe sees that output and its result is what the handler receives. ## Where pipes sit in the whole request - **Before pipes**: middleware, every guard, and the inbound code of every interceptor have already run. - **After pipes**: the handler, then the interceptors' outbound operators in reverse order. - **On a pipe error**: the exception passes back out through the interceptors, where a `catchError` operator can see it, and then to the exception filters, which Nest checks route first. Because pipes see only arguments, they are the right place for conversion and validation and the wrong place for authorization, which has already been decided by the guards. Pipes as a whole sit after guards and the interceptors' inbound code and immediately before the handler, so a pipe never runs for a request a guard denied.

  • In a NestJS 12 app, why might a global pipe receive a string id even though the handler declares id: number?
    Because the conversion is done by a parameter pipe such as `ParseIntPipe`, and parameter pipes run after the global, controller and route pipes for that argument. The global pipe sees the raw value extracted from the path, which is a string, along with an `ArgumentMetadata` whose `metatype` reflects the declared `Number` type when decorator metadata is emitted.
  • In a NestJS 12 app, is the last-parameter-first order a guarantee when pipes are asynchronous?
    It is the order the chains start in. The router resolves arguments with `Promise.all`, so each argument's own chain stays strictly ordered, but an async pipe awaiting I/O for one argument lets other arguments' pipes run meanwhile. Code should never depend on cross-argument timing.

  • Parameter pipes run before the global pipes because they are more specific.
  • Nest processes parameters from the first to the last.
  • A global pipe receives all handler arguments in one call.
  • Pipes in one @UsePipes(A, B) run last-listed first, like exception filters.