Add SSE subscription support to GraphiQL fetcher

Author: rushrs

.changeset/silent-lemons-learn.md

@@ -0,0 +1,5 @@
+---
+'@graphiql/toolkit': minor
+---
+
+Add GraphQL over SSE support to `createGraphiQLFetcher`.

packages/graphiql-toolkit/README.md

@@ -14,5 +14,5 @@ that are useful when working with these packages.
 
 - **[`createFetcher`](./docs/create-fetcher.md)** : a utility for creating a
   `fetcher` prop implementation for HTTP GET, POST including multipart,
-  websockets fetcher
+  GraphQL over SSE and websockets subscriptions
 - more to come!

packages/graphiql-toolkit/docs/create-fetcher.md

@@ -2,10 +2,11 @@
 
 A utility for generating a full-featured `fetcher` for GraphiQL including
 `@stream`, `@defer` `IncrementalDelivery`and `multipart` and subscriptions using
-`graphql-ws` or the legacy websockets protocol.
+GraphQL over SSE, `graphql-ws` or the legacy websockets protocol.
 
-Under the hood, it uses [`graphql-ws`](https://www.npmjs.com/package/graphql-ws)
-client and [`meros`](https://www.npmjs.com/package/meros) which act as client
+Under the hood, it uses [`graphql-sse`](https://www.npmjs.com/package/graphql-sse),
+[`graphql-ws`](https://www.npmjs.com/package/graphql-ws) and
+[`meros`](https://www.npmjs.com/package/meros) which act as client
 reference implementations of the
 [GraphQL over HTTP Working Group Spec](https://github.com/graphql/graphql-over-http)
 specification, and the most popular transport spec proposals.
@@ -45,6 +46,54 @@ const root = createRoot(document.getElementById('graphiql'));
 root.render(<App />);
 ```
 
+### Adding GraphQL over SSE subscriptions
+
+First you'll need to install `graphql-sse` as a peer dependency:
+
+```bash
+npm install graphql-sse
+```
+
+When loading GraphiQL from an ESM CDN with an import map, make sure the optional
+`graphql-sse` peer dependency is also mapped if you use `sseUrl`:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit",
+      "graphql": "https://esm.sh/graphql",
+      "graphql-sse": "https://esm.sh/graphql-sse?external=graphql"
+    }
+  }
+</script>
+```
+
+Just by providing the `sseUrl`, you can generate a `graphql-sse` client. This
+client supports HTTP/Multipart Incremental Delivery for `@defer` and `@stream`,
+_and_ subscriptions over Server-Sent Events.
+
+```jsx
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+import { GraphiQL } from 'graphiql';
+import { createGraphiQLFetcher } from '@graphiql/toolkit';
+
+const url = 'https://my-schema.com/graphql';
+
+const sseUrl = 'https://my-schema.com/graphql/stream';
+
+const fetcher = createGraphiQLFetcher({ url, sseUrl });
+
+export const App = () => <GraphiQL fetcher={fetcher} />;
+
+const root = createRoot(document.getElementById('graphiql'));
+root.render(<App />);
+```
+
+You can further customize the `graphql-sse` implementation by creating a custom
+client instance and providing it as the `sseClient` parameter.
+
 ### Adding `graphql-ws` websockets subscriptions
 
 First you'll need to install `graphql-ws` as a peer dependency:
@@ -90,6 +139,24 @@ This generates a `graphql-ws` client using the provided url. Note that a server
 must be compatible with the new `graphql-ws` subscriptions spec for this to
 work.
 
+### `sseUrl`
+
+This generates a `graphql-sse` client using the provided url. Note that a server
+must be compatible with the GraphQL over SSE protocol for this to work. When
+`sseUrl` or `sseClient` is provided, GraphiQL uses SSE for subscriptions instead
+of websockets.
+
+### `sseClient`
+
+Provide your own GraphQL over SSE subscriptions client. Using this option
+bypasses `sseUrl`. In theory, this could be any client using any transport, as
+long as it matches the `graphql-sse` client signature.
+
+### `sseClientOptions`
+
+Provide additional options used when creating a `graphql-sse` client from
+`sseUrl`, for example `singleConnection`.
+
 ### `wsClient`
 
 Provide your own subscriptions client. Using this option bypasses
@@ -129,6 +196,35 @@ Pass a custom fetch implementation such as `isomorphic-fetch`.
 
 ## Customization Examples
 
+### Custom `sseClient` Example using `graphql-sse`
+
+This example passes a `graphql-sse` client to the `sseClient` option:
+
+```jsx
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+import { GraphiQL } from 'graphiql';
+import { createClient } from 'graphql-sse';
+import { createGraphiQLFetcher } from '@graphiql/toolkit';
+
+const url = 'https://my-schema.com/graphql';
+
+const sseUrl = 'https://my-schema.com/graphql/stream';
+
+const fetcher = createGraphiQLFetcher({
+  url,
+  sseClient: createClient({
+    url: sseUrl,
+    singleConnection: true,
+  }),
+});
+
+export const App = () => <GraphiQL fetcher={fetcher} />;
+
+const root = createRoot(document.getElementById('graphiql'));
+root.render(<App />);
+```
+
 ### Custom `wsClient` Example using `graphql-ws`
 
 This example passes a `graphql-ws` client to the `wsClient` option:

packages/graphiql-toolkit/package.json

@@ -30,16 +30,21 @@
   },
   "devDependencies": {
     "graphql": "^16.9.0",
+    "graphql-sse": "^2.6.0",
     "graphql-ws": "^5.5.5",
     "isomorphic-fetch": "^3.0.0",
     "subscriptions-transport-ws": "0.11.0",
     "tsup": "^8.2.4"
   },
   "peerDependencies": {
     "graphql": "^15.5.0 || ^16.0.0 || ^17.0.0",
+    "graphql-sse": ">= 2.0.0",
     "graphql-ws": ">= 4.5.0"
   },
   "peerDependenciesMeta": {
+    "graphql-sse": {
+      "optional": true
+    },
     "graphql-ws": {
       "optional": true
     }

packages/graphiql-toolkit/src/create-fetcher/__tests__/buildFetcher.spec.ts

@@ -16,14 +16,22 @@ import {
   createSimpleFetcher as _createSimpleFetcher,
   createWebsocketsFetcherFromClient as _createWebsocketsFetcherFromClient,
   createLegacyWebsocketsFetcher as _createLegacyWebsocketsFetcher,
+  getSubscriptionFetcher as _getSubscriptionFetcher,
+  isSubscriptionWithName as _isSubscriptionWithName,
 } from '../lib';
 import { createClient as _createClient } from 'graphql-ws';
 import { SubscriptionClient } from 'subscriptions-transport-ws';
 
 const serverURL = 'http://localhost:3000/graphql';
 const wssURL = 'ws://localhost:3000/graphql';
+const sseURL = 'http://localhost:3000/graphql/stream';
 
 const exampleIntrospectionDocument = parse(getIntrospectionQuery());
+const exampleSubscriptionDocument = parse(/* GraphQL */ `
+  subscription Example {
+    example
+  }
+`);
 
 const createWebsocketsFetcherFromUrl = _createWebsocketsFetcherFromUrl as Mock<
   typeof _createWebsocketsFetcherFromUrl
@@ -42,6 +50,12 @@ const createWebsocketsFetcherFromClient =
 const createLegacyWebsocketsFetcher = _createLegacyWebsocketsFetcher as Mock<
   typeof _createLegacyWebsocketsFetcher
 >;
+const getSubscriptionFetcher = _getSubscriptionFetcher as Mock<
+  typeof _getSubscriptionFetcher
+>;
+const isSubscriptionWithName = _isSubscriptionWithName as Mock<
+  typeof _isSubscriptionWithName
+>;
 
 describe('createGraphiQLFetcher', () => {
   afterEach(() => {
@@ -138,4 +152,31 @@ describe('createGraphiQLFetcher', () => {
     expect(createWebsocketsFetcherFromClient.mock.calls).toEqual([]);
     expect(createLegacyWebsocketsFetcher.mock.calls).toEqual([]);
   });
+
+  it('uses the subscription fetcher for subscription operations', async () => {
+    const subscriptionFetcher = vi.fn(() => ({ data: { example: true } }));
+    isSubscriptionWithName.mockReturnValue(true);
+    getSubscriptionFetcher.mockResolvedValue(subscriptionFetcher);
+
+    const args = {
+      url: serverURL,
+      sseUrl: sseURL,
+      enableIncrementalDelivery: true,
+    };
+    const graphQLParams = {
+      query: 'subscription Example { example }',
+      operationName: 'Example',
+    };
+    const fetcherOpts = {
+      documentAST: exampleSubscriptionDocument,
+      headers: { authorization: 'Bearer token' },
+    };
+
+    const fetcher = createGraphiQLFetcher(args);
+    const result = await fetcher(graphQLParams, fetcherOpts);
+
+    expect(getSubscriptionFetcher.mock.calls).toEqual([[args, fetcherOpts]]);
+    expect(subscriptionFetcher.mock.calls).toEqual([[graphQLParams]]);
+    expect(result).toEqual({ data: { example: true } });
+  });
 });