Support for directives

[louy]

Hi there,

Awesome tool. We're strongly considering using it. Quick question on directives because I can't find anything in the docs:

How do you declare directives? How do you annotate different fields/types with directives?

[captbaritone]

Grats does not currently support adding or defining arbitrary schema directives, but it seems like a reasonable thing to support. Could you tell me more about the specific directives you you use that you'd like to support? Would help inform how they should be supported.

[louy]

For anyone interested, I have just hacked a solution for now. This also serves as an example of directives we have:

import { MapperKind, mapSchema } from '@graphql-tools/utils';
import { GraphQLSchema } from 'graphql';
import type { Int } from 'grats';

type Directive = {
  name: 'complexity' | 'sensitive';
  args: Record<string, unknown>;
};

/**
 * Directive controlling query cost analytics
 */
export function complexity(
  /** The complexity value for the field - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]
   *
   */
  value: Int,

  /** Information how field arguments influence cost of returned list - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]
   *
   */
  multipliers?: string[],

  /** Cost of field assign to directive doesn't depend on multiplier but cost of nested fields yes
   *
   */
  multiplyOnlyNestedFields?: boolean,

  /** In situation where we cannot define multiplier depending on arguments we use defaultValue to multiple
   *
   */
  defaultMultiplier?: Int,
): Directive {
  return {
    name: 'complexity',
    args: {
      value,
      multipliers,
      multiplyOnlyNestedFields,
      defaultMultiplier,
    },
  };
}

/** Marks a field as sensitive so it gets redacted in logs */
export function sensitive(
  /**An optional reason why the field is marked as sensitive*/
  reason?: string,
): Directive {
  return {
    name: 'sensitive',
    args: { reason },
  };
}

const directivesList: (
  | {
      directive: Directive;
      kind: 'FIELD';
      parent: string;
      name: string;
    }
  | {
      directive: Directive;
      kind: 'ARGUMENT';
      parent: string;
      field: string;
      argument: string;
    }
  | {
      directive: Directive;
      kind: 'TYPE';
      name: string;
    }
)[] = [];

export function addDirective(
  directive: Directive,
  kind: 'FIELD',
  parent: string,
  name: string,
): void;
export function addDirective(
  directive: Directive,
  kind: 'ARGUMENT',
  parent: string,
  field: string,
  argument: string,
): void;
export function addDirective(
  directive: Directive,
  kind: 'TYPE',
  name: string,
): void;
export function addDirective(
  directive: Directive,
  kind: 'TYPE' | 'FIELD' | 'ARGUMENT',
  arg1: string,
  arg2?: string,
  arg3?: string,
) {
  switch (kind) {
    case 'FIELD':
      directivesList.push({
        directive,
        kind,
        parent: arg1!,
        name: arg2!,
      });
      break;
    case 'ARGUMENT':
      directivesList.push({
        directive,
        kind,
        parent: arg1!,
        field: arg2!,
        argument: arg3!,
      });
      break;
    case 'TYPE':
      directivesList.push({
        directive,
        kind,
        name: arg1!,
      });
      break;
  }
}

export function applyDirectives(schema: GraphQLSchema) {
  const cloned = directivesList.slice();
  const mapped = mapSchema(schema, {
    [MapperKind.TYPE]: (type) => {
      const applicable = cloned.filter(
        (directive) =>
          directive.kind === 'TYPE' && directive.name === type.name,
      );

      if (applicable.length === 0) {
        return type;
      }

      type.extensions = type.extensions ?? {};

      const extensions: any = type.extensions;
      extensions.directives = extensions.directives ?? {};

      for (const item of applicable) {
        extensions.directives[item.directive.name] = item.directive.args;
        cloned.splice(cloned.indexOf(item), 1);
      }
    },

    // FIELD
    [MapperKind.FIELD](fieldConfig, fieldName, typeName) {
      const applicable = cloned.filter(
        (directive) =>
          (directive.kind === 'FIELD' &&
            directive.parent === typeName &&
            directive.name === fieldName) ||
          (directive.kind === 'ARGUMENT' &&
            directive.parent === typeName &&
            directive.field === fieldName),
      );

      if (applicable.length === 0) {
        return fieldConfig;
      }

      for (const item of applicable) {
        if (item.kind === 'FIELD') {
          fieldConfig.extensions = fieldConfig.extensions ?? {};
          const extensions: any = fieldConfig.extensions;
          extensions.directives = extensions.directives ?? {};

          extensions.directives[item.directive.name] = item.directive.args;
          cloned.splice(cloned.indexOf(item), 1);
        } else if (item.kind === 'ARGUMENT' && 'args' in fieldConfig) {
          fieldConfig.args = fieldConfig.args ?? {};
          const arg = fieldConfig.args[item.argument];
          if (arg) {
            arg.extensions = arg.extensions ?? {};
            const extensions: any = arg.extensions;
            extensions.directives = extensions.directives ?? {};

            extensions.directives[item.directive.name] = item.directive.args;
            cloned.splice(cloned.indexOf(item), 1);
          }
        }
      }
    },
  });
  if (cloned.length)
    throw new Error(
      `Found unresolved directives\n${JSON.stringify(cloned, null, 2)}`,
    );
  return mapped;
}

Usage:

addDirective(complexity(50), 'FIELD', 'Mutation', 'createFcmToken');
addDirective(sensitive(), 'ARGUMENT', 'Mutation', 'createFcmToken', 'token');
/**
 * Register Firebase Cloud Messaging token
 * @gqlMutationField
 */
export async function createFcmToken(
  /** @sensitive */
  token: string,
  { fetchFreshaApi }: Context,
): Promise<FcmToken | null> {
  // ...
}

And later:

applyDirectives(getSchema())

[louy]

Basically what I'd like to see is 2 things:

1. Ability to declare directives, potentially from functions, similar to the above two exmaples I have:

/**
 * Directive controlling query cost analytics
 * @gqlDirective on FIELD_DEFINITION
 */
export function complexity(
  /** The complexity value for the field - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]
   *
   */
  value: Int,

  /** Information how field arguments influence cost of returned list - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]
   *
   */
  multipliers?: string[],

  /** Cost of field assign to directive doesn't depend on multiplier but cost of nested fields yes
   *
   */
  multiplyOnlyNestedFields?: boolean,

  /** In situation where we cannot define multiplier depending on arguments we use defaultValue to multiple
   *
   */
  defaultMultiplier?: Int,
): Directive {}

Generates

  "Directive controlling query cost analytics"
  directive @complexity(
    "The complexity value for the field - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]"
    value: Int!

    "Information how field arguments influence cost of returned list - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]"
    multipliers: [String!]

    "Cost of field assign to directive doesn't depend on multiplier but cost of nested fields yes"
    multiplyOnlyNestedFields: Boolean

    "In situation where we cannot define multiplier depending on arguments we use defaultValue to multiple"
    defaultMultiplier: Int
  ) on FIELD_DEFINITION

2. Abilty to apply directives to the various things they apply to: fields, arguments, types, enums, etc
   This one is a lot tricker because grats doesn't use decorators. My hack was to introduce a function you have to call, but it is not type-safe and I prefer a safer solution (maybe you wrap resolver functions in directive apply)

[louy]

Directives don't really have logic like resolvers, so maybe a function doesn't make sense. Usually directives are used either to apply schema transformations (using mapSchema) or to be read later in resolvers/middleware (like the sensitive directive above, used to mask values in the logging middleware)

[captbaritone]

Thanks for the examples, helps clarify!

I think a reasonable starting place would be:

Define directives

You can define a directive on a type alias of an object literal type describing the directive's arguments:

/**
 * Directive controlling query cost analytics
 * @gqlDirective complexity on FIELD_DEFINITION
 */
type Complexity = {
  /** The complexity value for the field - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]
   *
   */
  value: Int,

  /** Information how field arguments influence cost of returned list - works as described in (graphql-query-complexity)[https://github.com/slicknode/graphql-query-complexity/blob/master/src/estimators/directive/README.md]
   *
   */
  multipliers?: string[],

  /** Cost of field assign to directive doesn't depend on multiplier but cost of nested fields yes
   *
   */
  multiplyOnlyNestedFields?: boolean,

  /** In situation where we cannot define multiplier depending on arguments we use defaultValue to multiple
   *
   */
  defaultMultiplier?: Int,
};

The @gqlDirective could be followed by either ON <...directiveLocations> in which case the type alias's name would be the directive name, or <directiveName> ON <...directiveLocations> to support aliasing the type name. Aliasing will probably be common since directives generally use snakeCase but types generally use PascalCase.

Using directives

How do you imagine the syntax for passing arguments to directives would look?

I think ideally it could be:

/**
 * @gqlField
 * @someDirective(someArg: "Hello")
 */
export class User {
  // ...
}

But we'll need to see if TypeScript will parse @someDirective(someArg: "Hello") as a docblock tag, or if we'll end up needing to do our own docblock parsing.

One thing that will be tricky is knowing which docblock tags should be interpreted as directives and which are unrelated to Grats. Elsewhere in Grats we handle this by parsing everything as if it belongs to Grats, and then in a later phase (when we know which names exist) we discard any which we learn are not related to Grats.

[louy]

I like this a lot. Yes.

The other problem with parsing however is multiline directive args

I was thinking an alternative might be

/**
 * @gqlField
 * @someDirective.shortArg String
 * @someDirective.longArg A very long
 * multi line string
 * @someDirective.booleanArg true
 * @someDirective.enumArg ENUM_VAL
 */
export class User {
  // ...
}

But then repeatable args become unclear, for that maybe you allow using only the directive name to count as the start of the invocation:

/**
 * @gqlField
 * @someDirective
 * @someDirective.shortArg String1
 * @someDirective
 * @someDirective.shortArg String2
 */
export class User {
  // ...
}

[felamaslen]

If we can agree on an approach here then I wouldn't mind contributing with an implementation.

[leo-fresha]

I think ideally it could be:

/**
 * @gqlField
 * @someDirective(someArg: "Hello")
 */
export class User {
  // ...
}

But we'll need to see if TypeScript will parse @someDirective(someArg: "Hello") as a docblock tag, or if we'll end up needing to do our own docblock parsing.

One thing that will be tricky is knowing which docblock tags should be interpreted as directives and which are unrelated to Grats. Elsewhere in Grats we handle this by parsing everything as if it belongs to Grats, and then in a later phase (when we know which names exist) we discard any which we learn are not related to Grats.

Why not @gqlDecorate <directiveName> <directiveArg>...

/**
 * @gqlType
 * @gqlDecorate cacheControl scope:PRIVATE maxAge:100
 */
type Wallet = {
  /**
   * @gqlField
   * @gqlDecorate complexity value:50
   */
  balance: Int,

  /** @gqlField */
  paymentMethods(
    /**
     * @gqlArg
     * @gqlDecorate deprecated
     */
    includeExpired: boolean | null
  ): [PaymentMethod]
}

It keeps with using @gql-prefixed doc tags. @gqlDirective to define a directive, and @gqlDecorate to decorate a target with an existing directive.
I'm not sure of the exact JSDoc syntax supported by Typescript, but there's probably a way to make this work, using curly braces or other JSDoc syntax like:

/** @gqlDecorate `complexity(value: 20, motivation: "This arg requires extra backend queries")` */

Might be worth taking a look at what TSDoc supports.

[captbaritone]

Thanks everyone for the feedback/ideas!

I looked into it a bit more and learned a few things:

1. TypeScript will let me parse @someDirective(someArg: "foo") in a docblock as a docblock tag.
2. Parsing such directives out of a docblock (by passing the text to the GraphQL-js parser and using special methods on the parser) is possible, but reporting parse errors as granular locations is not really viable due the case where the directive spans multiple lines but those lines are prefixed with * from the docblock. TS will strip those for us, so we can parse it fine, just not reliably point back to the correct source location
3. If a directive does not have arguments, it becomes indistinguishable from a docblock tag. Since we don't know all valid docblocks at extraction time, this means we would need to retain all dobblock tags as possible directives and strip them later when we are full program aware.

I think this points to something like what @leo-fresha is describing, where there's a tag that denotes "directive here" and the tag value is the directive.

That said, I'm not crazy about introducing special syntax here which deviates from both GraphQL and typescript: directives without an @, required quotes, a space after directive name...

I'm also not crazy about @gqlDecorate as a name since it does not map to any well defined name/concept in GraphQL.

Maybe @gqlDirective followed by plain old SDL directives? I'll need to check if TS treats this as two tags or one.

/**
 * @gqlType
 * @gqlDirective @cacheControl(scope:PRIVATE maxAge:100)
 */
type Wallet = {
  /**
   * @gqlField
   * @gqlDirective @complexity(value:50)
   */
  balance: Int,

That still leaves open: How do we define directives if @gqlDirective is used for adding directives...

As for @deprecated. I'd like to keep that using the existing @deprecated docblock tag since that is already a concept in TypeScript (it will render the function/method/etc as struck through).

[leo-fresha]

Personally I would keep @gqlDirective to define a directive, and use another tag for "applying" them.
@gqlDirective matches @gqlType, @gqlField etc used to define the other GraphQL concepts.

The GraphQL spec uses the term "annotate" consistently when talking about using directives, so what about @gqlAnnotate?

/**
 * @gqlAnnotate complexity(value:50)
 * or
 * @gqlAnnotate @complexity(value:50)
 */

A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document

In this example, a directive is defined which can be used to annotate a field

Directives can also be used to annotate the type system definition language as well

In this example, the directive @example annotates field and argument definitions

Or, for a more verbose but unmistakable option, @gqlApplyDirective

[captbaritone]

I've confirmed that TypeScript parser will treat

/**
 * @gqlAnnotate @complexity(value:50)
 */

As two separate tags, which is a bummer for us.

[captbaritone]

I'm exploring the ability to use docblock tags as directives directly in this WIP PR: #167

[louy]

Is there anything we can help with to move this forward?

[captbaritone]

I think I have a path forward in the above draft PR. I need to add support for directive validation (surprisingly it's not provided by regular schema validation) and I also want to revisit the API design for applying directives (just using docblock tags might pose an unacceptable tradeoff due to the risk of namespace collisions)

I suspect I'll have time to make progress on Friday.

[captbaritone]

Okay, I made quite a bit of progress today (you can see that progress in this draft PR: #167)

• Add validation for directive arguments which is surprisingly missing from GraphQL-js

Here are a few things I'm stuck on, and could use help thinking of solutions to:

Accessing schema directives at runtime

The graphql-js GraphQLSchema object does not actually preserve schema directives. If your schema is generated from parsing an SDL file, you can dig into the (optional) AST property it exposes, but the GraphQLSchema object Grats generates typegen for does not support a way to specify that, say, a field has a directive on it. This makes it hard to define a proof of concept for how you would actually use these directives.

Syntax for applying directives

My current approach is just to treat docblock tags that match directive names as directives and parse them as SDL. So:

/**
 * @gqlQueryField
 * @cost(credits: 10)
 */
export function greeting(): string {
  return "hello";
}

This is intuitive and simple (no new syntax) but it means if there's ever a namespace collision between docblock tag names you want to use and directive names you want to use, you might get stuck.

I'm going take a stab at the @gqlAnnotate approach proposed above by @leo-fresha:

/**
 * @gqlAnnotate complexity(value:50)
 */

[captbaritone]

Spent some time implementing @gqlAnnotate and realized that we'll need to find some consistency between how we support directives generically and how we support some built in directives. Currently there are a few which we currently support:

• @deprecated Some reason
• @specifiedBy https://example.com
• @oneOf

I think that's all of them?

Maybe when we add support for generic directives we should drop special handling for these and instead ask users to write them in whatever generic way we settle on? I think the biggest tension here is @deprecated which currently has an expected format in TypeScript and I like the fact that we transfer the TypeScript semantics to GraphQL.

Maybe a nice middle ground would be @deprecated which is the only one with shared TypeScript and GraphQL semantics is the only one with special syntax, and all others revert back to the generic syntax.

[captbaritone]

@louy Just curious what your specific urgency is? Are you need a resolution here before you can decide which GraphQL solution you are going to use? Or is it that it's blocking a specific use case. If it's the latter, maybe we can come up with some workaround to unblock you in the meantime.

[louy]

I think deprecated being special is fair, but also keep in mind people can potentially re-declare deprecated and add more arguments to it, so would be nice if it was both supported via @gqlAnnotate and via native syntax

Re: the urgency

Grats has been great overall. We've adopted it over codegen as it is tons better. However, it has made directives (which we use very heavily) very awkward. We have custom linting rules than enforce certain directives that we're unable to migrate to grats because our hacky solution (the one I documented in the first few comments) is really ugly.
The other issue is I worry devs don't add directives as often because they're really hard to write now.

As I said before, we're happy to support with this effort (contribute time) as it's not fair to put expectations on open-source maintainers (and you don't owe us anything)

[louy]

I personally don't see why @specifiedBy and @oneOf should be supported as jsdoc directives

[louy]

It would also mean that all grats decorators are prefixed with @gql (except for ones that are native to jsdoc, i.e. @deprecated)

[captbaritone]

Okay. I think I've figured out what syntax is going to be best for Grats. To validate it for myself I've written a first draft of two new doc pages trying to fully explain how to both define and use directives.

• Annotating With Directives
• Defining Directives

I'd love a pass of feedback on this if you have time.

[leo-fresha]

@captbaritone those drafts look good to me.

One thing that is confusing me is that here https://gist.github.com/captbaritone/6f8369241989bf1afa518acced5287a7 there are examples with two different syntaxes to define a directive, and I am not clear on which one is the correct one (or are both allowed?)

 /**
 * @gqlDirective
 * @gqlOn FIELD_DEFINITION
 */

/**
 * @gqlDirective on FIELD_DEFINITION
 */

[captbaritone]

Oops. The second one is left over from an earlier iteration. I'll update

[louy]

The proposal looks good!

[captbaritone]

As I worked through the implementation, I ended up pivoting back to this syntax:

/**
 * @gqlDirective on FIELD_DEFINITION
 */

I just merged #167 which supports defining and adding directives with all the documentation:

• https://grats.capt.dev/docs/docblock-tags/directive-definitions/
• https://grats.capt.dev/docs/docblock-tags/directive-annotations/

[email protected] has these changes. Would you be able to try that out and give feedback before I ship a formal release?

[louy]

I've done a quick test and it works great

@felamaslen will be testing this against our (entire?) codebase

[felamaslen]

@captbaritone thanks for sorting this out. It seems to work, except I now have the following issue:

Directive "@deprecated" may not be used on ENUM.

Looks like a regression in application of @deprecated directive to enums?

Oops, this actually looks like a mistake on our part. Enums cannot be deprecated

[felamaslen]

Having done some more testing, this works really well 👍

There is a slight issue which is that the schema AST returned by getSchema does not contain the directive nodes on applied directives. This means the consumer is responsible for splicing these in, by parsing the extensions.grats object.

What do you think about potentially exposing the directives in the AST directly, so consumers do not have to be aware of this?

[felamaslen]

FYI this is how I am currently applying the directives based on the extensions:

type GratsExtensions = {
  grats?: {
    directives?: { name: string; args?: Record<string, any> }[];
  };
};

function Directive(
  name: string,
  args: ConstDirectiveNode['arguments'],
): ConstDirectiveNode {
  return {
    kind: Kind.DIRECTIVE,
    name: { kind: Kind.NAME, value: name },
    arguments: args,
  };
}
function Argument(
  name: string,
  value: ConstArgumentNode['value'],
): ConstArgumentNode {
  return {
    kind: Kind.ARGUMENT,
    name: { kind: Kind.NAME, value: name },
    value,
  };
}

function extractDirective(
  schema: GraphQLSchema,
  directiveName: string,
  args: Record<string, any> | undefined,
): ConstDirectiveNode {
  const directive = schema.getDirective(directiveName);
  assert(directive, `Directive with name ${directiveName} not found in schema`);
  return Directive(
    directive.name,
    Object.entries(args ?? {}).map(([argName, argValue]) => {
      const argDefinition = directive.args.find((arg) => arg.name === argName);
      assert(
        argDefinition,
        `Directive arg on ${directiveName} with name ${argName} not found`,
      );
      const value = ((): ConstArgumentNode['value'] => {
        switch (argDefinition.type) {
          case GraphQLInt:
            return { kind: Kind.INT, value: argValue };
          // TODO(FM): support other primitive directive arg types, e.g. String
          default: {
            const customType = schema.getType(argDefinition.type.toString());
            if (customType instanceof GraphQLEnumType) {
              return {
                kind: Kind.ENUM,
                value: argValue,
              };
            } else {
              // TODO(FM): support other custom directive arg types, e.g. ObjectValueNode
              throw new Error(
                `Unknown type ${argDefinition.type} on directive arg ${directiveName}.${argDefinition.name}`,
              );
            }
          }
        }
      })();
      return Argument(argDefinition.name, value);
    }),
  );
}

export function applyDirectives(schema: GraphQLSchema) {
  return mapSchema(
    schema,
    {
      [MapperKind.FIELD](fieldConfig, fieldName, typeName) {
        const gratsDirectives =
          (fieldConfig.extensions as GratsExtensions).grats?.directives ?? [];

        for (const directive of gratsDirectives) {
          const directives = fieldConfig.astNode!.directives?.slice() ?? [];
          (fieldConfig.astNode!.directives as any) = directives;
          const directiveNode = extractDirective(
            schema,
            directive.name,
            directive.args,
          );
          directives.push(directiveNode);
        }
      },
      // similar for MapperKind.TYPE
    }
  )
}

[captbaritone]

Enums cannot be deprecated

I'll add a note to the changelog clarifying that the new directive validation may uncover previously invalid deprecated directives.

[captbaritone]

What do you think about potentially exposing the directives in the AST directly, so consumers do not have to be aware of this?

Hmm, I'm a little perplexed. Why do you need the AST of the directive definitions? Maybe you could share what is is that you are doing with the value you get from calling extractDirective?

[felamaslen]

Hmm, I'm a little perplexed. Why do you need the AST of the directive definitions? Maybe you could share what is is that you are doing with the value you get from calling extractDirective?

In our case, we need the schema AST with directives applied, in order to print the schema into a .graphql file. We use this file as the source of truth, e.g. for code reviews.

There are probably other use cases though for having an AST fully representative of the generated schema.

However, the GraphQLSchema class does not support defining directives, as it is a non-goal of graphql-js. I guess for now we can leave this, potentially with a note explaining why directives specified with @gqlAnnotate are added to the extensions object instead of the AST nodes (which don't exist without calling mergeSchemas).

It would be helpful IMHO to expose a util like getSchemaAST(), which returns the schema with applyDirectives called on it, but we can leave this out of scope for this issue.

[louy]

FYI, graphql-tools has a function printSchemaWithDirectives, that adds directives to the produced AST by pulling them from type.extensions.directives .

The shape of extensions['directives'] matches the one from grats. It probably makes sense to for grats to keep the same signature as the one from graphql-tools. Either way printSchemaWithDirectives takes a pathToDirectivesInExtensions option, which can be set to ['grats', 'directives'], which would work in current implementation.

The important use-case for directives is transforms. It would be great if switching from codegen to grats didn't mean you have to rewrite all your transforms. Looking at our codebase, we use getDirective from @graphql-tools/utils.

getDirective works in much the same way as printSchemaWithDirectives, so if grats was to put directives under the default extension everything remains mostly compatible with codegen (minus the lack of an ast) and migration becomes easier for everyone.

Alternatively, and especially during the migration/incremental adoption of grats, all our transforms would have to be rewritten to call getDirective twice, once with the default pathToDirectivesInExtensions = ['directives'] and a 2nd time with pathToDirectivesInExtensions = ['grats', 'directives'].

Thoughts? @captbaritone

Edit: We now use getDirective. Removed mentions of astNode.directives

[captbaritone]

In our case, we need the schema AST with directives applied, in order to print the schema into a .graphql file. We use this file as the source of truth, e.g. for code reviews.

Is there a reason the .graphql schema file generated by Grats is not sufficient for this?

[captbaritone]

@louy Thanks for the great breakdown! Very cool to see that @graphql-tools/utils already supports having the extension data under different paths. Also makes sense that having it under multiple keys for different schemas is awkward.

Could you tell me more about what transformations are in play here? I'm wondering if you actually need to be running them on the GraphQLSchema that Grats itself makes, or if you could get a GraphQLSchema by parsing the scehma.graphql file that Grats produces. This would include the directive ASTs automatically, but would not have the correct resolver functions.

Knowing more about what these transforms are actually being used for would help me understand the viability of that approach.

[felamaslen]

Is there a reason the .graphql schema file generated by Grats is not sufficient for this?

In our case, we merge the schema with some legacy type defs prior to generating the .graphql file.

Regarding transforms, for a given directive we might define a function, mapping GraphQLSchema to GraphQLSchema. It will use mapSchema (from @graphql-tools/utils) and find any fields / args / etc. using the given directive, and apply behaviour to the field as defined by the directive. For example, it might alter the resolve function to apply caching. We call getDirective (from @graphql-tools/utils) in our transform functions to find which directives are applied to a given field / argument / input definition, and this relies on the directive being defined in the AST node.

[felamaslen]

FYI, we have started implementing this, using the following mapping to convert the grats extensions to extensions compatible with getDirective:

import { MapperKind, mapSchema } from '@graphql-tools/utils';

type GratsExtensions = {
  grats?: {
    directives?: { name: string; args?: Record<string, any> }[];
  };
};

export function applyDirectives(schema: GraphQLSchema): GraphQLSchema {
  const mapped = mapSchema(
    schema,
    {
      [MapperKind.TYPE]: (type) => {
        const gratsDirectives = (type.extensions as GratsExtensions).grats
          ?.directives;
        if (gratsDirectives) {
          Object.assign(type.extensions as any, {
            directives: Object.fromEntries([
              ...Object.entries(type.extensions?.directives ?? {}),
              ...gratsDirectives.map((directive) => [
                directive.name,
                directive.args ?? {},
              ]),
            ]),
          });
        }
        return type;
      },

      [MapperKind.FIELD](fieldConfig, _fieldName, _typeName) {
        const gratsDirectives = (fieldConfig.extensions as GratsExtensions)
          .grats?.directives;
        if (gratsDirectives) {
          Object.assign(fieldConfig.extensions as any, {
            directives: Object.fromEntries([
              ...Object.entries(fieldConfig.extensions?.directives ?? {}),
              ...gratsDirectives.map((directive) => [
                directive.name,
                directive.args ?? {},
              ]),
            ]),
          });
        }
        return fieldConfig;
      },

      [MapperKind.ARGUMENT](argumentConfig, _fieldName, _typeName) {
        const gratsDirectives = (argumentConfig.extensions as GratsExtensions)
          .grats?.directives;
        if (gratsDirectives) {
          Object.assign(argumentConfig.extensions as any, {
            directives: Object.fromEntries([
              ...Object.entries(argumentConfig.extensions?.directives ?? {}),
              ...gratsDirectives.map((directive) => [
                directive.name,
                directive.args ?? {},
              ]),
            ]),
          });
        }
        return argumentConfig;
      },
    },
  );
}

[captbaritone]

Thanks! This is very helpful. Is the reason you want to use extensions.directives instead of extensions.grats.directives because you need to operate on a merged schema that includes the Grats schema and non-Grats schemas? Or is it because you are using some shared library to apply the server directives which non-configurably assumes that's where it can find directives?

[louy]

Yup it's because there are grats and non-grats schemas (codebase is partially migrated).

[louy]

Btw I've been looking at other codebases to see how they consume directives in their transforms, and some (e.g. graphql-directive-constraint) use a function called getDirectiveValues from the graphql-js package, which relies on astNode.

So my proposal above (of writing to *Config.extensions.directives) will only work for maybe half the transforms out there, not all of them.

But it would be nice if some libraries would work OOTB, as opposed to none that would work with grats schema today without tinkering with config (that is often not even exposed).

Examples of transforms that use *Config.extensions.directives:

• @graphql-directive/auth and @graphql-directive/validator
• graphql-rate-limit
• @profusion/apollo-validation-directives

Examples of transforms that use astNode.directives:

• graphql-directive-constraint
• @aws-amplify/amplify-graphql-* and @aws-amplify/graphql-directives

[tomgasson]

@captbaritone I like this @gqlDirective syntax form.

I've hit a problem definining @defer (or @stream), because the argument if is a reserved word.

/**
 * @gqlDirective on FRAGMENT_SPREAD | INLINE_FRAGMENT
 */
function defer({
  label,
  if = true, // Syntax error (reserved word)
}: {
  label: string;
  if?: boolean | null;
}): void {}

/**
 * @gqlDirective on FRAGMENT_SPREAD | INLINE_FRAGMENT
 */
function defer({
  label,
  'if': _ = true, // anonymous alias
}: {
  label: string;
  if?: boolean | null;
}): void {}

parses, but the output is missing the default value

directive @defer(label: String!, if: Boolean) on FRAGMENT_SPREAD | INLINE_FRAGMENT

should be

directive @defer(label: String!, if: Boolean = true) on FRAGMENT_SPREAD | INLINE_FRAGMENT

[captbaritone]

@tomgasson Good catch: https://github.com/captbaritone/grats/pull/185/files

Update: Shipped in [email protected] if you don't want to wait on a release.