@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-nestjs-devin/skills/nestjs-graphql/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: nestjs-graphql
+description: Comprehensive guide for NestJS GraphQL development using Apollo and code-first approach. This skill should be used when writing GraphQL resolvers, mutations, queries, types, subscriptions, or implementing advanced features like field middleware, complexity limits, and custom scalars. Also covers project-specific patterns including zero-trust auth decorators and DataLoader integration.
+---
+
+# NestJS GraphQL Development Guide
+
+## Overview
+
+This skill provides comprehensive guidance for building GraphQL APIs with NestJS using Apollo Server and the code-first approach. It covers official NestJS GraphQL patterns plus project-specific implementations for authentication, authorization, and data loading.
+
+## When to Use This Skill
+
+- Writing new GraphQL resolvers, queries, or mutations
+- Creating GraphQL object types, input types, or enums
+- Implementing field resolvers or computed fields
+- Adding subscriptions for real-time updates
+- Configuring query complexity limits
+- Creating custom scalars or field middleware
+- Implementing authentication/authorization on GraphQL operations
+- Setting up DataLoader for N+1 prevention
+
+## Quick Reference
+
+### Core Decorators
+
+| Decorator | Purpose | Import |
+|-----------|---------|--------|
+| `@Resolver()` | Define resolver class | `@nestjs/graphql` |
+| `@Query()` | Define query operation | `@nestjs/graphql` |
+| `@Mutation()` | Define mutation operation | `@nestjs/graphql` |
+| `@Args()` | Extract arguments | `@nestjs/graphql` |
+| `@Context()` | Access GraphQL context | `@nestjs/graphql` |
+| `@Parent()` | Access parent in field resolver | `@nestjs/graphql` |
+| `@ResolveField()` | Define field resolver | `@nestjs/graphql` |
+| `@ObjectType()` | Define GraphQL object type | `@nestjs/graphql` |
+| `@InputType()` | Define GraphQL input type | `@nestjs/graphql` |
+| `@Field()` | Define field on type | `@nestjs/graphql` |
+| `@Extensions()` | Attach metadata to fields | `@nestjs/graphql` |
+
+### Type Decorators
+
+| Decorator | GraphQL Type | TypeScript Type |
+|-----------|-------------|-----------------|
+| `@Field(() => String)` | "String!" | `string` |
+| `@Field(() => Int)` | "Int!" | `number` |
+| `@Field(() => Float)` | "Float!" | `number` |
+| `@Field(() => Boolean)` | "Boolean!" | `boolean` |
+| `@Field(() => ID)` | "ID!" | `string` |
+| `@Field(() => [String])` | "[String!]!" | `string[]` |
+| `@Field({ nullable: true })` | `String` | `string \| null` |
+
+## Code-First Patterns
+
+### Basic Resolver Structure
+
+```typescript
+import { Args, Context, Mutation, Query, Resolver } from "@nestjs/graphql";
+import { Public, Authed } from "../auth";
+
+@Resolver(() => Entity)
+export class EntityResolver {
+  constructor(private readonly entityService: EntityService) {}
+
+  @Query(() => Entity, { description: "Retrieve entity by ID" })
+  @Authed()
+  async entity(@Args("id", { type: () => ID }) id: string): Promise<Entity> {
+    return this.entityService.findById(id);
+  }
+
+  @Mutation(() => Entity, { description: "Create new entity" })
+  @Authed()
+  async createEntity(
+    @Args("input") input: CreateEntityInput,
+    @Context() { req }: GraphQLContext
+  ): Promise<Entity> {
+    return this.entityService.create(input, req.user.id);
+  }
+}
+```
+
+### Object Type Definition
+
+```typescript
+import { Field, ID, ObjectType } from "@nestjs/graphql";
+
+@ObjectType({ description: "Represents a user in the system" })
+export class User {
+  @Field(() => ID, { description: "Unique identifier" })
+  id: string;
+
+  @Field(() => String, { description: "User's email address" })
+  email: string;
+
+  @Field(() => String, { nullable: true, description: "Display name" })
+  displayName?: string;
+
+  @Field(() => Date, { description: "Account creation timestamp" })
+  createdAt: Date;
+}
+```
+
+### Input Type Definition
+
+```typescript
+import { Field, InputType } from "@nestjs/graphql";
+
+@InputType({ description: "Input for creating a new user" })
+export class CreateUserInput {
+  @Field(() => String, { description: "User's email address" })
+  email: string;
+
+  @Field(() => String, { description: "User's password" })
+  password: string;
+
+  @Field(() => String, { nullable: true, description: "Optional display name" })
+  displayName?: string;
+}
+```
+
+## References
+
+This skill includes detailed reference files for specific topics:
+
+### references/quick-start.md
+Setup and configuration for NestJS GraphQL with Apollo driver, module configuration, and code-first vs schema-first approaches.
+
+### references/resolvers-mutations.md
+Comprehensive guide to writing resolvers, queries, mutations, field resolvers, and using decorators like @Args, @Context, @Parent.
+
+### references/types-scalars.md
+Creating object types, input types, enums, interfaces, unions, and custom scalars. Includes mapped types (PartialType, PickType, etc.).
+
+### references/advanced-features.md
+Field middleware, query complexity, plugins, subscriptions, and extensions.
+
+### references/project-patterns.md
+Project-specific patterns including zero-trust auth decorators (@Public, @Authed, @Owner, @Groups), DataLoader integration, and GraphQL documentation standards.
+
+## Common Tasks
+
+### Adding a New Query
+
+1. Add method to resolver with `@Query()` decorator
+2. Add auth decorator (`@Public()`, `@Authed()`, or `@Groups()`)
+3. Define return type in decorator: `@Query(() => ReturnType)`
+4. Add description: `@Query(() => ReturnType, { description: "..." })`
+5. Use `@Args()` for parameters with descriptions
+
+### Adding a New Mutation
+
+1. Add method to resolver with `@Mutation()` decorator
+2. Add auth decorator (mutations typically use `@Authed()`)
+3. Create InputType for complex inputs
+4. Access user context via `@Context() { req }: GraphQLContext`
+
+### Adding Field Resolver
+
+```typescript
+@ResolveField(() => [Comment], { description: "Entity's comments" })
+async comments(
+  @Parent() entity: Entity,
+  @Context() { loaders }: GraphQLContext
+): Promise<Comment[]> {
+  return loaders.commentsLoader.load(entity.id);
+}
+```
+
+### Adding DataLoader for New Entity
+
+1. Add batch method to service: `getByIds(ids: string[]): Promise<Entity[]>`
+2. Add loader type to `IDataLoaders` interface
+3. Create loader in `DataLoaderService.getLoaders()`
+4. Use in resolver: `loaders.entityLoader.load(id)`
+
+See `references/project-patterns.md` for detailed DataLoader patterns.

package/plugins/lisa-nestjs-devin/skills/nestjs-graphql/references/advanced-features.md

@@ -0,0 +1,527 @@
+# Advanced Features
+
+Guide to field middleware, query complexity, plugins, subscriptions, and extensions.
+
+## Extensions
+
+Extensions allow attaching metadata to GraphQL schema elements.
+
+### @Extensions Decorator
+
+```typescript
+import { Extensions, Field, ObjectType } from "@nestjs/graphql";
+
+@ObjectType()
+export class User {
+  @Field()
+  @Extensions({ role: "ADMIN" })
+  secretField: string;
+}
+```
+
+### Accessing Extensions
+
+Extensions are available on field config in schema transformers:
+
+```typescript
+import { mapSchema, MapperKind } from "@graphql-tools/utils";
+
+const transformer = (schema: GraphQLSchema) => {
+  return mapSchema(schema, {
+    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
+      const extensions = fieldConfig.extensions;
+      if (extensions?.role === "ADMIN") {
+        // Wrap resolver with auth check
+      }
+      return fieldConfig;
+    },
+  });
+};
+```
+
+### Using Extensions for Auth
+
+```typescript
+// Decorator
+export const AUTH_EXTENSION_KEY = "auth";
+
+export const Public = () =>
+  Extensions({ [AUTH_EXTENSION_KEY]: { rules: [{ allow: "public" }] } });
+
+export const Authed = () =>
+  Extensions({ [AUTH_EXTENSION_KEY]: { rules: [{ allow: "authed" }] } });
+
+// Usage
+@Query(() => String)
+@Public()
+hello(): string {
+  return "Hello World";
+}
+```
+
+## Field Middleware
+
+Middleware that runs during field resolution.
+
+### Creating Middleware
+
+```typescript
+import { FieldMiddleware, MiddlewareContext, NextFn } from "@nestjs/graphql";
+
+export const loggingMiddleware: FieldMiddleware = async (
+  ctx: MiddlewareContext,
+  next: NextFn
+) => {
+  const start = Date.now();
+  const result = await next();
+  const duration = Date.now() - start;
+  console.log(`Field ${ctx.info.fieldName} took ${duration}ms`);
+  return result;
+};
+```
+
+### Applying Middleware to Field
+
+```typescript
+@ObjectType()
+export class User {
+  @Field({ middleware: [loggingMiddleware] })
+  email: string;
+}
+```
+
+### Global Middleware
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  buildSchemaOptions: {
+    fieldMiddleware: [loggingMiddleware],
+  },
+})
+```
+
+### Middleware Context
+
+```typescript
+interface MiddlewareContext<TSource = unknown, TContext = unknown> {
+  source: TSource;           // Parent object
+  args: Record<string, unknown>; // Field arguments
+  context: TContext;         // GraphQL context
+  info: GraphQLResolveInfo;  // Resolve info
+}
+```
+
+### Transform Middleware
+
+```typescript
+const upperCaseMiddleware: FieldMiddleware = async (ctx, next) => {
+  const value = await next();
+  return typeof value === "string" ? value.toUpperCase() : value;
+};
+```
+
+### Auth Middleware
+
+```typescript
+const authMiddleware: FieldMiddleware = async (ctx, next) => {
+  const { extensions } = ctx.info.parentType.getFields()[ctx.info.fieldName];
+
+  if (extensions?.auth === "admin") {
+    const user = ctx.context.req.user;
+    if (!user?.isAdmin) {
+      return null; // Hide field
+    }
+  }
+
+  return next();
+};
+```
+
+## Query Complexity
+
+Prevent expensive queries from overwhelming the server.
+
+### Installation
+
+```bash
+bun add graphql-query-complexity
+```
+
+### Complexity Plugin
+
+```typescript
+import { Plugin } from "@nestjs/apollo";
+import { GraphQLSchemaHost } from "@nestjs/graphql";
+import {
+  ApolloServerPlugin,
+  GraphQLRequestListener,
+} from "@apollo/server";
+import {
+  fieldExtensionsEstimator,
+  getComplexity,
+  simpleEstimator,
+} from "graphql-query-complexity";
+
+@Plugin()
+export class ComplexityPlugin implements ApolloServerPlugin {
+  constructor(private readonly gqlSchemaHost: GraphQLSchemaHost) {}
+
+  async requestDidStart(): Promise<GraphQLRequestListener<unknown>> {
+    const maxComplexity = 100;
+    const { schema } = this.gqlSchemaHost;
+
+    return {
+      didResolveOperation: async ({ request, document }) => {
+        const complexity = getComplexity({
+          schema,
+          operationName: request.operationName,
+          query: document,
+          variables: request.variables,
+          estimators: [
+            fieldExtensionsEstimator(),
+            simpleEstimator({ defaultComplexity: 1 }),
+          ],
+        });
+
+        if (complexity > maxComplexity) {
+          throw new Error(
+            `Query too complex: ${complexity}. Maximum: ${maxComplexity}`
+          );
+        }
+      },
+    };
+  }
+}
+```
+
+### Field-Level Complexity
+
+```typescript
+@ObjectType()
+export class User {
+  // Static complexity
+  @Field(() => String, { complexity: 1 })
+  name: string;
+
+  // Higher complexity for relations
+  @Field(() => [Post], { complexity: 10 })
+  posts: Post[];
+
+  // Dynamic complexity based on arguments
+  @Field(() => [Post], {
+    complexity: (options) => {
+      const limit = options.args.limit ?? 20;
+      return 1 + limit * 2;
+    },
+  })
+  recentPosts: Post[];
+
+  // Complexity with child multiplication
+  @Field(() => [Comment], {
+    complexity: (options) => {
+      return options.childComplexity * (options.args.first ?? 10);
+    },
+  })
+  comments: Comment[];
+}
+```
+
+### Complexity Guidelines
+
+| Field Type | Suggested Complexity |
+|------------|---------------------|
+| Scalar fields | 1 |
+| Enum fields | 1 |
+| Simple object fields | 2-5 |
+| Relation fields (belongsTo) | 5-10 |
+| Collection fields (hasMany) | 10-20 |
+| Aggregation fields | 5-15 |
+| Search/filter fields | 10-30 |
+
+## Plugins
+
+Apollo Server plugins for request lifecycle hooks.
+
+### Creating a Plugin
+
+```typescript
+import { Plugin } from "@nestjs/apollo";
+import {
+  ApolloServerPlugin,
+  GraphQLRequestListener,
+  GraphQLRequestContext,
+} from "@apollo/server";
+
+@Plugin()
+export class LoggingPlugin implements ApolloServerPlugin {
+  async requestDidStart(
+    requestContext: GraphQLRequestContext<unknown>
+  ): Promise<GraphQLRequestListener<unknown>> {
+    console.log("Request started");
+
+    return {
+      async willSendResponse() {
+        console.log("Response sent");
+      },
+
+      async didEncounterErrors({ errors }) {
+        console.log("Errors:", errors);
+      },
+    };
+  }
+}
+```
+
+### Request Lifecycle Hooks
+
+```typescript
+interface GraphQLRequestListener {
+  // Before parsing
+  parsingDidStart?(): Promise<void>;
+
+  // Before validation
+  validationDidStart?(): Promise<void>;
+
+  // After operation resolved
+  didResolveOperation?(): Promise<void>;
+
+  // Before response sent
+  willSendResponse?(): Promise<void>;
+
+  // On errors
+  didEncounterErrors?(): Promise<void>;
+
+  // Before execution
+  executionDidStart?(): Promise<void>;
+}
+```
+
+### Registering Plugins
+
+```typescript
+@Module({
+  imports: [GraphQLModule.forRoot<ApolloDriverConfig>({ /* ... */ })],
+  providers: [LoggingPlugin, ComplexityPlugin],
+})
+export class AppModule {}
+```
+
+### Performance Monitoring Plugin
+
+```typescript
+@Plugin()
+export class PerformancePlugin implements ApolloServerPlugin {
+  async requestDidStart(): Promise<GraphQLRequestListener<unknown>> {
+    const start = Date.now();
+
+    return {
+      async willSendResponse({ response }) {
+        const duration = Date.now() - start;
+        response.http.headers.set("X-Response-Time", `${duration}ms`);
+      },
+    };
+  }
+}
+```
+
+## Subscriptions
+
+Real-time updates via WebSocket.
+
+### Installation
+
+```bash
+bun add graphql-subscriptions
+```
+
+### PubSub Setup
+
+```typescript
+import { PubSub } from "graphql-subscriptions";
+
+// Simple in-memory PubSub (for development only)
+export const pubSub = new PubSub();
+
+// For production, use Redis:
+// import { RedisPubSub } from "graphql-redis-subscriptions";
+// export const pubSub = new RedisPubSub({ /* redis config */ });
+```
+
+### Subscription Resolver
+
+```typescript
+import { Args, Mutation, Resolver, Subscription } from "@nestjs/graphql";
+import { pubSub } from "./pubsub";
+
+const POST_CREATED = "postCreated";
+
+@Resolver(() => Post)
+export class PostResolver {
+  @Mutation(() => Post)
+  async createPost(@Args("input") input: CreatePostInput): Promise<Post> {
+    const post = await this.postService.create(input);
+    pubSub.publish(POST_CREATED, { postCreated: post });
+    return post;
+  }
+
+  @Subscription(() => Post, {
+    description: "Subscribe to new posts",
+  })
+  postCreated() {
+    return pubSub.asyncIterator(POST_CREATED);
+  }
+}
+```
+
+### Filtered Subscriptions
+
+```typescript
+@Subscription(() => Post, {
+  filter: (payload, variables) => {
+    return payload.postCreated.authorId === variables.authorId;
+  },
+})
+postCreated(@Args("authorId") authorId: string) {
+  return pubSub.asyncIterator(POST_CREATED);
+}
+```
+
+### Subscription with Resolver
+
+```typescript
+@Subscription(() => Post, {
+  resolve: (payload) => {
+    // Transform the payload before sending
+    return {
+      ...payload.postCreated,
+      isNew: true,
+    };
+  },
+})
+postCreated() {
+  return pubSub.asyncIterator(POST_CREATED);
+}
+```
+
+### Module Configuration for Subscriptions
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  autoSchemaFile: true,
+  subscriptions: {
+    "graphql-ws": true, // Modern WebSocket protocol
+    "subscriptions-transport-ws": true, // Legacy protocol (deprecated)
+  },
+  context: ({ req, connection }) => {
+    // HTTP request
+    if (req) {
+      return { req };
+    }
+    // WebSocket connection
+    if (connection) {
+      return { user: connection.context.user };
+    }
+  },
+})
+```
+
+### Subscription Authentication
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  subscriptions: {
+    "graphql-ws": {
+      onConnect: (context) => {
+        const { connectionParams } = context;
+        const token = connectionParams?.authorization;
+
+        if (!token) {
+          throw new Error("Missing auth token");
+        }
+
+        // Validate token and return user
+        const user = validateToken(token);
+        return { user };
+      },
+    },
+  },
+})
+```
+
+## Schema Transformation
+
+Transform the generated schema before use.
+
+### Using transformSchema
+
+```typescript
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  transformSchema: (schema) => {
+    return mapSchema(schema, {
+      [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
+        // Transform field config
+        return fieldConfig;
+      },
+    });
+  },
+})
+```
+
+### Combining Transformers
+
+```typescript
+const combinedTransformer = (schema: GraphQLSchema): GraphQLSchema => {
+  const withAuth = authTransformer(schema);
+  const withLogging = loggingTransformer(withAuth);
+  return withLogging;
+};
+
+GraphQLModule.forRoot<ApolloDriverConfig>({
+  transformSchema: combinedTransformer,
+})
+```
+
+## Directives
+
+Custom schema directives (schema-first approach).
+
+### Defining Directive
+
+```typescript
+import { Directive, Field, ObjectType } from "@nestjs/graphql";
+
+@Directive("@upper")
+@ObjectType()
+export class User {
+  @Directive("@deprecated(reason: \"Use name instead\")")
+  @Field()
+  firstName: string;
+}
+```
+
+### Registering Directive Transformer
+
+```typescript
+import { mapSchema, getDirective, MapperKind } from "@graphql-tools/utils";
+
+function upperDirectiveTransformer(schema: GraphQLSchema) {
+  return mapSchema(schema, {
+    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
+      const upperDirective = getDirective(schema, fieldConfig, "upper")?.[0];
+
+      if (upperDirective) {
+        const { resolve = defaultFieldResolver } = fieldConfig;
+        fieldConfig.resolve = async (source, args, context, info) => {
+          const result = await resolve(source, args, context, info);
+          return typeof result === "string" ? result.toUpperCase() : result;
+        };
+      }
+
+      return fieldConfig;
+    },
+  });
+}
+```
+
+**Note:** For code-first approach, prefer using `@Extensions()` decorator over directives. Extensions are simpler to implement and don't require SDL directive definitions.