index

Classes

CursorPaginationMetaDto

Defined in: src/dto/response.dto.ts:46

Constructors

Constructor

new CursorPaginationMetaDto(): CursorPaginationMetaDto;

Returns

CursorPaginationMetaDto

Properties

hasMore

hasMore: boolean;

Defined in: src/dto/response.dto.ts:57

limit

limit: number;

Defined in: src/dto/response.dto.ts:60

links?

optional links?: PaginationLinksDto;

Defined in: src/dto/response.dto.ts:66

nextCursor

nextCursor: string | null;

Defined in: src/dto/response.dto.ts:51

previousCursor

previousCursor: string | null;

Defined in: src/dto/response.dto.ts:54

totalCount?

optional totalCount?: number;

Defined in: src/dto/response.dto.ts:63

type

type: "cursor";

Defined in: src/dto/response.dto.ts:48

---

DeprecationMetaDto

Defined in: src/dto/response.dto.ts:87

Constructors

Constructor

new DeprecationMetaDto(): DeprecationMetaDto;

Returns

DeprecationMetaDto

Properties

deprecated

deprecated: true;

Defined in: src/dto/response.dto.ts:89

link?

optional link?: string;

Defined in: src/dto/response.dto.ts:101

message?

optional message?: string;

Defined in: src/dto/response.dto.ts:98

since?

optional since?: string;

Defined in: src/dto/response.dto.ts:92

sunset?

optional sunset?: string;

Defined in: src/dto/response.dto.ts:95

---

ErrorDetailDto

Defined in: src/dto/response.dto.ts:173

Constructors

Constructor

new ErrorDetailDto(): ErrorDetailDto;

Returns

ErrorDetailDto

Properties

code

code: string;

Defined in: src/dto/response.dto.ts:175

details?

optional details?: unknown;

Defined in: src/dto/response.dto.ts:183

message

message: string;

Defined in: src/dto/response.dto.ts:178

---

ErrorResponseMetaDto

Defined in: src/dto/response.dto.ts:186

Indexable

[key: string]: unknown

Additional context fields (e.g., traceId, correlationId) injected via CLS

Constructors

Constructor

new ErrorResponseMetaDto(): ErrorResponseMetaDto;

Returns

ErrorResponseMetaDto

Properties

deprecation?

optional deprecation?: DeprecationMetaDto;

Defined in: src/dto/response.dto.ts:191

rateLimit?

optional rateLimit?: RateLimitMetaDto;

Defined in: src/dto/response.dto.ts:194

responseTime?

optional responseTime?: number;

Defined in: src/dto/response.dto.ts:188

---

FilterMetaDto

Defined in: src/dto/response.dto.ts:77

Constructors

Constructor

new FilterMetaDto(): FilterMetaDto;

Returns

FilterMetaDto

Properties

filters

filters: Record<string, unknown>;

Defined in: src/dto/response.dto.ts:84

---

NestI18nAdapter

Defined in: src/adapters/i18n.adapter.ts:25

Built-in adapter for nestjs-i18n. Wraps I18nService from the nestjs-i18n package.

Implements

• I18nAdapter

Constructors

Constructor

new NestI18nAdapter(i18nService): NestI18nAdapter;

Defined in: src/adapters/i18n.adapter.ts:26

Parameters

Parameter	Type
i18nService	I18nServiceLike

Returns

NestI18nAdapter

Methods

resolveLanguage()

resolveLanguage(request): string;

Defined in: src/adapters/i18n.adapter.ts:41

Resolve the preferred language from the request

Parameters

Parameter	Type
request	unknown

Returns

string

Implementation of

I18nAdapter.resolveLanguage

translate()

translate(key, options?): string;

Defined in: src/adapters/i18n.adapter.ts:28

Translate a message key to the target language

Parameters

Parameter	Type
key	string
options?	{ args?: Record<string, unknown>; lang?: string; }
options.args?	Record<string, unknown>
options.lang?	string

Returns

string

Implementation of

I18nAdapter.translate

---

PaginationLinksDto

Defined in: src/dto/response.dto.ts:3

Constructors

Constructor

new PaginationLinksDto(): PaginationLinksDto;

Returns

PaginationLinksDto

Properties

first

first: string;

Defined in: src/dto/response.dto.ts:8

last

last: string | null;

Defined in: src/dto/response.dto.ts:17

next

next: string | null;

Defined in: src/dto/response.dto.ts:14

prev

prev: string | null;

Defined in: src/dto/response.dto.ts:11

self

self: string;

Defined in: src/dto/response.dto.ts:5

---

PaginationMetaDto

Defined in: src/dto/response.dto.ts:20

Constructors

Constructor

new PaginationMetaDto(): PaginationMetaDto;

Returns

PaginationMetaDto

Properties

hasNext

hasNext: boolean;

Defined in: src/dto/response.dto.ts:37

hasPrev

hasPrev: boolean;

Defined in: src/dto/response.dto.ts:40

limit

limit: number;

Defined in: src/dto/response.dto.ts:28

links?

optional links?: PaginationLinksDto;

Defined in: src/dto/response.dto.ts:43

page

page: number;

Defined in: src/dto/response.dto.ts:25

total

total: number;

Defined in: src/dto/response.dto.ts:31

totalPages

totalPages: number;

Defined in: src/dto/response.dto.ts:34

type?

optional type?: "offset";

Defined in: src/dto/response.dto.ts:22

---

ProblemDetailsDto

Defined in: src/dto/response.dto.ts:223

Constructors

Constructor

new ProblemDetailsDto(): ProblemDetailsDto;

Returns

ProblemDetailsDto

Properties

code?

optional code?: string;

Defined in: src/dto/response.dto.ts:240

detail

detail: string;

Defined in: src/dto/response.dto.ts:234

details?

optional details?: unknown;

Defined in: src/dto/response.dto.ts:246

instance

instance: string;

Defined in: src/dto/response.dto.ts:237

meta?

optional meta?: ErrorResponseMetaDto;

Defined in: src/dto/response.dto.ts:249

requestId?

optional requestId?: string;

Defined in: src/dto/response.dto.ts:243

status

status: number;

Defined in: src/dto/response.dto.ts:231

title

title: string;

Defined in: src/dto/response.dto.ts:228

type

type: string;

Defined in: src/dto/response.dto.ts:225

---

RateLimitMetaDto

Defined in: src/dto/response.dto.ts:104

Constructors

Constructor

new RateLimitMetaDto(): RateLimitMetaDto;

Returns

RateLimitMetaDto

Properties

limit

limit: number;

Defined in: src/dto/response.dto.ts:106

remaining

remaining: number;

Defined in: src/dto/response.dto.ts:109

reset

reset: number;

Defined in: src/dto/response.dto.ts:112

retryAfter?

optional retryAfter?: number;

Defined in: src/dto/response.dto.ts:115

---

ResponseMetaDto

Defined in: src/dto/response.dto.ts:119

Constructors

Constructor

new ResponseMetaDto(): ResponseMetaDto;

Returns

ResponseMetaDto

Properties

deprecation?

optional deprecation?: DeprecationMetaDto;

Defined in: src/dto/response.dto.ts:141

filters?

optional filters?: Record<string, unknown>;

Defined in: src/dto/response.dto.ts:138

message?

optional message?: string;

Defined in: src/dto/response.dto.ts:129

pagination?

optional pagination?: 
  | PaginationMetaDto
  | CursorPaginationMetaDto;

Defined in: src/dto/response.dto.ts:126

rateLimit?

optional rateLimit?: RateLimitMetaDto;

Defined in: src/dto/response.dto.ts:144

responseTime?

optional responseTime?: number;

Defined in: src/dto/response.dto.ts:132

sort?

optional sort?: SortMetaDto;

Defined in: src/dto/response.dto.ts:135

---

SafeErrorResponseDto

Defined in: src/dto/response.dto.ts:200

Constructors

Constructor

new SafeErrorResponseDto(): SafeErrorResponseDto;

Returns

SafeErrorResponseDto

Properties

error

error: ErrorDetailDto;

Defined in: src/dto/response.dto.ts:211

meta?

optional meta?: ErrorResponseMetaDto;

Defined in: src/dto/response.dto.ts:214

path?

optional path?: string;

Defined in: src/dto/response.dto.ts:220

requestId?

optional requestId?: string;

Defined in: src/dto/response.dto.ts:208

statusCode

statusCode: number;

Defined in: src/dto/response.dto.ts:205

success

success: false;

Defined in: src/dto/response.dto.ts:202

timestamp?

optional timestamp?: string;

Defined in: src/dto/response.dto.ts:217

---

SafeExceptionFilter

Defined in: src/filters/safe-exception.filter.ts:63

Global exception filter that wraps errors in the SafeErrorResponse or RFC 9457 Problem Details envelope.

Known Limitation — Guard-phase exceptions

NestJS lifecycle: Middleware → Guards → Interceptors → Pipes → Handler. Metadata set by the interceptor (@Deprecated(), @ProblemType(), responseTime) is stored on the request object. When a guard throws before the interceptor runs, these values are unavailable to this filter:

• meta.responseTime — start time was never captured
• meta.deprecation / Deprecation headers — @Deprecated() options not forwarded
• Problem Details type URI — @ProblemType() value not forwarded (falls back to config.baseUrl-derived URI or about:blank)

This is an architectural constraint of NestJS's ArgumentsHost, which does not expose getHandler() for reflector-based metadata reads.

Implements

• ExceptionFilter

Constructors

Constructor

new SafeExceptionFilter(
   httpAdapterHost, 
   options?, 
   moduleRef?): SafeExceptionFilter;

Defined in: src/filters/safe-exception.filter.ts:68

Parameters

Parameter	Type
httpAdapterHost	HttpAdapterHost
options	SafeResponseModuleOptions
moduleRef?	ModuleRef

Returns

SafeExceptionFilter

Methods

catch()

catch(exception, host): void;

Defined in: src/filters/safe-exception.filter.ts:92

Method to implement a custom exception filter.

Parameters

Parameter	Type	Description
exception	unknown	the class of the exception being handled
host	ArgumentsHost	used to access an array of arguments for the in-flight request

Returns

void

Implementation of

ExceptionFilter.catch

---

SafeResponseInterceptor

Defined in: src/interceptors/safe-response.interceptor.ts:60

Implements

• NestInterceptor

Constructors

Constructor

new SafeResponseInterceptor(
   reflector, 
   options?, 
   moduleRef?): SafeResponseInterceptor;

Defined in: src/interceptors/safe-response.interceptor.ts:65

Parameters

Parameter	Type
reflector	Reflector
options	SafeResponseModuleOptions
moduleRef?	ModuleRef

Returns

SafeResponseInterceptor

Methods

intercept()

intercept(context, next): Observable<any>;

Defined in: src/interceptors/safe-response.interceptor.ts:80

Method to implement a custom interceptor.

Parameters

Parameter	Type	Description
context	ExecutionContext	an ExecutionContext object providing methods to access the route handler and class about to be invoked.
next	CallHandler	a reference to the CallHandler, which provides access to an Observable representing the response stream from the route handler.

Returns

Observable<any>

Implementation of

NestInterceptor.intercept

---

SafeResponseModule

Defined in: src/safe-response.module.ts:12

Implements

• OnModuleInit

Constructors

Constructor

new SafeResponseModule(): SafeResponseModule;

Returns

SafeResponseModule

Methods

onModuleInit()

onModuleInit(): void;

Defined in: src/safe-response.module.ts:16

Returns

void

Implementation of

OnModuleInit.onModuleInit

register()

static register(options?): DynamicModule;

Defined in: src/safe-response.module.ts:27

Parameters

Parameter	Type
options	SafeResponseModuleOptions

Returns

DynamicModule

registerAsync()

static registerAsync(options): DynamicModule;

Defined in: src/safe-response.module.ts:48

Parameters

Parameter	Type
options	SafeResponseModuleAsyncOptions

Returns

DynamicModule

---

SafeSuccessResponseDto

Defined in: src/dto/response.dto.ts:147

Constructors

Constructor

new SafeSuccessResponseDto(): SafeSuccessResponseDto;

Returns

SafeSuccessResponseDto

Properties

code?

optional code?: string;

Defined in: src/dto/response.dto.ts:155

data

data: unknown;

Defined in: src/dto/response.dto.ts:161

meta?

optional meta?: ResponseMetaDto;

Defined in: src/dto/response.dto.ts:164

path?

optional path?: string;

Defined in: src/dto/response.dto.ts:170

requestId?

optional requestId?: string;

Defined in: src/dto/response.dto.ts:158

statusCode

statusCode: number;

Defined in: src/dto/response.dto.ts:152

success

success: true;

Defined in: src/dto/response.dto.ts:149

timestamp?

optional timestamp?: string;

Defined in: src/dto/response.dto.ts:167

---

SortMetaDto

Defined in: src/dto/response.dto.ts:69

Constructors

Constructor

new SortMetaDto(): SortMetaDto;

Returns

SortMetaDto

Properties

field

field: string;

Defined in: src/dto/response.dto.ts:71

order

order: "asc" | "desc";

Defined in: src/dto/response.dto.ts:74

Interfaces

ApiSafeErrorResponseOptions

Defined in: src/interfaces/index.ts:237

Properties

code?

optional code?: string;

Defined in: src/interfaces/index.ts:241

Override the auto-resolved error code from DEFAULT_ERROR_CODE_MAP

description?

optional description?: string;

Defined in: src/interfaces/index.ts:239

Description shown in Swagger UI

details?

optional details?: unknown;

Defined in: src/interfaces/index.ts:245

Example details value (type is inferred: array → array schema, object → object schema)

message?

optional message?: string;

Defined in: src/interfaces/index.ts:243

Example error message

---

ContextOptions

Defined in: src/interfaces/index.ts:10

Properties

fields?

optional fields?: Record<string, string>;

Defined in: src/interfaces/index.ts:12

Map CLS store keys to response meta fields. Key = meta field name, Value = CLS store key.

resolver?

optional resolver?: (store) => Record<string, unknown>;

Defined in: src/interfaces/index.ts:14

Custom resolver function. Receives the CLS service instance and returns fields to inject.

Parameters

Parameter	Type
store	unknown

Returns

Record<string, unknown>

---

CursorPaginatedOptions

Defined in: src/interfaces/index.ts:222

Properties

links?

optional links?: boolean;

Defined in: src/interfaces/index.ts:225

Generate HATEOAS navigation links in pagination meta. Default: false

maxLimit?

optional maxLimit?: number;

Defined in: src/interfaces/index.ts:223

---

CursorPaginatedResult

Defined in: src/interfaces/index.ts:228

Type Parameters

Type Parameter	Default type
T	unknown

Properties

data

data: T[];

Defined in: src/interfaces/index.ts:229

hasMore

hasMore: boolean;

Defined in: src/interfaces/index.ts:232

limit

limit: number;

Defined in: src/interfaces/index.ts:233

nextCursor

nextCursor: string | null;

Defined in: src/interfaces/index.ts:230

previousCursor?

optional previousCursor?: string | null;

Defined in: src/interfaces/index.ts:231

totalCount?

optional totalCount?: number;

Defined in: src/interfaces/index.ts:234

---

CursorPaginationMeta

Defined in: src/interfaces/index.ts:143

Properties

hasMore

hasMore: boolean;

Defined in: src/interfaces/index.ts:147

limit

limit: number;

Defined in: src/interfaces/index.ts:148

links?

optional links?: PaginationLinks;

Defined in: src/interfaces/index.ts:150

nextCursor

nextCursor: string | null;

Defined in: src/interfaces/index.ts:145

previousCursor

previousCursor: string | null;

Defined in: src/interfaces/index.ts:146

totalCount?

optional totalCount?: number;

Defined in: src/interfaces/index.ts:149

type

type: "cursor";

Defined in: src/interfaces/index.ts:144

---

DeprecatedOptions

Defined in: src/interfaces/index.ts:19

Properties

link?

optional link?: string;

Defined in: src/interfaces/index.ts:27

URL of the successor endpoint or migration guide

message?

optional message?: string;

Defined in: src/interfaces/index.ts:25

Human-readable deprecation message for API consumers

since?

optional since?: string | Date;

Defined in: src/interfaces/index.ts:21

Date when the endpoint was deprecated (ISO string or Date object)

sunset?

optional sunset?: string | Date;

Defined in: src/interfaces/index.ts:23

Date when the endpoint will be removed (ISO string or Date object)

---

DeprecationMeta

Defined in: src/interfaces/index.ts:30

Properties

deprecated

deprecated: true;

Defined in: src/interfaces/index.ts:31

link?

optional link?: string;

Defined in: src/interfaces/index.ts:35

message?

optional message?: string;

Defined in: src/interfaces/index.ts:34

since?

optional since?: string;

Defined in: src/interfaces/index.ts:32

sunset?

optional sunset?: string;

Defined in: src/interfaces/index.ts:33

---

ErrorCodeMapperContext

Defined in: src/interfaces/index.ts:50

Properties

defaultCode

defaultCode: string;

Defined in: src/interfaces/index.ts:54

Default code from errorCodes option or DEFAULT_ERROR_CODE_MAP

statusCode

statusCode: number;

Defined in: src/interfaces/index.ts:52

Resolved HTTP status code

---

I18nAdapter

Defined in: src/adapters/i18n.adapter.ts:5

Interface for i18n adapters. Implementations bridge the gap between @nestarc/safe-response and i18n libraries.

Methods

resolveLanguage()

resolveLanguage(request): string;

Defined in: src/adapters/i18n.adapter.ts:9

Resolve the preferred language from the request

Parameters

Parameter	Type
request	unknown

Returns

string

translate()

translate(key, options?): string;

Defined in: src/adapters/i18n.adapter.ts:7

Translate a message key to the target language

Parameters

Parameter	Type
key	string
options?	{ args?: Record<string, unknown>; lang?: string; }
options.args?	Record<string, unknown>
options.lang?	string

Returns

string

---

I18nServiceLike

Defined in: src/adapters/i18n.adapter.ts:17

Minimal interface for nestjs-i18n's I18nService. Requires only the translate() method, making it structurally compatible with nestjs-i18n v10+ without importing the package at compile time.

Methods

translate()

translate(key, options?): unknown;

Defined in: src/adapters/i18n.adapter.ts:18

Parameters

Parameter	Type
key	string
options?	{ args?: Record<string, unknown>; lang?: string; }
options.args?	Record<string, unknown>
options.lang?	string

Returns

unknown

---

PaginatedOptions

Defined in: src/interfaces/index.ts:209

Properties

links?

optional links?: boolean;

Defined in: src/interfaces/index.ts:212

Generate HATEOAS navigation links in pagination meta. Default: false

maxLimit?

optional maxLimit?: number;

Defined in: src/interfaces/index.ts:210

---

PaginatedResult

Defined in: src/interfaces/index.ts:215

Type Parameters

Type Parameter	Default type
T	unknown

Properties

data

data: T[];

Defined in: src/interfaces/index.ts:216

limit

limit: number;

Defined in: src/interfaces/index.ts:219

page

page: number;

Defined in: src/interfaces/index.ts:218

total

total: number;

Defined in: src/interfaces/index.ts:217

---

PaginationLinks

Defined in: src/interfaces/index.ts:201

Properties

first

first: string;

Defined in: src/interfaces/index.ts:203

last

last: string | null;

Defined in: src/interfaces/index.ts:206

next

next: string | null;

Defined in: src/interfaces/index.ts:205

prev

prev: string | null;

Defined in: src/interfaces/index.ts:204

self

self: string;

Defined in: src/interfaces/index.ts:202

---

PaginationMeta

Defined in: src/interfaces/index.ts:132

Properties

hasNext

hasNext: boolean;

Defined in: src/interfaces/index.ts:138

hasPrev

hasPrev: boolean;

Defined in: src/interfaces/index.ts:139

limit

limit: number;

Defined in: src/interfaces/index.ts:135

links?

optional links?: PaginationLinks;

Defined in: src/interfaces/index.ts:140

page

page: number;

Defined in: src/interfaces/index.ts:134

total

total: number;

Defined in: src/interfaces/index.ts:136

totalPages

totalPages: number;

Defined in: src/interfaces/index.ts:137

type?

optional type?: "offset";

Defined in: src/interfaces/index.ts:133

---

ProblemDetailsOptions

Defined in: src/interfaces/index.ts:95

Properties

baseUrl?

optional baseUrl?: string;

Defined in: src/interfaces/index.ts:97

Base URL for problem type URIs (e.g., 'https://api.example.com/problems')

---

RateLimitMeta

Defined in: src/interfaces/index.ts:43

Properties

limit

limit: number;

Defined in: src/interfaces/index.ts:44

remaining

remaining: number;

Defined in: src/interfaces/index.ts:45

reset

reset: number;

Defined in: src/interfaces/index.ts:46

retryAfter?

optional retryAfter?: number;

Defined in: src/interfaces/index.ts:47

---

RateLimitOptions

Defined in: src/interfaces/index.ts:38

Properties

headerPrefix?

optional headerPrefix?: string;

Defined in: src/interfaces/index.ts:40

Header name prefix (default: 'X-RateLimit'). Headers read: {prefix}-Limit, {prefix}-Remaining, {prefix}-Reset

---

RequestIdOptions

Defined in: src/interfaces/index.ts:3

Properties

generator?

optional generator?: () => string;

Defined in: src/interfaces/index.ts:7

Custom ID generator (default: crypto.randomUUID())

Returns

string

headerName?

optional headerName?: string;

Defined in: src/interfaces/index.ts:5

Custom header name (default: 'X-Request-Id')

---

ResponseMeta

Defined in: src/interfaces/index.ts:158

Indexable

[key: string]: unknown

Additional context fields (e.g., traceId, correlationId)

Properties

deprecation?

optional deprecation?: DeprecationMeta;

Defined in: src/interfaces/index.ts:164

filters?

optional filters?: Record<string, unknown>;

Defined in: src/interfaces/index.ts:163

message?

optional message?: string;

Defined in: src/interfaces/index.ts:160

pagination?

optional pagination?: 
  | PaginationMeta
  | CursorPaginationMeta;

Defined in: src/interfaces/index.ts:159

rateLimit?

optional rateLimit?: RateLimitMeta;

Defined in: src/interfaces/index.ts:165

responseTime?

optional responseTime?: number;

Defined in: src/interfaces/index.ts:161

sort?

optional sort?: SortInfo;

Defined in: src/interfaces/index.ts:162

---

SafeCursorPaginatedEndpointOptions

Defined in: src/interfaces/index.ts:306

Properties

code?

optional code?: string;

Defined in: src/interfaces/index.ts:320

Custom success code

deprecated?

optional deprecated?: DeprecatedOptions;

Defined in: src/interfaces/index.ts:324

Mark endpoint as deprecated with RFC headers

description?

optional description?: string;

Defined in: src/interfaces/index.ts:316

Swagger response description

errors?

optional errors?: ApiSafeErrorResponseConfig[];

Defined in: src/interfaces/index.ts:322

Error responses to document in Swagger

filter?

optional filter?: boolean;

Defined in: src/interfaces/index.ts:314

Include filter metadata (default: false)

links?

optional links?: boolean;

Defined in: src/interfaces/index.ts:310

Generate HATEOAS navigation links (default: false)

maxLimit?

optional maxLimit?: number;

Defined in: src/interfaces/index.ts:308

Maximum items per page

message?

optional message?: string;

Defined in: src/interfaces/index.ts:318

Custom response message in meta

problemDetails?

optional problemDetails?: boolean;

Defined in: src/interfaces/index.ts:330

Use RFC 9457 Problem Details schema for error responses in Swagger (default: false). Note: This only controls Swagger documentation schema. The actual runtime error format is determined by the module-level problemDetails option. Keep both in sync.

sort?

optional sort?: boolean;

Defined in: src/interfaces/index.ts:312

Include sort metadata (default: false)

---

SafeEndpointOptions

Defined in: src/interfaces/index.ts:252

Properties

code?

optional code?: string;

Defined in: src/interfaces/index.ts:266

Custom success code

deprecated?

optional deprecated?: DeprecatedOptions;

Defined in: src/interfaces/index.ts:270

Mark endpoint as deprecated with RFC headers

description?

optional description?: string;

Defined in: src/interfaces/index.ts:258

Swagger response description

errors?

optional errors?: ApiSafeErrorResponseConfig[];

Defined in: src/interfaces/index.ts:268

Error responses to document in Swagger

filter?

optional filter?: boolean;

Defined in: src/interfaces/index.ts:262

Include filter metadata from handler return value (default: false)

isArray?

optional isArray?: boolean;

Defined in: src/interfaces/index.ts:256

Whether data is an array (default: false)

message?

optional message?: string;

Defined in: src/interfaces/index.ts:264

Custom response message in meta

problemDetails?

optional problemDetails?: boolean;

Defined in: src/interfaces/index.ts:276

Use RFC 9457 Problem Details schema for error responses in Swagger (default: false). Note: This only controls Swagger documentation schema. The actual runtime error format is determined by the module-level problemDetails option. Keep both in sync.

sort?

optional sort?: boolean;

Defined in: src/interfaces/index.ts:260

Include sort metadata from handler return value (default: false)

statusCode?

optional statusCode?: number;

Defined in: src/interfaces/index.ts:254

HTTP status code for Swagger response (default: 200)

---

SafeErrorResponse

Defined in: src/interfaces/index.ts:181

Properties

error

error: {
  code: string;
  details?: unknown;
  message: string;
};

Defined in: src/interfaces/index.ts:185

code

code: string;

details?

optional details?: unknown;

message

message: string;

meta?

optional meta?: {
[key: string]: unknown;
  deprecation?: DeprecationMeta;
  rateLimit?: RateLimitMeta;
  responseTime?: number;
};

Defined in: src/interfaces/index.ts:190

Index Signature

[key: string]: unknown

Additional context fields (e.g., traceId, correlationId)

deprecation?

optional deprecation?: DeprecationMeta;

rateLimit?

optional rateLimit?: RateLimitMeta;

responseTime?

optional responseTime?: number;

path?

optional path?: string;

Defined in: src/interfaces/index.ts:198

requestId?

optional requestId?: string;

Defined in: src/interfaces/index.ts:184

statusCode

statusCode: number;

Defined in: src/interfaces/index.ts:183

success

success: false;

Defined in: src/interfaces/index.ts:182

timestamp?

optional timestamp?: string;

Defined in: src/interfaces/index.ts:197

---

SafePaginatedEndpointOptions

Defined in: src/interfaces/index.ts:279

Properties

code?

optional code?: string;

Defined in: src/interfaces/index.ts:293

Custom success code

deprecated?

optional deprecated?: DeprecatedOptions;

Defined in: src/interfaces/index.ts:297

Mark endpoint as deprecated with RFC headers

description?

optional description?: string;

Defined in: src/interfaces/index.ts:289

Swagger response description

errors?

optional errors?: ApiSafeErrorResponseConfig[];

Defined in: src/interfaces/index.ts:295

Error responses to document in Swagger

filter?

optional filter?: boolean;

Defined in: src/interfaces/index.ts:287

Include filter metadata from handler return value (default: false)

links?

optional links?: boolean;

Defined in: src/interfaces/index.ts:283

Generate HATEOAS navigation links (default: false)

maxLimit?

optional maxLimit?: number;

Defined in: src/interfaces/index.ts:281

Maximum items per page (clamped via PaginatedOptions.maxLimit)

message?

optional message?: string;

Defined in: src/interfaces/index.ts:291

Custom response message in meta

problemDetails?

optional problemDetails?: boolean;

Defined in: src/interfaces/index.ts:303

Use RFC 9457 Problem Details schema for error responses in Swagger (default: false). Note: This only controls Swagger documentation schema. The actual runtime error format is determined by the module-level problemDetails option. Keep both in sync.

sort?

optional sort?: boolean;

Defined in: src/interfaces/index.ts:285

Include sort metadata from handler return value (default: false)

---

SafeProblemDetailsResponse

Defined in: src/interfaces/index.ts:100

Properties

code?

optional code?: string;

Defined in: src/interfaces/index.ts:107

Extension member: machine-readable error code

detail

detail: string;

Defined in: src/interfaces/index.ts:104

details?

optional details?: unknown;

Defined in: src/interfaces/index.ts:111

Extension member: validation error details

instance

instance: string;

Defined in: src/interfaces/index.ts:105

meta?

optional meta?: {
[key: string]: unknown;
  deprecation?: DeprecationMeta;
  rateLimit?: RateLimitMeta;
  responseTime?: number;
};

Defined in: src/interfaces/index.ts:113

Extension member: response time and context

Index Signature

[key: string]: unknown

Additional context fields (e.g., traceId, correlationId)

deprecation?

optional deprecation?: DeprecationMeta;

rateLimit?

optional rateLimit?: RateLimitMeta;

responseTime?

optional responseTime?: number;

requestId?

optional requestId?: string;

Defined in: src/interfaces/index.ts:109

Extension member: request tracking ID

status

status: number;

Defined in: src/interfaces/index.ts:103

title

title: string;

Defined in: src/interfaces/index.ts:102

type

type: string;

Defined in: src/interfaces/index.ts:101

---

SafeResponseModuleAsyncOptions

Defined in: src/interfaces/index.ts:122

Extends

• Pick<ModuleMetadata, "imports">

Properties

imports?

optional imports?: (
  | DynamicModule
  | Type<any>
  | Promise<DynamicModule>
  | ForwardReference<any>)[];

Defined in: node_modules/@nestjs/common/interfaces/modules/module-metadata.interface.d.ts:18

Optional list of imported modules that export the providers which are required in this module.

Inherited from

Pick.imports

inject?

optional inject?: any[];

Defined in: src/interfaces/index.ts:129

useFactory

useFactory: (...args) => 
  | SafeResponseModuleOptions
| Promise<SafeResponseModuleOptions>;

Defined in: src/interfaces/index.ts:124

Parameters

Parameter	Type
...args	any[]

Returns

| SafeResponseModuleOptions | Promise<SafeResponseModuleOptions>

---

SafeResponseModuleOptions

Defined in: src/interfaces/index.ts:62

Properties

context?

optional context?: ContextOptions;

Defined in: src/interfaces/index.ts:84

Inject request context values (e.g., traceId) into response meta. Requires nestjs-cls.

dateFormatter?

optional dateFormatter?: () => string;

Defined in: src/interfaces/index.ts:70

Custom date formatter function (default: ISO 8601)

Returns

string

errorCodeMapper?

optional errorCodeMapper?: (exception, context?) => string | undefined;

Defined in: src/interfaces/index.ts:68

Custom error code mapper function. Optional second arg provides statusCode and defaultCode context.

Parameters

Parameter	Type
exception	unknown
context?	ErrorCodeMapperContext

Returns

string | undefined

errorCodes?

optional errorCodes?: Record<number, string>;

Defined in: src/interfaces/index.ts:92

Declarative error code map. Merged on top of DEFAULT_ERROR_CODE_MAP. Use for simple status-to-code mappings.

i18n?

optional i18n?: boolean | I18nAdapter;

Defined in: src/interfaces/index.ts:86

Enable i18n for error/success messages. true = auto-detect nestjs-i18n, or pass a custom I18nAdapter.

path?

optional path?: boolean;

Defined in: src/interfaces/index.ts:66

Include path field in responses (default: true)

problemDetails?

optional problemDetails?: boolean | ProblemDetailsOptions;

Defined in: src/interfaces/index.ts:80

Enable RFC 9457 Problem Details format for error responses. Default: false

rateLimit?

optional rateLimit?: boolean | RateLimitOptions;

Defined in: src/interfaces/index.ts:88

Mirror rate limit response headers into meta.rateLimit. true uses defaults, or pass options object.

requestId?

optional requestId?: boolean | RequestIdOptions;

Defined in: src/interfaces/index.ts:76

Enable request ID tracking. true uses defaults, or pass options object.

responseTime?

optional responseTime?: boolean;

Defined in: src/interfaces/index.ts:78

Include response time in meta (milliseconds). Default: false

successCodeMapper?

optional successCodeMapper?: (statusCode) => string | undefined;

Defined in: src/interfaces/index.ts:72

Custom success code mapper function (statusCode → code string)

Parameters

Parameter	Type
statusCode	number

Returns

string | undefined

suppressWarnings?

optional suppressWarnings?: boolean;

Defined in: src/interfaces/index.ts:90

Suppress shape-mismatch warnings for @Paginated, @CursorPaginated, @SortMeta, @FilterMeta. Default: false

swagger?

optional swagger?: SwaggerOptions;

Defined in: src/interfaces/index.ts:82

Swagger documentation options

timestamp?

optional timestamp?: boolean;

Defined in: src/interfaces/index.ts:64

Include timestamp field in responses (default: true)

transformResponse?

optional transformResponse?: (data) => unknown;

Defined in: src/interfaces/index.ts:74

Transform data before wrapping (sync only, runs before pagination check)

Parameters

Parameter	Type
data	unknown

Returns

unknown

---

SafeSuccessResponse

Defined in: src/interfaces/index.ts:170

Type Parameters

Type Parameter	Default type
T	unknown

Properties

code?

optional code?: string;

Defined in: src/interfaces/index.ts:173

data

data: T;

Defined in: src/interfaces/index.ts:175

meta?

optional meta?: ResponseMeta;

Defined in: src/interfaces/index.ts:176

path?

optional path?: string;

Defined in: src/interfaces/index.ts:178

requestId?

optional requestId?: string;

Defined in: src/interfaces/index.ts:174

statusCode

statusCode: number;

Defined in: src/interfaces/index.ts:172

success

success: true;

Defined in: src/interfaces/index.ts:171

timestamp?

optional timestamp?: string;

Defined in: src/interfaces/index.ts:177

---

SortInfo

Defined in: src/interfaces/index.ts:153

Properties

field

field: string;

Defined in: src/interfaces/index.ts:154

order

order: "asc" | "desc";

Defined in: src/interfaces/index.ts:155

---

SwaggerOptions

Defined in: src/interfaces/index.ts:57

Properties

globalErrors?

optional globalErrors?: ApiSafeErrorResponseConfig[];

Defined in: src/interfaces/index.ts:59

Error responses to add to all routes (e.g., [401, 403, 500])

Type Aliases

ApiSafeErrorResponseConfig

type ApiSafeErrorResponseConfig = 
  | number
  | {
  status: number;
} & ApiSafeErrorResponseOptions;

Defined in: src/interfaces/index.ts:248

Variables

DEFAULT_ERROR_CODE_MAP

const DEFAULT_ERROR_CODE_MAP: {
  400: "BAD_REQUEST";
  401: "UNAUTHORIZED";
  403: "FORBIDDEN";
  404: "NOT_FOUND";
  405: "METHOD_NOT_ALLOWED";
  409: "CONFLICT";
  422: "UNPROCESSABLE_ENTITY";
  429: "TOO_MANY_REQUESTS";
  500: "INTERNAL_SERVER_ERROR";
  502: "BAD_GATEWAY";
  503: "SERVICE_UNAVAILABLE";
};

Defined in: src/constants.ts:39

Type Declaration

Name	Type	Default value	Defined in
400	"BAD_REQUEST"	'BAD_REQUEST'	src/constants.ts:40
401	"UNAUTHORIZED"	'UNAUTHORIZED'	src/constants.ts:41
403	"FORBIDDEN"	'FORBIDDEN'	src/constants.ts:42
404	"NOT_FOUND"	'NOT_FOUND'	src/constants.ts:43
405	"METHOD_NOT_ALLOWED"	'METHOD_NOT_ALLOWED'	src/constants.ts:44
409	"CONFLICT"	'CONFLICT'	src/constants.ts:45
422	"UNPROCESSABLE_ENTITY"	'UNPROCESSABLE_ENTITY'	src/constants.ts:46
429	"TOO_MANY_REQUESTS"	'TOO_MANY_REQUESTS'	src/constants.ts:47
500	"INTERNAL_SERVER_ERROR"	'INTERNAL_SERVER_ERROR'	src/constants.ts:48
502	"BAD_GATEWAY"	'BAD_GATEWAY'	src/constants.ts:49
503	"SERVICE_UNAVAILABLE"	'SERVICE_UNAVAILABLE'	src/constants.ts:50

---

DEFAULT_PROBLEM_TITLE_MAP

const DEFAULT_PROBLEM_TITLE_MAP: {
  400: "Bad Request";
  401: "Unauthorized";
  403: "Forbidden";
  404: "Not Found";
  405: "Method Not Allowed";
  409: "Conflict";
  422: "Unprocessable Entity";
  429: "Too Many Requests";
  500: "Internal Server Error";
  502: "Bad Gateway";
  503: "Service Unavailable";
};

Defined in: src/constants.ts:25

Type Declaration

Name	Type	Default value	Defined in
400	"Bad Request"	'Bad Request'	src/constants.ts:26
401	"Unauthorized"	'Unauthorized'	src/constants.ts:27
403	"Forbidden"	'Forbidden'	src/constants.ts:28
404	"Not Found"	'Not Found'	src/constants.ts:29
405	"Method Not Allowed"	'Method Not Allowed'	src/constants.ts:30
409	"Conflict"	'Conflict'	src/constants.ts:31
422	"Unprocessable Entity"	'Unprocessable Entity'	src/constants.ts:32
429	"Too Many Requests"	'Too Many Requests'	src/constants.ts:33
500	"Internal Server Error"	'Internal Server Error'	src/constants.ts:34
502	"Bad Gateway"	'Bad Gateway'	src/constants.ts:35
503	"Service Unavailable"	'Service Unavailable'	src/constants.ts:36

Functions

ApiCursorPaginatedSafeResponse()

function ApiCursorPaginatedSafeResponse<T>(model, options?): MethodDecorator;

Defined in: src/decorators/index.ts:218

Document a cursor-paginated response with Swagger schema.

Type Parameters

Type Parameter
T extends Type<any>

Parameters

Parameter	Type
model	T
options?	{ description?: string; }
options.description?	string

Returns

MethodDecorator

---

ApiPaginatedSafeResponse()

function ApiPaginatedSafeResponse<T>(model, options?): MethodDecorator;

Defined in: src/decorators/index.ts:80

Document a paginated response with Swagger schema.

Type Parameters

Type Parameter
T extends Type<any>

Parameters

Parameter	Type
model	T
options?	{ description?: string; }
options.description?	string

Returns

MethodDecorator

---

ApiSafeErrorResponse()

function ApiSafeErrorResponse(status, options?): MethodDecorator;

Defined in: src/decorators/index.ts:149

Document a single error response in Swagger with the SafeErrorResponseDto envelope. Error code auto-resolves from DEFAULT_ERROR_CODE_MAP if not provided.

Parameters

Parameter	Type
status	number
options?	ApiSafeErrorResponseOptions

Returns

MethodDecorator

Example

@ApiSafeErrorResponse(404)
@ApiSafeErrorResponse(400, { code: 'VALIDATION_ERROR', details: ['email must be an email'] })

---

ApiSafeErrorResponses()

function ApiSafeErrorResponses(configs): MethodDecorator;

Defined in: src/decorators/index.ts:204

Document multiple error responses in Swagger at once. Accepts an array of status codes (number) or config objects.

Parameters

Parameter	Type
configs	ApiSafeErrorResponseConfig[]

Returns

MethodDecorator

Example

@ApiSafeErrorResponses([400, 401, 404])
@ApiSafeErrorResponses([
  400,
  { status: 401, description: 'Token expired' },
  { status: 404, code: 'USER_NOT_FOUND' },
])

---

ApiSafeProblemResponse()

function ApiSafeProblemResponse(status, options?): MethodDecorator;

Defined in: src/decorators/index.ts:338

Document an RFC 9457 Problem Details error response in Swagger.

Always generates status-specific examples (status, title, code) via allOf composition with ProblemDetailsDto. When code, message, or details are provided, those override the auto-resolved defaults.

Parameters

Parameter	Type
status	number
options?	{ code?: string; description?: string; details?: unknown; message?: string; }
options.code?	string
options.description?	string
options.details?	unknown
options.message?	string

Returns

MethodDecorator

---

ApiSafeResponse()

function ApiSafeResponse<T>(model, options?): MethodDecorator;

Defined in: src/decorators/index.ts:45

Document the Swagger data field with a specific DTO type.

Type Parameters

Type Parameter
T extends Type<any>

Parameters

Parameter	Type
model	T
options?	{ description?: string; isArray?: boolean; statusCode?: number; }
options.description?	string
options.isArray?	boolean
options.statusCode?	number

Returns

MethodDecorator

---

applyGlobalErrors()

function applyGlobalErrors<T>(document, options): T;

Defined in: src/swagger/global-errors.ts:44

Apply global error response schemas to all operations in an OpenAPI document.

Call this after SwaggerModule.createDocument() and before SwaggerModule.setup():

const document = SwaggerModule.createDocument(app, config);
applyGlobalErrors(document, options);
SwaggerModule.setup('api', app, document);

The generic preserves the caller's document type — if you pass OpenAPIObject, you get OpenAPIObject back, so chaining with SwaggerModule.setup() works without manual casts.

Routes decorated with @SkipGlobalErrors() are excluded. Route-level error responses take priority over global ones (no overwriting).

Type Parameters

Type Parameter
T extends object

Parameters

Parameter	Type
document	T
options	SafeResponseModuleOptions

Returns

T

---

CursorPaginated()

function CursorPaginated(options?): CustomDecorator<string>;

Defined in: src/decorators/index.ts:268

Enable cursor-based pagination metadata auto-calculation.

Parameters

Parameter	Type
options?	CursorPaginatedOptions

Returns

CustomDecorator<string>

---

Deprecated()

function Deprecated(options?): <TFunction, Y>(target, propertyKey?, descriptor?) => void;

Defined in: src/decorators/index.ts:325

Mark a route as deprecated with RFC 9745 Deprecation and RFC 8594 Sunset headers. Also sets deprecated: true in the Swagger operation documentation.

Parameters

Parameter	Type	Description
options?	DeprecatedOptions	Optional deprecation configuration

Returns

<TFunction, Y>(target, propertyKey?, descriptor?) => void

Example

@Get('v1/users')
@Deprecated({ sunset: '2026-12-31', link: '/v2/users' })
findAll() { ... }

---

FilterMeta()

function FilterMeta(): CustomDecorator<string>;

Defined in: src/decorators/index.ts:300

Include filter metadata in the response meta. The handler must return a filters field in the paginated result.

Returns

CustomDecorator<string>

---

lookupErrorCode()

function lookupErrorCode(statusCode): string | undefined;

Defined in: src/constants.ts:54

Look up an error code by HTTP status. Returns undefined for unmapped status codes.

Parameters

Parameter	Type
statusCode	number

Returns

string | undefined

---

lookupProblemTitle()

function lookupProblemTitle(statusCode): string | undefined;

Defined in: src/constants.ts:59

Look up a problem title by HTTP status. Returns undefined for unmapped status codes.

Parameters

Parameter	Type
statusCode	number

Returns

string | undefined

---

Paginated()

function Paginated(options?): CustomDecorator<string>;

Defined in: src/decorators/index.ts:262

Enable offset pagination metadata auto-calculation.

Parameters

Parameter	Type
options?	PaginatedOptions

Returns

CustomDecorator<string>

---

ProblemType()

function ProblemType(typeUri): CustomDecorator<string>;

Defined in: src/decorators/index.ts:287

Set the RFC 9457 problem type URI for this route. Used when problemDetails is enabled in module options.

Parameters

Parameter	Type
typeUri	string

Returns

CustomDecorator<string>

---

RawResponse()

function RawResponse(): CustomDecorator<string>;

Defined in: src/decorators/index.ts:257

Skip response wrapping for this route.

Returns

CustomDecorator<string>

---

ResponseMessage()

function ResponseMessage(message): CustomDecorator<string>;

Defined in: src/decorators/index.ts:274

Set a custom message in the response meta.

Parameters

Parameter	Type
message	string

Returns

CustomDecorator<string>

---

SafeCursorPaginatedEndpoint()

function SafeCursorPaginatedEndpoint<T>(model, options?): MethodDecorator;

Defined in: src/decorators/index.ts:436

Composite decorator for cursor-paginated endpoints. Combines Swagger cursor-paginated response, @CursorPaginated(), sort/filter meta, and more.

Type Parameters

Type Parameter
T extends Type<any>

Parameters

Parameter	Type
model	T
options	SafeCursorPaginatedEndpointOptions

Returns

MethodDecorator

---

SafeEndpoint()

function SafeEndpoint<T>(model, options?): MethodDecorator;

Defined in: src/decorators/index.ts:379

Composite decorator for standard (non-paginated) endpoints. Combines Swagger response, success code, message, error responses, and deprecation.

Type Parameters

Type Parameter
T extends Type<any>

Parameters

Parameter	Type
model	T
options	SafeEndpointOptions

Returns

MethodDecorator

---

SafePaginatedEndpoint()

function SafePaginatedEndpoint<T>(model, options?): MethodDecorator;

Defined in: src/decorators/index.ts:407

Composite decorator for offset-paginated endpoints. Combines Swagger paginated response, @Paginated(), sort/filter meta, and more.

Type Parameters

Type Parameter
T extends Type<any>

Parameters

Parameter	Type
model	T
options	SafePaginatedEndpointOptions

Returns

MethodDecorator

---

SafeResponse()

function SafeResponse(options?): MethodDecorator;

Defined in: src/decorators/index.ts:23

Apply standard safe response wrapping + basic Swagger schema.

Parameters

Parameter	Type
options?	{ description?: string; statusCode?: number; }
options.description?	string
options.statusCode?	number

Returns

MethodDecorator

---

SkipGlobalErrors()

function SkipGlobalErrors(): <TFunction, Y>(target, propertyKey?, descriptor?) => void;

Defined in: src/decorators/index.ts:306

Skip global error responses for this route. Use on health checks, public endpoints, etc. that should not inherit global error documentation.

Returns

<TFunction, Y>(target, propertyKey?, descriptor?) => void

---

SortMeta()

function SortMeta(): CustomDecorator<string>;

Defined in: src/decorators/index.ts:294

Include sort metadata in the response meta. The handler must return a sort field in the paginated result.

Returns

CustomDecorator<string>

---

SuccessCode()

function SuccessCode(code): CustomDecorator<string>;

Defined in: src/decorators/index.ts:281

Set a custom success code for this route (method-level only). Takes priority over successCodeMapper module option.

Parameters

Parameter	Type
code	string

Returns

CustomDecorator<string>