separateOperations - a utility function for splitting an AST (#456)

* separateOperations - a utility function for splitting one AST into one per operation.

A typical task using GraphQL at Facebook looks something like:

1. Load and parse all .graphql files which may contain operations or fragments.
2. Use `concatAST` to produce one AST that contains all operations and fragments.
3. Separate this all-encompasing AST into individual ASTs that represent each operation which could be sent to the server in isolation.

`separateOperations` fulfills this third step.

* add flow types, more tests

Author: leebyron

src/index.js

@@ -192,6 +192,9 @@ export {
   // Concatenates multiple AST together.
   concatAST,
 
+  // Separates an AST into an AST per Operation.
+  separateOperations,
+
   // Comparators for types
   isEqualType,
   isTypeSubTypeOf,

src/utilities/__tests__/separateOperations-test.js

@@ -0,0 +1,180 @@
+/**
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+import { describe, it } from 'mocha';
+import { expect } from 'chai';
+import { separateOperations } from '../separateOperations';
+import { parse, print } from '../../language';
+
+
+describe('separateOperations', () => {
+
+  it('separates one AST into multiple, maintaining document order', () => {
+
+    const ast = parse(`
+      {
+        ...Y
+        ...X
+      }
+
+      query One {
+        foo
+        bar
+        ...A
+        ...X
+      }
+
+      fragment A on T {
+        field
+        ...B
+      }
+
+      fragment X on T {
+        fieldX
+      }
+
+      query Two {
+        ...A
+        ...Y
+        baz
+      }
+
+      fragment Y on T {
+        fieldY
+      }
+
+      fragment B on T {
+        something
+      }
+    `);
+
+    const separatedASTs = separateOperations(ast);
+
+    expect(Object.keys(separatedASTs)).to.deep.equal([ '', 'One', 'Two' ]);
+
+    expect(print(separatedASTs[''])).to.equal(
+`{
+  ...Y
+  ...X
+}
+
+fragment X on T {
+  fieldX
+}
+
+fragment Y on T {
+  fieldY
+}
+`
+    );
+
+    expect(print(separatedASTs.One)).to.equal(
+`query One {
+  foo
+  bar
+  ...A
+  ...X
+}
+
+fragment A on T {
+  field
+  ...B
+}
+
+fragment X on T {
+  fieldX
+}
+
+fragment B on T {
+  something
+}
+`
+    );
+
+    expect(print(separatedASTs.Two)).to.equal(
+`fragment A on T {
+  field
+  ...B
+}
+
+query Two {
+  ...A
+  ...Y
+  baz
+}
+
+fragment Y on T {
+  fieldY
+}
+
+fragment B on T {
+  something
+}
+`
+    );
+
+  });
+
+  it('survives circular dependencies', () => {
+
+    const ast = parse(`
+      query One {
+        ...A
+      }
+
+      fragment A on T {
+        ...B
+      }
+
+      fragment B on T {
+        ...A
+      }
+
+      query Two {
+        ...B
+      }
+    `);
+
+    const separatedASTs = separateOperations(ast);
+
+    expect(Object.keys(separatedASTs)).to.deep.equal([ 'One', 'Two' ]);
+
+    expect(print(separatedASTs.One)).to.equal(
+`query One {
+  ...A
+}
+
+fragment A on T {
+  ...B
+}
+
+fragment B on T {
+  ...A
+}
+`
+    );
+
+    expect(print(separatedASTs.Two)).to.equal(
+`fragment A on T {
+  ...B
+}
+
+fragment B on T {
+  ...A
+}
+
+query Two {
+  ...B
+}
+`
+    );
+
+  });
+
+});

src/utilities/index.js

@@ -48,6 +48,9 @@ export { isValidLiteralValue } from './isValidLiteralValue';
 // Concatenates multiple AST together.
 export { concatAST } from './concatAST';
 
+// Separates an AST into an AST per Operation.
+export { separateOperations } from './separateOperations';
+
 // Comparators for types
 export {
   isEqualType,

src/utilities/separateOperations.js

@@ -0,0 +1,90 @@
+/* @flow */
+/**
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+import { visit } from '../language/visitor';
+import type {
+  Document,
+  OperationDefinition,
+} from '../language/ast';
+
+/**
+ * separateOperations accepts a single AST document which may contain many
+ * operations and fragments and returns a collection of AST documents each of
+ * which contains a single operation as well the fragment definitions it
+ * refers to.
+ */
+export function separateOperations(
+  documentAST: Document
+): { [operationName: string]: Document } {
+
+  const operations = [];
+  const depGraph: DepGraph = Object.create(null);
+  let fromName;
+
+  // Populate the list of operations and build a dependency graph.
+  visit(documentAST, {
+    OperationDefinition(node) {
+      operations.push(node);
+      fromName = opName(node);
+    },
+    FragmentDefinition(node) {
+      fromName = node.name.value;
+    },
+    FragmentSpread(node) {
+      const toName = node.name.value;
+      (depGraph[fromName] ||
+        (depGraph[fromName] = Object.create(null)))[toName] = true;
+    }
+  });
+
+  // For each operation, produce a new synthesized AST which includes only what
+  // is necessary for completing that operation.
+  const separatedDocumentASTs = Object.create(null);
+  operations.forEach(operation => {
+    const operationName = opName(operation);
+    const dependencies = Object.create(null);
+    collectTransitiveDependencies(dependencies, depGraph, operationName);
+
+    separatedDocumentASTs[operationName] = {
+      kind: 'Document',
+      definitions: documentAST.definitions.filter(def =>
+        def === operation ||
+        def.kind === 'FragmentDefinition' && dependencies[def.name.value]
+      )
+    };
+  });
+
+  return separatedDocumentASTs;
+}
+
+type DepGraph = {[from: string]: {[to: string]: boolean}};
+
+// Provides the empty string for anonymous operations.
+function opName(operation: OperationDefinition): string {
+  return operation.name ? operation.name.value : '';
+}
+
+// From a dependency graph, collects a list of transitive dependencies by
+// recursing through a dependency graph.
+function collectTransitiveDependencies(
+  collected: {[key: string]: boolean},
+  depGraph: DepGraph,
+  fromName: string
+): void {
+  const immediateDeps = depGraph[fromName];
+  if (immediateDeps) {
+    Object.keys(immediateDeps).forEach(toName => {
+      if (!collected[toName]) {
+        collected[toName] = true;
+        collectTransitiveDependencies(collected, depGraph, toName);
+      }
+    });
+  }
+}