@biggora/claude-plugins 1.2.2 → 1.3.1

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

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

@@ -0,0 +1,87 @@
+---
+name: lifecycle-events
+description: Application and provider lifecycle hooks in NestJS
+---
+
+# Lifecycle Events
+
+NestJS provides lifecycle hooks that give visibility into key application events and allow running code when they occur.
+
+## Lifecycle Sequence
+
+The lifecycle consists of three phases: **initializing**, **running**, and **terminating**.
+
+## Lifecycle Hooks
+
+| Hook | When Triggered |
+|------|----------------|
+| `onModuleInit()` | Called once the host module's dependencies have been resolved |
+| `onApplicationBootstrap()` | Called once all modules have been initialized, but before listening |
+| `onModuleDestroy()` | Called after a termination signal (e.g., SIGTERM) has been received |
+| `beforeApplicationShutdown()` | Called after all `onModuleDestroy()` handlers have completed |
+| `onApplicationShutdown()` | Called after connections close (`app.close()` resolves) |
+
+## Usage
+
+Implement the appropriate interface to register a lifecycle hook:
+
+```typescript
+import { Injectable, OnModuleInit, OnApplicationBootstrap } from '@nestjs/common';
+
+@Injectable()
+export class UsersService implements OnModuleInit, OnApplicationBootstrap {
+  onModuleInit() {
+    console.log('Module initialized');
+  }
+
+  onApplicationBootstrap() {
+    console.log('Application bootstrapped');
+  }
+}
+```
+
+## Asynchronous Initialization
+
+Hooks can be async - Nest will wait for the promise to resolve:
+
+```typescript
+async onModuleInit(): Promise<void> {
+  await this.fetchConfiguration();
+}
+```
+
+## Enabling Shutdown Hooks
+
+Shutdown hooks are disabled by default. Enable them in `main.ts`:
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.enableShutdownHooks();
+  await app.listen(3000);
+}
+```
+
+Handle shutdown signals:
+
+```typescript
+@Injectable()
+class DatabaseService implements OnApplicationShutdown {
+  onApplicationShutdown(signal: string) {
+    console.log(`Received ${signal}, closing connections...`);
+    // Cleanup logic
+  }
+}
+```
+
+## Key Points
+
+- Lifecycle hooks are not triggered for **request-scoped** providers
+- Execution order depends on module import order
+- Windows has limited shutdown hook support (SIGINT works, SIGTERM doesn't)
+- `enableShutdownHooks` consumes memory by starting listeners
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/lifecycle-events
+-->

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

@@ -0,0 +1,107 @@
+---
+name: module-reference
+description: Accessing providers dynamically with ModuleRef
+---
+
+# Module Reference
+
+`ModuleRef` provides methods to navigate the DI container and obtain references to providers dynamically.
+
+## Basic Usage
+
+Inject `ModuleRef` to access providers:
+
+```typescript
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+
+@Injectable()
+export class CatsService implements OnModuleInit {
+  private service: Service;
+
+  constructor(private moduleRef: ModuleRef) {}
+
+  onModuleInit() {
+    this.service = this.moduleRef.get(Service);
+  }
+}
+```
+
+## Retrieving Instances
+
+### Static Instances (`get()`)
+
+```typescript
+// From current module
+const service = this.moduleRef.get(Service);
+
+// From global context (different module)
+const service = this.moduleRef.get(Service, { strict: false });
+```
+
+### Scoped Providers (`resolve()`)
+
+For transient or request-scoped providers:
+
+```typescript
+const transientService = await this.moduleRef.resolve(TransientService);
+```
+
+Each `resolve()` call returns a unique instance. To get the same instance, pass a context identifier:
+
+```typescript
+import { ContextIdFactory } from '@nestjs/core';
+
+const contextId = ContextIdFactory.create();
+const service1 = await this.moduleRef.resolve(TransientService, contextId);
+const service2 = await this.moduleRef.resolve(TransientService, contextId);
+// service1 === service2
+```
+
+## Request Context
+
+Get the context ID from an existing request:
+
+```typescript
+@Injectable()
+export class CatsService {
+  constructor(
+    @Inject(REQUEST) private request: Record<string, unknown>,
+    private moduleRef: ModuleRef,
+  ) {}
+
+  async getRepository() {
+    const contextId = ContextIdFactory.getByRequest(this.request);
+    return this.moduleRef.resolve(CatsRepository, contextId);
+  }
+}
+```
+
+## Dynamic Instantiation
+
+Create instances of classes not registered as providers:
+
+```typescript
+const factory = await this.moduleRef.create(CatsFactory);
+```
+
+## Register REQUEST Provider
+
+For manually created DI sub-trees:
+
+```typescript
+const contextId = ContextIdFactory.create();
+this.moduleRef.registerRequestByContextId(myRequestObject, contextId);
+```
+
+## Key Points
+
+- `get()` only retrieves static (singleton) instances
+- `resolve()` is async and for scoped providers
+- Use `{ strict: false }` to access providers from other modules
+- `ModuleRef` is imported from `@nestjs/core`
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/module-ref
+-->

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

@@ -0,0 +1,197 @@
+---
+name: fundamentals-pipes
+description: NestJS pipes for data transformation and validation
+---
+
+# Pipes
+
+Pipes transform input data to the desired form or validate input data. They operate on arguments before route handlers are invoked.
+
+## Built-in Pipes
+
+- `ValidationPipe` - Validates DTOs
+- `ParseIntPipe` - Parses strings to integers
+- `ParseFloatPipe` - Parses strings to floats
+- `ParseBoolPipe` - Parses strings to booleans
+- `ParseArrayPipe` - Parses strings to arrays
+- `ParseUUIDPipe` - Validates UUIDs
+- `ParseEnumPipe` - Validates enum values
+- `DefaultValuePipe` - Provides default values
+- `ParseFilePipe` - Validates file uploads
+- `ParseDatePipe` - Parses date strings
+
+## Binding Pipes
+
+### Parameter-level Binding
+
+```typescript
+@Get(':id')
+async findOne(@Param('id', ParseIntPipe) id: number) {
+  return this.catsService.findOne(id);
+}
+```
+
+### With Options
+
+```typescript
+@Get(':id')
+async findOne(
+  @Param('id', new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE }))
+  id: number,
+) {
+  return this.catsService.findOne(id);
+}
+```
+
+### Query Parameters
+
+```typescript
+@Get()
+async findOne(@Query('id', ParseIntPipe) id: number) {
+  return this.catsService.findOne(id);
+}
+```
+
+## Custom Pipes
+
+### Basic Pipe
+
+```typescript
+import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';
+
+@Injectable()
+export class ValidationPipe implements PipeTransform {
+  transform(value: any, metadata: ArgumentMetadata) {
+    return value;
+  }
+}
+```
+
+### Validation Pipe with Zod
+
+```typescript
+import { PipeTransform, ArgumentMetadata, BadRequestException } from '@nestjs/common';
+import { ZodSchema } from 'zod';
+
+export class ZodValidationPipe implements PipeTransform {
+  constructor(private schema: ZodSchema) {}
+
+  transform(value: unknown, metadata: ArgumentMetadata) {
+    try {
+      const parsedValue = this.schema.parse(value);
+      return parsedValue;
+    } catch (error) {
+      throw new BadRequestException('Validation failed');
+    }
+  }
+}
+```
+
+Usage:
+
+```typescript
+@Post()
+@UsePipes(new ZodValidationPipe(createCatSchema))
+async create(@Body() createCatDto: CreateCatDto) {
+  this.catsService.create(createCatDto);
+}
+```
+
+### Validation Pipe with class-validator
+
+```typescript
+import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';
+import { validate } from 'class-validator';
+import { plainToInstance } from 'class-transformer';
+
+@Injectable()
+export class ValidationPipe implements PipeTransform<any> {
+  async transform(value: any, { metatype }: ArgumentMetadata) {
+    if (!metatype || !this.toValidate(metatype)) {
+      return value;
+    }
+    const object = plainToInstance(metatype, value);
+    const errors = await validate(object);
+    if (errors.length > 0) {
+      throw new BadRequestException('Validation failed');
+    }
+    return value;
+  }
+
+  private toValidate(metatype: Function): boolean {
+    const types: Function[] = [String, Boolean, Number, Array, Object];
+    return !types.includes(metatype);
+  }
+}
+```
+
+### Transformation Pipe
+
+```typescript
+import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';
+
+@Injectable()
+export class ParseIntPipe implements PipeTransform<string, number> {
+  transform(value: string, metadata: ArgumentMetadata): number {
+    const val = parseInt(value, 10);
+    if (isNaN(val)) {
+      throw new BadRequestException('Validation failed');
+    }
+    return val;
+  }
+}
+```
+
+## Global Pipes
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalPipes(new ValidationPipe());
+  await app.listen(3000);
+}
+```
+
+Or via module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_PIPE } from '@nestjs/core';
+
+@Module({
+  providers: [
+    {
+      provide: APP_PIPE,
+      useClass: ValidationPipe,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Default Values
+
+```typescript
+@Get()
+async findAll(
+  @Query('activeOnly', new DefaultValuePipe(false), ParseBoolPipe) activeOnly: boolean,
+  @Query('page', new DefaultValuePipe(0), ParseIntPipe) page: number,
+) {
+  return this.catsService.findAll({ activeOnly, page });
+}
+```
+
+## Key Points
+
+- Pipes run before route handlers
+- Pipes can transform or validate data
+- Use built-in `ValidationPipe` for DTO validation
+- Pipes can be parameter, method, controller, or global scoped
+- Pipes throw exceptions to stop execution
+- Use `DefaultValuePipe` before `Parse*` pipes for optional parameters
+
+<!--
+Source references:
+- https://docs.nestjs.com/pipes
+- https://docs.nestjs.com/techniques/validation
+-->