Request with directives - collecting use cases - brainstorm

[dtrckd]

elm-graphql lacks the ability the create GraphQL request with directives at that time.

One use case is to be able to perform request with directives such as those available in Dgraph (support native GraphQL request) :

• https://dgraph.io/docs/graphql/custom/directive/
• https://dgraph.io/docs/graphql/queries/cascade/
• https://dgraph.io/docs/graphql/queries/skip-include/

[dtrckd]

Hi,

Other use cases concern the directives available in Hasura. You'll find again the@skip and @include directives.
Here are some examples : https://hasura.io/docs/latest/graphql/core/databases/postgres/queries/variables-aliases-fragments-directives.html#include-if-boolean

But also many more, such as @cached or @stream (#557 ) as described here https://hasura.io/blog/graphql-directives-you-should-know-about/.

[dillonkearns]

Thanks for the conversation and context @dtrckd.

So for reference, here are the parts of the GraphQL Introspection Schema that are related to Directives. This tells us what information we can introspect about a directive:

• Name
• Description
• What context it can be used in (annotating a query, or a field, or a fragment, etc.)
• Its arguments, including their types

type __Directive {
  name: String!
  description: String
  locations: [__DirectiveLocation!]!
  args: [__InputValue!]!
}

enum __DirectiveLocation {
  QUERY
  MUTATION
  SUBSCRIPTION
  FIELD
  FRAGMENT_DEFINITION
  FRAGMENT_SPREAD
  INLINE_FRAGMENT
  SCHEMA
  SCALAR
  OBJECT
  FIELD_DEFINITION
  ARGUMENT_DEFINITION
  INTERFACE
  UNION
  ENUM
  ENUM_VALUE
  INPUT_OBJECT
  INPUT_FIELD_DEFINITION
}

The arguments part is charted territory in elm-graphql - we have several places where we already do that.

The __DirectiveLocation is the new piece. I was thinking about this a bit and how you would model that. That's been the part that trips me up (besides just understanding what exactly GraphQL Directives can be used for and all the nuances of the syntax).

So just to brainstorm on that a bit, let's say you had a directive called @cache with locations: [QUERY].

myRootQuery : SelectionSet MyData RootQuery
myRootQuery = -- ...

myRootQueryWithDirective : SelectionSet MyData RootQuery
myRootQueryWithDirective =
    myRootQuery |> Api.Directive.cache

I believe something along those lines would work for this case (there are still a few details of course around handling arguments, etc. but that's charted territory so shouldn't be problematic).

But there are a few other cases that I'm not sure about.

How to Handle More Complex Directive Locations?

How would we handle cases where you could have multiple directive locations? For example, if something could be on a query, subscription, or mutation? Or on a scalar or union?

Also, in a sense, everything in elm-graphql is an INLINE_FRAGMENT. So would this just not be a constraint in elm-graphql and be treated as applying anywhere?

For composing together multiple possible locations, the idea I described here with using records for the context phantom types could potentially make this sort of thing feasible: #577 (comment). I'm not 100% sure about that, though, and there may be some other cases to consider.

Hopefully that gets the conversation going a bit more! It would be helpful to have a few concrete (and real-world) examples of some directives that you use. Do you think you (or anyone else reading this) could share some?

[megatrond]

Concrete dgraph usecase:

query {
  queryScreening @cascade {
    title
    movie {
      subtitlesLanguage
      spokenLanguage
      screenable {
        audioFormat
        pictureFormat
        dubbed
        duration
        movie {
          title
        }
      }
    }
    ticketSale {
      categories {
        price
        name
      }
    }
  }
}

We have an api for movie screenings, and some of them have null for ticketsale (i.e the screening has been schduled, but for some reason tickets aren't available at the moment.

Adding the @cascade directive to the query causes dgraph to exclude any screening that has null values for any of the fields. It can also take an optional fields argument

query {
  queryScreening  {
    movie  {
      subtitlesLanguage
      spokenLanguage
      screenable @cascade(fields: ["audioFormat"]) {
        audioFormat
        pictureFormat
        dubbed
        duration
        movie {
          title
        }
      }
    }
    ticketSale {
      categories {
        price
        name
      }
    }
  }
}

if you want to be real specific. This will omit any result that have a null value for audioFormat

[megatrond]

I might be reading the introspection query from dgraph wrong, but there seems to be two directives related to queries:

directive @cascade(fields: [String]) on FIELD
directive @cacheControl(maxAge: Int!) on QUERY

dgraphs own docs on both of them:

• https://dgraph.io/docs/graphql/queries/cascade
• https://dgraph.io/docs/graphql/queries/cached-results/

[dtrckd]

I @megatrond, yes it seems to be correct. The example in the doc give clear exampe of where how each directives is used in queries.

[gampleman]

https://graphql.org/blog/2020-12-08-improving-latency-with-defer-and-stream-directives/ seems to be an upcoming specification. The tricky bit here is that this would quite drastically change how the networking works, so would also need to be integrated into the client part of elm-graphql, not just codegen.

[chris-gallo]

A use case I've recently come across is localization directives available via Shopify's storefront API. They offer an @inContext directive in queries and mutations to support internationalization for localized pricing and translatable resources.

---

Examples:

Localized Pricing

query allProducts @inContext(country: CA) {
  products(first: 1) {
    edges {
      node {
        variants(first: 1) {
          edges {
            node {
              price {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
}

mutation @inContext(country: FR) {
  checkoutCreate(input: {
    buyerIdentity: {
      countryCode: FR
    }
  }) {
    checkout {
      buyerIdentity {
        countryCode
      }
      totalPrice {
        amount
        currencyCode # EUR
      }
       lineItems(first: 1) {
        edges {
          node {
            title
            variant {
              price {
                amount
                currencyCode # EUR
              }
            }
          }
        }
      }
    }
  }
}

Translatable Resources

query productDetails @inContext(language: ES) {
  product(handle: "white-t-shirt") {
    title
    description
    descriptionHtml
    options {
      name
      values
    }
  }
}