@nestarc/safe-response

Classes

CursorPaginationMetaDto

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:179

Constructors

Constructor

new ErrorDetailDto(): ErrorDetailDto;

Returns

ErrorDetailDto

Properties

code

code: string;

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

details?

optional details?: unknown;

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

message

message: string;

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

ErrorResponseMetaDto

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

Indexable

[key: string]: unknown

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

Constructors

Constructor

new ErrorResponseMetaDto(): ErrorResponseMetaDto;

Returns

ErrorResponseMetaDto

Properties

apiVersion?

optional apiVersion?: string;

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

deprecation?

optional deprecation?: DeprecationMetaDto;

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

rateLimit?

optional rateLimit?: RateLimitMetaDto;

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

responseTime?

optional responseTime?: number;

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

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: string | null;

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

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:232

Constructors

Constructor

new ProblemDetailsDto(): ProblemDetailsDto;

Returns

ProblemDetailsDto

Properties

code?

optional code?: string;

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

detail

detail: string;

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

details?

optional details?: unknown;

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

instance

instance: string;

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

meta?

optional meta?: ErrorResponseMetaDto;

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

requestId?

optional requestId?: string;

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

status

status: number;

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

title

title: string;

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

type

type: string;

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

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

apiVersion?

optional apiVersion?: string;

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

deprecation?

optional deprecation?: DeprecationMetaDto;

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

fields?

optional fields?: string[];

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

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:209

Constructors

Constructor

new SafeErrorResponseDto(): SafeErrorResponseDto;

Returns

SafeErrorResponseDto

Properties

error

error: ErrorDetailDto;

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

meta?

optional meta?: ErrorResponseMetaDto;

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

path?

optional path?: string;

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

requestId?

optional requestId?: string;

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

statusCode

statusCode: number;

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

success

success: false;

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

timestamp?

optional timestamp?: string;

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

SafeException

Defined in: src/errors/index.ts:53

Custom exception that resolves status/message from the error catalog.

When thrown, the SafeExceptionFilter looks up the errorKey in the registered errorCatalog to resolve the HTTP status, message, and details. The key itself becomes the error code in the response.

Falls back to 500 Internal Server Error if no catalog is registered or the key is not found.

Example

typescript

throw new SafeException('USER_NOT_FOUND');
throw new SafeException('VALIDATION_ERROR', { message: 'Custom message', details: [...] });

Extends

HttpException

Constructors

Constructor

new SafeException(key, options?): SafeException;

Defined in: src/errors/index.ts:58

Parameters

Parameter	Type
`key`	`string`
`options?`	{ `details?`: `unknown`; `message?`: `string`; }
`options.details?`	`unknown`
`options.message?`	`string`

Returns

SafeException

Overrides

HttpException.constructor

Properties

cause

cause: unknown;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:28

Exception cause. Indicates the specific original cause of the error. It is used when catching and re-throwing an error with a more-specific or useful error message in order to still have access to the original error.

Inherited from

HttpException.cause

errorKey

readonly errorKey: string;

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

message

message: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

HttpException.message

name

name: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

HttpException.name

overrideDetails?

readonly optional overrideDetails?: unknown;

Defined in: src/errors/index.ts:56

overrideMessage?

readonly optional overrideMessage?: string;

Defined in: src/errors/index.ts:55

stack?

optional stack?: string;

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

HttpException.stack

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

HttpException.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

HttpException.captureStackTrace

createBody()

Call Signature

static createBody(
   nil,
   message,
   statusCode): HttpExceptionBody;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:74

Parameters

Parameter	Type
`nil`	`""` \| `null`
`message`	`HttpExceptionBodyMessage`
`statusCode`	`number`

Returns

HttpExceptionBody

Inherited from

HttpException.createBody

Call Signature

static createBody(
   message,
   error,
   statusCode): HttpExceptionBody;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:75

Parameters

Parameter	Type
`message`	`HttpExceptionBodyMessage`
`error`	`string`
`statusCode`	`number`

Returns

HttpExceptionBody

Inherited from

HttpException.createBody

Call Signature

static createBody<Body>(custom): Body;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:76

Type Parameters

Type Parameter
`Body` extends `Record`<`string`, `unknown`>

Parameters

Parameter	Type
`custom`	`Body`

Returns

Body

Inherited from

HttpException.createBody

extractDescriptionAndOptionsFrom()

static extractDescriptionAndOptionsFrom(descriptionOrOptions): DescriptionAndOptions;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:84

Utility method used to extract the error description and httpExceptionOptions from the given argument. This is used by inheriting classes to correctly parse both options.

Parameters

Parameter	Type
`descriptionOrOptions`	`string` \| `HttpExceptionOptions`

Returns

DescriptionAndOptions

the error description and the httpExceptionOptions as an object.

Inherited from

HttpException.extractDescriptionAndOptionsFrom

getDescriptionFrom()

static getDescriptionFrom(descriptionOrOptions): string;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:77

Parameters

Parameter	Type
`descriptionOrOptions`	`string` \| `HttpExceptionOptions`

Returns

string

Inherited from

HttpException.getDescriptionFrom

getHttpExceptionOptionsFrom()

static getHttpExceptionOptionsFrom(descriptionOrOptions): HttpExceptionOptions;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:78

Parameters

Parameter	Type
`descriptionOrOptions`	`string` \| `HttpExceptionOptions`

Returns

HttpExceptionOptions

Inherited from

HttpException.getHttpExceptionOptionsFrom

getResponse()

getResponse(): string | object;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:72

Returns

string | object

Inherited from

HttpException.getResponse

getStatus()

getStatus(): number;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:73

Returns

number

Inherited from

HttpException.getStatus

initCause()

initCause(): void;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:69

Configures error chaining support

Returns

void

See

Inherited from

HttpException.initCause

initMessage()

initMessage(): void;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:70

Returns

void

Inherited from

HttpException.initMessage

initName()

initName(): void;

Defined in: node_modules/@nestjs/common/exceptions/http.exception.d.ts:71

Returns

void

Inherited from

HttpException.initName

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

HttpException.prepareStackTrace

SafeExceptionFilter

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

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:70

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:94

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:65

Implements

NestInterceptor

Constructors

Constructor

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

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

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:85

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:153

Constructors

Constructor

new SafeSuccessResponseDto(): SafeSuccessResponseDto;

Returns

SafeSuccessResponseDto

Properties

code?

optional code?: string;

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

data

data: unknown;

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

meta?

optional meta?: ResponseMetaDto;

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

path?

optional path?: string;

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

requestId?

optional requestId?: string;

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

statusCode

statusCode: number;

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

success

success: true;

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

timestamp?

optional timestamp?: string;

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

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:247

Properties

code?

optional code?: string;

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

Override the auto-resolved error code from DEFAULT_ERROR_CODE_MAP

description?

optional description?: string;

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

Description shown in Swagger UI

details?

optional details?: unknown;

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

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

message?

optional message?: string;

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

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:232

Properties

links?

optional links?: boolean;

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

Generate HATEOAS navigation links in pagination meta. Default: false

maxLimit?

optional maxLimit?: number;

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

CursorPaginatedResult

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

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Properties

data

data: T[];

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

hasMore

hasMore: boolean;

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

limit

limit: number;

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

nextCursor

nextCursor: string | null;

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

previousCursor?

optional previousCursor?: string | null;

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

totalCount?

optional totalCount?: number;

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

CursorPaginationMeta

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

Properties

hasMore

hasMore: boolean;

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

limit

limit: number;

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

links?

optional links?: PaginationLinks;

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

nextCursor

nextCursor: string | null;

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

previousCursor

previousCursor: string | null;

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

totalCount?

optional totalCount?: number;

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

type

type: "cursor";

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

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

ErrorDefinition

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

Properties

description?

optional description?: string;

Defined in: src/errors/index.ts:11

Swagger description (used in @ApiSafeErrorResponse)

details?

optional details?: unknown;

Defined in: src/errors/index.ts:13

Default error details

message

message: string;

Defined in: src/errors/index.ts:9

Default error message

status

status: number;

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

HTTP status code for this error

FieldSelectionOptions

Defined in: src/shared/field-selection.ts:8

Partial response (field selection) utilities.

Enables Google-style ?fields=id,name,address.city query parameter for selecting specific fields from the response data.

Properties

maxDepth?

optional maxDepth?: number;

Defined in: src/shared/field-selection.ts:14

Maximum nesting depth for dot-notation fields (default: 3)

maxFieldLength?

optional maxFieldLength?: number;

Defined in: src/shared/field-selection.ts:18

Maximum length of each requested field path

maxFields?

optional maxFields?: number;

Defined in: src/shared/field-selection.ts:16

Maximum number of requested field paths to honor

queryParam?

optional queryParam?: string;

Defined in: src/shared/field-selection.ts:10

Query parameter name (default: 'fields')

separator?

optional separator?: string;

Defined in: src/shared/field-selection.ts:12

Field separator (default: ',')

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:219

Properties

links?

optional links?: boolean;

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

Generate HATEOAS navigation links in pagination meta. Default: false

maxLimit?

optional maxLimit?: number;

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

PaginatedResult

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

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Properties

data

data: T[];

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

limit

limit: number;

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

page

page: number;

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

total

total: number;

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

PaginationLinks

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

Properties

first

first: string;

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

last

last: string | null;

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

next: string | null;

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

prev: string | null;

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

self

self: string;

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

PaginationMeta

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

Properties

hasNext

hasNext: boolean;

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

hasPrev

hasPrev: boolean;

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

limit

limit: number;

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

links?

optional links?: PaginationLinks;

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

page

page: number;

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

total

total: number;

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

totalPages

totalPages: number;

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

type?

optional type?: "offset";

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

ProblemDetailsOptions

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

Properties

baseUrl?

optional baseUrl?: string;

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

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:165

Indexable

[key: string]: unknown

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

Properties

apiVersion?

optional apiVersion?: string;

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

deprecation?

optional deprecation?: DeprecationMeta;

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

fields?

optional fields?: string[];

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

filters?

optional filters?: Record<string, unknown>;

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

message?

optional message?: string;

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

pagination?

optional pagination?:
  | PaginationMeta
  | CursorPaginationMeta;

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

rateLimit?

optional rateLimit?: RateLimitMeta;

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

responseTime?

optional responseTime?: number;

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

sort?

optional sort?: SortInfo;

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

SafeCursorPaginatedEndpointOptions

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

Properties

code?

optional code?: string;

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

Custom success code

deprecated?

optional deprecated?: DeprecatedOptions;

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

Mark endpoint as deprecated with RFC headers

description?

optional description?: string;

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

Swagger response description

errorFormat?

optional errorFormat?: ErrorDocumentationFormat;

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

Error response documentation format for composite decorators. Runtime format is still module-level problemDetails.

errors?

optional errors?: ApiSafeErrorResponseConfig[];

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

Error responses to document in Swagger

fieldSelection?

optional fieldSelection?: boolean | FieldSelectionOptions;

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

Enable or disable field selection for this route. Overrides module-level fieldSelection.

filter?

optional filter?: boolean;

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

Include filter metadata (default: false)

links?

optional links?: boolean;

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

Generate HATEOAS navigation links (default: false)

maxLimit?

optional maxLimit?: number;

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

Maximum items per page

message?

optional message?: string;

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

Custom response message in meta

problemDetails?

optional problemDetails?: boolean;

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

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:332

Include sort metadata (default: false)

SafeEndpointOptions

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

Properties

code?

optional code?: string;

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

Custom success code

deprecated?

optional deprecated?: DeprecatedOptions;

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

Mark endpoint as deprecated with RFC headers

description?

optional description?: string;

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

Swagger response description

errorFormat?

optional errorFormat?: ErrorDocumentationFormat;

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

Error response documentation format for composite decorators. Runtime format is still module-level problemDetails.

errors?

optional errors?: ApiSafeErrorResponseConfig[];

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

Error responses to document in Swagger

fieldSelection?

optional fieldSelection?: boolean | FieldSelectionOptions;

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

Enable or disable field selection for this route. Overrides module-level fieldSelection.

filter?

optional filter?: boolean;

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

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

isArray?

optional isArray?: boolean;

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

Whether data is an array (default: false)

message?

optional message?: string;

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

Custom response message in meta

problemDetails?

optional problemDetails?: boolean;

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

sort?

optional sort?: boolean;

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

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

statusCode?

optional statusCode?: number;

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

HTTP status code for Swagger response (default: 200)

SafeErrorResponse

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

Properties

error

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

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

code

code: string;

details?

optional details?: unknown;

message

message: string;

meta?

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

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

Index Signature

[key: string]: unknown

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

apiVersion?

optional apiVersion?: string;

deprecation?

optional deprecation?: DeprecationMeta;

rateLimit?

optional rateLimit?: RateLimitMeta;

responseTime?

optional responseTime?: number;

path?

optional path?: string;

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

requestId?

optional requestId?: string;

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

statusCode

statusCode: number;

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

success

success: false;

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

timestamp?

optional timestamp?: string;

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

SafePaginatedEndpointOptions

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

Properties

code?

optional code?: string;

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

Custom success code

deprecated?

optional deprecated?: DeprecatedOptions;

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

Mark endpoint as deprecated with RFC headers

description?

optional description?: string;

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

Swagger response description

errorFormat?

optional errorFormat?: ErrorDocumentationFormat;

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

Error response documentation format for composite decorators. Runtime format is still module-level problemDetails.

errors?

optional errors?: ApiSafeErrorResponseConfig[];

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

Error responses to document in Swagger

fieldSelection?

optional fieldSelection?: boolean | FieldSelectionOptions;

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

Enable or disable field selection for this route. Overrides module-level fieldSelection.

filter?

optional filter?: boolean;

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

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

links?

optional links?: boolean;

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

Generate HATEOAS navigation links (default: false)

maxLimit?

optional maxLimit?: number;

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

Maximum items per page (clamped via PaginatedOptions.maxLimit)

message?

optional message?: string;

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

Custom response message in meta

problemDetails?

optional problemDetails?: boolean;

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

sort?

optional sort?: boolean;

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

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

SafeProblemDetailsResponse

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

Properties

code?

optional code?: string;

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

Extension member: machine-readable error code

detail

detail: string;

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

details?

optional details?: unknown;

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

Extension member: validation error details

instance

instance: string;

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

meta?

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

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

Extension member: response time and context

Index Signature

[key: string]: unknown

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

apiVersion?

optional apiVersion?: string;

deprecation?

optional deprecation?: DeprecationMeta;

rateLimit?

optional rateLimit?: RateLimitMeta;

responseTime?

optional responseTime?: number;

requestId?

optional requestId?: string;

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

Extension member: request tracking ID

status

status: number;

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

title

title: string;

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

type

type: string;

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

SafeResponseModuleAsyncOptions

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

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:136

useFactory

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

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

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

errorCatalog?

optional errorCatalog?: ErrorCatalog<string>;

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

Error catalog for centralized error definitions. Created via defineErrors().

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.

fieldSelection?

optional fieldSelection?: boolean | FieldSelectionOptions;

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

Enable partial response via field selection query parameter. true uses defaults, or pass options.

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

version?

optional version?: string;

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

API version string to include in every response's meta.apiVersion.

SafeSuccessResponse

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

Type Parameters

Type Parameter	Default type
`T`	`unknown`

Properties

code?

optional code?: string;

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

data

data: T;

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

meta?

optional meta?: ResponseMeta;

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

path?

optional path?: string;

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

requestId?

optional requestId?: string;

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

statusCode

statusCode: number;

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

success

success: true;

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

timestamp?

optional timestamp?: string;

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

SortInfo

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

Properties

field

field: string;

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

order

order: "asc" | "desc";

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

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:258

ErrorCatalog

type ErrorCatalog<K> = Record<K, ErrorDefinition>;

Defined in: src/errors/index.ts:16

Type Parameters

Type Parameter	Default type
`K` extends `string`	`string`

ErrorDocumentationFormat

type ErrorDocumentationFormat = "safe" | "problem";

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

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:41

Type Declaration

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

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:27

Type Declaration

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

Functions

ApiCursorPaginatedSafeResponse()

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

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

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:82

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

ApiSafeCatalogError()

function ApiSafeCatalogError<K>(
   catalog,
   key,
   options?): MethodDecorator;

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

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type
`catalog`	`ErrorCatalog`<`K`>
`key`	`K`
`options?`	`ApiSafeErrorResponseOptions`

Returns

MethodDecorator

ApiSafeCatalogErrors()

function ApiSafeCatalogErrors<K>(catalog, keys): MethodDecorator;

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

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type
`catalog`	`ErrorCatalog`<`K`>
`keys`	readonly `K`[]

Returns

MethodDecorator

ApiSafeErrorResponse()

function ApiSafeErrorResponse(status, options?): MethodDecorator;

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

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

typescript

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

ApiSafeErrorResponses()

function ApiSafeErrorResponses(configs): MethodDecorator;

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

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

typescript

@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:371

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:47

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():

typescript

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

createSafeException()

function createSafeException<K>(catalog): (key, options?) => SafeException;

Defined in: src/errors/index.ts:67

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type
`catalog`	`ErrorCatalog`<`K`>

Returns

(key, options?) => SafeException

CursorPaginated()

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

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

Enable cursor-based pagination metadata auto-calculation.

Parameters

Parameter	Type
`options?`	`CursorPaginatedOptions`

Returns

CustomDecorator<string>

defineErrors()

function defineErrors<K>(catalog): ErrorCatalog<K>;

Defined in: src/errors/index.ts:29

Define a typed error catalog. Returns the catalog with literal key types preserved.

Type Parameters

Type Parameter
`K` extends `string`

Parameters

Parameter	Type
`catalog`	`Record`<`K`, `ErrorDefinition`>

Returns

ErrorCatalog<K>

Example

typescript

const errors = defineErrors({
  USER_NOT_FOUND: { status: 404, message: 'User not found' },
  EMAIL_TAKEN: { status: 409, message: 'Email already registered' },
});

Deprecated()

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

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

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

typescript

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

FieldSelection()

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

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

Enable field selection (partial response) for this route. Allows clients to specify ?fields=id,name to receive only selected fields. Pass false to explicitly disable field selection on a route when the module-level option is enabled.

Parameters

Parameter	Type
`options?`	`boolean` \| `FieldSelectionOptions`

Returns

CustomDecorator<string>

FilterMeta()

function FilterMeta(): CustomDecorator<string>;

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

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:56

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:61

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:287

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:312

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:282

Skip response wrapping for this route.

Returns

CustomDecorator<string>

ResponseMessage()

function ResponseMessage(message): CustomDecorator<string>;

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

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:475

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:412

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:443

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:25

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:339

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:319

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:306

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>

@nestarc/safe-response ​

Classes ​

CursorPaginationMetaDto ​

Constructors ​

Constructor ​

Returns ​

Properties ​

hasMore ​

limit ​

links? ​

nextCursor ​

previousCursor ​

totalCount? ​

type ​

DeprecationMetaDto ​

Constructors ​

Constructor ​

Returns ​

Properties ​

deprecated ​

link? ​

message? ​

since? ​

sunset? ​

ErrorDetailDto ​

Constructors ​

Constructor ​

Returns ​

Properties ​

code ​

details? ​

message ​

ErrorResponseMetaDto ​

Indexable ​

Constructors ​

Constructor ​

Returns ​

Properties ​

apiVersion? ​

deprecation? ​

rateLimit? ​

responseTime? ​

FilterMetaDto ​

Constructors ​

Constructor ​

Returns ​

Properties ​

filters ​

NestI18nAdapter ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

resolveLanguage() ​

Parameters ​

Returns ​

Implementation of ​

translate() ​

Parameters ​

Returns ​

Implementation of ​

PaginationLinksDto ​

Constructors ​

Constructor ​

Returns ​

Properties ​

first ​

last ​

next ​

prev ​

self ​

PaginationMetaDto ​

Constructors ​

Constructor ​

Returns ​

Properties ​

hasNext ​

hasPrev ​

@nestarc/safe-response

Classes

CursorPaginationMetaDto

Constructors

Constructor

Returns

Properties

hasMore

limit

links?

nextCursor

previousCursor

totalCount?

type

DeprecationMetaDto

Constructors

Constructor

Returns

Properties

deprecated

link?

message?

since?

sunset?

ErrorDetailDto

Constructors

Constructor

Returns

Properties

code

details?

message

ErrorResponseMetaDto

Indexable

Constructors

Constructor

Returns

Properties

apiVersion?

deprecation?

rateLimit?

responseTime?

FilterMetaDto

Constructors

Constructor

Returns

Properties

filters

NestI18nAdapter

Implements

Constructors

Constructor

Parameters

Returns

Methods

resolveLanguage()

Parameters

Returns

Implementation of

translate()

Parameters

Returns

Implementation of

PaginationLinksDto

Constructors

Constructor

Returns

Properties

first

last

next

prev

self

PaginationMetaDto

Constructors

Constructor

Returns

Properties

hasNext

hasPrev