@biggora/claude-plugins 1.2.2 → 1.3.0

package/src/skills/nest-best-practices/references/fundamentals-exception-filters.md

@@ -0,0 +1,202 @@
+---
+name: fundamentals-exception-filters
+description: NestJS exception filters for error handling
+---
+
+# Exception Filters
+
+Exception filters give you full control over the exceptions layer and the response sent back to the client.
+
+## Throwing Exceptions
+
+```typescript
+@Get()
+async findAll() {
+  throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
+}
+```
+
+Response:
+
+```json
+{
+  "statusCode": 403,
+  "message": "Forbidden"
+}
+```
+
+## Custom Response Body
+
+```typescript
+throw new HttpException({
+  status: HttpStatus.FORBIDDEN,
+  error: 'This is a custom message',
+}, HttpStatus.FORBIDDEN);
+```
+
+## Built-in HTTP Exceptions
+
+- `BadRequestException`
+- `UnauthorizedException`
+- `NotFoundException`
+- `ForbiddenException`
+- `NotAcceptableException`
+- `RequestTimeoutException`
+- `ConflictException`
+- `GoneException`
+- `HttpVersionNotSupportedException`
+- `PayloadTooLargeException`
+- `UnsupportedMediaTypeException`
+- `UnprocessableEntityException`
+- `InternalServerErrorException`
+- `NotImplementedException`
+- `ImATeapotException`
+- `MethodNotAllowedException`
+- `BadGatewayException`
+- `ServiceUnavailableException`
+- `GatewayTimeoutException`
+- `PreconditionFailedException`
+
+## Custom Exception Filter
+
+```typescript
+import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+    const status = exception.getStatus();
+
+    response
+      .status(status)
+      .json({
+        statusCode: status,
+        timestamp: new Date().toISOString(),
+        path: request.url,
+      });
+  }
+}
+```
+
+## Binding Filters
+
+### Method-scoped
+
+```typescript
+@Post()
+@UseFilters(new HttpExceptionFilter())
+async create(@Body() createCatDto: CreateCatDto) {
+  throw new ForbiddenException();
+}
+```
+
+### Controller-scoped
+
+```typescript
+@Controller()
+@UseFilters(new HttpExceptionFilter())
+export class CatsController {}
+```
+
+### Global Filters
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.useGlobalFilters(new HttpExceptionFilter());
+```
+
+Or via module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: HttpExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Catching Everything
+
+```typescript
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    // Handle all exceptions
+  }
+}
+```
+
+## Platform-agnostic Filter
+
+```typescript
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+
+@Catch()
+export class CatchEverythingFilter implements ExceptionFilter {
+  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const { httpAdapter } = this.httpAdapterHost;
+    const ctx = host.switchToHttp();
+
+    const httpStatus =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const responseBody = {
+      statusCode: httpStatus,
+      timestamp: new Date().toISOString(),
+      path: httpAdapter.getRequestUrl(ctx.getRequest()),
+    };
+
+    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
+  }
+}
+```
+
+## Extending Base Filter
+
+```typescript
+import { Catch, ArgumentsHost } from '@nestjs/common';
+import { BaseExceptionFilter } from '@nestjs/core';
+
+@Catch()
+export class AllExceptionsFilter extends BaseExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    super.catch(exception, host);
+  }
+}
+```
+
+## Key Points
+
+- Filters catch exceptions and format responses
+- Use `@Catch()` to specify exception types
+- Filters can be method, controller, or global scoped
+- Use `HttpAdapterHost` for platform-agnostic code
+- Extend `BaseExceptionFilter` to reuse default behavior
+- Multiple filters can be chained
+
+<!--
+Source references:
+- https://docs.nestjs.com/exception-filters
+-->

package/src/skills/nest-best-practices/references/fundamentals-execution-context.md

@@ -0,0 +1,107 @@
+---
+name: fundamentals-execution-context
+description: Accessing execution context in NestJS guards, filters, and interceptors
+---
+
+# Execution Context
+
+`ExecutionContext` provides information about the current execution context, useful for building generic guards, filters, and interceptors.
+
+## ArgumentsHost
+
+`ArgumentsHost` provides methods to retrieve handler arguments:
+
+```typescript
+const ctx = host.switchToHttp();
+const request = ctx.getRequest<Request>();
+const response = ctx.getResponse<Response>();
+```
+
+## Application Context Types
+
+Determine application type:
+
+```typescript
+if (host.getType() === 'http') {
+  // HTTP context
+} else if (host.getType() === 'rpc') {
+  // Microservice context
+} else if (host.getType<GqlContextType>() === 'graphql') {
+  // GraphQL context
+}
+```
+
+## Switching Contexts
+
+### HTTP Context
+
+```typescript
+const ctx = host.switchToHttp();
+const request = ctx.getRequest<Request>();
+const response = ctx.getResponse<Response>();
+```
+
+### WebSocket Context
+
+```typescript
+const ctx = host.switchToWs();
+const client = ctx.getClient<Socket>();
+const data = ctx.getData();
+```
+
+### RPC Context
+
+```typescript
+const ctx = host.switchToRpc();
+const data = ctx.getData();
+const context = ctx.getContext();
+```
+
+## ExecutionContext
+
+`ExecutionContext` extends `ArgumentsHost` with additional methods:
+
+```typescript
+export interface ExecutionContext extends ArgumentsHost {
+  getClass<T = any>(): Type<T>;
+  getHandler(): Function;
+}
+```
+
+## Using in Guards
+
+```typescript
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const roles = this.reflector.get(Roles, context.getHandler());
+    const request = context.switchToHttp().getRequest();
+    return matchRoles(roles, request.user.roles);
+  }
+}
+```
+
+## Reflection and Metadata
+
+Access route metadata:
+
+```typescript
+const roles = this.reflector.get(Roles, context.getHandler());
+const roles = this.reflector.get(Roles, context.getClass());
+```
+
+## Key Points
+
+- `ArgumentsHost` provides access to handler arguments
+- `ExecutionContext` adds class and handler information
+- Use `switchToHttp()`, `switchToWs()`, `switchToRpc()` for context-specific access
+- Use `getType()` to determine application context
+- `Reflector` provides access to route metadata
+- Execution context is available in guards, filters, and interceptors
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/execution-context
+-->

package/src/skills/nest-best-practices/references/fundamentals-guards.md

@@ -0,0 +1,136 @@
+---
+name: fundamentals-guards
+description: NestJS guards for authorization and access control
+---
+
+# Guards
+
+Guards determine whether a request should be handled by a route handler. They have access to `ExecutionContext` and know what will be executed next.
+
+## Basic Guard
+
+```typescript
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  canActivate(
+    context: ExecutionContext,
+  ): boolean | Promise<boolean> | Observable<boolean> {
+    const request = context.switchToHttp().getRequest();
+    return validateRequest(request);
+  }
+}
+```
+
+## Role-based Guard
+
+```typescript
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Roles } from './roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const roles = this.reflector.get(Roles, context.getHandler());
+    if (!roles) {
+      return true;
+    }
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+    return matchRoles(roles, user.roles);
+  }
+}
+```
+
+## Custom Decorator
+
+```typescript
+import { Reflector } from '@nestjs/core';
+
+export const Roles = Reflector.createDecorator<string[]>();
+```
+
+Usage:
+
+```typescript
+@Post()
+@Roles(['admin'])
+async create(@Body() createCatDto: CreateCatDto) {
+  this.catsService.create(createCatDto);
+}
+```
+
+## Binding Guards
+
+### Controller-scoped
+
+```typescript
+@Controller('cats')
+@UseGuards(RolesGuard)
+export class CatsController {}
+```
+
+### Method-scoped
+
+```typescript
+@Post()
+@UseGuards(RolesGuard)
+async create(@Body() createCatDto: CreateCatDto) {
+  this.catsService.create(createCatDto);
+}
+```
+
+### Global Guards
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.useGlobalGuards(new RolesGuard());
+```
+
+Or via module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+
+@Module({
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: RolesGuard,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Multiple Guards
+
+```typescript
+@UseGuards(AuthGuard, RolesGuard)
+export class CatsController {}
+```
+
+## Execution Order
+
+Guards are executed:
+- After middleware
+- Before interceptors and pipes
+
+## Key Points
+
+- Guards return `true` to allow, `false` to deny
+- Guards can be async (return `Promise<boolean>`)
+- Use `Reflector` to access route metadata
+- Guards throw exceptions to deny access
+- Use `@SetMetadata()` or `Reflector.createDecorator()` for custom metadata
+- Guards have access to `ExecutionContext`
+
+<!--
+Source references:
+- https://docs.nestjs.com/guards
+-->

package/src/skills/nest-best-practices/references/fundamentals-interceptors.md

@@ -0,0 +1,187 @@
+---
+name: fundamentals-interceptors
+description: NestJS interceptors for aspect-oriented programming
+---
+
+# Interceptors
+
+Interceptors implement aspect-oriented programming (AOP). They can bind extra logic before/after method execution, transform results, handle exceptions, and extend function behavior.
+
+## Basic Interceptor
+
+```typescript
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    console.log('Before...');
+
+    const now = Date.now();
+    return next
+      .handle()
+      .pipe(
+        tap(() => console.log(`After... ${Date.now() - now}ms`)),
+      );
+  }
+}
+```
+
+## Response Transformation
+
+```typescript
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+export interface Response<T> {
+  data: T;
+}
+
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
+    return next.handle().pipe(map(data => ({ data })));
+  }
+}
+```
+
+## Exception Mapping
+
+```typescript
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  BadGatewayException,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable, throwError } from 'rxjs';
+import { catchError } from 'rxjs/operators';
+
+@Injectable()
+export class ErrorsInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next
+      .handle()
+      .pipe(
+        catchError(err => throwError(() => new BadGatewayException())),
+      );
+  }
+}
+```
+
+## Caching Interceptor
+
+```typescript
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable, of } from 'rxjs';
+
+@Injectable()
+export class CacheInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const isCached = true;
+    if (isCached) {
+      return of([]);
+    }
+    return next.handle();
+  }
+}
+```
+
+## Timeout Interceptor
+
+```typescript
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler, RequestTimeoutException } from '@nestjs/common';
+import { Observable, throwError, TimeoutError } from 'rxjs';
+import { catchError, timeout } from 'rxjs/operators';
+
+@Injectable()
+export class TimeoutInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next.handle().pipe(
+      timeout(5000),
+      catchError(err => {
+        if (err instanceof TimeoutError) {
+          return throwError(() => new RequestTimeoutException());
+        }
+        return throwError(() => err);
+      }),
+    );
+  }
+}
+```
+
+## Binding Interceptors
+
+### Controller-scoped
+
+```typescript
+@Controller('cats')
+@UseInterceptors(LoggingInterceptor)
+export class CatsController {}
+```
+
+### Method-scoped
+
+```typescript
+@Get()
+@UseInterceptors(LoggingInterceptor)
+async findAll() {
+  return [];
+}
+```
+
+### Global Interceptors
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.useGlobalInterceptors(new LoggingInterceptor());
+```
+
+Or via module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: LoggingInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Null Transformation
+
+```typescript
+@Injectable()
+export class ExcludeNullInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next
+      .handle()
+      .pipe(map(value => value === null ? '' : value));
+  }
+}
+```
+
+## Key Points
+
+- Interceptors wrap request/response stream
+- Use RxJS operators to manipulate streams
+- Must call `next.handle()` to continue execution
+- Can transform responses using `map()`
+- Can handle errors using `catchError()`
+- Can override stream completely (caching)
+- Interceptors support dependency injection
+
+<!--
+Source references:
+- https://docs.nestjs.com/interceptors
+-->

package/src/skills/nest-best-practices/references/fundamentals-lazy-loading.md

@@ -0,0 +1,89 @@
+---
+name: lazy-loading
+description: Lazy loading modules for serverless and performance optimization
+---
+
+# Lazy Loading Modules
+
+Lazy loading helps decrease bootstrap time by loading modules only when needed, particularly useful for serverless environments where cold start latency matters.
+
+## Basic Usage
+
+Inject `LazyModuleLoader` to load modules on-demand:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { LazyModuleLoader } from '@nestjs/core';
+
+@Injectable()
+export class CatsService {
+  constructor(private lazyModuleLoader: LazyModuleLoader) {}
+
+  async loadFeature() {
+    const { LazyModule } = await import('./lazy.module');
+    const moduleRef = await this.lazyModuleLoader.load(() => LazyModule);
+
+    const { LazyService } = await import('./lazy.service');
+    const lazyService = moduleRef.get(LazyService);
+    return lazyService.doSomething();
+  }
+}
+```
+
+## Module Definition
+
+Lazy loaded modules are standard Nest modules:
+
+```typescript
+@Module({
+  providers: [LazyService],
+  exports: [LazyService],
+})
+export class LazyModule {}
+```
+
+## Caching Behavior
+
+Lazy loaded modules are cached after the first load:
+
+```
+Load "LazyModule" attempt: 1 - time: 2.379ms
+Load "LazyModule" attempt: 2 - time: 0.294ms  // Cached
+```
+
+## Limitations
+
+**Cannot lazy load:**
+- Controllers (routes must be registered at startup)
+- Resolvers (GraphQL schema generated at startup)
+- Gateways (WebSocket routes registered at startup)
+
+**Other restrictions:**
+- Cannot register as global modules
+- Global enhancers (guards/interceptors) won't work
+- Lifecycle hooks are not invoked in lazy loaded modules
+
+## Webpack Configuration
+
+For Webpack, update `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Use Cases
+
+Best suited for:
+- Serverless functions (Lambda, Cloud Functions)
+- Worker/cron jobs with conditional logic
+- Feature modules loaded based on runtime conditions
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/lazy-loading-modules
+-->