Add @Extensions decorator

CHANGELOG.md

@@ -11,6 +11,7 @@
 - add basic support for directives with `@Directive()` decorator (#369)
 - add possibility to tune up the performance and disable auth & middlewares stack for simple field resolvers (#479)
 - optimize resolvers execution paths to speed up a lot basic scenarios (#488)
+- add `@Extensions` decorator for putting metadata into GraphQL types config (#521)
 ### Fixes
 - refactor union types function syntax handling to prevent possible errors with circular refs
 - fix transforming and validating nested inputs and arrays (#462)

dev.js

@@ -4,6 +4,7 @@ require("ts-node/register/transpile-only");
 // require("./examples/authorization/index.ts");
 // require("./examples/automatic-validation/index.ts");
 // require("./examples/enums-and-unions/index.ts");
+// require("./examples/extensions/index.ts");
 // require("./examples/generic-types/index.ts");
 // require("./examples/interfaces-inheritance/index.ts");
 // require("./examples/middlewares-custom-decorators/index.ts");

docs/extensions.md

@@ -0,0 +1,117 @@
+---
+title: Extensions
+---
+
+The `graphql-js` library allows for putting arbitrary data into GraphQL types config inside the `extensions` property.
+Annotating schema types or fields with a custom metadata, that can be then used at runtime by middlewares or resolvers, is a really powerful and useful feature.
+
+For such use cases, **TypeGraphQL** provides the `@Extensions` decorator, which adds the data we defined to the `extensions` property of the executable schema for the decorated classes, methods or properties.
+
+> Be aware that this is a low-level decorator and you generally have to provide your own logic to make use of the `extensions` metadata.
+
+## Using the `@Extensions` decorator
+
+Adding extensions to the schema type is as simple as using the `@Extensions` decorator and passing it an object of the custom data we want:
+
+```typescript
+@Extensions({ complexity: 2 })
+```
+
+We can pass several fields to the decorator:
+
+```typescript
+@Extensions({ logMessage: "Restricted access", logLevel: 1 })
+```
+
+And we can also decorate a type several times. The snippet below shows that this attaches the exact same extensions data to the schema type as the snippet above:
+
+```typescript
+@Extensions({ logMessage: "Restricted access" })
+@Extensions({ logLevel: 1 })
+```
+
+If we decorate the same type several times with the same extensions key, the one defined at the bottom takes precedence:
+
+```typescript
+@Extensions({ logMessage: "Restricted access" })
+@Extensions({ logMessage: "Another message" })
+```
+
+The above usage results in your GraphQL type having a `logMessage: "Another message"` property in its extensions.
+
+TypeGraphQL classes with the following decorators can be annotated with `@Extensions` decorator:
+
+- `@ObjectType`
+- `@InputType`
+- `@Field`
+- `@Query`
+- `@Mutation`
+- `@FieldResolver`
+
+So the `@Extensions` decorator can be placed over the class property/method or over the type class itself, and multiple times if necessary, depending on what we want to do with the extensions data:
+
+```typescript
+@Extensions({ roles: ["USER"] })
+@ObjectType()
+class Foo {
+  @Field()
+  field: string;
+}
+
+@ObjectType()
+class Bar {
+  @Extensions({ roles: ["USER"] })
+  @Field()
+  field: string;
+}
+
+@ObjectType()
+class Bar {
+  @Extensions({ roles: ["USER"] })
+  @Extensions({ visible: false, logMessage: "User accessed restricted field" })
+  @Field()
+  field: string;
+}
+
+@Resolver(of => Foo)
+class FooBarResolver {
+  @Extensions({ roles: ["USER"] })
+  @Query()
+  foobar(@Arg("baz") baz: string): string {
+    return "foobar";
+  }
+
+  @Extensions({ roles: ["ADMIN"] })
+  @FieldResolver()
+  bar(): string {
+    return "foobar";
+  }
+}
+```
+
+## Using the extensions data in runtime
+
+Once we have decorated the necessary types with extensions, the executable schema will contain the extensions data, and we can make use of it in any way we choose. The most common use will be to read it at runtime in resolvers or middlewares and perform some custom logic there.
+
+Here is a simple example of a global middleware that will be logging a message on field resolver execution whenever the field is decorated appropriately with `@Extensions`:
+
+```typescript
+export class LoggerMiddleware implements MiddlewareInterface<Context> {
+  constructor(private readonly logger: Logger) {}
+
+  use({ info }: ResolverData, next: NextFn) {
+    // extract `extensions` object from GraphQLResolveInfo object to get the `logMessage` value
+    const { logMessage } = info.parentType.getFields()[info.fieldName].extensions || {};
+
+    if (logMessage) {
+      this.logger.log(logMessage);
+    }
+
+    return next();
+  }
+}
+```
+
+## Examples
+
+You can see more detailed examples of usage [here](https://github.com/MichalLytek/type-graphql/tree/master/examples/extensions).

examples/extensions/context.interface.ts

@@ -0,0 +1,5 @@
+import { User } from "./user.interface";
+
+export interface Context {
+  user?: User;
+}

examples/extensions/examples.gql

@@ -0,0 +1,36 @@
+query GetPublicRecipes {
+  recipes {
+    title
+    description
+    averageRating
+  }
+}
+
+query GetRecipesForAuthedUser {
+  recipes {
+    title
+    description
+    ingredients
+    averageRating
+  }
+}
+
+query GetRecipesForAdmin {
+  recipes {
+    title
+    description
+    ingredients
+    averageRating
+    ratings
+  }
+}
+
+mutation AddRecipeByAuthedUser {
+  addRecipe(title: "Sample Recipe") {
+    averageRating
+  }
+}
+
+mutation DeleteRecipeByAdmin {
+  deleteRecipe(title: "Recipe 1")
+}

examples/extensions/helpers/config.extractors.ts

@@ -0,0 +1,18 @@
+import { GraphQLResolveInfo, GraphQLFieldConfig, GraphQLObjectTypeConfig } from "graphql";
+
+export const extractFieldConfig = (info: GraphQLResolveInfo): GraphQLFieldConfig<any, any> => {
+  const { type, extensions, description, deprecationReason } = info.parentType.getFields()[
+    info.fieldName
+  ];
+
+  return {
+    type,
+    description,
+    extensions,
+    deprecationReason,
+  };
+};
+
+export const extractParentTypeConfig = (
+  info: GraphQLResolveInfo,
+): GraphQLObjectTypeConfig<any, any> => info.parentType.toConfig();

examples/extensions/helpers/recipe.ts

@@ -0,0 +1,27 @@
+import { plainToClass } from "class-transformer";
+
+import { Recipe } from "../recipe.type";
+
+export function createRecipe(recipeData: Partial<Recipe>): Recipe {
+  return plainToClass(Recipe, recipeData);
+}
+
+export const sampleRecipes = [
+  createRecipe({
+    title: "Recipe 1",
+    description: "Desc 1",
+    ingredients: ["one", "two", "three"],
+    ratings: [3, 4, 5, 5, 5],
+  }),
+  createRecipe({
+    title: "Recipe 2",
+    description: "Desc 2",
+    ingredients: ["four", "five", "six"],
+    ratings: [3, 4, 5, 3, 2],
+  }),
+  createRecipe({
+    title: "Recipe 3",
+    ingredients: ["seven", "eight", "nine"],
+    ratings: [4, 4, 5, 5, 4],
+  }),
+];

examples/extensions/index.ts

@@ -0,0 +1,36 @@
+import "reflect-metadata";
+import { ApolloServer } from "apollo-server";
+import Container from "typedi";
+import { buildSchema } from "../../src";
+
+import { ExampleResolver } from "./resolver";
+import { Context } from "./context.interface";
+import { LoggerMiddleware } from "./logger.middleware";
+
+void (async function bootstrap() {
+  // build TypeGraphQL executable schema
+  const schema = await buildSchema({
+    container: Container,
+    resolvers: [ExampleResolver],
+    globalMiddlewares: [LoggerMiddleware],
+  });
+
+  // Create GraphQL server
+  const server = new ApolloServer({
+    schema,
+    context: () => {
+      const ctx: Context = {
+        // example user
+        user: {
+          id: 123,
+          name: "Sample user",
+        },
+      };
+      return ctx;
+    },
+  });
+
+  // Start the server
+  const { url } = await server.listen(4000);
+  console.log(`Server is running, GraphQL Playground available at ${url}`);
+})();

examples/extensions/log-message.decorator.ts

@@ -0,0 +1,20 @@
+import { Extensions } from "../../src";
+
+interface LogOptions {
+  message: string;
+  level?: number;
+}
+
+export function LogMessage(messageOrOptions: string | LogOptions) {
+  // parse the parameters of the custom decorator
+  const log: LogOptions =
+    typeof messageOrOptions === "string"
+      ? {
+          level: 4,
+          message: messageOrOptions,
+        }
+      : messageOrOptions;
+
+  // return the `@Extensions` decorator with a prepared property
+  return Extensions({ log });
+}

examples/extensions/logger.middleware.ts

@@ -0,0 +1,39 @@
+import { Service } from "typedi";
+import { GraphQLResolveInfo, GraphQLFieldConfig, GraphQLObjectTypeConfig } from "graphql";
+import { MiddlewareInterface, NextFn, ResolverData } from "../../src";
+
+import { extractFieldConfig, extractParentTypeConfig } from "./helpers/config.extractors";
+import { Context } from "./context.interface";
+import { Logger } from "./logger.service";
+
+const extractLoggerExtensionsFromConfig = (
+  config: GraphQLObjectTypeConfig<any, any> | GraphQLFieldConfig<any, any>,
+) => (config.extensions && config.extensions.log) || {};
+
+const getLoggerExtensions = (info: GraphQLResolveInfo) => {
+  const fieldConfig = extractFieldConfig(info);
+  const fieldLoggerExtensions = extractLoggerExtensionsFromConfig(fieldConfig);
+
+  const parentConfig = extractParentTypeConfig(info);
+  const parentLoggerExtensions = extractLoggerExtensionsFromConfig(parentConfig);
+
+  return {
+    ...parentLoggerExtensions,
+    ...fieldLoggerExtensions,
+  };
+};
+
+@Service()
+export class LoggerMiddleware implements MiddlewareInterface<Context> {
+  constructor(private readonly logger: Logger) {}
+
+  use({ context: { user }, info }: ResolverData<Context>, next: NextFn) {
+    const { message, level = 0 } = getLoggerExtensions(info);
+
+    if (message) {
+      this.logger.log(level, `${user ? ` (user: ${user.id})` : ""}`, message);
+    }
+
+    return next();
+  }
+}

examples/extensions/logger.service.ts

@@ -0,0 +1,9 @@
+import { Service } from "typedi";
+
+@Service()
+export class Logger {
+  log(...args: any[]) {
+    // replace with more sophisticated solution :)
+    console.log(...args);
+  }
+}

examples/extensions/recipe.type.ts

@@ -0,0 +1,29 @@
+import { ObjectType, Extensions, Field, Int, Float } from "../../src";
+
+import { LogMessage } from "./log-message.decorator";
+
+@ObjectType()
+// log a message when any Recipe field is accessed
+@LogMessage("Recipe field accessed")
+export class Recipe {
+  @Field()
+  title: string;
+
+  @Field({ nullable: true })
+  description?: string;
+
+  @Field(type => [String])
+  // We can use raw Extensions decorator if we want
+  @Extensions({ log: { message: "ingredients field accessed", level: 0 } })
+  ingredients: string[];
+
+  // this will override the object type log message
+  @LogMessage("Ratings accessed")
+  @Field(type => [Int])
+  ratings: number[];
+
+  @Field(type => Float, { nullable: true })
+  get averageRating(): number | null {
+    return this.ratings.reduce((a, b) => a + b, 0) / this.ratings.length;
+  }
+}