feat: new encapsulation for transport spec

Author: acao

examples/graphiql-create-react-app/package.json

@@ -3,8 +3,6 @@
   "version": "0.1.11-alpha.8",
   "private": true,
   "dependencies": {
-    "@types/react": "^16.9.34",
-    "@types/react-dom": "^16.9.6",
     "graphiql": "file:../../packages/graphiql",
     "graphql": "^15.0.0",
     "react": "^16.13.1",

examples/graphiql-parcel/package.json

@@ -22,8 +22,6 @@
     ]
   },
   "dependencies": {
-    "@types/react": "^16.9.34",
-    "@types/react-dom": "^16.9.6",
     "graphiql": "file:../../packages/graphiql",
     "graphql": "15.0.0",
     "react": "^16.13.1",

package.json

@@ -81,19 +81,21 @@
     "@strictsoftware/typedoc-plugin-monorepo": "^0.3.1",
     "@testing-library/jest-dom": "^5.4.0",
     "@types/codemirror": "^0.0.90",
+    "@types/express": "^4.17.11",
     "@types/fetch-mock": "^7.3.2",
-    "@types/jest": "^26.0.8",
+    "@types/jest": "^26.0.20",
     "@types/node": "^13.11.1",
     "@types/prettier": "^2.0.0",
     "@types/theme-ui": "^0.3.1",
+    "@types/ws": "^7.4.0",
     "@typescript-eslint/eslint-plugin": "^2.27.0",
     "@typescript-eslint/parser": "^2.27.0",
     "babel-eslint": "^10.1.0",
     "babel-jest": "^25.3.0",
     "conventional-changelog-conventionalcommits": "^4.2.3",
     "copy": "^0.3.2",
     "cross-env": "^7.0.2",
-    "cypress": "^4.3.0",
+    "cypress": "^4.7.0",
     "eslint": "^6.8.0",
     "eslint-config-prettier": "^6.10.1",
     "eslint-plugin-babel": "^5.3.0",
@@ -119,7 +121,7 @@
     "rimraf": "^3.0.2",
     "ts-jest": "^25.3.1",
     "typedoc": "^0.19.2",
-    "typescript": "^3.9.5",
+    "typescript": "^4.1.3",
     "whatwg-url": "^8.4.0"
   }
 }

packages/graphiql-build-fetcher/README.md

@@ -0,0 +1,146 @@
+## `@graphiql/build-fetcher`
+
+a utility for generating a full-featured fetcher for GraphiQL.
+
+under the hood, it uses [`graphql-ws`](https://www.npmjs.com/package/graphql-ws) and [`fetch-multipart-graphql`](https://www.npmjs.com/package/fetch-multipart-graphql) to follow the [GraphQL over HTTP Working Group Spec](https://github.com/graphql/graphql-over-http) both accepted and advanced proposals.
+
+### Setup
+
+[`graphiql`](https://npmjs.com/package/graphiql) and thus `react` and `react-dom` should already be installed. 
+
+you'll need to install `@graphiql/build-fetcher`
+
+npm
+```bash
+npm install --save @graphiql/build-fetcher
+```
+
+yarn
+```bash
+yarn add @graphiql/build-fetcher
+```
+
+### Getting Started
+
+We have a few flexible options to get you started with the client. It's  meant to cover the majority of common use cases with a simple encapsulation.
+
+#### HTTP/Multipart Usage
+
+Here's a simple example. In this case, a websocket client isn't even initialized, only http (with multipart `@stream` and `@defer` support of course!).
+
+```ts
+import * as React from "react"
+import ReactDOM from "react-dom"
+import { GraphiQL } from "graphiql"
+import { buildGraphiQLFetcher } from "@graphiql/build-fetcher"
+
+const url = 'https://myschema.com/graphql'
+
+const fetcher = buildGraphiQLFetcher({ url });
+
+export const App = () => <GraphiQL fetcher={fetcher} />;
+
+ReactDOM.render(document.getElementByID('graphiql'), <App />)
+```
+#### HTTP/Multipart & Websockets 
+
+Just by providing the `subscriptionsUrl`, you can generate a `graphql-ws` client
+
+```ts
+import * as React from "react"
+import ReactDOM from "react-dom"
+import { GraphiQL } from "graphiql"
+import { buildGraphiQLFetcher } from "@graphiql/build-fetcher"
+
+const url = 'https://myschema.com/graphql'
+
+const subscriptionsUrl = "wss://myschema.com/graphql"
+
+const fetcher = buildGraphiQLFetcher({ 
+  url, 
+  subscriptionsUrl
+});
+
+export const App = () => <GraphiQL fetcher={fetcher} />;
+
+ReactDOM.render(document.getElementByID('graphiql'), <App />)
+```
+
+You can further customize the `wsClient` implementation below
+
+### Options
+
+#### `url` (*required*)
+
+This is url used for all `HTTP` requests, and for schema introspection.
+
+#### `subscriptionsUrl`
+
+This generates a `graphql-ws` client.
+
+#### `wsClient`
+
+provide your own subscriptions client. bypasses `subscriptionsUrl`. In theory, this could be any client using any transport, as long as it matches `graphql-ws` `Client` signature.
+
+#### `headers`
+
+Pass headers to any and all requests
+
+#### `fetch`
+
+Pass a custom fetch implementation such as `isomorphic-feth`
+
+### Customization Examples
+
+
+
+#### Custom `wsClient` Example
+Just by providing the `subscriptionsUrl`
+
+```ts
+import * as React from "react"
+import ReactDOM from "react-dom"
+import { GraphiQL } from "graphiql"
+import { createClient } from "graphql-ws"
+import { buildGraphiQLFetcher } from "@graphiql/build-fetcher"
+
+const url = 'https://myschema.com/graphql'
+
+const subscriptionsUrl = "wss://myschema.com/graphql"
+
+const fetcher = buildGraphiQLFetcher({ 
+  url, 
+  wsClient: createClient({ 
+    url: subscriptionsUrl , 
+    keepAlive: 2000
+  })
+});
+
+export const App = () => <GraphiQL fetcher={fetcher} />;
+
+ReactDOM.render(document.getElementByID('graphiql'), <App />)
+```
+
+
+#### Custom `fetcher` Example
+For SSR, we might want to use something like `isomorphic-fetch`
+
+```ts
+import * as React from "react"
+import ReactDOM from "react-dom"
+import { GraphiQL } from "graphiql"
+import { fetch } from "isomorphic-fetch"
+import { buildGraphiQLFetcher } from "@graphiql/build-fetcher"
+
+const url = 'https://myschema.com/graphql'
+
+
+const fetcher = buildGraphiQLFetcher({ 
+  url, 
+  fetch
+});
+
+export const App = () => <GraphiQL fetcher={fetcher} />;
+
+ReactDOM.render(document.getElementByID('graphiql'), <App />)
+```

packages/graphiql-build-fetcher/jest.config.js

@@ -0,0 +1,5 @@
+const base = require('../../jest.config.base')(__dirname);
+
+module.exports = {
+  ...base,
+};

packages/graphiql-build-fetcher/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@graphiql/build-fetcher",
+  "version": "0.0.1",
+  "description": "Utility to build a fetcher for GraphiQL",
+  "contributors": [
+    "Rikki Schulte <[email protected]> (http://rikki.dev/"
+  ],
+  "repository": "http://github.com/graphql/graphiql",
+  "homepage": "http://github.com/graphql/graphiql/tree/master/packages/graphiql#readme",
+  "bugs": {
+    "url": "https://github.com/graphql/graphiql/issues?q=issue+label:graphiql"
+  },
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "esm/index.js",
+  "scripts": {
+    "server": "ts-node test/server.ts"
+  },
+  "dependencies": {
+    "graphql-ws": "^4.1.0",
+    "graphql-transport-ws": "^1.9.0",
+    "fetch-multipart-graphql": "^3.0.0",
+    "@n1ru4l/push-pull-async-iterable-iterator": "^2.0.1",
+    "@graphiql/toolkit": "^0.0.1"
+  },
+  "devDependencies": {
+    "isomorphic-fetch": "^3.0.0",
+    "express": "^4.17.1",
+    "express-graphql": "experimental-stream-defer",
+    "ws": "^7.4.2",
+    "ts-node": "^9.1.1"
+  }
+}

packages/graphiql-build-fetcher/src/__tests__/buildFetcher.spec.ts

@@ -0,0 +1,91 @@
+import { parse, getIntrospectionQuery } from 'graphql';
+import { buildGraphiQLFetcher } from '../buildFetcher';
+
+import 'isomorphic-fetch';
+
+jest.mock('../lib');
+
+jest.mock('graphql-ws');
+
+jest.mock('graphql-transport-ws');
+
+import {
+  createWebsocketsClient,
+  createWebsocketsFetcher,
+  createMultipartFetcher,
+  createSimpleFetcher,
+} from '../lib';
+import { createClient } from 'graphql-ws';
+
+const exampleWithSubscripton =  /* GraphQL */ `
+subscription Example {
+  example
+}
+query SomethingElse {
+  example
+}
+`;
+
+const exampleWithSubscriptonNode = parse(exampleWithSubscripton);
+
+const serverURL = 'http://localhost:3000/graphql';
+const wssURL = 'ws://localhost:3000/graphql';
+
+const exampleIntrospectionJson = parse(getIntrospectionQuery());
+
+describe('buildGraphiQLFetcher', () => {
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+  it('returns fetcher without websocket client by default', async () => {
+    createWebsocketsClient.mockReturnValue(true);
+    const fetcher = buildGraphiQLFetcher({ url: serverURL });
+    expect(createWebsocketsClient.mock.calls).toEqual([]);
+    expect(createMultipartFetcher.mock.calls).toEqual([
+      [{ enableMultipart: true, url: serverURL }],
+    ]);
+
+  });
+  it('returns fetcher without websocket client or multipart', () => {
+    createWebsocketsClient.mockReturnValue(true);
+    buildGraphiQLFetcher({ url: serverURL, enableMultipart: false });
+    expect(createWebsocketsClient.mock.calls).toEqual([]);
+    expect(createMultipartFetcher.mock.calls).toEqual([]);
+    expect(createSimpleFetcher.mock.calls).toEqual([
+      [{ enableMultipart: false, url: serverURL }, fetch],
+    ]);
+  });
+  it('returns fetcher with websocket client', () => {
+    createWebsocketsClient.mockReturnValue('Client1');
+
+    const args = {
+      url: serverURL,
+      subscriptionsUrl: wssURL,
+      enableMultipart: true,
+    };
+
+    buildGraphiQLFetcher(args);
+
+    expect(createMultipartFetcher.mock.calls).toEqual([[args]]);
+    expect(createWebsocketsClient.mock.calls).toEqual([[args]]);
+    expect(createWebsocketsFetcher.mock.calls).toEqual([['Client1']]);
+  });
+
+  it('returns fetcher with custom wsClient', () => {
+    createClient.mockReturnValue('WSClient');
+    createWebsocketsFetcher.mockReturnValue('CustomWSSFetcher');
+
+    const wsClient = createClient({ url: wssURL });
+    const args = {
+      url: serverURL,
+      wsClient,
+      enableMultipart: true,
+    };
+
+    buildGraphiQLFetcher(args);
+
+    expect(createMultipartFetcher.mock.calls).toEqual([[args]]);
+    expect(createWebsocketsClient.mock.calls).toEqual([]);
+    expect(createWebsocketsFetcher.mock.calls).toEqual([['WSClient']]);
+  });
+});

packages/graphiql-build-fetcher/src/__tests__/lib.spec.ts

@@ -0,0 +1,57 @@
+import { parse } from 'graphql';
+import { isSubcriptionWithName, createWebsocketsClient } from '../lib';
+
+import "isomorphic-fetch"
+
+
+jest.mock('graphql-ws')
+
+jest.mock("graphql-transport-ws")
+
+
+
+import { createClient } from "graphql-ws"
+
+import { createClient as  createLegacyClient } from "graphql-transport-ws"
+
+const exampleWithSubscripton = /* GraphQL */ parse(`
+  subscription Example {
+    example
+  }
+  query SomethingElse {
+    example
+  }
+`);
+
+describe('isSubcriptionWithName', () => {
+  it('detects when the subscription is present', () => {
+    expect(
+      isSubcriptionWithName(exampleWithSubscripton, 'Example'),
+    ).toBeTruthy();
+  });
+  it('detects when the specified operation is not a subscription', () => {
+    expect(
+      isSubcriptionWithName(exampleWithSubscripton, 'SomethingElse'),
+    ).toBeFalsy();
+  });
+  it('detects when the operation is not present', () => {
+    expect(
+      isSubcriptionWithName(exampleWithSubscripton, 'NotPresent'),
+    ).toBeFalsy();
+  });
+});
+
+describe('createWebsocketsClient', () => {
+  afterEach(() => {
+    // @ts-ignore
+    createClient.mockRestore()
+  })
+  it('creates a websockets client using provided url', () => {
+    createWebsocketsClient({
+      url: 'https://example.com',
+      subscriptionsUrl: 'wss://example.com',
+    });
+    // @ts-ignore
+    expect(createClient.mock.calls[0][0]).toEqual({"url": "wss://example.com"})
+  });
+});