spoonfeeder 0.1.0

package/templates/base/src/shared/errors/application.error.ts

@@ -0,0 +1,21 @@
+export class ApplicationError extends Error {
+  public readonly traceCode: string;
+  public readonly errorCode: string;
+  public readonly statusCode: number;
+  public readonly debugInfo?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    traceCode: string,
+    errorCode: string,
+    statusCode: number = 500,
+    debugInfo?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this.traceCode = traceCode;
+    this.errorCode = errorCode;
+    this.statusCode = statusCode;
+    this.debugInfo = debugInfo;
+  }
+}

package/templates/base/src/shared/errors/forbidden.error.ts

@@ -0,0 +1,7 @@
+import { ApplicationError } from './application.error';
+
+export class ForbiddenError extends ApplicationError {
+  constructor(message: string, traceCode: string, debugInfo?: Record<string, unknown>) {
+    super(message, traceCode, 'FORBIDDEN', 403, debugInfo);
+  }
+}

package/templates/base/src/shared/errors/index.ts

@@ -0,0 +1,6 @@
+export { ApplicationError } from './application.error';
+export { ValidationError } from './validation.error';
+export { NotFoundError } from './not-found.error';
+export { ForbiddenError } from './forbidden.error';
+export { InvalidRequestError } from './invalid-request.error';
+export { RequesterError } from './requester.error';

package/templates/base/src/shared/errors/invalid-request.error.ts

@@ -0,0 +1,7 @@
+import { ApplicationError } from './application.error';
+
+export class InvalidRequestError extends ApplicationError {
+  constructor(message: string, traceCode: string, debugInfo?: Record<string, unknown>) {
+    super(message, traceCode, 'INVALID_REQUEST', 400, debugInfo);
+  }
+}

package/templates/base/src/shared/errors/not-found.error.ts

@@ -0,0 +1,7 @@
+import { ApplicationError } from './application.error';
+
+export class NotFoundError extends ApplicationError {
+  constructor(message: string, traceCode: string, debugInfo?: Record<string, unknown>) {
+    super(message, traceCode, 'NOT_FOUND', 404, debugInfo);
+  }
+}

package/templates/base/src/shared/errors/requester.error.ts

@@ -0,0 +1,7 @@
+import { ApplicationError } from './application.error';
+
+export class RequesterError extends ApplicationError {
+  constructor(message: string, traceCode: string, debugInfo?: Record<string, unknown>) {
+    super(message, traceCode, 'REQUESTER_ERROR', 502, debugInfo);
+  }
+}

package/templates/base/src/shared/errors/validation.error.ts

@@ -0,0 +1,7 @@
+import { ApplicationError } from './application.error';
+
+export class ValidationError extends ApplicationError {
+  constructor(message: string, traceCode: string, debugInfo?: Record<string, unknown>) {
+    super(message, traceCode, 'VALIDATION_ERROR', 400, debugInfo);
+  }
+}

package/templates/base/src/shared/filters/http-exception.filter.ts

@@ -0,0 +1,139 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { FastifyReply, FastifyRequest } from 'fastify';
+import { ApplicationError } from '@/shared/errors/application.error';
+
+const HTTP_STATUS_CODES: Record<number, string> = {
+  400: 'BAD_REQUEST',
+  401: 'UNAUTHORIZED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  409: 'CONFLICT',
+  422: 'UNPROCESSABLE_ENTITY',
+  429: 'TOO_MANY_REQUESTS',
+};
+
+const HTTP_STATUS_TITLES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  409: 'Conflict',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+};
+
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalExceptionFilter.name);
+  private readonly isTestEnvironment = process.env.NODE_ENV === 'test';
+  private readonly isProduction = process.env.NODE_ENV === 'production';
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<FastifyReply>();
+    const request = ctx.getRequest<FastifyRequest>();
+
+    const { status, body } = this.buildErrorResponse(exception, request);
+
+    if (!this.isTestEnvironment) {
+      this.logger.error(
+        `${request.method} ${request.url} - ${status} [${body.traceCode}]`,
+        exception instanceof Error ? exception.stack : undefined,
+      );
+    }
+
+    void response.code(status).header('content-type', 'application/problem+json').send(body);
+  }
+
+  private buildErrorResponse(exception: unknown, request: FastifyRequest) {
+    if (exception instanceof ApplicationError) {
+      const errorCode = exception.errorCode;
+      return {
+        status: exception.statusCode,
+        body: {
+          type: `urn:error:${errorCode.toLowerCase().replace(/_/g, '-')}`,
+          title: HTTP_STATUS_TITLES[exception.statusCode] ?? 'Error',
+          status: exception.statusCode,
+          detail: exception.message,
+          instance: request.url,
+          traceCode: exception.traceCode,
+          errorCode,
+          timestamp: new Date().toISOString(),
+          debugInformation: this.isProduction
+            ? null
+            : {
+                ...(exception.debugInfo ?? {}),
+                stack: exception.stack?.split('\n'),
+              },
+        },
+      };
+    }
+
+    if (exception instanceof HttpException) {
+      const exceptionResponse = exception.getResponse();
+      const rawMessage =
+        typeof exceptionResponse === 'string'
+          ? exceptionResponse
+          : ((exceptionResponse as Record<string, unknown>).message ?? exception.message);
+      const detail = Array.isArray(rawMessage)
+        ? (rawMessage as string[]).join('; ')
+        : typeof rawMessage === 'string'
+          ? rawMessage
+          : exception.message;
+      const statusCode = exception.getStatus();
+      const errorCode = HTTP_STATUS_CODES[statusCode] ?? 'HTTP_ERROR';
+
+      return {
+        status: statusCode,
+        body: {
+          type: `urn:error:${errorCode.toLowerCase().replace(/_/g, '-')}`,
+          title: HTTP_STATUS_TITLES[statusCode] ?? 'Error',
+          status: statusCode,
+          detail,
+          instance: request.url,
+          traceCode: this.generateTraceCode(),
+          errorCode,
+          timestamp: new Date().toISOString(),
+          debugInformation: this.isProduction
+            ? null
+            : {
+                stack: exception instanceof Error ? exception.stack?.split('\n') : undefined,
+              },
+        },
+      };
+    }
+
+    return {
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      body: {
+        type: 'urn:error:internal-error',
+        title: 'Internal Server Error',
+        status: HttpStatus.INTERNAL_SERVER_ERROR,
+        detail: 'Internal server error',
+        instance: request.url,
+        traceCode: this.generateTraceCode(),
+        errorCode: 'INTERNAL_ERROR',
+        timestamp: new Date().toISOString(),
+        debugInformation: this.isProduction
+          ? null
+          : {
+              stack: exception instanceof Error ? exception.stack?.split('\n') : undefined,
+            },
+      },
+    };
+  }
+
+  private generateTraceCode(): string {
+    return `ERR_${Date.now()}_${Math.random().toString(36).substring(2, 8).toUpperCase()}`;
+  }
+}

package/templates/base/src/shared/interceptors/response.interceptor.ts

@@ -0,0 +1,22 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+interface DataResponse<T> {
+  data: T;
+}
+
+@Injectable()
+export class ResponseInterceptor<T> implements NestInterceptor<T, DataResponse<T> | undefined> {
+  intercept(
+    _context: ExecutionContext,
+    next: CallHandler<T>,
+  ): Observable<DataResponse<T> | undefined> {
+    return next.handle().pipe(
+      map((data) => {
+        if (data === undefined || data === null) return undefined;
+        return { data };
+      }),
+    );
+  }
+}

package/templates/base/src/shared/middleware/request-timeout.middleware.ts

@@ -0,0 +1,32 @@
+import { Injectable, NestMiddleware, RequestTimeoutException } from '@nestjs/common';
+import { FastifyRequest, FastifyReply } from 'fastify';
+
+@Injectable()
+export class RequestTimeoutMiddleware implements NestMiddleware {
+  private readonly timeoutMs: number;
+
+  constructor() {
+    this.timeoutMs = Number(process.env.REQUEST_TIMEOUT_MS ?? 30000);
+  }
+
+  use(req: FastifyRequest['raw'], res: FastifyReply['raw'], next: () => void): void {
+    const timer = setTimeout(() => {
+      if (!res.writableEnded) {
+        res.statusCode = 408;
+        res.end(
+          JSON.stringify({
+            type: 'urn:error:request-timeout',
+            title: 'Request Timeout',
+            status: 408,
+            detail: 'Request processing exceeded the time limit',
+            instance: (req as any).url,
+            timestamp: new Date().toISOString(),
+          }),
+        );
+      }
+    }, this.timeoutMs);
+
+    res.on('close', () => clearTimeout(timer));
+    next();
+  }
+}

package/templates/base/src/shared/pipes/parse-uuid.pipe.ts

@@ -0,0 +1,13 @@
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+@Injectable()
+export class ParseUuidPipe implements PipeTransform<string, string> {
+  transform(value: string): string {
+    if (!UUID_REGEX.test(value)) {
+      throw new BadRequestException(`"${value}" is not a valid UUID`);
+    }
+    return value.toLowerCase();
+  }
+}

package/templates/base/src/shared/utils/index.ts

@@ -0,0 +1,2 @@
+export { sleep } from './sleep.util';
+export { retry, type RetryOptions } from './retry.util';

package/templates/base/src/shared/utils/retry.util.ts

@@ -0,0 +1,32 @@
+import { Logger } from '@nestjs/common';
+
+const logger = new Logger('Retry');
+
+export interface RetryOptions {
+  maxAttempts: number;
+  delayMs: number;
+  backoffMultiplier?: number;
+}
+
+export async function retry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> {
+  const { maxAttempts, delayMs, backoffMultiplier = 2 } = options;
+
+  let lastError: Error | undefined;
+  let currentDelay = delayMs;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      logger.warn(`Attempt ${attempt}/${maxAttempts} failed: ${lastError.message}`);
+
+      if (attempt < maxAttempts) {
+        await new Promise((resolve) => setTimeout(resolve, currentDelay));
+        currentDelay *= backoffMultiplier;
+      }
+    }
+  }
+
+  throw lastError;
+}

package/templates/base/src/shared/utils/sleep.util.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/templates/base/tests/e2e/app.e2e-spec.ts.ejs

@@ -0,0 +1,25 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
+import { AppModule } from '@/app.module';
+
+describe('App (e2e)', () => {
+  let app: NestFastifyApplication;
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it('should be defined', () => {
+    expect(app).toBeDefined();
+  });
+});

package/templates/base/tests/unit/app.module.spec.ts

@@ -0,0 +1,11 @@
+import { Test } from '@nestjs/testing';
+import { AppModule } from '@/app.module';
+
+describe('AppModule', () => {
+  it('should compile', async () => {
+    const module = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+    expect(module).toBeDefined();
+  });
+});

package/templates/base/tests/unit/shared/errors/error-hierarchy.spec.ts

@@ -0,0 +1,69 @@
+import {
+  ApplicationError,
+  ValidationError,
+  NotFoundError,
+  ForbiddenError,
+  InvalidRequestError,
+  RequesterError,
+} from '@/shared/errors';
+
+describe('ApplicationError', () => {
+  it('should set all properties', () => {
+    const err = new ApplicationError('msg', 'T_001', 'CODE', 500, { key: 'val' });
+    expect(err.message).toBe('msg');
+    expect(err.traceCode).toBe('T_001');
+    expect(err.errorCode).toBe('CODE');
+    expect(err.statusCode).toBe(500);
+    expect(err.debugInfo).toEqual({ key: 'val' });
+    expect(err.name).toBe('ApplicationError');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('should default statusCode to 500', () => {
+    const err = new ApplicationError('msg', 'T', 'C');
+    expect(err.statusCode).toBe(500);
+  });
+
+  it('should allow undefined debugInfo', () => {
+    const err = new ApplicationError('msg', 'T', 'C');
+    expect(err.debugInfo).toBeUndefined();
+  });
+});
+
+describe.each([
+  { Class: ValidationError, code: 'VALIDATION_ERROR', status: 400 },
+  { Class: NotFoundError, code: 'NOT_FOUND', status: 404 },
+  { Class: ForbiddenError, code: 'FORBIDDEN', status: 403 },
+  { Class: InvalidRequestError, code: 'INVALID_REQUEST', status: 400 },
+  { Class: RequesterError, code: 'REQUESTER_ERROR', status: 502 },
+])('$Class.name', ({ Class, code, status }) => {
+  it(`should have statusCode ${status}`, () => {
+    const err = new Class('msg', 'T_001');
+    expect(err.statusCode).toBe(status);
+  });
+
+  it(`should have errorCode ${code}`, () => {
+    const err = new Class('msg', 'T_001');
+    expect(err.errorCode).toBe(code);
+  });
+
+  it('should preserve traceCode', () => {
+    const err = new Class('msg', 'A_NF_00001');
+    expect(err.traceCode).toBe('A_NF_00001');
+  });
+
+  it('should carry debugInfo', () => {
+    const err = new Class('msg', 'T', { userId: 42 });
+    expect(err.debugInfo).toEqual({ userId: 42 });
+  });
+
+  it('should be instanceof ApplicationError', () => {
+    const err = new Class('msg', 'T');
+    expect(err).toBeInstanceOf(ApplicationError);
+  });
+
+  it('should have correct name', () => {
+    const err = new Class('msg', 'T');
+    expect(err.name).toBe(Class.name);
+  });
+});

package/templates/base/tests/unit/shared/filters/http-exception.filter.spec.ts

@@ -0,0 +1,188 @@
+import { ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
+import { GlobalExceptionFilter } from '@/shared/filters/http-exception.filter';
+import { NotFoundError } from '@/shared/errors/not-found.error';
+import { ApplicationError } from '@/shared/errors/application.error';
+import { ValidationError } from '@/shared/errors/validation.error';
+
+const mockSend = jest.fn<void, [Record<string, unknown>]>();
+const mockHeader = jest.fn().mockReturnValue({ send: mockSend });
+const mockCode = jest.fn().mockReturnValue({ header: mockHeader });
+const mockResponse = { code: mockCode };
+const mockRequest = { method: 'GET', url: '/test' };
+
+const createMockHost = (): ArgumentsHost =>
+  ({
+    switchToHttp: () => ({
+      getResponse: () => mockResponse,
+      getRequest: () => mockRequest,
+    }),
+  }) as unknown as ArgumentsHost;
+
+describe('GlobalExceptionFilter', () => {
+  let filter: GlobalExceptionFilter;
+  const originalNodeEnv = process.env.NODE_ENV;
+
+  beforeEach(() => {
+    process.env.NODE_ENV = 'test';
+    filter = new GlobalExceptionFilter();
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalNodeEnv;
+  });
+
+  describe('catch', () => {
+    it('should handle HttpException with correct status and error code', () => {
+      const exception = new HttpException('Not found', HttpStatus.NOT_FOUND);
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      expect(mockCode).toHaveBeenCalledTimes(1);
+      expect(mockCode).toHaveBeenCalledWith(HttpStatus.NOT_FOUND);
+      expect(mockHeader).toHaveBeenCalledWith('content-type', 'application/problem+json');
+      expect(mockSend).toHaveBeenCalledTimes(1);
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.type).toBe('urn:error:not-found');
+      expect(body.title).toBe('Not Found');
+      expect(body.status).toBe(HttpStatus.NOT_FOUND);
+      expect(body.detail).toBe('Not found');
+      expect(body.errorCode).toBe('NOT_FOUND');
+      expect(body.instance).toBe('/test');
+      expect(body.timestamp).toBeDefined();
+      expect(body.traceCode).toMatch(/^ERR_\d+_[A-Z0-9]+$/);
+    });
+
+    it('should handle unknown exception as 500 internal server error', () => {
+      const exception = new Error('Unexpected error');
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      expect(mockCode).toHaveBeenCalledWith(HttpStatus.INTERNAL_SERVER_ERROR);
+      expect(mockHeader).toHaveBeenCalledWith('content-type', 'application/problem+json');
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.type).toBe('urn:error:internal-error');
+      expect(body.title).toBe('Internal Server Error');
+      expect(body.status).toBe(HttpStatus.INTERNAL_SERVER_ERROR);
+      expect(body.detail).toBe('Internal server error');
+      expect(body.errorCode).toBe('INTERNAL_ERROR');
+    });
+
+    it('should use HTTP_ERROR code for unmapped status codes', () => {
+      const exception = new HttpException('Teapot', 418);
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.type).toBe('urn:error:http-error');
+      expect(body.title).toBe('Error');
+      expect(body.status).toBe(418);
+      expect(body.errorCode).toBe('HTTP_ERROR');
+    });
+
+    it('should handle ApplicationError with static trace code', () => {
+      const exception = new NotFoundError('User not found', 'A_NF_00001');
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      expect(mockCode).toHaveBeenCalledWith(404);
+      expect(mockHeader).toHaveBeenCalledWith('content-type', 'application/problem+json');
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.type).toBe('urn:error:not-found');
+      expect(body.title).toBe('Not Found');
+      expect(body.status).toBe(404);
+      expect(body.detail).toBe('User not found');
+      expect(body.errorCode).toBe('NOT_FOUND');
+      expect(body.traceCode).toBe('A_NF_00001');
+      expect(body.instance).toBe('/test');
+      expect(body.timestamp).toBeDefined();
+    });
+
+    it('should handle ValidationError with 400 status', () => {
+      const exception = new ValidationError('Invalid email', 'A_VL_00001', {
+        field: 'email',
+      });
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      expect(mockCode).toHaveBeenCalledWith(400);
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.type).toBe('urn:error:validation-error');
+      expect(body.title).toBe('Bad Request');
+      expect(body.status).toBe(400);
+      expect(body.detail).toBe('Invalid email');
+      expect(body.errorCode).toBe('VALIDATION_ERROR');
+      expect(body.traceCode).toBe('A_VL_00001');
+    });
+
+    it('should include debugInformation in non-production', () => {
+      const debugInfo = { userId: 42, attemptedResource: '/admin' };
+      const exception = new ApplicationError(
+        'Something failed',
+        'A_DB_00001',
+        'DEBUG_TEST',
+        500,
+        debugInfo,
+      );
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      const body = mockSend.mock.calls[0][0];
+      const debug = body.debugInformation as Record<string, unknown>;
+      expect(debug).not.toBeNull();
+      expect(debug.userId).toBe(42);
+      expect(debug.attemptedResource).toBe('/admin');
+      expect(debug.stack).toBeDefined();
+    });
+
+    it('should set debugInformation to null in production', () => {
+      process.env.NODE_ENV = 'production';
+      const productionFilter = new GlobalExceptionFilter();
+
+      const exception = new ApplicationError('Something failed', 'A_DB_00002', 'DEBUG_TEST', 500, {
+        secret: 'should-not-leak',
+      });
+      const host = createMockHost();
+
+      productionFilter.catch(exception, host);
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.debugInformation).toBeNull();
+    });
+
+    it('should include debugInformation for HttpException in non-production', () => {
+      const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+      const host = createMockHost();
+
+      filter.catch(exception, host);
+
+      const body = mockSend.mock.calls[0][0];
+      const debug = body.debugInformation as Record<string, unknown>;
+      expect(debug).not.toBeNull();
+      expect(debug.stack).toBeDefined();
+    });
+
+    it('should set debugInformation to null for HttpException in production', () => {
+      process.env.NODE_ENV = 'production';
+      const productionFilter = new GlobalExceptionFilter();
+
+      const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+      const host = createMockHost();
+
+      productionFilter.catch(exception, host);
+
+      const body = mockSend.mock.calls[0][0];
+      expect(body.debugInformation).toBeNull();
+    });
+  });
+});