API suggestions

[josephsavona]

Hey @robrichard! Thanks again for publishing this! Following up on our discussion on your PR, I have a couple suggestions for the API. Mainly it would be nice to hide the details a bit - for example not requiring the user to call retain() or sendQuery(). An example of this style is @denvned's https://github.com/denvned/isomorphic-relay

For Relay Modern, the equivalent might be something like:

// server
import { prefetchQuery, Renderer } from '...';

async function serverRender() {
  const {data, props} = await prefetchQuery(environment, graphql`...`, variables); // throws on error
  const markup = React.renderToString(
    <Renderer {...props} />
  );
  // render markup plus JSON.stringify(data)
}

// client
import {loadPrefetchedQuery, Renderer} from '...';
const props = loadPrefetchedQuery(env, query, vars, data); // data is JSON.parse(...) of data from server
ReactDOM.render(
  <Renderer {...props} />
);

Key points are that the details are hidden from the user, and that Renderer accepts input that is most easily created by executing one of prefetchQuery() (server) or loadPrefetchedQuery() (client). As far as loading prefetched data on the client, you can use environment.getStore().publish(new Source(data)).