createRequest with transforms API

docs/source/schema-delegation.md

@@ -193,8 +193,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` 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(
+  targetSchema: GraphQLSchema,
+  targetOperation: 'query' | 'mutation' | 'subscription',
+  roots: Array<OperationRootDefinition>,
+  documentInfo: 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(
+      subschema,
+      'query',
+      [
+        { 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 },
+]
+```
+
+#### documentInfo: 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

@@ -200,3 +200,10 @@ export type GraphQLParseOptions = {
   allowLegacySDLImplementsInterfaces?: boolean;
   experimentalFragmentVariables?: boolean;
 };
+
+export type OperationRootDefinition = {
+  fieldName: string,
+  alias?: string,
+  args?: { [key: string]: any },
+  info?: GraphQLResolveInfo
+};

src/stitching/delegateToSchema.ts

@@ -1,35 +1,112 @@
 import {
-  ArgumentNode,
-  DocumentNode,
   FieldNode,
-  FragmentDefinitionNode,
+  ArgumentNode,
   Kind,
   OperationDefinitionNode,
   SelectionSetNode,
   SelectionNode,
   subscribe,
   execute,
   validate,
-  VariableDefinitionNode,
+  GraphQLResolveInfo,
   GraphQLSchema,
 } from 'graphql';
 
 import {
-  Operation,
   Request,
   IDelegateToSchemaOptions,
+  Transform,
+  OperationRootDefinition,
 } from '../Interfaces';
 
 import {
   applyRequestTransforms,
-  applyResultTransforms,
+  applyResultTransforms
 } from '../transforms/transforms';
 
 import AddArgumentsAsVariables from '../transforms/AddArgumentsAsVariables';
 import FilterToSchema from '../transforms/FilterToSchema';
 import AddTypenameToAbstract from '../transforms/AddTypenameToAbstract';
 import CheckResultAndHandleErrors from '../transforms/CheckResultAndHandleErrors';
 
+export function createRequest(
+  targetSchema: GraphQLSchema,
+  targetOperation: 'query' | 'mutation' | 'subscription',
+  roots: Array<OperationRootDefinition>,
+  documentInfo: GraphQLResolveInfo,
+  transforms?: Array<Transform>,
+): Request {
+  const selections: Array<SelectionNode> = roots.map(({ fieldName, info, alias }) => {
+    const newSelections: Array<SelectionNode> = info
+      ? [].concat(...info.fieldNodes.map((field: FieldNode) => field.selectionSet ? field.selectionSet.selections : []))
+      : [];
+
+    const args: Array<ArgumentNode> = info
+      ? [].concat( ...info.fieldNodes.map((field: FieldNode) => field.arguments || []))
+      : [];
+
+    const rootSelectionSet = newSelections.length > 0
+      ? {
+        kind: Kind.SELECTION_SET,
+        selections: newSelections
+      }
+      : null;
+
+    const rootField: FieldNode = {
+      kind: Kind.FIELD,
+      name: {
+        kind: Kind.NAME,
+        value: fieldName,
+      },
+      alias: alias
+       ? {
+         kind: Kind.NAME,
+         value: alias
+       }
+       : null,
+       selectionSet: rootSelectionSet,
+       arguments: args
+    };
+
+    return rootField;
+  }, []);
+
+  const selectionSet: SelectionSetNode = {
+    kind: Kind.SELECTION_SET,
+    selections,
+  };
+
+  const operationDefinition: OperationDefinitionNode = {
+    kind: Kind.OPERATION_DEFINITION,
+    operation: targetOperation,
+    variableDefinitions: documentInfo.operation.variableDefinitions,
+    selectionSet,
+  };
+
+  const fragments = Object.keys(documentInfo.fragments).map(
+    fragmentName => documentInfo.fragments[fragmentName],
+  );
+
+  const document = {
+    kind: Kind.DOCUMENT,
+    definitions: [operationDefinition, ...fragments],
+  };
+
+  const rawRequest: Request = {
+    document,
+    variables: documentInfo.variableValues as Record<string, any>,
+  };
+
+  transforms = [
+    ...(transforms || []),
+    new AddArgumentsAsVariables(targetSchema, roots),
+    new FilterToSchema(targetSchema),
+    new AddTypenameToAbstract(targetSchema),
+  ];
+
+  return applyRequestTransforms(rawRequest, transforms);
+}
+
 export default function delegateToSchema(
   options: IDelegateToSchemaOptions | GraphQLSchema,
   ...args: any[],
@@ -46,112 +123,59 @@ export default function delegateToSchema(
 async function delegateToSchemaImplementation(
   options: IDelegateToSchemaOptions,
 ): Promise<any> {
-  const { info, args = {} } = options;
-  const rawDocument: DocumentNode = createDocument(
-    options.fieldName,
-    options.operation,
-    info.fieldNodes,
-    Object.keys(info.fragments).map(
-      fragmentName => info.fragments[fragmentName],
-    ),
-    info.operation.variableDefinitions,
+  const {
+    info,
+    args = {},
+    fieldName,
+    schema,
+    operation,
+    context
+   } = options;
+  const processedRequest = createRequest(
+    schema,
+    operation,
+    [
+      {
+        fieldName,
+        args,
+        info
+      }
+    ],
+    info,
+    options.transforms
   );
 
-  const rawRequest: Request = {
-    document: rawDocument,
-    variables: info.variableValues as Record<string, any>,
-  };
+  const errors = validate(schema, processedRequest.document);
+  if (errors.length > 0) {
+    throw errors;
+  }
 
   const transforms = [
     ...(options.transforms || []),
-    new AddArgumentsAsVariables(options.schema, args),
-    new FilterToSchema(options.schema),
-    new AddTypenameToAbstract(options.schema),
-    new CheckResultAndHandleErrors(info, options.fieldName),
+    new CheckResultAndHandleErrors(info, fieldName),
   ];
 
-  const processedRequest = applyRequestTransforms(rawRequest, transforms);
-
-  const errors = validate(options.schema, processedRequest.document);
-  if (errors.length > 0) {
-    throw errors;
-  }
-
-  if (options.operation === 'query' || options.operation === 'mutation') {
+  if (operation === 'query' || operation === 'mutation') {
     return applyResultTransforms(
       await execute(
-        options.schema,
+        schema,
         processedRequest.document,
         info.rootValue,
-        options.context,
+        context,
         processedRequest.variables,
       ),
       transforms,
     );
   }
 
-  if (options.operation === 'subscription') {
+  if (operation === 'subscription') {
     // apply result processing ???
     return subscribe(
-      options.schema,
+      schema,
       processedRequest.document,
       info.rootValue,
-      options.context,
+      context,
       processedRequest.variables,
     );
   }
 }
-
-function createDocument(
-  targetField: string,
-  targetOperation: Operation,
-  originalSelections: Array<SelectionNode>,
-  fragments: Array<FragmentDefinitionNode>,
-  variables: Array<VariableDefinitionNode>,
-): DocumentNode {
-  let selections: Array<SelectionNode> = [];
-  let args: Array<ArgumentNode> = [];
-
-  originalSelections.forEach((field: FieldNode) => {
-    const fieldSelections = field.selectionSet
-      ? field.selectionSet.selections
-      : [];
-    selections = selections.concat(fieldSelections);
-    args = args.concat(field.arguments || []);
-  });
-
-  let selectionSet = null;
-  if (selections.length > 0) {
-    selectionSet = {
-      kind: Kind.SELECTION_SET,
-      selections: selections,
-    };
-  }
-
-  const rootField: FieldNode = {
-    kind: Kind.FIELD,
-    alias: null,
-    arguments: args,
-    selectionSet,
-    name: {
-      kind: Kind.NAME,
-      value: targetField,
-    },
-  };
-  const rootSelectionSet: SelectionSetNode = {
-    kind: Kind.SELECTION_SET,
-    selections: [rootField],
-  };
-
-  const operationDefinition: OperationDefinitionNode = {
-    kind: Kind.OPERATION_DEFINITION,
-    operation: targetOperation,
-    variableDefinitions: variables,
-    selectionSet: rootSelectionSet,
-  };
-
-  return {
-    kind: Kind.DOCUMENT,
-    definitions: [operationDefinition, ...fragments],
-  };
-}

src/stitching/index.ts

@@ -1,7 +1,7 @@
 import makeRemoteExecutableSchema, { createResolver as defaultCreateRemoteResolver } from './makeRemoteExecutableSchema';
 import introspectSchema from './introspectSchema';
 import mergeSchemas from './mergeSchemas';
-import delegateToSchema from './delegateToSchema';
+import delegateToSchema, { createRequest } from './delegateToSchema';
 import defaultMergedResolver from './defaultMergedResolver';
 
 export {
@@ -12,5 +12,6 @@ export {
   // but exposed for the community use
   delegateToSchema,
   defaultMergedResolver,
+  createRequest,
   defaultCreateRemoteResolver
 };