Setting directives using ObjectType constructor (not IDL)

[MichalLytek]

I am reviving #1262 as I have an use case that is related to that discussion:

Right now directives are purely a feature of the GraphQL language and IDL, so a schema not created using IDL definitionally won't contain directives. When building a schema in code, you have the full power of the host programming environment, so directives shouldn't be necessary. Directives are a tool for supplying additional intent to be later interpreted by the host programming environment.

You can include any arbitrary data on a GraphQLObjectType that you like - it's just a JS object after all. Directives are a language-level feature, not a structural property of a type.

I agree that "directives are a tool for supplying additional intent" and "you have the full power of the host programming environment". But since the GraphQL ecosystem has grown, I think we should think about interoperability with 3rd-party libraries. The examples that I am thinking about is Apollo cache control and Prisma, which are using directives to provide some metadata to make awesome underlaying features work.

As graphql-js doesn't allow for registering directives using imperative way (ObjectType constructor), to be able to use Prisma, we are forced to use IDL to create our types. But this way might be not available when you are using the imperative way as you build a library on top of graphql-js, as well as when you would have to refactor your whole app by migrating to IDL to add apollo-cache integration.

So I think that now directives are a much more widespread feature and we should allow for interoperability with this 3rd-party tools.

[MichalLytek]

After 3 days, ping @leebyron as an author of the quotes and ping @IvanGoncharov as an author of #746 that have added support for directives 😃

[IvanGoncharov]

@19majkel94 My position is the same as I wrote in #1262

I think this question is connected to the topic discussed on the last WG: Exposing schema metadata. So I think we should decide what we expose through introspection(directives or something else) and then add the same thing to GraphQL*Type classes.

[nodkz]

The new Apollo Server v2 introduce requirements for graphql-compose (and graphql-js) users to somehow provide directive via GraphQL*Type classes for providing an info for CDN cache. Without providing directives via GraphQL*Type we have no way to use Apollo Server v2.

Another use case was with graphql-cost-analysis which allows rejecting complex queries. It provides a comfortable way to add a complexity calculation logic without modifying resolvers.

It will be cool if Lee changes its position according to directives.

Repeat here a desired way for declaration directives from #1262:

const UserType = new GraphQLObjectType({
  name: 'User',
  fields: {
    name: {
      type: GraphQLString,
      description: '...',
      resolve: () => ...,
      directives: [
        { name: 'cost',  args: { useMultipliers: false, complexity: 2 } },
        { name: 'unique' },
      ],
      // or maybe simpler if graphql spec does not allow duplicated names
      directives: {
        cost: { useMultipliers: false, complexity: 2 },
        unique: true,
      },
    },
  },
});

[nodkz]

@IvanGoncharov @taion maybe you take care about this feature in the upcoming WG meetup 2018-09-20?

My English does not alow to me to do it myself 😊

[taion]

The cost analysis case example is interesting, because in the context of using the programmatic API, I think it's suboptimal to set up costing via directives. Instead of the above, a better way to express the same would be to add a getCost(childCost, variables) callback to the field, then do something like:

myConnection: {
  type: FooConnection,
  getCost: (childCost, { first }) => first * childCost,
},

[leebyron]

Directives are purely a feature of the GraphQL language and are not part of type definitions - this is because different tools will use and interpret directives in different ways.

I assume the Apollo tools translate these GraphQL language directives to some other kind of metadata on the underlying schema and type objects - it would be best to use whatever API the apollo tools expect directly.

[nodkz]

@leebyron Now I understood what you mean. It can be explained in another way:

For the query:

query {
  authors {
    id
    name @uppercase
  }
}

needs to create such directive:

const UppercaseDirective = new GraphQLDirective({
  name: 'uppercase',
  description: 'Provides default value for input field.',
  locations: [DirectiveLocation.FIELD],
});
const schema = new GraphQLSchema({
  directives: [UppercaseDirective],
  ...
});

and such Author type with resolve method:

const UppercaseDirective = new GraphQLDirective({
  name: 'uppercase',
  description: 'Provides default value for input field.',
  locations: [DirectiveLocation.FIELD],
});

const AuthorType = new GraphQLObjectType({
  name: 'Author',
  fields: () => ({
    id: { type: GraphQLInt },
    name: {
      type: GraphQLString,
      resolve: (source, args, context, info) => {
        if (info.fieldNodes?.[0].directives?.[0]?.name?.value === 'uppercase') {
          return source.name.toUpperCase();
        }
        return source.name;
      },
    },
  }),
});

For now Directives are quite stupid and adds only some meta to infoAST argument. You need manually traverse fieldNodes in your resolve method for checking directive name by string. (BTW its very strange that info does not contain Directive instance for fast comparision which cheked on query validation step, eg info.fieldNodes?.[0].directives?.[0]?.instance === UppercaseDirective).

Anyway with current directive implementation it does not make sence adding directives to FieldConfig.

[nodkz]

BUT what if can use directive as middleware?

For example, we create a new kind of directive:

const ChangeCaseDirective = new GraphQLMiddlewareDirective({
  name: 'changecase',
  // locations: [...], // no need, because this directive works only `DirectiveLocation.FIELD` level
  args: {
    fieldName: { type: new GraphQLNonNull(GraphQLString) },
    upper: { type: new GraphQLNonNull(GraphQLBoolean) },
    lower: { type: new GraphQLNonNull(GraphQLBoolean) },
  },
  resolve: async (directiveArgs, resolve, source, args, context, info) => {
     const { fieldName, upper,  lower} = directiveArgs;
     let value = await resolve(source, args, context, info) || source[fieldName];
     if (typeof value === 'string') {
        if (directiveArgs.upper) value = value.toUpperCase();
        else if (directiveArgs.lower) value = value.toLowerCase();
     }
     return value;
  },
});

const schema = new GraphQLSchema({
  directives: [ChangeCaseDirective],
  ...
});

This directive can be defined only on schema build step via SDL or ObjectType constructor. It cannot be defined in GraphQL query, otherwise

• for such purposes can be used regular args
• or it can be security vulnerabilities.

So with such directive we can custruct type in such way:

const AuthorType = new GraphQLObjectType({
  name: 'Author',
  fields: () => ({
    id: { type: GraphQLInt },
    name: { type: GraphQLString },
    lowerName: { 
      type: GraphQLString,
      directives: [
        [ChangeCaseDirective, { fieldName: 'name', lower: true} ]
      ],
    },
    upperName: { 
      type: GraphQLString,
      directives: [
        [ChangeCaseDirective, { fieldName: 'name', upper: true} ]
      ],
    }, 
  }),
});

With such case, it is almost similar to @maticzav aproach in graphql-middleware.

And maybe no reason to make such GraphQLMiddlewareDirective.
Cause with graphql-middleware it can be done in the more convenient way with better static analysis:

const AuthorType = new GraphQLObjectType({
  name: 'Author',
  fields: () => ({
    id: { type: GraphQLInt },
    name: { type: GraphQLString },
    lowerName: { 
      type: GraphQLString,
      middlewares: [
        changeCase({ fieldName: 'name', lower: true }),
      ],
    },
    upperName: { 
      type: GraphQLString,
      middlewares: [
        changeCase({ fieldName: 'name', upper: true }),
      ],
    }, 
  }),
});

@leebyron It will be great if graphql will have the ability to provide middlewares for resolve methods out of the box. Cause it helps to keep resolve methods thin and enabling code reuse and a clear separation of concerns (for query cost, permission rules, logging, error tracking and other useful methods).

[nodkz]

With current implementation of resolve method applying several middlewares looks aweful:

const changeCaseMW = changeCase({ fieldName: 'name', lower: true });
const queryCostMW = queryCost({ ...someSettings });
 
const AuthorType = new GraphQLObjectType({
  name: 'Author',
  fields: () => ({
    id: { type: GraphQLInt },
    name: { type: GraphQLString },
    lowerName: { 
      type: GraphQLString,
      resolve: async (source, args, context, info) => {
        return queryCostMW( 
           () =>changeCaseMW(
               () => { return ...somehow resolved data... },
               source, args, context, info
            ),
            source, args, context, info
        );
      },
    },
  }),
});