@biggora/claude-plugins 1.2.2 → 1.3.1

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

@@ -0,0 +1,125 @@
+---
+name: fundamentals-dynamic-modules
+description: Creating configurable dynamic modules in NestJS
+---
+
+# Dynamic Modules
+
+Dynamic modules allow you to create modules that can be configured at runtime, providing flexible and customizable module APIs.
+
+## Static vs Dynamic Modules
+
+Static modules have fixed configuration:
+
+```typescript
+@Module({
+  imports: [ConfigModule],
+})
+export class AppModule {}
+```
+
+Dynamic modules accept configuration:
+
+```typescript
+@Module({
+  imports: [ConfigModule.forRoot({ envFilePath: '.env' })],
+})
+export class AppModule {}
+```
+
+## Creating Dynamic Modules
+
+```typescript
+import { Module, DynamicModule } from '@nestjs/common';
+
+@Module({
+  providers: [Connection],
+  exports: [Connection],
+})
+export class DatabaseModule {
+  static forRoot(entities = [], options?): DynamicModule {
+    const providers = createDatabaseProviders(options, entities);
+    return {
+      module: DatabaseModule,
+      providers: providers,
+      exports: providers,
+    };
+  }
+}
+```
+
+## Using Dynamic Modules
+
+```typescript
+@Module({
+  imports: [DatabaseModule.forRoot([User])],
+})
+export class AppModule {}
+```
+
+## Global Dynamic Modules
+
+```typescript
+{
+  global: true,
+  module: DatabaseModule,
+  providers: providers,
+  exports: providers,
+}
+```
+
+## Re-exporting Dynamic Modules
+
+```typescript
+@Module({
+  imports: [DatabaseModule.forRoot([User])],
+  exports: [DatabaseModule],
+})
+export class AppModule {}
+```
+
+## Async Dynamic Modules
+
+```typescript
+static forRootAsync(options: ConfigModuleAsyncOptions): DynamicModule {
+  return {
+    module: ConfigModule,
+    imports: options.imports || [],
+    providers: [
+      {
+        provide: CONFIG_OPTIONS,
+        useFactory: options.useFactory,
+        inject: options.inject || [],
+      },
+    ],
+    exports: [ConfigService],
+  };
+}
+```
+
+## ConfigurableModuleBuilder
+
+Use `ConfigurableModuleBuilder` for advanced scenarios:
+
+```typescript
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
+  new ConfigurableModuleBuilder<ConfigModuleOptions>()
+    .setClassMethodName('forRoot')
+    .build();
+```
+
+## Key Points
+
+- Dynamic modules provide runtime configuration
+- Use static `forRoot()` or `forRootAsync()` methods
+- Return `DynamicModule` from factory methods
+- Dynamic module properties extend base module metadata
+- Use `ConfigurableModuleBuilder` for complex scenarios
+- Dynamic modules can be global or scoped
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/dynamic-modules
+-->

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
+-->