diff --git a/GraphQL-JS.md b/GraphQL-JS.md new file mode 100644 index 00000000..8752bc15 --- /dev/null +++ b/GraphQL-JS.md @@ -0,0 +1,45 @@ +## Differences to GraphQL-JS + +In order to achieve better performance, the `graphql-jit` compiler introduces some limitations. +The primary limitation is that all computed properties must have a resolver and only these can return a `Promise`. + +JIT treats the Promise objects at non-computed properties as values and does not await them. So, in such cases, the return value in GraphQL-JIT would be `null`, whereas in GraphQL-JS it would be the awaited value of the Promise. + +Note: This is not to be confused with async resolvers. Async resolvers are supported and awaited by both GraphQL-JS and GraphQL-JIT. + +As an example of this limitation, consider the following schema and resolvers: + +```graphql +type Query { + foo: Foo +} +type Foo { + bar: String +} +``` + +```ts +const resolvers = { + Query: { + // Promise returning functions are supported in both GraphQL-JS and GraphQL-JIT + async foo() { + await Promise.resolve(); + + return { + // The following Promise is not supported by GraphQL-JIT + // without a resolver defined for bar + // like the commented out resolver below + bar: Promise.resolve("bar") + }; + } + }, + Foo: { + // An example resolver that would make GraphQL-JIT + // await the Promise at value bar. + // + // bar(parent) { + // return parent.bar; + // } + } +}; +``` diff --git a/README.md b/README.md index 1ed93e18..4988d16f 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ code which yields much better performance. `graphql-jit` leverages this behaviou #### Benchmarks GraphQL-JS 16 on Node 16.13.0 + ```bash $ yarn benchmark skip-json Starting introspection @@ -37,6 +38,8 @@ The goal is to support the [June 2018 version of the GraphQL spec](https://faceb In order to achieve better performance, the `graphql-jit` compiler introduces some limitations. The primary limitation is that all computed properties must have a resolver and only these can return a `Promise`. +More details here - [GraphQL-JS.md](./GraphQL-JS.md) + ## Install ```sh @@ -58,7 +61,7 @@ type Query { const resolvers = { Query: { hello() { - return new Promise(resolve => setTimeout(() => resolve("World!"), 200)); + return new Promise((resolve) => setTimeout(() => resolve("World!"), 200)); } } };