@biggora/claude-plugins 1.2.2 → 1.3.1

package/src/skills/nest-best-practices/references/fundamentals-provider-scopes.md

@@ -0,0 +1,92 @@
+---
+name: fundamentals-provider-scopes
+description: Provider scopes in NestJS (singleton, request, transient)
+---
+
+# Provider Scopes
+
+Providers can have different lifetimes (scopes) that determine how instances are created and shared.
+
+## Scope Types
+
+- `DEFAULT` - Singleton, shared across entire application
+- `REQUEST` - New instance per request
+- `TRANSIENT` - New instance per consumer
+
+## Default Scope (Singleton)
+
+```typescript
+@Injectable()
+export class CatsService {}
+```
+
+Singleton is the default and recommended scope.
+
+## Request Scope
+
+```typescript
+import { Injectable, Scope } from '@nestjs/common';
+
+@Injectable({ scope: Scope.REQUEST })
+export class CatsService {}
+```
+
+## Transient Scope
+
+```typescript
+@Injectable({ scope: Scope.TRANSIENT })
+export class LoggerService {}
+```
+
+## Custom Provider Scopes
+
+```typescript
+{
+  provide: 'CACHE_MANAGER',
+  useClass: CacheManager,
+  scope: Scope.TRANSIENT,
+}
+```
+
+## Controller Scope
+
+```typescript
+@Controller({
+  path: 'cats',
+  scope: Scope.REQUEST,
+})
+export class CatsController {}
+```
+
+## Accessing Request Object
+
+Inject `REQUEST` to access request in request-scoped providers:
+
+```typescript
+import { Injectable, Scope, Inject } from '@nestjs/common';
+import { REQUEST } from '@nestjs/core';
+import { Request } from 'express';
+
+@Injectable({ scope: Scope.REQUEST })
+export class CatsService {
+  constructor(@Inject(REQUEST) private request: Request) {}
+}
+```
+
+## Scope Hierarchy
+
+Request scope bubbles up the injection chain. If a controller depends on a request-scoped provider, the controller becomes request-scoped.
+
+## Key Points
+
+- Singleton scope is default and recommended
+- Request scope creates new instance per request
+- Transient scope creates new instance per consumer
+- Request scope propagates up dependency chain
+- Use `REQUEST` token to access request object
+- WebSocket gateways should not use request-scoped providers
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/injection-scopes
+-->

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

@@ -0,0 +1,142 @@
+---
+name: testing
+description: Unit testing and e2e testing in NestJS with @nestjs/testing
+---
+
+# Testing
+
+NestJS provides utilities for unit and end-to-end testing, with built-in Jest and Supertest integration.
+
+## Installation
+
+```bash
+npm i --save-dev @nestjs/testing
+```
+
+## Unit Testing
+
+### Basic Test Setup
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { CatsController } from './cats.controller';
+import { CatsService } from './cats.service';
+
+describe('CatsController', () => {
+  let controller: CatsController;
+  let service: CatsService;
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [CatsController],
+      providers: [CatsService],
+    }).compile();
+
+    service = moduleRef.get(CatsService);
+    controller = moduleRef.get(CatsController);
+  });
+
+  it('should return cats', async () => {
+    const result = ['cat'];
+    jest.spyOn(service, 'findAll').mockImplementation(() => result);
+    expect(await controller.findAll()).toBe(result);
+  });
+});
+```
+
+### Auto Mocking
+
+Use `useMocker()` to automatically mock dependencies:
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  controllers: [CatsController],
+})
+  .useMocker((token) => {
+    if (token === CatsService) {
+      return { findAll: jest.fn().mockResolvedValue(['cat']) };
+    }
+  })
+  .compile();
+```
+
+### Overriding Providers
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  imports: [CatsModule],
+})
+  .overrideProvider(CatsService)
+  .useValue(mockCatsService)
+  .compile();
+```
+
+## End-to-End Testing
+
+```typescript
+import * as request from 'supertest';
+import { Test } from '@nestjs/testing';
+import { CatsModule } from '../src/cats/cats.module';
+import { INestApplication } from '@nestjs/common';
+
+describe('Cats', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [CatsModule],
+    })
+      .overrideProvider(CatsService)
+      .useValue({ findAll: () => ['test'] })
+      .compile();
+
+    app = moduleRef.createNestApplication();
+    await app.init();
+  });
+
+  it('/GET cats', () => {
+    return request(app.getHttpServer())
+      .get('/cats')
+      .expect(200)
+      .expect({ data: ['test'] });
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+});
+```
+
+## Testing Scoped Providers
+
+```typescript
+const contextId = ContextIdFactory.create();
+jest.spyOn(ContextIdFactory, 'getByRequest').mockImplementation(() => contextId);
+
+const service = await moduleRef.resolve(CatsService, contextId);
+```
+
+## Override Methods
+
+| Method | Purpose |
+|--------|---------|
+| `overrideProvider()` | Override a provider |
+| `overrideModule()` | Override a module |
+| `overrideGuard()` | Override a guard |
+| `overrideInterceptor()` | Override an interceptor |
+| `overrideFilter()` | Override an exception filter |
+| `overridePipe()` | Override a pipe |
+
+Each returns an object with `useClass`, `useValue`, or `useFactory`.
+
+## Key Points
+
+- Keep test files near source files with `.spec.ts` or `.test.ts` suffix
+- E2E tests go in `test/` directory with `.e2e-spec.ts` suffix
+- `compile()` is async and must be awaited
+- Use `resolve()` for scoped providers instead of `get()`
+
+<!--
+Source references:
+- https://docs.nestjs.com/fundamentals/testing
+-->

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