@biggora/claude-plugins 1.2.2 → 1.3.0

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

@@ -0,0 +1,233 @@
+---
+name: graphql
+description: Building GraphQL APIs with code-first and schema-first approaches
+---
+
+# GraphQL
+
+NestJS provides GraphQL integration through Apollo Server or Mercurius.
+
+## Installation
+
+```bash
+# Apollo (default)
+npm install @nestjs/graphql @nestjs/apollo @apollo/server @as-integrations/express5 graphql
+
+# Mercurius (Fastify)
+npm install @nestjs/graphql @nestjs/mercurius graphql mercurius
+```
+
+## Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { GraphQLModule } from '@nestjs/graphql';
+import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
+import { join } from 'path';
+
+@Module({
+  imports: [
+    GraphQLModule.forRoot<ApolloDriverConfig>({
+      driver: ApolloDriver,
+      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
+      // Or in-memory: autoSchemaFile: true
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Code-First Approach
+
+### Object Type
+
+```typescript
+import { ObjectType, Field, ID, Int } from '@nestjs/graphql';
+
+@ObjectType()
+export class Author {
+  @Field(() => ID)
+  id: string;
+
+  @Field()
+  name: string;
+
+  @Field(() => Int, { nullable: true })
+  age?: number;
+
+  @Field(() => [Post])
+  posts: Post[];
+}
+```
+
+### Resolver
+
+```typescript
+import { Resolver, Query, Mutation, Args, ID } from '@nestjs/graphql';
+
+@Resolver(() => Author)
+export class AuthorsResolver {
+  constructor(private authorsService: AuthorsService) {}
+
+  @Query(() => [Author], { name: 'authors' })
+  findAll() {
+    return this.authorsService.findAll();
+  }
+
+  @Query(() => Author, { name: 'author' })
+  findOne(@Args('id', { type: () => ID }) id: string) {
+    return this.authorsService.findOne(id);
+  }
+
+  @Mutation(() => Author)
+  createAuthor(@Args('input') input: CreateAuthorInput) {
+    return this.authorsService.create(input);
+  }
+}
+```
+
+### Input Type
+
+```typescript
+import { InputType, Field } from '@nestjs/graphql';
+
+@InputType()
+export class CreateAuthorInput {
+  @Field()
+  name: string;
+
+  @Field({ nullable: true })
+  bio?: string;
+}
+```
+
+## Schema-First Approach
+
+### GraphQL Schema
+
+```graphql
+# authors.graphql
+type Author {
+  id: ID!
+  name: String!
+  posts: [Post!]!
+}
+
+type Query {
+  authors: [Author!]!
+  author(id: ID!): Author
+}
+```
+
+### Configuration
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  typePaths: ['./**/*.graphql'],
+  definitions: {
+    path: join(process.cwd(), 'src/graphql.ts'),
+    outputAs: 'class',
+  },
+}),
+```
+
+### Resolver
+
+```typescript
+@Resolver('Author')
+export class AuthorsResolver {
+  @Query('authors')
+  findAll() {
+    return this.authorsService.findAll();
+  }
+
+  @Query('author')
+  findOne(@Args('id') id: string) {
+    return this.authorsService.findOne(id);
+  }
+}
+```
+
+## Subscriptions
+
+```typescript
+import { Subscription, Resolver } from '@nestjs/graphql';
+import { PubSub } from 'graphql-subscriptions';
+
+const pubSub = new PubSub();
+
+@Resolver()
+export class AuthorsResolver {
+  @Mutation(() => Author)
+  async createAuthor(@Args('input') input: CreateAuthorInput) {
+    const author = await this.authorsService.create(input);
+    pubSub.publish('authorCreated', { authorCreated: author });
+    return author;
+  }
+
+  @Subscription(() => Author)
+  authorCreated() {
+    return pubSub.asyncIterableIterator('authorCreated');
+  }
+}
+```
+
+## Field Resolvers
+
+```typescript
+@Resolver(() => Author)
+export class AuthorsResolver {
+  @ResolveField(() => [Post])
+  posts(@Parent() author: Author) {
+    return this.postsService.findByAuthorId(author.id);
+  }
+}
+```
+
+## Guards and Interceptors
+
+```typescript
+@Query(() => Author)
+@UseGuards(GqlAuthGuard)
+whoAmI(@CurrentUser() user: User) {
+  return user;
+}
+```
+
+## Context
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  autoSchemaFile: true,
+  context: ({ req, res }) => ({ req, res }),
+}),
+```
+
+## Async Configuration
+
+```typescript
+GraphQLModule.forRootAsync<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    autoSchemaFile: true,
+    playground: configService.get('NODE_ENV') !== 'production',
+  }),
+  inject: [ConfigService],
+}),
+```
+
+## Key Points
+
+- **Code-first**: TypeScript classes generate GraphQL schema
+- **Schema-first**: SDL files generate TypeScript types
+- Use `autoSchemaFile` for code-first
+- Use `typePaths` for schema-first
+- Resolvers must be registered as providers
+
+<!--
+Source references:
+- https://docs.nestjs.com/graphql/quick-start
+-->

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

@@ -0,0 +1,199 @@
+---
+name: graphql-resolvers-mutations
+description: GraphQL resolvers, mutations, and field resolvers
+---
+
+# GraphQL Resolvers & Mutations
+
+## Object Types (Code First)
+
+```typescript
+import { ObjectType, Field, ID, Int } from '@nestjs/graphql';
+
+@ObjectType()
+export class Author {
+  @Field(() => ID)
+  id: string;
+
+  @Field()
+  name: string;
+
+  @Field(() => Int, { nullable: true })
+  age?: number;
+
+  @Field(() => [Post])
+  posts: Post[];
+}
+```
+
+## Resolver
+
+```typescript
+import { Resolver, Query, Mutation, Args, ResolveField, Parent, ID } from '@nestjs/graphql';
+
+@Resolver(() => Author)
+export class AuthorsResolver {
+  constructor(
+    private authorsService: AuthorsService,
+    private postsService: PostsService,
+  ) {}
+
+  @Query(() => [Author], { name: 'authors' })
+  findAll() {
+    return this.authorsService.findAll();
+  }
+
+  @Query(() => Author, { nullable: true })
+  findOne(@Args('id', { type: () => ID }) id: string) {
+    return this.authorsService.findOne(id);
+  }
+
+  @ResolveField(() => [Post])
+  posts(@Parent() author: Author) {
+    return this.postsService.findByAuthorId(author.id);
+  }
+}
+```
+
+## Mutations
+
+```typescript
+import { InputType, Field, ArgsType } from '@nestjs/graphql';
+
+@InputType()
+export class CreateAuthorInput {
+  @Field()
+  name: string;
+
+  @Field({ nullable: true })
+  bio?: string;
+}
+
+@Resolver(() => Author)
+export class AuthorsResolver {
+  @Mutation(() => Author)
+  createAuthor(@Args('input') input: CreateAuthorInput) {
+    return this.authorsService.create(input);
+  }
+
+  @Mutation(() => Author)
+  updateAuthor(
+    @Args('id', { type: () => ID }) id: string,
+    @Args('input') input: UpdateAuthorInput,
+  ) {
+    return this.authorsService.update(id, input);
+  }
+
+  @Mutation(() => Boolean)
+  deleteAuthor(@Args('id', { type: () => ID }) id: string) {
+    return this.authorsService.delete(id);
+  }
+}
+```
+
+## Args Class
+
+```typescript
+@ArgsType()
+class GetAuthorsArgs {
+  @Field(() => Int, { defaultValue: 0 })
+  offset: number;
+
+  @Field(() => Int, { defaultValue: 10 })
+  limit: number;
+
+  @Field({ nullable: true })
+  search?: string;
+}
+
+@Query(() => [Author])
+authors(@Args() args: GetAuthorsArgs) {
+  return this.authorsService.findAll(args);
+}
+```
+
+## Field Options
+
+```typescript
+@Field(() => String, {
+  description: 'The author name',
+  deprecationReason: 'Use fullName instead',
+  nullable: true,
+})
+name?: string;
+```
+
+## Nullable Arrays
+
+```typescript
+// Array itself is nullable
+@Field(() => [Post], { nullable: true })
+posts?: Post[];
+
+// Array items are nullable
+@Field(() => [Post], { nullable: 'items' })
+posts: (Post | null)[];
+
+// Both nullable
+@Field(() => [Post], { nullable: 'itemsAndList' })
+posts?: (Post | null)[];
+```
+
+## GraphQL Decorators
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@ObjectType()` | Define GraphQL type |
+| `@Field()` | Define field |
+| `@InputType()` | Define input type |
+| `@ArgsType()` | Define args class |
+| `@Resolver()` | Define resolver |
+| `@Query()` | Define query |
+| `@Mutation()` | Define mutation |
+| `@ResolveField()` | Define field resolver |
+| `@Parent()` | Access parent object |
+| `@Args()` | Access arguments |
+| `@Context()` | Access context |
+
+## Query Options
+
+```typescript
+@Query(() => Author, {
+  name: 'author',           // GraphQL query name
+  description: 'Get author by ID',
+  nullable: true,           // Can return null
+  deprecationReason: 'Use findAuthor instead',
+})
+async getAuthor(@Args('id', { type: () => ID }) id: string) {}
+```
+
+## Context Access
+
+```typescript
+@Query(() => Author)
+whoAmI(@Context() context: any) {
+  return context.req.user;
+}
+
+// Or extract specific property
+@Query(() => Author)
+whoAmI(@Context('req') req: Request) {
+  return req.user;
+}
+```
+
+## Using Guards
+
+```typescript
+@Query(() => Author)
+@UseGuards(GqlAuthGuard)
+whoAmI(@Context() context: any) {
+  return context.req.user;
+}
+```
+
+<!--
+Source references:
+- https://docs.nestjs.com/graphql/resolvers-map
+- https://docs.nestjs.com/graphql/mutations
+-->

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