createRequest with transforms API

docs/source/schema-delegation.md

@@ -196,8 +196,105 @@ Also provides the `info.mergeInfo.delegateToSchema` function discussed above.
 
 [Transforms](./schema-transforms.html) to apply to the query and results. Should be the same transforms that were used to transform the schema, if any. After transformation, `transformedSchema.transforms` contains the transforms that were applied.
 
+<h3 id="createRequest">createRequest</h3>
+
+The `createRequest` function is a utility function for creating queries with multiple, aliased, roots and possible argument name collisions. The function should be called with these parameters:
+
+```js
+createRequest(options: {
+  schema: GraphQLSchema;
+  operation: 'query' | 'mutation' | 'subscription';
+  roots: Array<OperationRootDefinition>;
+  info: GraphQLResolveInfo;
+  transforms?: Array<Transform>;
+}): Request
+```
+
+where `OperationRootDefinition` is the following:
+```js
+type OperationRootDefinition = {
+  fieldName: string,
+  // string to rename the root fieldName as
+  alias?: string,
+  // args passed to the root field
+  args?: { [key: string]: any },
+  // contains the `fieldNodes` that will act as the root field's selection set
+  info?: GraphQLResolveInfo
+};
+```
+
+#### Example
+```js
+User: {
+  bookings(parent, args, context, info) {
+    const { document, variables } = createRequest({
+      schema: subschema,
+      operation: 'query',
+      roots: [
+        { fieldName: 'node', alias: 'booking1', args: { id: 'b1' }, info },
+        { fieldName: 'node', alias: 'booking2', args: { id: 'b2' }, info },
+      ],
+      info
+    })
+    return graphql.execute(
+      subschema,
+      document,
+      {},
+      context,
+      variables
+    ).then(result => {
+      return Object.values(result.data) // turn aliased keys into array of values
+    })
+  }
+},
+```
+
+#### schema: GraphQLSchema
+
+A subschema to get type information from.
+
+#### operation: 'query' | 'mutation' | 'subscription'
+
+An operation to use during the delegation.
+
+#### roots: Array<OperationRootDefinition>
+
+A list of root definitions. This is where you can define multiple root fields for your query, as well as which args should be passed to each, and if they should be aliased or not
+
+##### Example
+```js
+[
+  // Info contains your selections, which in this case would be something like `['id']`
+  { fieldName: 'node', alias: 'user1', args: { id: '1' }, info },
+  { fieldName: 'node', alias: 'user2', args: { id: '2' }, info },
+]
+```
+
+#### info: GraphQLResolveInfo
+
+Info object containing fields that are not specific to root fields, but rather the document as a whole, like `fragments` and other `variableValues`
+
+#### transforms: Array<Transform>
+
+[Transforms](./transforms.html) to apply to the query and results. Should be the same transforms that were used to transform the schema, if any. One can use `transformedSchema.transforms` to retrieve transforms.
+
 <h2 id="considerations">Additional considerations</h2>
 
 ### Aliases
 
 Delegation preserves aliases that are passed from the parent query. However that presents problems, because default GraphQL resolvers retrieve field from parent based on their name, not aliases. This way results with aliases will be missing from the delegated result. `mergeSchemas` and `transformSchemas` go around that by using `src/stitching/defaultMergedResolver` for all fields without explicit resolver. When building new libraries around delegation, one should consider how the aliases will be handled.
+
+However, to create an aliased query/mutation, you can use `createRequest` and pass the resulting `document` and `variables` into `graphql` (or `execute` or your own fetcher). For example:
+```js
+import { graphql } from 'graphql'
+
+const { document, variables } = createRequestResult
+
+graphql(
+  schema,
+  print(document),
+  rootValue,
+  context,
+  variables
+)
+```

src/Interfaces.ts

@@ -61,6 +61,14 @@ export interface IDelegateToSchemaOptions<TContext = { [key: string]: any }> {
   skipValidation?: boolean;
 }
 
+export interface ICreateRequestOptions {
+  schema: GraphQLSchema;
+  operation: 'query' | 'mutation' | 'subscription';
+  roots: Array<OperationRootDefinition>;
+  info: IGraphQLToolsResolveInfo;
+  transforms?: Array<Transform>;
+}
+
 export type MergeInfo = {
   delegate: (
     type: 'query' | 'mutation' | 'subscription',
@@ -213,3 +221,10 @@ export type GraphQLParseOptions = {
   allowLegacySDLImplementsInterfaces?: boolean;
   experimentalFragmentVariables?: boolean;
 };
+
+export type OperationRootDefinition = {
+  fieldName: string,
+  alias?: string,
+  args?: { [key: string]: any },
+  info?: GraphQLResolveInfo
+};