Easy way to use directives

[yanns]

The problem

As experienced with GraphQL federation, users of sangria often needs to add custom directives to fields, object types...

current API is not user-friendly

The current way for doing is using the copy method and is not friendly:

  private val ProductType: ObjectType[Unit, Product] = ObjectType(
    "Product",
    fields = fields[Unit, Product](...)
  ).copy(astDirectives =
    Vector(
      Key("id"),
      Key("sku package"),
      Key("sku variation { id }")
    )
  )

current API is not type safe

Furthermore, custom directives declare locations, restricting where they can be applied.
Currently, a custom directive can be used on any types that accepts ast.Directive.
For example, the following compiles although the Key directive should not be applied to a Field:

Field(...)copy(astDirectives =
    Vector(
      Key("id"),
      Key("sku package"),
      Key("sku variation { id }")
    )
  )

possible solutions

Relying on the author of the directive providing helpers

We can rely on the author of the directive to provide type helpers. Example:

  object Shareable {
    val directive: ast.Directive = ast.Directive(
      name = "shareable",
      arguments = Vector.empty
    )

    def apply[Ctx, Val](field: Field[Ctx, Val]): Field[Ctx, Val] =
      field.copy(astDirectives = field.astDirectives :+ directive)

    def apply[Ctx, Val: ClassTag](obj: ObjectType[Ctx, Val]): ObjectType[Ctx, Val] =
      obj.copy(astDirectives = obj.astDirectives :+ directive)
  }

  val ProductDimensionType: ObjectType[Unit, ProductDimension] = Shareable(
      ObjectType(...)
  )

  val ProductType: ObjectType[Unit, Product] = ObjectType(
    "Product",
    fields = fields[Unit, Product](
      Field("id", IDType, resolve = _.value.id.value),
      Shareable(Field("sku", OptionType(StringType), resolve = _.value.sku))
    )
  )

Issues with that approach:

• it's still possible to use the copy method to apply the directive on any other types.
• the API is not optimal. By applying different directives, the code looks strange:

Shareable(
  External(
    Tag("internal)(
      Field("sku", OptionType(StringType), resolve = _.value.sku)
    )
  )
)

In theory, it would be possible to add extension methods through implicit conversions for a better API:

  implicit class FieldOps[Ctx, Val](field: Field[Ctx, Val]) {
    def shareable: Field[Ctx, Val] = Shareable(field)
    def external: Field[Ctx, Val] = External(field)
  }

  val ProductType: ObjectType[Unit, Product] = ObjectType(
    "Product",
    fields = fields[Unit, Product](
      Field("id", IDType, resolve = _.value.id.value),
      Field("sku", OptionType(StringType), resolve = _.value.sku).shareable.external
    )
  )

but scalac is not clever enough to infer the right types:

ProductGraphQLSchema.scala:55:54: missing parameter type for expanded function ((<x$10: error>) => x$10.value.sku)
[error]       Field("sku", OptionType(StringType), resolve = _.value.sku).shareable.external,

We need to help it, and the result is not optimal:

  val ProductType: ObjectType[Unit, Product] = ObjectType(
    "Product",
    fields = fields[Unit, Product](
      Field("id", IDType, resolve = _.value.id.value), {
        val sku: Field[Unit, Product] = Field("sku", OptionType(StringType), resolve = _.value.sku)
        sku.shareable.external
      },

Adding type safe directive on builders

Another way would be to tag directive to indicate where they can be applied:

    val Shareable: ast.Directive @@ OnField @@ OnObjectType = ast.Directive(
      name = "shareable",
      arguments = Vector.empty
    )

or:

    val Shareable: ast.Directive with OnField with OnObjectType = new ast.Directive(
      name = "shareable",
      arguments = Vector.empty
    ) with OnField with OnObjectType

and then we could add those in apply method:

object Field {
  def apply[](..., directives: (ast.Directive with OnField)*)
}

That way, we could use a directive directly:

Field("sku", OptionType(StringType), resolve = _.value.sku)
->
Field("sku", OptionType(StringType), resolve = _.value.sku, directives = Shareable, External, Tag("internal))

or on a method:

Field("sku", OptionType(StringType), resolve = _.value.sku).directives(Shareable, External, Tag("internal))

This approach seems to most promising:

• directive can declare with the scala type system where they can be applied
• the API user can easily use custom directives

I still have to check if this approach can compile ;)

Next steps

Once this API stabilized, we need to check how to support custom directives with auto-derivation.

[yanns]

Related issues:

• ast.Directive vs schema.Directive #467
• [Feature Request] Ability to add directives #671

[yanns]

Prototypes for a type safe API:

• API for setting custom directives #916
• Better support for custom directives  #915

[yanns]

Prototype for a simple API, not type safe: #918

[yanns]

We will go with #918 first, the simplest API.
#916 could be applied later on top.