Common NestJs Library

this is a NestJs Common Library, can be use on fastify and express

Environment Variables for Module Or Services

1.) I18n - I18nCoreModule

LOCALES_FALLBACK_LANGUAGE=en_US    ##language fallback
LOCALES_MAP_PATH=                  ##override i18n loaderOptions.path
LOCALES_LIVE_RELOAD=1              ## loaderOptions live reload

2.) LoggerUtils & LoggerMiddleware

DEBUG_MODE=1                       ## Logger log Level

HTTP_LOG_USER_AGENT=1              ## log User Agent on request
HTTP_LOG_REQUEST=1                 ## log request data (query, params, body) on request
HTTP_LOG_RESPONSE=1                ## log response data on request
HTTP_LOG_SENSITIVEKEYS=pwd,secret  ## censor log response data with the keys, value is in comma separated

Trust Proxy Configuration

Why It Matters

When your application runs behind a reverse proxy (Cloudflare, AWS ALB, nginx), client IP addresses appear as the proxy's IP. Attackers can spoof X-Forwarded-For headers to bypass rate limiting or hide their identity.

Default in 3.0.0: Trust proxy is DISABLED (fail-closed). You must explicitly configure trusted proxies.

Provider Presets

import { configureTrustProxy } from '@nathapp/nestjs-common';

// Cloudflare
configureTrustProxy(app, { provider: 'cloudflare' });

// AWS Application Load Balancer
configureTrustProxy(app, { provider: 'aws-alb' });

// Private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
configureTrustProxy(app, { provider: 'private' });

// Localhost only
configureTrustProxy(app, { provider: 'loopback' });

// Link-local addresses (169.254.0.0/16, fe80::/10)
configureTrustProxy(app, { provider: 'linklocal' });

Custom CIDR Configuration

configureTrustProxy(app, {
  trustedProxies: [
    '203.0.113.0/24',       // Your proxy subnet
    '2001:db8::/32',        // IPv6 range
    '10.0.0.1',             // Single IP
  ]
});

Migration from 2.x

v2.x behavior: Trust all proxies by default (security risk).

v3.0.0 behavior: Trust no proxies by default. Explicitly configure:

// Before (2.x) - implicit trust-all
// No configuration needed

// After (3.0.0) - explicit configuration required
configureTrustProxy(app, { provider: 'cloudflare' });

Common Deployments

Cloudflare → Your Server:

configureTrustProxy(app, { provider: 'cloudflare' });

AWS ALB → ECS/EC2:

configureTrustProxy(app, { provider: 'aws-alb' });

nginx (10.0.0.0/24) → App:

configureTrustProxy(app, { trustedProxies: ['10.0.0.0/24'] });

Multiple Layers (Cloudflare → nginx → App):

configureTrustProxy(app, {
  trustedProxies: [
    ...resolveProviderCidrs('cloudflare'),
    '10.0.0.0/24',  // Your nginx subnet
  ]
});

Exception Handling

Basic Setup

import { ExceptionModule } from '@nathapp/nestjs-common';

@Module({
  imports: [
    ExceptionModule.forRoot({
      handlers: [MyCustomExceptionHandler],
    }),
  ],
})
export class AppModule {}

Handler Priority Chain

Handlers are executed in registration order. First matching handler wins:

import { IExceptionHandler } from '@nathapp/nestjs-common';

export class DatabaseExceptionHandler implements IExceptionHandler {
  canHandle(exception: unknown): boolean {
    return exception instanceof DatabaseException;
  }

  handle(exception: DatabaseException, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    response.status(503).json({
      error: 'Database temporarily unavailable',
    });
  }
}

Registering Handlers Dynamically

import { GlobalExceptionFilter } from '@nathapp/nestjs-common';

export class AppService {
  constructor(private globalFilter: GlobalExceptionFilter) {}

  onModuleInit() {
    this.globalFilter.registerHandler(new RateLimitExceptionHandler());
  }
}