GraphQL Tools Transformations

The wrapSchema function from @graphql-tools/wrap – GraphQL Tools allows you to wrap an existing schema, add some transformations and as a result get a new schema, implementing a different contract, which is really useful when implementing your own gateway.

Unfortunately, it’s not all that well documented. Consider this to be a work in progress to compensate for that.

First of all, wrapSchema is taking an array of Transform implementations. A Transform itself is not isolated to a specific bit of the underlying schema, or the requests and results passing through it.

export interface Transform<T = Record<string, any>> {  
  transformSchema?: SchemaTransform
  transformRequest?: RequestTransform<T>  
  transformResult?: ResultTransform<T>
}

There are some helper classes easing the construction of a Transform. In most cases, those helper classes allow you to easily isolate the scope of your transformation to particular subset of the schema, and prevent you from having to do all of at the legwork.

In many of those cases, the constructors of those Transform implementations take Transformers. Naming is not really helping here, and it quickly becomes pretty confusing. But here are some basic rules of thumb to preserve your sanity:

1. Transforms are classes that implement the Transform contract.
2. The Transforms provided by graphql-tools never have the word “Transform” in them.
3. Transforms often take Transformer (note the er suffix) instances as constructor arguments.
4. Transformers are functions that perform a specific bit of the transformation.
5. The Transformers defined by graphql-tools all have the word “Transformer” in them, and they are merely defined as function types.
6. Transformers are the functions you need to implement in order to use a graphql-tools provided Transform.
7. Transformer functions with the word Node in their name affect the data passing through the Transform; they typically produce some sort of GraphQL…Config object, representing a part of the schema.
8. Transformer functions without the word Node in their name affect the schema; they typically produce some sort of Node object, representing part of the data floating through the system. (Data that is expected to be compliant with the aforementioned schema..)