@biggora/claude-plugins 1.2.2 → 1.3.1

package/src/skills/nest-best-practices/references/recipes-cqrs.md

@@ -0,0 +1,176 @@
+---
+name: cqrs
+description: Command Query Responsibility Segregation pattern for complex applications
+---
+
+# CQRS
+
+Separate read and write operations for scalability and flexibility.
+
+## Installation
+
+```bash
+npm install @nestjs/cqrs
+```
+
+```typescript
+@Module({
+  imports: [CqrsModule.forRoot()],
+})
+export class AppModule {}
+```
+
+## Commands
+
+Commands change application state. Use `CommandBus` to dispatch.
+
+```typescript
+// kill-dragon.command.ts
+export class KillDragonCommand extends Command<{ actionId: string }> {
+  constructor(
+    public readonly heroId: string,
+    public readonly dragonId: string,
+  ) {
+    super();
+  }
+}
+
+// kill-dragon.handler.ts
+@CommandHandler(KillDragonCommand)
+export class KillDragonHandler implements ICommandHandler<KillDragonCommand> {
+  constructor(private repository: HeroesRepository) {}
+
+  async execute(command: KillDragonCommand) {
+    const { heroId, dragonId } = command;
+    const hero = await this.repository.findOneById(+heroId);
+    hero.killEnemy(dragonId);
+    await this.repository.persist(hero);
+    return { actionId: crypto.randomUUID() };
+  }
+}
+```
+
+```typescript
+// Usage
+await this.commandBus.execute(
+  new KillDragonCommand(heroId, killDragonDto.dragonId)
+);
+```
+
+## Queries
+
+```typescript
+export class GetHeroQuery extends Query<Hero> {
+  constructor(public readonly heroId: string) {
+    super();
+  }
+}
+
+@QueryHandler(GetHeroQuery)
+export class GetHeroHandler implements IQueryHandler<GetHeroQuery> {
+  constructor(private repository: HeroesRepository) {}
+
+  async execute(query: GetHeroQuery) {
+    return this.repository.findOneById(query.heroId);
+  }
+}
+```
+
+```typescript
+const hero = await this.queryBus.execute(new GetHeroQuery(heroId));
+```
+
+## Events
+
+```typescript
+export class HeroKilledDragonEvent {
+  constructor(
+    public readonly heroId: string,
+    public readonly dragonId: string,
+  ) {}
+}
+
+@EventsHandler(HeroKilledDragonEvent)
+export class HeroKilledDragonHandler implements IEventHandler<HeroKilledDragonEvent> {
+  handle(event: HeroKilledDragonEvent) {
+    // Update read model, send notifications, etc.
+  }
+}
+```
+
+Publish from model with `AggregateRoot`:
+
+```typescript
+export class Hero extends AggregateRoot {
+  killEnemy(enemyId: string) {
+    this.apply(new HeroKilledDragonEvent(this.id, enemyId));
+  }
+}
+```
+
+Requires `EventPublisher.mergeObjectContext()` and `hero.commit()`.
+
+Or publish manually:
+
+```typescript
+this.eventBus.publish(new HeroKilledDragonEvent(heroId, dragonId));
+```
+
+## Sagas
+
+Long-running processes that listen to events and dispatch commands.
+
+```typescript
+@Injectable()
+export class HeroesGameSagas {
+  @Saga()
+  dragonKilled = (events$: Observable<any>): Observable<ICommand> => {
+    return events$.pipe(
+      ofType(HeroKilledDragonEvent),
+      map((event) => new DropAncientItemCommand(event.heroId, fakeItemID)),
+    );
+  };
+}
+```
+
+Register saga as provider. `ofType` filters events; return command to dispatch.
+
+## Request-Scoped Handlers
+
+```typescript
+@CommandHandler(KillDragonCommand, { scope: Scope.REQUEST })
+export class KillDragonHandler {
+  constructor(@Inject(REQUEST) private request: MyRequest) {}
+}
+```
+
+Pass `AsyncContext` when executing:
+
+```typescript
+const myRequest = new MyRequest(user);
+await this.commandBus.execute(command, myRequest);
+```
+
+## Unhandled Exceptions
+
+Event handler errors don't reach Exception filters. Subscribe to `UnhandledExceptionBus`:
+
+```typescript
+this.unhandledExceptionsBus
+  .pipe(takeUntil(this.destroy$))
+  .subscribe((exceptionInfo) => {
+    // Handle exception
+  });
+```
+
+## Key Points
+
+- Commands: task-based, change state; Queries: data-centric, read state
+- Register all handlers/sagas as providers
+- Event handlers run asynchronously—no HTTP response
+- Use Redis-backed event store for production sagas
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/cqrs
+-->

package/src/skills/nest-best-practices/references/recipes-crud-generator.md

@@ -0,0 +1,87 @@
+---
+name: recipes-crud-generator
+description: Using Nest CLI to generate CRUD resources
+---
+
+# CRUD Generator
+
+Nest CLI provides a resource generator that automatically creates all boilerplate code for CRUD operations.
+
+## Generate Resource
+
+```bash
+nest g resource
+```
+
+The generator will prompt for:
+- Resource name
+- Transport layer (REST API, GraphQL, Microservice, WebSocket)
+- Whether to generate CRUD entry points
+
+## Generated Files
+
+For REST API, generates:
+- Module file (`users.module.ts`)
+- Controller file (`users.controller.ts`)
+- Service file (`users.service.ts`)
+- DTO files (`create-user.dto.ts`, `update-user.dto.ts`)
+- Entity file (`user.entity.ts`)
+- Test files (`.spec.ts`)
+
+## Generated Controller
+
+```typescript
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get()
+  findAll() {
+    return this.usersService.findAll();
+  }
+
+  @Get(':id')
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(+id);
+  }
+
+  @Patch(':id')
+  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
+    return this.usersService.update(+id, updateUserDto);
+  }
+
+  @Delete(':id')
+  remove(@Param('id') id: string) {
+    return this.usersService.remove(+id);
+  }
+}
+```
+
+## GraphQL Support
+
+For GraphQL applications, generates resolvers instead of controllers:
+
+```bash
+nest g resource users
+# Select: GraphQL (code first)
+# Select: Yes for CRUD entry points
+```
+
+## Key Points
+
+- Generates all CRUD boilerplate automatically
+- Supports REST, GraphQL, Microservices, and WebSockets
+- Service methods contain placeholders for implementation
+- Not tied to any specific ORM
+- Includes test files
+- Saves significant development time
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/crud-generator
+-->

package/src/skills/nest-best-practices/references/recipes-documentation.md

@@ -0,0 +1,93 @@
+---
+name: recipes-documentation
+description: OpenAPI/Swagger documentation setup in NestJS
+---
+
+# API Documentation
+
+NestJS provides integration with Swagger/OpenAPI for automatic API documentation generation.
+
+## Installation
+
+```bash
+npm install --save @nestjs/swagger
+```
+
+## Basic Setup
+
+```typescript
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const config = new DocumentBuilder()
+    .setTitle('Cats example')
+    .setDescription('The cats API description')
+    .setVersion('1.0')
+    .addTag('cats')
+    .build();
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, document);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## DTO Decorators
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  age: number;
+
+  @ApiProperty()
+  breed: string;
+}
+```
+
+## Controller Decorators
+
+```typescript
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+
+@ApiTags('cats')
+@Controller('cats')
+export class CatsController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new cat' })
+  @ApiResponse({ status: 201, description: 'The cat has been successfully created.' })
+  @ApiResponse({ status: 403, description: 'Forbidden.' })
+  create(@Body() createCatDto: CreateCatDto) {
+    return this.catsService.create(createCatDto);
+  }
+}
+```
+
+## Security
+
+```typescript
+const config = new DocumentBuilder()
+  .addBearerAuth()
+  .build();
+```
+
+## Key Points
+
+- Use `@nestjs/swagger` for OpenAPI integration
+- Decorate DTOs with `@ApiProperty()`
+- Use `@ApiTags()` to group endpoints
+- Add `@ApiOperation()` and `@ApiResponse()` for documentation
+- Configure security schemes for authentication
+- Access docs at `/api` endpoint
+
+<!--
+Source references:
+- https://docs.nestjs.com/openapi/introduction
+-->

package/src/skills/nest-best-practices/references/recipes-mongoose.md

@@ -0,0 +1,153 @@
+---
+name: mongoose
+description: MongoDB integration with Mongoose ODM
+---
+
+# Mongoose (MongoDB)
+
+Mongoose is the most popular MongoDB object modeling tool for Node.js.
+
+## Installation
+
+```bash
+npm i @nestjs/mongoose mongoose
+```
+
+## Setup
+
+```typescript
+@Module({
+  imports: [
+    MongooseModule.forRoot('mongodb://localhost/nest'),
+    // Or with options
+    MongooseModule.forRoot('mongodb://localhost/nest', {
+      connectionName: 'cats',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Schema Definition
+
+```typescript
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
+import { HydratedDocument } from 'mongoose';
+
+export type CatDocument = HydratedDocument<Cat>;
+
+@Schema()
+export class Cat {
+  @Prop()
+  name: string;
+
+  @Prop({ required: true })
+  age: number;
+
+  @Prop([String])
+  tags: string[];
+
+  @Prop({ default: Date.now })
+  createdAt: Date;
+
+  @Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' })
+  owner: Owner;
+}
+
+export const CatSchema = SchemaFactory.createForClass(Cat);
+```
+
+## Register Model
+
+```typescript
+@Module({
+  imports: [
+    MongooseModule.forFeature([
+      { name: Cat.name, schema: CatSchema },
+    ]),
+  ],
+})
+export class CatsModule {}
+```
+
+## Inject and Use
+
+```typescript
+@Injectable()
+export class CatsService {
+  constructor(
+    @InjectModel(Cat.name) private catModel: Model<CatDocument>,
+  ) {}
+
+  async create(createCatDto: CreateCatDto) {
+    const created = new this.catModel(createCatDto);
+    return created.save();
+  }
+
+  async findAll(): Promise<Cat[]> {
+    return this.catModel.find().exec();
+  }
+
+  async findOne(id: string) {
+    return this.catModel.findById(id).populate('owner').exec();
+  }
+}
+```
+
+## @Prop Options
+
+| Option | Description |
+|--------|-------------|
+| `required` | Required field |
+| `default` | Default value |
+| `unique` | Unique index |
+| `index` | Create index |
+| `type` | Explicit type (e.g., `mongoose.Schema.Types.ObjectId`) |
+| `ref` | Reference to another model |
+
+## Relations (Population)
+
+```typescript
+@Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' })
+owner: Owner;
+
+// Multiple
+@Prop({ type: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' }] })
+owners: Owner[];
+```
+
+```typescript
+return this.catModel.find().populate('owner').exec();
+return this.catModel.find().populate({ path: 'owner', select: 'name' }).exec();
+```
+
+## Plugins
+
+```typescript
+CatSchema.plugin(require('mongoose-autopopulate'));
+```
+
+## Async Configuration
+
+```typescript
+MongooseModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    uri: config.get('MONGODB_URI'),
+  }),
+  inject: [ConfigService],
+}),
+```
+
+## Key Points
+
+- Use `@Schema()` and `@Prop()` decorators
+- `SchemaFactory.createForClass()` generates schema
+- `@InjectModel()` injects Model
+- Use `populate()` for relations
+- `HydratedDocument<Cat>` for typed documents
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/mongodb
+-->

package/src/skills/nest-best-practices/references/recipes-prisma.md

@@ -0,0 +1,98 @@
+---
+name: recipes-prisma
+description: Prisma ORM integration in NestJS
+---
+
+# Prisma Integration
+
+Prisma is a next-generation ORM that provides type-safe database access.
+
+## Installation
+
+```bash
+npm install --save @prisma/client
+npm install --save-dev prisma
+npx prisma init
+```
+
+## Prisma Service
+
+```typescript
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit {
+  async onModuleInit() {
+    await this.$connect();
+  }
+}
+```
+
+## Module Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}
+```
+
+## Using Prisma Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+@Injectable()
+export class UsersService {
+  constructor(private prisma: PrismaService) {}
+
+  async findAll() {
+    return this.prisma.user.findMany();
+  }
+
+  async findOne(id: number) {
+    return this.prisma.user.findUnique({
+      where: { id },
+    });
+  }
+
+  async create(data: CreateUserDto) {
+    return this.prisma.user.create({
+      data,
+    });
+  }
+
+  async update(id: number, data: UpdateUserDto) {
+    return this.prisma.user.update({
+      where: { id },
+      data,
+    });
+  }
+
+  async remove(id: number) {
+    return this.prisma.user.delete({
+      where: { id },
+    });
+  }
+}
+```
+
+## Key Points
+
+- Prisma provides type-safe database access
+- Extend `PrismaClient` for service
+- Use `$connect()` in `onModuleInit()`
+- Prisma generates types from schema
+- Use Prisma Studio for database management
+- Supports migrations and seeding
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/prisma
+-->