Discussion around GraphQL schema decorators

[helfer]

Here's a draft spec for GraphQL schema decorators: https://github.com/apollostack/graphql-tools/blob/master/graphql-decorator-spec.md

It's only a draft so far. I'd love to get feedback on the following points:

• Is the purpose of schema decorators made clear?
• Does the spec make sense?
• What decorators would you want to implement / use?

Feedback on points not listed above is of course also appreciated!

The main motivation for decorators is to make Apollo highly extensible, so anyone can easily write their decorators, which the whole community can use.

[johnthepink]

@helfer yea this makes sense to me. I'd use something like this for user permissions and auth. Logging is helpful too. Nice work!

[jbaxleyiii]

@helfer I like the + usage since the decorators give additive value.

I think something like @depreciation should be added to the schema spec but in the interim, this works great.

I'm a fan. 👍

[helfer]

@jbaxleyiii Yeah, I wanted to use @, but then people will confuse it with directives. The two concepts should really be merged, but unfortunately directives are very narrow and not reusable at the moment, and they come after the thing they modify, which I think looks really weird with decorators.

[stubailo]

What's the plan for adding the + syntax? Do we have to fork the parser?

[helfer]

Yeah, we have to fork the parser (and maybe buildASTSchema), but if my latest PR gets merged, it will produce schemas that are 100% compatible with the current version of graphql-js.

If we want to return that data in the introspection query as well, then we have to create our own versions of some other stuff as well. I think it's worth it though, because those features will eventually make their way into GraphQL, and temporary forks will give us an opportunity to iterate much much faster.

[helfer]

Moved here: https://github.com/apollostack/graphql-decorators

[emmanuelbuah]

are graphql decorators included in current release/npm version?

[helfer]

@emmanuelbuah no, we haven't done anything in that direction yet.

[emmanuelbuah]

Thanks for the quick response.

[linonetwo]

I'm imagining a way to change schema by a mutation:

When doing RESTful endpoint wrapping, some endpoint will return a huge amount of data, and thus I need to do some caching at the wrapping layer.
So I can write:

+cache(period: 3600)
type ConfigType {
  alarmTypes(forceUpdate: Boolean): [AlarmCodeType!]!
}

To describe that this type of data can be cached for 3600ms at wrapping layer. And if needed, it can be forced update.

But if there are some emergency, and at this kind of time, other people will probably update lots of alarmCode to the server, but I still don't want to query REST endpoint every time I query graphQL layer. So client side caching time should be shortened for this period of time.

Can I write this? :

type CacheTimeType {
  time: Int!
}

+cache(period: time on CacheTimeType)
type ConfigType {
  alarmTypes(forceUpdate: Boolean): [AlarmCodeType!]!
}

I'm not very clear about it, just imagining : )

[helfer]

I think it's useful to set a shorter cache timeout sometimes, but I think it doesn't make sense to add a lot of additional complexity to the schema, like dynamic decorators. But for this kind of decorator you could definitely have a variable cache timeout. Rather than saying something like time on CacheTimeType, I would then give it a full query, which can be run against the same schema at the time of query execution, or is sent to the client, which then sends the query.

However, I think this may still not solve your problem, because those clients that got the old cache timeout will not refetch for one hour, at which point your emergency might already be over. And anyway, I think in those cases you could also manually update your schema to have a shorter timeout, so I'm not 100% convinced that this is a great use-case.