docs: add fetcher section to the readme

packages/graphiql/README.md

@@ -325,6 +325,156 @@ In order to theme the editor portions of the interface, you can supply a `editor
 />
 ```
 
+### Fetcher
+
+GraphiQL allows using any GraphQL protocol via the fetcher abstraction. A fetcher could establish a WebSocket connection, do a HTTP call or even execute GraphQL operations against a local schema within the browser.
+
+#### Return Type Overview
+
+A fetcher is allowed to return a `Promise`, `Observable` or `AsyncIterable`. Depending on the needs either one might be sufficient.
+
+##### Promise
+
+A `Promise` is best for used for describing a single result. E.g. a GraphQL Operation that only results in a single execution result that must be delivered to the client.
+
+**Example document for single execution result**
+
+```graphql
+query FetchSomeIDQuery($someId: String!) {
+  human(id: $someId) {
+    name
+  }
+}
+```
+
+A popular protocol for this type of fetcher would be GraphQL over HTTP (without the extended HTTP multipart spec for the stream directives).
+
+**Example fetcher GraphQL over HTTP**
+
+```ts
+function graphQLFetcher(graphQLParams) {
+  return window
+    .fetch(window.location.origin + '/graphql', {
+      method: 'post',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(graphQLParams),
+    })
+    .then(response => response.json());
+}
+```
+
+##### Observable
+
+A `Observable` can describe multiple results. E.g. a GraphQL operation that results in multiple execution results.
+
+A example for this is a subscription operation or the new stream directives ([`@defer` and `@stream`](https://github.com/graphql/graphql-spec/blob/master/rfcs/DeferStream.md)).
+
+**Example document for multiple execution results: Subscription**
+
+```graphql
+subscription OnHumanAddedSubscription {
+  onHumanAdded {
+    id
+    name
+  }
+}
+```
+
+**Example document for multiple execution results: @defer**
+
+```graphql
+query FetchSomeIDQuery($someId: String!) {
+  human(id: $someId) {
+    id
+    ... on Human @defer {
+      name
+    }
+  }
+}
+```
+
+A popular protocol for this type of fetcher would be GraphQL over HTTP (including the HTTP multipart spec) or GraphQL over WebSocket.
+
+Observables are in contrast to Promises and AsyncIterables not part of the ECMAScript specification.
+
+##### AsyncIterable
+
+A `AsyncIterable` can describe multiple results. E.g. a GraphQL operation that results in multiple execution results.
+
+See the Observable section above for a list of sample operations!
+
+A AsyncIterable can do everything a Observable is able to, in addition to that they are also part of the ECMA specification.
+
+The `graphql`, `execute` and `subscribe` functions exported from `graphql.js` return `Promise`/`AsyncIterable`. Therefore they can be used as schema fetcher in the browser with minimal wrapping code.
+
+**Example fetch with local schema**
+
+```ts
+const schema = new graphql.GraphQLSchema({
+  mutation: new graphql.GraphQLObjectType({
+    name: 'Mutation',
+    fields: {
+      ping: {
+        type: graphql.GraphQLBoolean,
+        resolve: () => true,
+      },
+    },
+  }),
+  query: new graphql.GraphQLObjectType({
+    name: 'Query',
+    fields: {
+      ping: {
+        type: graphql.GraphQLBoolean,
+        resolve: () => true,
+      },
+    },
+  }),
+  subscription: new graphql.GraphQLObjectType({
+    name: 'Subscription',
+    fields: {
+      count: {
+        type: graphql.GraphQLInt,
+        subscribe: async function* () {
+          for (let counter = 0; counter < 10; counter++) {
+            yield { count: counter };
+            await new Promise(res => setTimeout(res, 1000));
+          }
+        },
+      },
+    },
+  }),
+});
+
+const fetcher = graphQLParams => {
+  const document = graphql.parse(graphQLParams.query);
+  const operation = graphql.getOperationAST(
+    document,
+    graphQLParams.operationName,
+  );
+  if (operation.operation === 'subscription') {
+    // AsyncIterable
+    return graphql.subscribe(
+      schema,
+      document,
+      {},
+      {},
+      graphQLParams.variables,
+      graphQLParams.operationName,
+    );
+  }
+
+  // Promise or AsyncIterable
+  return graphql.execute(
+    schema,
+    document,
+    {},
+    {},
+    graphQLParams.variables,
+    graphQLParams.operationName,
+  );
+};
+```
+
 ### Query Samples
 
 **Query**