@nestarc/safe-response
Standardized API response wrapper for NestJS — auto-wraps success/error responses, pagination metadata, and Swagger schema generation with a single module import.
For the response-contract design trade-offs behind the package, read A NestJS API Response Format You Won't Regret.
Current Release
This guide targets 0.16.0, released on October 2, 2026. It fixes response-to-Swagger contracts, omitted data for undefined payloads, dynamic success statuses, Express payload-limit errors, field selection immutability, and repeated filters in cursor links. See the 0.16.0 release notes and migration notes.
Features
- Automatic response wrapping — HTTP handler return values wrapped in
{ success, statusCode, data }, with route and file-response opt-outs - Error standardization — exceptions converted to
{ success: false, error: { code, message, details } } - Pagination metadata — offset (
page/limit/total) and cursor (nextCursor/hasMore) pagination with auto-calculated meta and HATEOAS links - Sort/Filter metadata —
@SortMeta()and@FilterMeta()decorators to include sorting and filtering info in responsemeta - Request ID tracking — opt-in
requestIdfield in all responses with incoming header reuse, auto-generation, and response header propagation - Response time — opt-in
meta.responseTime(ms) for performance monitoring - RFC 9457 Problem Details — opt-in standard error format with
application/problem+json - Swagger integration —
@ApiSafeResponse(Dto)for success schemas,@ApiSafeErrorResponse()/@ApiSafeErrorResponses()for error schemas — all with the wrapped envelope - Global error Swagger —
applyGlobalErrors()injects common error responses (401, 403, 500) into all OpenAPI operations - Frontend client types —
@nestarc/safe-response/clientprovides types and type guards without server runtime imports; see the package peer and resolution boundaries - nestjs-i18n integration — automatic error/success message translation via adapter pattern
- API deprecation —
@Deprecated()decorator with RFC 9745/8594Deprecation/Sunsetheaders, Swaggerdeprecated: true, and responsemeta.deprecation - Rate limit metadata — opt-in
meta.rateLimitmirroring ofX-RateLimit-*response headers for frontend consumption - nestjs-cls integration — inject CLS store values (traceId, correlationId) into response
meta - Field selection — Google-style
?fields=id,name,address.citypartial responses with quotas and prototype-safe path handling v0.15.0 - Error catalog —
defineErrors(),createSafeException(), and catalog-backed Swagger decorators v0.15.0 - API version metadata — opt-in
meta.apiVersionon success and error responses v0.14.0 - StreamableFile detection — file download responses skip wrapping automatically v0.14.0
- class-validator support — validation errors parsed into
detailsarray with "Validation failed" message - Custom error codes — map exceptions to machine-readable codes via
errorCodeMapper - Composite decorators —
@SafeEndpoint(),@SafePaginatedEndpoint(),@SafeCursorPaginatedEndpoint()combine Swagger + runtime + error docs, with per-route field selection and explicit error format docs - Declarative error codes —
errorCodesoption for simple status-to-code mapping without writing a mapper function - Shape-mismatch warnings —
@Paginated(),@CursorPaginated(),@SortMeta(),@FilterMeta()warn when handler data doesn't match expected shape - Opt-out per route —
@RawResponse()skips wrapping for health checks, SSE, file downloads - Platform-agnostic — works with both Express and Fastify adapters out of the box
- Context-safe — automatically skips wrapping for non-HTTP contexts (RPC, WebSocket)
- Dynamic Module —
register()/registerAsync()with full DI support
Installation
npm install @nestarc/[email protected]Peer Dependencies
Use the installation guide to choose the matching NestJS/Swagger majors and Node.js runtime for your application.
Quick Start
import { Module } from '@nestjs/common';
import { SafeResponseModule } from '@nestarc/safe-response';
@Module({
imports: [
SafeResponseModule.register({
fieldSelection: true,
version: '1.0.0',
}),
],
})
export class AppModule {}Register the module once in the root module. HTTP handler returns receive an envelope; @RawResponse(), StreamableFile, manually sent responses, and responses without a body such as HTTP 204 have different boundaries described in Response Format.
To measure the cost of wrapping a response, the HTTP benchmark compares raw and wrapped Express endpoints for both a successful request and a 404.
For list endpoints, follow the pagination examples to return the fields expected by @Paginated() or @CursorPaginated() and document the resulting envelope in Swagger. The handler still supplies the items and pagination values from your data query.
With Fastify
Works the same way — no extra configuration needed:
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';
const app = await NestFactory.create<NestFastifyApplication>(
AppModule,
new FastifyAdapter(),
);
await app.listen(3000);Compatibility
| NestJS | @nestjs/swagger | Node.js compatibility tested in 0.16.0 |
|---|---|---|
| 10 | 8 | 18, 20, 22, 24 |
| 11 | 11 | 20, 22, 24 |
The package declares Node.js >=18; NestJS 11 requires Node.js >=20. Express and Fastify are covered; keep the HTTP adapter on the same NestJS major as @nestjs/core. Other required peers are RxJS ^7 and reflect-metadata ^0.2.
Source: 0.16.0 package metadata and compatibility workflow.