Attachments

This API is experimental.

All GraphQL elements in the schema can have addition custom attachments. This can be used by other libraries or extensions to change the behavior of execution. For example, for supporting custom input validations or configuring the max age for some fields in an extension that caches responses.

AttachmentWithValidation

An attachment can register validation logic by implementing AttachmentWithValidation. The required validation method validateElement will be executed when the GraphQLSchema is validated, as an argument it will receive the Schema validation context and the GraphQLElement associated with the attachment.

ToDirectiveValue

Implementing this interface allows the GraphQLSchema's SDL String to contain the attachment's information by adding directives over the specific element associated with the attachment. Attachments that implement ToDirectiveValue require the following getters:

  /// The directive value represented by this object
  DirectiveNode get directiveValue;

  /// The directive definition of the [directiveValue]
  GraphQLDirective get directiveDefinition;

---

We provide two attachments, both of which implement AttachmentWithValidation and ToDirectiveValue.

KeyAttachment

Implements the key directive over a given object. The fields String is required.

ValidaAttachment

Implements the valida directive over a given input field or argument. The annotation argument should be the ValidaField specified for the element. You probably should use it manually, when using code generation the validation will be performed for any @Valida() annotated class or resolver and the attachment will be placed at the appropriate location.

Usage

To use associate a GraphQLElement (type, field or directive) with attachments, you may pass them as arguments to each of the GraphQLElements constructor.

AttachFn for code generation

To add attachments to types or fields when using code generation you can use the AttachFn decorator. An example of this is the following, using the KeyAttachment for KeyDirective and the ValidaAttachment for ValidaDirective (which is set up in the generated code).

@Valida()
@AttachFn(KeyedAttachment.attachments)
@GraphQLObject()
class KeyedAttachment {
  final String id;
  final String name;
  @ValidaDate(max: 'now')
  final DateTime createdAt;
  final NestedAttachment nested;

  KeyedAttachment({
    required this.id,
    required this.name,
    required this.createdAt,
    required this.nested,
  });

  static List<AttachmentWithValidation> attachments() {
    return const [
      KeyAttachment('id'),
      KeyAttachment('name nested {id}'),
    ];
  }
}

@AttachFn(NestedAttachment.attachments)
@GraphQLObject()
class NestedAttachment {
  final int id;

  NestedAttachment({
    required this.id,
  });

  static List<AttachmentWithValidation> attachments() {
    return const [
      KeyAttachment('id'),
    ];
  }
}

Will generate the following GraphQL schema:

type KeyedAttachment @key(fields: "id") @key(fields: "name nested {id}") {
  id: ID!
  name: String!
  createdAt: Date! @valida(jsonSpec: """
{"variantType":"date","max":"now"}
""")
  nested: NestedAttachment!
}''',
  '''
type NestedAttachment @key(fields: "id") {
  id: Int!