@biggora/claude-plugins 1.2.2 → 1.3.0

package/src/skills/nest-best-practices/references/graphql-subscriptions.md

@@ -0,0 +1,228 @@
+---
+name: graphql-subscriptions
+description: Real-time GraphQL subscriptions with PubSub
+---
+
+# GraphQL Subscriptions
+
+Subscriptions enable real-time server-to-client communication.
+
+## Enable Subscriptions (Apollo)
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  subscriptions: {
+    'graphql-ws': true,
+  },
+}),
+```
+
+## Basic Subscription
+
+```typescript
+import { Resolver, Mutation, Subscription } from '@nestjs/graphql';
+import { PubSub } from 'graphql-subscriptions';
+
+const pubSub = new PubSub();
+
+@Resolver(() => Comment)
+export class CommentsResolver {
+  @Subscription(() => Comment)
+  commentAdded() {
+    return pubSub.asyncIterableIterator('commentAdded');
+  }
+
+  @Mutation(() => Comment)
+  async addComment(@Args('input') input: CreateCommentInput) {
+    const comment = await this.commentsService.create(input);
+    
+    // Publish event
+    pubSub.publish('commentAdded', { commentAdded: comment });
+    
+    return comment;
+  }
+}
+```
+
+## Filtering Events
+
+```typescript
+@Subscription(() => Comment, {
+  filter: (payload, variables) =>
+    payload.commentAdded.postId === variables.postId,
+})
+commentAdded(@Args('postId') postId: string) {
+  return pubSub.asyncIterableIterator('commentAdded');
+}
+```
+
+## Transforming Payload
+
+```typescript
+@Subscription(() => Comment, {
+  resolve: (payload) => payload.commentAdded,
+})
+commentAdded() {
+  return pubSub.asyncIterableIterator('commentAdded');
+}
+```
+
+## Named Subscription
+
+```typescript
+@Subscription(() => Comment, {
+  name: 'commentAdded',
+})
+subscribeToCommentAdded() {
+  return pubSub.asyncIterableIterator('commentAdded');
+}
+```
+
+## PubSub as Provider
+
+Inject PubSub instead of global instance:
+
+```typescript
+// pubsub.module.ts
+@Module({
+  providers: [
+    {
+      provide: 'PUB_SUB',
+      useValue: new PubSub(),
+    },
+  ],
+  exports: ['PUB_SUB'],
+})
+export class PubSubModule {}
+
+// resolver
+@Resolver()
+export class CommentsResolver {
+  constructor(@Inject('PUB_SUB') private pubSub: PubSub) {}
+
+  @Subscription(() => Comment)
+  commentAdded() {
+    return this.pubSub.asyncIterableIterator('commentAdded');
+  }
+}
+```
+
+## Production PubSub
+
+The default `PubSub` is not for production. Use Redis-backed implementation:
+
+```bash
+npm install graphql-redis-subscriptions ioredis
+```
+
+```typescript
+import { RedisPubSub } from 'graphql-redis-subscriptions';
+import Redis from 'ioredis';
+
+const options = {
+  host: 'localhost',
+  port: 6379,
+};
+
+{
+  provide: 'PUB_SUB',
+  useFactory: () => new RedisPubSub({
+    publisher: new Redis(options),
+    subscriber: new Redis(options),
+  }),
+}
+```
+
+## WebSocket Authentication
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  subscriptions: {
+    'graphql-ws': {
+      onConnect: (context) => {
+        const { connectionParams, extra } = context;
+        const token = connectionParams.authToken;
+        
+        if (!isValidToken(token)) {
+          throw new Error('Invalid token');
+        }
+        
+        extra.user = decodeToken(token);
+      },
+    },
+  },
+  context: ({ extra }) => ({
+    user: extra?.user,
+  }),
+}),
+```
+
+## Mercurius Subscriptions
+
+```typescript
+GraphQLModule.forRoot<MercuriusDriverConfig>({
+  driver: MercuriusDriver,
+  subscription: true,
+}),
+```
+
+```typescript
+@Subscription(() => Comment)
+commentAdded(@Context('pubsub') pubSub: PubSub) {
+  return pubSub.subscribe('commentAdded');
+}
+
+@Mutation(() => Comment)
+async addComment(
+  @Args('input') input: CreateCommentInput,
+  @Context('pubsub') pubSub: PubSub,
+) {
+  const comment = await this.commentsService.create(input);
+  
+  await pubSub.publish({
+    topic: 'commentAdded',
+    payload: { commentAdded: comment },
+  });
+  
+  return comment;
+}
+```
+
+## Client-Side
+
+```javascript
+import { createClient } from 'graphql-ws';
+
+const client = createClient({
+  url: 'ws://localhost:3000/graphql',
+  connectionParams: {
+    authToken: 'Bearer xxx',
+  },
+});
+
+client.subscribe(
+  {
+    query: `subscription { commentAdded { id content } }`,
+  },
+  {
+    next: (data) => console.log(data),
+    error: (error) => console.error(error),
+    complete: () => console.log('done'),
+  },
+);
+```
+
+## Key Points
+
+- Use `graphql-ws` instead of deprecated `subscriptions-transport-ws`
+- Payload shape must match subscription return type
+- Use Redis-backed PubSub for production (multi-instance support)
+- `filter` function determines which clients receive events
+- `resolve` function transforms the payload before sending
+
+<!--
+Source references:
+- https://docs.nestjs.com/graphql/subscriptions
+-->

package/src/skills/nest-best-practices/references/microservices-grpc.md

@@ -0,0 +1,175 @@
+---
+name: microservices-grpc
+description: gRPC microservices with Protocol Buffers
+---
+
+# gRPC Microservices
+
+High-performance RPC framework using Protocol Buffers.
+
+## Installation
+
+```bash
+npm i @grpc/grpc-js @grpc/proto-loader
+```
+
+## Server Setup
+
+```typescript
+const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
+  transport: Transport.GRPC,
+  options: {
+    package: 'hero',
+    protoPath: join(__dirname, 'hero/hero.proto'),
+    url: '0.0.0.0:50051',
+  },
+});
+```
+
+## Proto Definition
+
+```protobuf
+// hero.proto
+syntax = "proto3";
+
+package hero;
+
+service HeroesService {
+  rpc FindOne (HeroById) returns (Hero) {}
+}
+
+message HeroById {
+  int32 id = 1;
+}
+
+message Hero {
+  int32 id = 1;
+  string name = 2;
+}
+```
+
+## nest-cli.json (Copy Proto Files)
+
+```json
+{
+  "compilerOptions": {
+    "assets": ["**/*.proto"],
+    "watchAssets": true
+  }
+}
+```
+
+## Controller
+
+```typescript
+@Controller()
+export class HeroesController {
+  @GrpcMethod('HeroesService', 'FindOne')
+  findOne(data: HeroById, metadata: Metadata, call: ServerUnaryCall<any, any>): Hero {
+    return this.items.find(({ id }) => id === data.id);
+  }
+}
+```
+
+Omit decorator args for auto-binding: `@GrpcMethod()` uses class/method name.
+
+## Client
+
+```typescript
+ClientsModule.register([
+  {
+    name: 'HERO_PACKAGE',
+    transport: Transport.GRPC,
+    options: {
+      package: 'hero',
+      protoPath: join(__dirname, 'hero/hero.proto'),
+    },
+  },
+]),
+```
+
+```typescript
+@Injectable()
+export class AppService implements OnModuleInit {
+  private heroesService: HeroesService;
+
+  constructor(@Inject('HERO_PACKAGE') private client: ClientGrpc) {}
+
+  onModuleInit() {
+    this.heroesService = this.client.getService<HeroesService>('HeroesService');
+  }
+
+  getHero() {
+    return this.heroesService.findOne({ id: 1 });
+  }
+}
+```
+
+## gRPC Metadata
+
+```typescript
+// Send
+const metadata = new Metadata();
+metadata.add('Set-Cookie', 'yummy_cookie=choco');
+return this.heroesService.findOne({ id: 1 }, metadata);
+
+// Receive and respond
+findOne(data, metadata: Metadata, call: ServerUnaryCall<any, any>) {
+  const serverMetadata = new Metadata();
+  serverMetadata.add('Set-Cookie', 'choco');
+  call.sendMetadata(serverMetadata);
+  return hero;
+}
+```
+
+## Streaming
+
+Use `@GrpcStreamMethod()` for duplex streams:
+
+```typescript
+@GrpcStreamMethod()
+bidiHello(messages: Observable<any>, metadata, call): Observable<any> {
+  return messages.pipe(
+    map((msg) => ({ reply: `Hello, ${msg.greeting}!` })),
+  );
+}
+```
+
+Or `@GrpcStreamCall()` for raw stream access:
+
+```typescript
+@GrpcStreamCall()
+bidiHello(requestStream: any) {
+  requestStream.on('data', (msg) => {
+    requestStream.write({ reply: 'Hello!' });
+  });
+}
+```
+
+## gRPC Reflection
+
+```bash
+npm i @grpc/reflection
+```
+
+```typescript
+import { ReflectionService } from '@grpc/reflection';
+
+options: {
+  onLoadPackageDefinition: (pkg, server) => {
+    new ReflectionService(pkg).addToServer(server);
+  },
+},
+```
+
+## Key Points
+
+- Use `ClientGrpc.getService()` not `ClientProxy`
+- Methods are lowerCamelCase in TypeScript
+- Set `loader.keepCase: true` for underscore field names
+- Streaming handlers must return `Observable` for full-duplex
+
+<!--
+Source references:
+- https://docs.nestjs.com/microservices/grpc
+-->

package/src/skills/nest-best-practices/references/microservices-overview.md

@@ -0,0 +1,221 @@
+---
+name: microservices
+description: Building microservices with various transport layers
+---
+
+# Microservices
+
+NestJS supports microservice architecture with multiple transport protocols.
+
+## Installation
+
+```bash
+npm install @nestjs/microservices
+```
+
+## Available Transporters
+
+| Transport | Package |
+|-----------|---------|
+| TCP | Built-in |
+| Redis | `redis` |
+| MQTT | `mqtt` |
+| NATS | `nats` |
+| RabbitMQ | `amqplib` |
+| Kafka | `kafkajs` |
+| gRPC | `@grpc/grpc-js` |
+
+## Creating a Microservice
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { Transport, MicroserviceOptions } from '@nestjs/microservices';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
+    AppModule,
+    {
+      transport: Transport.TCP,
+      options: { host: 'localhost', port: 3001 },
+    },
+  );
+  await app.listen();
+}
+bootstrap();
+```
+
+## Hybrid Application
+
+Combine HTTP and microservice:
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.connectMicroservice<MicroserviceOptions>({
+  transport: Transport.TCP,
+  options: { port: 3001 },
+});
+await app.startAllMicroservices();
+await app.listen(3000);
+```
+
+## Request-Response Pattern
+
+### Handler (Microservice)
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { MessagePattern, Payload } from '@nestjs/microservices';
+
+@Controller()
+export class MathController {
+  @MessagePattern({ cmd: 'sum' })
+  sum(@Payload() data: number[]): number {
+    return data.reduce((a, b) => a + b, 0);
+  }
+}
+```
+
+### Client (Producer)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ClientsModule, Transport } from '@nestjs/microservices';
+
+@Module({
+  imports: [
+    ClientsModule.register([
+      {
+        name: 'MATH_SERVICE',
+        transport: Transport.TCP,
+        options: { host: 'localhost', port: 3001 },
+      },
+    ]),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { ClientProxy } from '@nestjs/microservices';
+import { firstValueFrom } from 'rxjs';
+
+@Injectable()
+export class AppService {
+  constructor(@Inject('MATH_SERVICE') private client: ClientProxy) {}
+
+  async calculate(): Promise<number> {
+    const pattern = { cmd: 'sum' };
+    const payload = [1, 2, 3, 4, 5];
+    return firstValueFrom(this.client.send<number>(pattern, payload));
+  }
+}
+```
+
+## Event-Based Pattern
+
+### Handler
+
+```typescript
+@EventPattern('user_created')
+async handleUserCreated(@Payload() data: CreateUserEvent) {
+  await this.usersService.processNewUser(data);
+}
+```
+
+### Emitter
+
+```typescript
+async createUser(dto: CreateUserDto) {
+  const user = await this.usersRepository.create(dto);
+  this.client.emit('user_created', new CreateUserEvent(user));
+  return user;
+}
+```
+
+## Accessing Context
+
+```typescript
+import { Ctx, Payload, NatsContext } from '@nestjs/microservices';
+
+@MessagePattern('time.us.*')
+getDate(@Payload() data: any, @Ctx() context: NatsContext) {
+  console.log(`Subject: ${context.getSubject()}`);
+  return new Date().toISOString();
+}
+```
+
+## Async Configuration
+
+```typescript
+ClientsModule.registerAsync([
+  {
+    name: 'MATH_SERVICE',
+    imports: [ConfigModule],
+    useFactory: async (configService: ConfigService) => ({
+      transport: Transport.TCP,
+      options: {
+        host: configService.get('MATH_HOST'),
+        port: configService.get('MATH_PORT'),
+      },
+    }),
+    inject: [ConfigService],
+  },
+]);
+```
+
+## Timeout Handling
+
+```typescript
+import { timeout } from 'rxjs/operators';
+
+this.client
+  .send<number>({ cmd: 'sum' }, [1, 2, 3])
+  .pipe(timeout(5000));
+```
+
+## TLS Support
+
+```typescript
+// Server
+const app = await NestFactory.createMicroservice<MicroserviceOptions>(
+  AppModule,
+  {
+    transport: Transport.TCP,
+    options: {
+      tlsOptions: {
+        key: fs.readFileSync('key.pem'),
+        cert: fs.readFileSync('cert.pem'),
+      },
+    },
+  },
+);
+
+// Client
+ClientsModule.register([
+  {
+    name: 'SERVICE',
+    transport: Transport.TCP,
+    options: {
+      tlsOptions: {
+        ca: [fs.readFileSync('ca.pem')],
+      },
+    },
+  },
+]);
+```
+
+## Key Points
+
+- `@MessagePattern()` for request-response (requires reply)
+- `@EventPattern()` for fire-and-forget events
+- Client connection is lazy (connects on first call)
+- Use `firstValueFrom` to convert Observable to Promise
+- TCP is the default transport
+
+<!--
+Source references:
+- https://docs.nestjs.com/microservices/basics
+-->