@buenojs/bueno 0.8.5 → 0.8.7

package/src/graphql/decorators.ts

@@ -0,0 +1,358 @@
+/**
+ * GraphQL Decorators
+ *
+ * Code-first decorator API for defining GraphQL schemas from TypeScript classes.
+ * Follows the same WeakMap metadata pattern as the OpenAPI module.
+ *
+ * @example
+ * ```typescript
+ * @ObjectType()
+ * class User {
+ *   @Field(() => String)  id: string;
+ *   @Field(() => String)  name: string;
+ * }
+ *
+ * @Resolver()
+ * class UserResolver {
+ *   @Query(() => [User])
+ *   users(): User[] { return []; }
+ * }
+ * ```
+ */
+
+import type {
+	Constructor,
+	TypeFn,
+	FieldDecoratorOptions,
+	FieldOptions,
+} from "./types";
+import {
+	setResolverMetadata,
+	setObjectTypeMetadata,
+	setInputTypeMetadata,
+	addQueryField,
+	addMutationField,
+	addSubscriptionField,
+	getQueryFields,
+	getMutationFields,
+	getSubscriptionFields,
+	setGqlPropertyMetadata,
+	setParamMetadata,
+	getParamMetadata,
+} from "./metadata";
+import { registerTypeClass } from "./schema-builder";
+
+// ============= Class Decorators =============
+
+/**
+ * Marks a class as a GraphQL resolver.
+ * Dependencies are resolved from the DI container via @Inject.
+ *
+ * @param name - Optional GraphQL type name this resolver is for (e.g. 'User').
+ *               Omit for root-level Query/Mutation/Subscription resolvers.
+ *
+ * @example
+ * ```typescript
+ * @Resolver()
+ * class UserResolver { ... }
+ *
+ * @Resolver('User')
+ * class UserFieldResolver { ... }
+ * ```
+ */
+export function Resolver(name?: string): ClassDecorator {
+	return (target: unknown) => {
+		const ctor = target as Constructor;
+		setResolverMetadata(ctor, {
+			name: name ?? ctor.name,
+		});
+	};
+}
+
+/**
+ * Marks a class as a GraphQL output type.
+ *
+ * @example
+ * ```typescript
+ * @ObjectType()
+ * class User {
+ *   @Field(() => String) id: string;
+ * }
+ * ```
+ */
+export function ObjectType(
+	name?: string,
+	options?: { description?: string },
+): ClassDecorator {
+	return (target: unknown) => {
+		const ctor = target as Constructor;
+		setObjectTypeMetadata(ctor, {
+			name: name ?? ctor.name,
+			kind: "object",
+			description: options?.description,
+		});
+		registerTypeClass(ctor);
+	};
+}
+
+/**
+ * Marks a class as a GraphQL input type.
+ *
+ * @example
+ * ```typescript
+ * @InputType()
+ * class CreateUserInput {
+ *   @Field(() => String) name: string;
+ * }
+ * ```
+ */
+export function InputType(
+	name?: string,
+	options?: { description?: string },
+): ClassDecorator {
+	return (target: unknown) => {
+		const ctor = target as Constructor;
+		setInputTypeMetadata(ctor, {
+			name: name ?? ctor.name,
+			kind: "input",
+			description: options?.description,
+		});
+		registerTypeClass(ctor);
+	};
+}
+
+// ============= Method Decorators =============
+
+/**
+ * Marks a method as a GraphQL Query field.
+ *
+ * @param typeFn - Thunk returning the return type constructor
+ * @param options - Field options (nullable, description, name override)
+ *
+ * @example
+ * ```typescript
+ * @Query(() => [User])
+ * async users(): Promise<User[]> { ... }
+ *
+ * @Query(() => User, { nullable: true })
+ * async user(@Args('id') id: string): Promise<User | null> { ... }
+ * ```
+ */
+export function Query(typeFn: TypeFn, options: FieldOptions = {}): MethodDecorator {
+	return (
+		target: object,
+		propertyKey: string | symbol,
+		descriptor: PropertyDescriptor,
+	): PropertyDescriptor => {
+		const methodName = String(propertyKey);
+		addQueryField(target, {
+			methodName,
+			fieldName: options.name ?? methodName,
+			typeFn,
+			kind: "query",
+			nullable: options.nullable ?? false,
+			description: options.description,
+			deprecationReason: options.deprecationReason,
+			paramMetadata: getParamMetadata(target, methodName),
+		});
+		return descriptor;
+	};
+}
+
+/**
+ * Marks a method as a GraphQL Mutation field.
+ *
+ * @example
+ * ```typescript
+ * @Mutation(() => User)
+ * async createUser(@Args('input', CreateUserInput) input: CreateUserInput): Promise<User> { ... }
+ * ```
+ */
+export function Mutation(typeFn: TypeFn, options: FieldOptions = {}): MethodDecorator {
+	return (
+		target: object,
+		propertyKey: string | symbol,
+		descriptor: PropertyDescriptor,
+	): PropertyDescriptor => {
+		const methodName = String(propertyKey);
+		addMutationField(target, {
+			methodName,
+			fieldName: options.name ?? methodName,
+			typeFn,
+			kind: "mutation",
+			nullable: options.nullable ?? false,
+			description: options.description,
+			deprecationReason: options.deprecationReason,
+			paramMetadata: getParamMetadata(target, methodName),
+		});
+		return descriptor;
+	};
+}
+
+/**
+ * Marks a method as a GraphQL Subscription field.
+ * The method must return an AsyncGenerator.
+ *
+ * Requires an engine with supportsSubscriptions = true (e.g. GraphQLJsAdapter).
+ * Requires subscriptions: true in GraphQLModule.setup().
+ *
+ * @example
+ * ```typescript
+ * @Subscription(() => Message)
+ * async *messageAdded(): AsyncGenerator<Message> {
+ *   yield* pubSub.subscribe('message:added');
+ * }
+ * ```
+ */
+export function Subscription(typeFn: TypeFn, options: FieldOptions = {}): MethodDecorator {
+	return (
+		target: object,
+		propertyKey: string | symbol,
+		descriptor: PropertyDescriptor,
+	): PropertyDescriptor => {
+		const methodName = String(propertyKey);
+		addSubscriptionField(target, {
+			methodName,
+			fieldName: options.name ?? methodName,
+			typeFn,
+			kind: "subscription",
+			nullable: options.nullable ?? false,
+			description: options.description,
+			deprecationReason: options.deprecationReason,
+			paramMetadata: getParamMetadata(target, methodName),
+		});
+		return descriptor;
+	};
+}
+
+// ============= Property Decorator =============
+
+/**
+ * Marks a property as a GraphQL field.
+ * Used on @ObjectType and @InputType classes.
+ *
+ * @param typeFn - Thunk returning the field type
+ * @param options - Field options
+ *
+ * @example
+ * ```typescript
+ * @ObjectType()
+ * class User {
+ *   @Field(() => String)                    id: string;
+ *   @Field(() => String, { nullable: true }) bio?: string;
+ *   @Field(() => [Post])                    posts: Post[];
+ * }
+ * ```
+ */
+export function Field(
+	typeFn: TypeFn,
+	options: FieldDecoratorOptions = {},
+): PropertyDecorator {
+	return (target: object, propertyKey: string | symbol): void => {
+		const key =
+			typeof propertyKey === "symbol" ? propertyKey.toString() : propertyKey;
+		setGqlPropertyMetadata(target, propertyKey, {
+			propertyKey: key,
+			typeFn,
+			nullable: options.nullable ?? false,
+			description: options.description,
+			deprecationReason: options.deprecationReason,
+			defaultValue: options.defaultValue,
+		});
+	};
+}
+
+// ============= Parameter Decorators =============
+
+/**
+ * Extracts a specific GraphQL argument by name into a method parameter.
+ *
+ * @param name - The argument name as it appears in the GraphQL query
+ * @param inputTypeFn - Optional: type thunk for object input types (validates shape)
+ *
+ * @example
+ * ```typescript
+ * @Query(() => User)
+ * async user(@Args('id') id: string): Promise<User> { ... }
+ *
+ * @Mutation(() => User)
+ * async createUser(@Args('input', CreateUserInput) input: CreateUserInput): Promise<User> { ... }
+ * ```
+ */
+export function Args(name: string, inputType?: Constructor): ParameterDecorator {
+	return (
+		target: object,
+		propertyKey: string | symbol | undefined,
+		parameterIndex: number,
+	): void => {
+		if (!propertyKey) return;
+		const methodName = String(propertyKey);
+		setParamMetadata(target, methodName, parameterIndex, {
+			index: parameterIndex,
+			kind: inputType ? "argsObject" : "args",
+			argName: name,
+			inputTypeFn: inputType ? () => inputType : undefined,
+		});
+		// Re-sync param metadata into existing resolver field metadata
+		syncParamMetadata(target, methodName);
+	};
+}
+
+/**
+ * Injects the GraphQL context object into a resolver method parameter.
+ *
+ * Named @GqlContext to avoid collision with the HTTP Context class.
+ *
+ * @example
+ * ```typescript
+ * @Mutation(() => Post)
+ * async createPost(
+ *   @Args('title') title: string,
+ *   @GqlContext() ctx: GraphQLContext,
+ * ): Promise<Post> {
+ *   const userId = (ctx.user as User).id;
+ *   ...
+ * }
+ * ```
+ */
+export function GqlContext(): ParameterDecorator {
+	return (
+		target: object,
+		propertyKey: string | symbol | undefined,
+		parameterIndex: number,
+	): void => {
+		if (!propertyKey) return;
+		const methodName = String(propertyKey);
+		setParamMetadata(target, methodName, parameterIndex, {
+			index: parameterIndex,
+			kind: "context",
+		});
+		syncParamMetadata(target, methodName);
+	};
+}
+
+// ============= Internal Helper =============
+
+/**
+ * Re-syncs param metadata into already-registered resolver field entries.
+ * Decorators are applied bottom-up in TypeScript, so @Args/@GqlContext may run
+ * before @Query/@Mutation. This helper updates the field entry with the latest
+ * param metadata after each parameter decorator runs.
+ */
+function syncParamMetadata(prototype: object, methodName: string): void {
+	const params = getParamMetadata(prototype, methodName);
+
+	const syncFields = (
+		fields: ReturnType<typeof getQueryFields>,
+		addFn: typeof addQueryField,
+	): void => {
+		const field = fields.find((f) => f.methodName === methodName);
+		if (field) {
+			addFn(prototype, { ...field, paramMetadata: params });
+		}
+	};
+
+	syncFields(getQueryFields(prototype), addQueryField);
+	syncFields(getMutationFields(prototype), addMutationField);
+	syncFields(getSubscriptionFields(prototype), addSubscriptionField);
+}

package/src/graphql/execution-pipeline.ts

@@ -0,0 +1,227 @@
+/**
+ * GraphQL Execution Pipeline
+ *
+ * Applies the same guard/interceptor pipeline used for HTTP controllers
+ * to GraphQL resolver methods.
+ *
+ * Guards and interceptors receive the real HTTP Context, enriched with
+ * GraphQL-specific metadata:
+ * - context.get('graphql:operation') → resolver field name (e.g. 'users')
+ * - context.get('graphql:type')      → 'query' | 'mutation' | 'subscription'
+ * - context.get('graphql:resolver')  → resolver class constructor
+ *
+ * ## Guard Compatibility
+ * - ✅ Auth guards reading Authorization/Cookie headers
+ * - ✅ API key guards
+ * - ✅ Custom guards reading any header/cookie
+ * - ⚠️  Route-based guards (reading context.path) — see /graphql for all ops
+ * - ⚠️  CSRF guards (may block all POSTs) — need graphql-aware adaptation
+ */
+
+import type { Context } from "../context";
+import type { Container, Token } from "../container";
+import type { Guard, CanActivate, GuardFn } from "../modules/guards";
+import type { Interceptor, NestInterceptor, InterceptorFn } from "../modules/interceptors";
+import type { GraphQLContext, ResolvedField, GraphQLError } from "./types";
+import {
+	executeGuards,
+	getClassGuards,
+	getMethodGuards,
+} from "../modules/guards";
+import {
+	executeInterceptors,
+	getClassInterceptors,
+	getMethodInterceptors,
+	isNestInterceptor,
+	isInterceptorFn,
+} from "../modules/interceptors";
+import { enrichContextForGraphQL } from "./context-builder";
+
+export type { Guard, Interceptor };
+
+// ============= Pipeline Options =============
+
+export interface ResolverPipelineOptions {
+	/** The resolver class constructor (for reading class-level guard metadata) */
+	resolverClass: new (...args: unknown[]) => unknown;
+	/** Field name (for reading method-level guard metadata) */
+	fieldName: string;
+	/** The resolved field descriptor */
+	resolvedField: ResolvedField;
+	/** GraphQL arguments extracted from the query */
+	args: Record<string, unknown>;
+	/** Built GraphQL context */
+	graphqlContext: GraphQLContext;
+	/** HTTP Context from the current request */
+	httpContext: Context;
+	/** DI container for resolving guard/interceptor instances */
+	container: Container;
+	/** Global guards from app.getGlobalGuards() */
+	globalGuards: Guard[];
+	/** Global interceptors from app.getGlobalInterceptors() */
+	globalInterceptors: Interceptor[];
+	/** Operation type for enriching context */
+	operationType: "query" | "mutation" | "subscription";
+}
+
+// ============= Pipeline Executor =============
+
+/**
+ * Execute a resolver method through the full guard → interceptor pipeline.
+ *
+ * Returns the resolver method's return value, or throws if a guard blocks.
+ * GraphQL errors should be caught by the caller and placed into the errors array.
+ */
+export async function executeResolverWithPipeline(
+	options: ResolverPipelineOptions,
+): Promise<unknown> {
+	const {
+		resolverClass,
+		fieldName,
+		resolvedField,
+		args,
+		graphqlContext,
+		httpContext,
+		container,
+		globalGuards,
+		globalInterceptors,
+		operationType,
+	} = options;
+
+	// Enrich HTTP context with GraphQL metadata for guard inspection
+	enrichContextForGraphQL(
+		httpContext,
+		fieldName,
+		operationType,
+		resolverClass,
+	);
+
+	// Read class-level and method-level guards/interceptors
+	const classGuards = getClassGuards(resolverClass) ?? [];
+	const methodGuards = getMethodGuards(resolverClass.prototype as object, fieldName) ?? [];
+	const classInterceptors = getClassInterceptors(resolverClass) ?? [];
+	const methodInterceptors =
+		getMethodInterceptors(resolverClass.prototype as object, fieldName) ?? [];
+
+	// Guard resolver helper
+	const resolveGuard = (guard: Guard): CanActivate | GuardFn | null => {
+		if (
+			typeof guard === "object" &&
+			guard !== null &&
+			!("canActivate" in guard)
+		) {
+			try {
+				return container.resolve(guard as Token) as CanActivate;
+			} catch {
+				return null;
+			}
+		}
+		return null;
+	};
+
+	// Interceptor resolver helper
+	const resolveInterceptor = (
+		interceptor: Interceptor,
+	): NestInterceptor | InterceptorFn | null => {
+		if (!isNestInterceptor(interceptor) && !isInterceptorFn(interceptor)) {
+			try {
+				return container.resolve(
+					interceptor as Token,
+				) as NestInterceptor;
+			} catch {
+				return null;
+			}
+		}
+		return null;
+	};
+
+	// Step 1: Execute guards
+	const guardsPassed = await executeGuards(httpContext, {
+		globalGuards,
+		classGuards,
+		methodGuards,
+		resolveGuard,
+	});
+
+	if (!guardsPassed) {
+		throw new GraphQLForbiddenError(
+			`Access denied to field '${fieldName}'`,
+		);
+	}
+
+	// Step 2: Execute interceptors wrapping the resolver call
+	return executeInterceptors(
+		httpContext,
+		async () => {
+			return callResolver(resolvedField, args, graphqlContext);
+		},
+		{
+			globalInterceptors,
+			classInterceptors,
+			methodInterceptors,
+			resolveInterceptor,
+		},
+	);
+}
+
+// ============= Resolver Caller =============
+
+/**
+ * Calls the actual resolver method with the correct argument list.
+ * Resolves @Args and @GqlContext parameters at their declared positions.
+ */
+export async function callResolver(
+	field: ResolvedField,
+	args: Record<string, unknown>,
+	gqlContext: GraphQLContext,
+): Promise<unknown> {
+	const instance = field.resolverInstance as Record<
+		string,
+		(...a: unknown[]) => unknown
+	>;
+	const methodArgs = buildMethodArgs(field, args, gqlContext);
+	const result = instance[field.methodName](...methodArgs);
+	return result instanceof Promise ? await result : result;
+}
+
+function buildMethodArgs(
+	field: ResolvedField,
+	args: Record<string, unknown>,
+	gqlContext: GraphQLContext,
+): unknown[] {
+	const methodArgs: unknown[] = [];
+
+	for (const param of field.paramMetadata) {
+		switch (param.kind) {
+			case "context":
+				methodArgs[param.index] = gqlContext;
+				break;
+			case "args":
+				methodArgs[param.index] = param.argName ? args[param.argName] : args;
+				break;
+			case "argsObject":
+				methodArgs[param.index] = param.argName ? args[param.argName] : args;
+				break;
+		}
+	}
+
+	return methodArgs;
+}
+
+// ============= Custom Error =============
+
+export class GraphQLForbiddenError extends Error {
+	readonly extensions = { code: "FORBIDDEN" };
+
+	constructor(message = "Forbidden") {
+		super(message);
+		this.name = "GraphQLForbiddenError";
+	}
+
+	toGraphQLError(): GraphQLError {
+		return {
+			message: this.message,
+			extensions: this.extensions,
+		};
+	}
+}