[1.0] Add new way to make connections between a node field and another node

[KyleAMathews]

One (of many) beautiful things about GraphQL is it makes it very easy to write queries which jump between multiple node types. But up to now, source plugins couldn't setup those relationships other than putting node IDs in the node "children" array. Which while nice isn't enough. Especially source plugins which are modeling complex data types.

This PR adds a new way for a source plugin author (or anyone extending a node type) to add connections between nodes.

In the simplest case where a field points to another node's id you do:

const nodeA = {
  id: 'super',
  type: 'NodeA',
}

const nodeB = {
  id: 'awesome',
  type: 'NodeB',
  fieldPointingToNodeA___NODE: 'super',
}

Now when Gatsby creates the GraphQL schema for these nodes, it'll see the field in NodeB ending with ___NODE and it'll try to create a connection between the nodes. It'll take super and look up the node with that id (ids are globally unique). When it finds it, it makes the connection between the nodes so that you can then write graphql queries like:

{
  nodeB(id: "awesome') {
    id
    fieldPointingToNodeA {
      id
      type
    }
  }
}

Which returns a JSON object looking like:

{
  nodeB: {
    id: "awesome",
    fieldPointingToNodeA: {
      id: "super",
      type: "NodeA",
    },
}

Fields ending with ___node can have a value of a single node id or an array. If you use an array, all referenced nodes must be of the same type.

But you don't always want to point to an id. Sometimes it's easier to point to a different field's value for whatever reason. In these cases, you can specify on the field the name of the foreign node's field you're referencing to e.g. fieldReference___NODE___anotherField. Warning, ensure this other field is globally unique as well as otherwise the wrong node could be returned.

At some point in the future we might need to add a way source plugins to programmatically find the other node.

[gatsbybot]

Deploy preview ready!

Built with commit f4bb573

https://deploy-preview-902--using-drupal.netlify.com

[gatsbybot]

Deploy preview ready!

Built with commit f4bb573

https://deploy-preview-902--gatsbyjs.netlify.com

[gatsbybot]

Deploy preview ready!

Built with commit f4bb573

https://deploy-preview-902--gatsbygram.netlify.com