nestjs-std-errors

NestJS utilities for consistent STD-001 HTTP error responses.

This package helps you standardize error contracts across controllers, filters, and validation in one place.

Features

• StdHttpException with typed factory methods (validation, domain, auth, permission, notFound, server).
• StdExceptionFilter that normalizes thrown errors to STD-001.
• createStdValidationExceptionFactory() for ValidationPipe (class-validator).
• TypeScript types for your API contract: StdErrorEnvelope, StdErrorPayload, StdIssue.
• Request ID support via auto-detection or custom resolver.

Compatibility

• NestJS: ^11
• Node.js: ESM runtime (package "type": "module")
• Peer deps: @nestjs/common, @nestjs/core, class-validator, reflect-metadata, rxjs

Installation

npm i nestjs-std-errors

For local monorepo usage:

npm i ./packages/nestjs-std-errors

Quick start

1) Register the global exception filter

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { StdExceptionFilter } from "nestjs-std-errors";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalFilters(
    new StdExceptionFilter({
      defaultServerMessage: "Internal server error",
      requestIdResolver: (req) => {
        const r = req as { headers?: Record<string, unknown>; id?: unknown };
        const xRequestId = r.headers?.["x-request-id"];
        if (typeof xRequestId === "string") return xRequestId;
        if (typeof r.id === "string") return r.id;
        return undefined;
      },
    })
  );

  await app.listen(3000);
}
bootstrap();

2) Register ValidationPipe with package exception factory

import { ValidationPipe } from "@nestjs/common";
import { createStdValidationExceptionFactory } from "nestjs-std-errors";

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    transform: true,
    forbidNonWhitelisted: true,
    exceptionFactory: createStdValidationExceptionFactory({
      message: "Request validation failed",
    }),
  })
);

What this gives you:

• Maps ValidationError[] to details.issues[].
• Converts validator constraints to stable issue codes (required, email, uuid, min_length, etc.).
• Produces dot-notation paths for nested DTOs (items.0.price).

3) Throw typed errors from application code

import { StdHttpException } from "nestjs-std-errors";

throw StdHttpException.validation({
  message: "Request validation failed",
  issues: [
    { code: "email", message: "email must be an email", path: "email" },
    {
      code: "min_length",
      message: "password must be longer than or equal to 8 characters",
      path: "password",
    },
  ],
});

import { StdHttpException } from "nestjs-std-errors";

throw StdHttpException.domain({
  code: "PINNED_MATERIAL_MUST_BELONG_TO_PLACE",
  message: "Pinned material must belong to the same place",
});

API overview

StdHttpException

Factory methods:

• StdHttpException.validation({ message, issues?, status? })
• StdHttpException.domain({ message, code, issues?, status? })
• StdHttpException.auth(message?, code?)
• StdHttpException.permission(message?, code?)
• StdHttpException.notFound(message?, code?)
• StdHttpException.server(message?, code?)

Convenience factories

import {
  createAuthException,
  createDomainException,
  createNotFoundException,
  createPermissionException,
  createServerException,
  createValidationException,
} from "nestjs-std-errors";

Validation mapping helpers

• createStdValidationExceptionFactory(options?)
• mapValidationErrorsToStdIssues(errors, options?)

Response example

{
  "meta": {
    "requestId": "82f1c58c-1d32-4f85-8e84-cf7bd4b9d0f4"
  },
  "error": {
    "type": "validation",
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "issues": [
        {
          "code": "email",
          "message": "email must be an email",
          "path": "email"
        }
      ]
    }
  }
}

STD-001 conventions

• error.type, error.code, and error.message are required.
• error.details.issues[] is allowed only for validation and domain errors.
• Use dot notation for paths (items.0.price), not bracket notation.
• Client-side logic should branch by type/code, not by message.

Why use this package

• Keeps error shape predictable across all API endpoints.
• Reduces repeated error-formatting code in controllers/services.
• Improves frontend reliability with stable machine-readable codes.

License

MIT