@biggora/claude-plugins 1.2.2 → 1.3.0

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

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

@@ -0,0 +1,92 @@
+---
+name: fundamentals-provider-scopes
+description: Provider scopes in NestJS (singleton, request, transient)
+---
+
+# Provider Scopes
+
+Providers can have different lifetimes (scopes) that determine how instances are created and shared.
+
+## Scope Types
+
+- `DEFAULT` - Singleton, shared across entire application
+- `REQUEST` - New instance per request
+- `TRANSIENT` - New instance per consumer
+
+## Default Scope (Singleton)
+
+```typescript
+@Injectable()
+export class CatsService {}
+```
+
+Singleton is the default and recommended scope.
+
+## Request Scope
+
+```typescript
+import { Injectable, Scope } from '@nestjs/common';
+
+@Injectable({ scope: Scope.REQUEST })
+export class CatsService {}
+```
+
+## Transient Scope
+
+```typescript
+@Injectable({ scope: Scope.TRANSIENT })
+export class LoggerService {}
+```
+
+## Custom Provider Scopes
+
+```typescript
+{
+  provide: 'CACHE_MANAGER',
+  useClass: CacheManager,
+  scope: Scope.TRANSIENT,
+}
+```
+
+## Controller Scope
+
+```typescript
+@Controller({
+  path: 'cats',
+  scope: Scope.REQUEST,
+})
+export class CatsController {}
+```
+
+## Accessing Request Object
+
+Inject `REQUEST` to access request in request-scoped providers:
+
+```typescript
+import { Injectable, Scope, Inject } from '@nestjs/common';
+import { REQUEST } from '@nestjs/core';
+import { Request } from 'express';
+
+@Injectable({ scope: Scope.REQUEST })
+export class CatsService {
+  constructor(@Inject(REQUEST) private request: Request) {}
+}
+```
+
+## Scope Hierarchy
+
+Request scope bubbles up the injection chain. If a controller depends on a request-scoped provider, the controller becomes request-scoped.
+
+## Key Points
+
+- Singleton scope is default and recommended
+- Request scope creates new instance per request
+- Transient scope creates new instance per consumer
+- Request scope propagates up dependency chain
+- Use `REQUEST` token to access request object
+- WebSocket gateways should not use request-scoped providers
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/injection-scopes
+-->

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

@@ -0,0 +1,142 @@
+---
+name: testing
+description: Unit testing and e2e testing in NestJS with @nestjs/testing
+---
+
+# Testing
+
+NestJS provides utilities for unit and end-to-end testing, with built-in Jest and Supertest integration.
+
+## Installation
+
+```bash
+npm i --save-dev @nestjs/testing
+```
+
+## Unit Testing
+
+### Basic Test Setup
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { CatsController } from './cats.controller';
+import { CatsService } from './cats.service';
+
+describe('CatsController', () => {
+  let controller: CatsController;
+  let service: CatsService;
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [CatsController],
+      providers: [CatsService],
+    }).compile();
+
+    service = moduleRef.get(CatsService);
+    controller = moduleRef.get(CatsController);
+  });
+
+  it('should return cats', async () => {
+    const result = ['cat'];
+    jest.spyOn(service, 'findAll').mockImplementation(() => result);
+    expect(await controller.findAll()).toBe(result);
+  });
+});
+```
+
+### Auto Mocking
+
+Use `useMocker()` to automatically mock dependencies:
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  controllers: [CatsController],
+})
+  .useMocker((token) => {
+    if (token === CatsService) {
+      return { findAll: jest.fn().mockResolvedValue(['cat']) };
+    }
+  })
+  .compile();
+```
+
+### Overriding Providers
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  imports: [CatsModule],
+})
+  .overrideProvider(CatsService)
+  .useValue(mockCatsService)
+  .compile();
+```
+
+## End-to-End Testing
+
+```typescript
+import * as request from 'supertest';
+import { Test } from '@nestjs/testing';
+import { CatsModule } from '../src/cats/cats.module';
+import { INestApplication } from '@nestjs/common';
+
+describe('Cats', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CatsModule],
+    })
+      .overrideProvider(CatsService)
+      .useValue({ findAll: () => ['test'] })
+      .compile();
+
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  it('/GET cats', () => {
+    return request(app.getHttpServer())
+      .get('/cats')
+      .expect(200)
+      .expect({ data: ['test'] });
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+});
+```
+
+## Testing Scoped Providers
+
+```typescript
+const contextId = ContextIdFactory.create();
+jest.spyOn(ContextIdFactory, 'getByRequest').mockImplementation(() => contextId);
+
+const service = await moduleRef.resolve(CatsService, contextId);
+```
+
+## Override Methods
+
+| Method | Purpose |
+|--------|---------|
+| `overrideProvider()` | Override a provider |
+| `overrideModule()` | Override a module |
+| `overrideGuard()` | Override a guard |
+| `overrideInterceptor()` | Override an interceptor |
+| `overrideFilter()` | Override an exception filter |
+| `overridePipe()` | Override a pipe |
+
+Each returns an object with `useClass`, `useValue`, or `useFactory`.
+
+## Key Points
+
+- Keep test files near source files with `.spec.ts` or `.test.ts` suffix
+- E2E tests go in `test/` directory with `.e2e-spec.ts` suffix
+- `compile()` is async and must be awaited
+- Use `resolve()` for scoped providers instead of `get()`
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/testing
+-->