@biggora/claude-plugins 1.2.2 → 1.3.1

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

@@ -0,0 +1,138 @@
+---
+name: core-modules
+description: NestJS modules for organizing application structure
+---
+
+# Modules
+
+Modules are classes annotated with `@Module()` decorator that organize application components. Every Nest application has at least one root module.
+
+## Basic Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CatsController } from './cats.controller';
+import { CatsService } from './cats.service';
+
+@Module({
+  controllers: [CatsController],
+  providers: [CatsService],
+})
+export class CatsModule {}
+```
+
+## Module Properties
+
+- `providers` - Services that can be injected
+- `controllers` - Controllers in this module
+- `imports` - Other modules to import
+- `exports` - Providers to make available to other modules
+
+## Feature Modules
+
+Group related functionality:
+
+```typescript
+@Module({
+  controllers: [CatsController],
+  providers: [CatsService],
+})
+export class CatsModule {}
+```
+
+## Shared Modules
+
+Export providers to share across modules:
+
+```typescript
+@Module({
+  providers: [CatsService],
+  exports: [CatsService],
+})
+export class CatsModule {}
+```
+
+## Global Modules
+
+Make providers available everywhere:
+
+```typescript
+import { Module, Global } from '@nestjs/common';
+
+@Global()
+@Module({
+  providers: [CatsService],
+  exports: [CatsService],
+})
+export class CatsModule {}
+```
+
+## Dynamic Modules
+
+Create configurable modules:
+
+```typescript
+@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,
+    };
+  }
+}
+```
+
+Usage:
+
+```typescript
+@Module({
+  imports: [DatabaseModule.forRoot([User])],
+})
+export class AppModule {}
+```
+
+## Module Re-exporting
+
+Re-export imported modules:
+
+```typescript
+@Module({
+  imports: [CommonModule],
+  exports: [CommonModule],
+})
+export class CoreModule {}
+```
+
+## Module Dependency Injection
+
+Modules can inject providers:
+
+```typescript
+@Module({
+  providers: [CatsService],
+})
+export class CatsModule {
+  constructor(private catsService: CatsService) {}
+}
+```
+
+## Key Points
+
+- Modules encapsulate providers by default
+- Export providers to make them available to other modules
+- Use `@Global()` sparingly - prefer explicit imports
+- Dynamic modules allow runtime configuration
+- Modules are singletons by default
+- Module classes cannot be injected as providers
+
+<!--
+Source references:
+- https://docs.nestjs.com/modules
+- https://docs.nestjs.com/fundamentals/dynamic-modules
+-->

package/src/skills/nest-best-practices/references/core-providers.md

@@ -0,0 +1,188 @@
+---
+name: core-providers
+description: NestJS providers and services for dependency injection
+---
+
+# Providers
+
+Providers are classes that can be injected as dependencies. Services, repositories, factories, and helpers are all providers.
+
+## Basic Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class CatsService {
+  private readonly cats: Cat[] = [];
+
+  create(cat: Cat) {
+    this.cats.push(cat);
+  }
+
+  findAll(): Cat[] {
+    return this.cats;
+  }
+}
+```
+
+## Dependency Injection
+
+Inject services in controllers:
+
+```typescript
+@Controller('cats')
+export class CatsController {
+  constructor(private catsService: CatsService) {}
+
+  @Get()
+  async findAll(): Promise<Cat[]> {
+    return this.catsService.findAll();
+  }
+}
+```
+
+## Provider Registration
+
+Register providers in modules:
+
+```typescript
+@Module({
+  controllers: [CatsController],
+  providers: [CatsService],
+})
+export class CatsModule {}
+```
+
+## Optional Providers
+
+Mark dependencies as optional:
+
+```typescript
+import { Injectable, Optional, Inject } from '@nestjs/common';
+
+@Injectable()
+export class HttpService<T> {
+  constructor(@Optional() @Inject('HTTP_OPTIONS') private httpClient: T) {}
+}
+```
+
+## Property-based Injection
+
+Inject at property level:
+
+```typescript
+@Injectable()
+export class HttpService<T> {
+  @Inject('HTTP_OPTIONS')
+  private readonly httpClient: T;
+}
+```
+
+## Custom Providers
+
+### Value Providers
+
+```typescript
+const mockCatsService = {
+  findAll: () => ['test'],
+};
+
+@Module({
+  providers: [
+    {
+      provide: CatsService,
+      useValue: mockCatsService,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+### Class Providers
+
+```typescript
+const configServiceProvider = {
+  provide: ConfigService,
+  useClass: process.env.NODE_ENV === 'development'
+    ? DevelopmentConfigService
+    : ProductionConfigService,
+};
+
+@Module({
+  providers: [configServiceProvider],
+})
+export class AppModule {}
+```
+
+### Factory Providers
+
+```typescript
+const connectionProvider = {
+  provide: 'CONNECTION',
+  useFactory: (optionsProvider: OptionsProvider) => {
+    const options = optionsProvider.get();
+    return new DatabaseConnection(options);
+  },
+  inject: [OptionsProvider],
+};
+
+@Module({
+  providers: [connectionProvider, OptionsProvider],
+})
+export class AppModule {}
+```
+
+### Alias Providers
+
+```typescript
+const loggerAliasProvider = {
+  provide: 'AliasedLoggerService',
+  useExisting: LoggerService,
+};
+
+@Module({
+  providers: [LoggerService, loggerAliasProvider],
+})
+export class AppModule {}
+```
+
+## Non-class-based Tokens
+
+Use strings or symbols as tokens:
+
+```typescript
+@Module({
+  providers: [
+    {
+      provide: 'CONNECTION',
+      useValue: connection,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+Inject using `@Inject()`:
+
+```typescript
+@Injectable()
+export class CatsRepository {
+  constructor(@Inject('CONNECTION') connection: Connection) {}
+}
+```
+
+## Key Points
+
+- Use `@Injectable()` decorator to mark classes as providers
+- Prefer constructor-based injection over property-based
+- Providers are singletons by default
+- Use custom providers for mocks, factories, and aliases
+- Export providers to make them available to other modules
+- Use string tokens for non-class providers
+
+<!--
+Source references:
+- https://docs.nestjs.com/providers
+- https://docs.nestjs.com/fundamentals/custom-providers
+-->

package/src/skills/nest-best-practices/references/faq-raw-body-hybrid.md

@@ -0,0 +1,122 @@
+---
+name: raw-body-hybrid
+description: Raw request body for webhooks and hybrid HTTP+microservice applications
+---
+
+# Raw Body and Hybrid Applications
+
+## Raw Body (Webhook Signature Verification)
+
+Required for Stripe, GitHub webhooks, etc. where you need the unparsed body to compute HMAC.
+
+### Express
+
+```typescript
+const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+  rawBody: true,
+});
+```
+
+```typescript
+import { Controller, Post, RawBodyRequest, Req } from '@nestjs/common';
+import { Request } from 'express';
+
+@Controller('webhooks')
+class WebhooksController {
+  @Post('stripe')
+  stripe(@Req() req: RawBodyRequest<Request>) {
+    const raw = req.rawBody; // Buffer
+    const signature = req.headers['stripe-signature'];
+    // Verify signature with raw body
+  }
+}
+```
+
+### Fastify
+
+```typescript
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter(),
+  { rawBody: true },
+);
+```
+
+### Additional Parsers
+
+```typescript
+app.useBodyParser('text');
+app.useBodyParser('json', { limit: '10mb' });
+```
+
+## Hybrid Applications
+
+Combine HTTP server with one or more microservice listeners.
+
+```typescript
+const app = await NestFactory.create(AppModule);
+
+// Connect microservices
+app.connectMicroservice<MicroserviceOptions>({
+  transport: Transport.TCP,
+  options: { port: 3001 },
+});
+
+app.connectMicroservice<MicroserviceOptions>({
+  transport: Transport.REDIS,
+  options: { host: 'localhost', port: 6379 },
+});
+
+await app.startAllMicroservices();
+await app.listen(3001);
+```
+
+### Non-HTTP Applications
+
+Use `app.init()` instead of `app.listen()` when not handling HTTP:
+
+```typescript
+await app.startAllMicroservices();
+await app.init();
+```
+
+### Binding Patterns to Transport
+
+When multiple transports exist, bind `@MessagePattern()` to specific transport:
+
+```typescript
+@MessagePattern('time.us.*', Transport.NATS)
+getDate(@Payload() data: number[], @Ctx() context: NatsContext) {
+  return new Date().toLocaleTimeString();
+}
+
+@MessagePattern({ cmd: 'time.us' }, Transport.TCP)
+getTCPDate(@Payload() data: number[]) {
+  return new Date().toLocaleTimeString();
+}
+```
+
+### Inherit App Config
+
+By default, microservices don't inherit global pipes/guards/interceptors. To inherit:
+
+```typescript
+app.connectMicroservice<MicroserviceOptions>(
+  { transport: Transport.TCP },
+  { inheritAppConfig: true },
+);
+```
+
+## Key Points
+
+- `rawBody: true` must be set at app creation
+- Don't use `bodyParser: false` with raw body
+- `RawBodyRequest` interface adds `rawBody` to request
+- Each `connectMicroservice()` adds one transport
+- Call `startAllMicroservices()` before `listen()`
+
+<!--
+Source references:
+- https://docs.nestjs.com/faq/raw-body
+- https://docs.nestjs.com/faq/hybrid-application
+-->

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

@@ -0,0 +1,89 @@
+---
+name: circular-dependency
+description: Resolving circular dependencies between providers and modules
+---
+
+# Circular Dependency
+
+Circular dependencies occur when two classes depend on each other. While they should be avoided, NestJS provides techniques to resolve them when necessary.
+
+## Forward Reference for Providers
+
+Use `forwardRef()` when two providers depend on each other:
+
+```typescript
+// cats.service.ts
+import { Injectable, Inject, forwardRef } from '@nestjs/common';
+import { CommonService } from './common.service';
+
+@Injectable()
+export class CatsService {
+  constructor(
+    @Inject(forwardRef(() => CommonService))
+    private commonService: CommonService,
+  ) {}
+}
+```
+
+```typescript
+// common.service.ts
+@Injectable()
+export class CommonService {
+  constructor(
+    @Inject(forwardRef(() => CatsService))
+    private catsService: CatsService,
+  ) {}
+}
+```
+
+## Forward Reference for Modules
+
+Apply `forwardRef()` on both sides of module imports:
+
+```typescript
+// common.module.ts
+@Module({
+  imports: [forwardRef(() => CatsModule)],
+})
+export class CommonModule {}
+
+// cats.module.ts
+@Module({
+  imports: [forwardRef(() => CommonModule)],
+})
+export class CatsModule {}
+```
+
+## Using ModuleRef Alternative
+
+Refactor to use `ModuleRef` to retrieve providers dynamically:
+
+```typescript
+@Injectable()
+export class CatsService implements OnModuleInit {
+  private commonService: CommonService;
+
+  constructor(private moduleRef: ModuleRef) {}
+
+  onModuleInit() {
+    this.commonService = this.moduleRef.get(CommonService);
+  }
+}
+```
+
+## Common Causes
+
+- Barrel files (index.ts) grouping imports - avoid when importing within same directory
+- Over-coupled service design
+
+## Key Points
+
+- `forwardRef()` is imported from `@nestjs/common`
+- Instantiation order is indeterminate with forward references
+- Avoid circular dependencies with `Scope.REQUEST` providers (can cause undefined dependencies)
+- Consider refactoring to eliminate circular dependencies when possible
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/circular-dependency
+-->

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

@@ -0,0 +1,107 @@
+---
+name: fundamentals-custom-decorators
+description: Creating custom parameter decorators in NestJS
+---
+
+# Custom Decorators
+
+Create custom parameter decorators to extract data from requests in a reusable way.
+
+## Basic Custom Decorator
+
+```typescript
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const User = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.user;
+  },
+);
+```
+
+Usage:
+
+```typescript
+@Get()
+async findOne(@User() user: UserEntity) {
+  console.log(user);
+}
+```
+
+## Decorator with Data
+
+Pass data to decorator:
+
+```typescript
+export const User = createParamDecorator(
+  (data: string, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    const user = request.user;
+
+    return data ? user?.[data] : user;
+  },
+);
+```
+
+Usage:
+
+```typescript
+@Get()
+async findOne(@User('firstName') firstName: string) {
+  console.log(`Hello ${firstName}`);
+}
+```
+
+## Working with Pipes
+
+Apply pipes to custom decorators:
+
+```typescript
+@Get()
+async findOne(
+  @User(new ValidationPipe({ validateCustomDecorators: true }))
+  user: UserEntity,
+) {
+  console.log(user);
+}
+```
+
+## Decorator Composition
+
+Combine multiple decorators:
+
+```typescript
+import { applyDecorators } from '@nestjs/common';
+
+export function Auth(...roles: Role[]) {
+  return applyDecorators(
+    SetMetadata('roles', roles),
+    UseGuards(AuthGuard, RolesGuard),
+    ApiBearerAuth(),
+    ApiUnauthorizedResponse({ description: 'Unauthorized' }),
+  );
+}
+```
+
+Usage:
+
+```typescript
+@Get('users')
+@Auth('admin')
+findAllUsers() {}
+```
+
+## Key Points
+
+- Use `createParamDecorator()` to create custom decorators
+- Decorators receive `ExecutionContext` for accessing request/response
+- Pass data as second parameter to decorator factory
+- Custom decorators work with pipes
+- Use `applyDecorators()` to compose multiple decorators
+- TypeScript generics can enforce type safety
+
+<!--
+Source references:
+- https://docs.nestjs.com/custom-decorators
+-->