@biggora/claude-plugins 1.2.2 → 1.3.1

package/src/skills/nest-best-practices/references/graphql-scalars-unions-enums.md

@@ -0,0 +1,180 @@
+---
+name: graphql-scalars-unions-enums
+description: GraphQL custom scalars, interfaces, union types, and enums
+---
+
+# GraphQL Scalars, Interfaces, Unions & Enums
+
+## Interfaces
+
+```typescript
+import { Field, ID, InterfaceType } from '@nestjs/graphql';
+
+@InterfaceType()
+export abstract class Character {
+  @Field(() => ID)
+  id: string;
+
+  @Field()
+  name: string;
+}
+```
+
+Implement interface:
+
+```typescript
+@ObjectType({ implements: () => [Character] })
+export class Human implements Character {
+  id: string;
+  name: string;
+}
+```
+
+Custom `resolveType`:
+
+```typescript
+@InterfaceType({
+  resolveType(book) {
+    if (book.colors) return ColoringBook;
+    return TextBook;
+  },
+})
+export abstract class Book { ... }
+```
+
+Interface resolver (shared field resolvers):
+
+```typescript
+@Resolver(() => Character)
+export class CharacterInterfaceResolver {
+  @ResolveField(() => [Character])
+  friends(@Parent() character) {
+    return this.getFriends(character);
+  }
+}
+```
+
+## Scalars, Unions & Enums
+
+## Built-in Scalars
+
+- `ID`, `Int`, `Float`, `String`, `Boolean`
+- `GraphQLISODateTime` (default for Date)
+- `GraphQLTimestamp` (Date as epoch ms)
+
+```typescript
+GraphQLModule.forRoot({
+  buildSchemaOptions: {
+    dateScalarMode: 'timestamp',  // Use GraphQLTimestamp for Date
+    numberScalarMode: 'integer',  // Use Int for number
+  },
+}),
+```
+
+## Custom Scalar
+
+```typescript
+import { Scalar, CustomScalar } from '@nestjs/graphql';
+import { Kind, ValueNode } from 'graphql';
+
+@Scalar('Date', () => Date)
+export class DateScalar implements CustomScalar<number, Date> {
+  description = 'Date custom scalar';
+
+  parseValue(value: number): Date {
+    return new Date(value);
+  }
+
+  serialize(value: Date): number {
+    return value.getTime();
+  }
+
+  parseLiteral(ast: ValueNode): Date {
+    if (ast.kind === Kind.INT) return new Date(ast.value);
+    return null;
+  }
+}
+```
+
+Register as provider. Use: `@Field(() => Date) creationDate: Date;`
+
+## Import Scalar (e.g., JSON)
+
+```bash
+npm i graphql-type-json
+```
+
+```typescript
+import GraphQLJSON from 'graphql-type-json';
+
+GraphQLModule.forRoot({
+  resolvers: { JSON: GraphQLJSON },
+}),
+```
+
+## Union Types
+
+```typescript
+import { createUnionType } from '@nestjs/graphql';
+
+export const ResultUnion = createUnionType({
+  name: 'ResultUnion',
+  types: () => [Author, Book] as const,
+  resolveType(value) {
+    if (value.name) return Author;
+    if (value.title) return Book;
+    return null;
+  },
+});
+
+@Query(() => [ResultUnion])
+search(): Array<typeof ResultUnion> {
+  return [new Author(), new Book()];
+}
+```
+
+Return class instances for default `resolveType`. Schema first: add `__resolveType` resolver.
+
+## Enums
+
+```typescript
+import { registerEnumType } from '@nestjs/graphql';
+
+export enum AllowedColor {
+  RED,
+  GREEN,
+  BLUE,
+}
+
+registerEnumType(AllowedColor, {
+  name: 'AllowedColor',
+  description: 'Supported colors',
+  valuesMap: {
+    RED: { description: 'Default color' },
+    BLUE: { deprecationReason: 'Too blue' },
+  },
+});
+```
+
+```typescript
+@Field(() => AllowedColor)
+favoriteColor: AllowedColor;
+```
+
+Schema first: define in SDL; use `resolvers` for internal value mapping.
+
+## Key Points
+
+- Use abstract class with `@InterfaceType()` (not TypeScript interface)
+- `implements: () => [Character]` for ObjectType implementing interface
+- Use `as const` for union types array
+- Custom scalars need `parseValue`, `serialize`, `parseLiteral`
+- `graphql-scalars` package for common scalars (UUID, Email, etc.)
+- Enum internal values: use resolver object in schema-first
+
+<!--
+Source references:
+- https://docs.nestjs.com/graphql/interfaces
+- https://docs.nestjs.com/graphql/scalars
+- https://docs.nestjs.com/graphql/unions-and-enums
+-->

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