chore: documentation cleanup

Author: acao

packages/graphiql-create-fetcher/src/createFetcher.ts

@@ -35,7 +35,7 @@ export function createGraphiQLFetcher(options: CreateFetcherOptions): Fetcher {
   if (!httpFetch) {
     throw Error('No valid fetcher implementation available');
   }
-
+  // simpler fetcher for schema requests
   const simpleFetcher = createSimpleFetcher(options, httpFetch);
 
   if (options.subscriptionUrl) {
@@ -49,12 +49,15 @@ export function createGraphiQLFetcher(options: CreateFetcherOptions): Fetcher {
     ? createMultipartFetcher(options, httpFetch)
     : simpleFetcher;
 
-  return (graphQLParams, opts) => {
+  return (graphQLParams, fetcherOpts) => {
     if (graphQLParams.operationName === 'IntrospectionQuery') {
-      return simpleFetcher(graphQLParams, opts);
+      return (options.schemaFetcher || simpleFetcher)(
+        graphQLParams,
+        fetcherOpts,
+      );
     }
     const isSubscription = isSubscriptionWithName(
-      opts?.documentAST!,
+      fetcherOpts?.documentAST!,
       graphQLParams.operationName,
     );
     if (isSubscription) {
@@ -69,6 +72,6 @@ export function createGraphiQLFetcher(options: CreateFetcherOptions): Fetcher {
       }
       return wsFetcher(graphQLParams);
     }
-    return httpFetcher(graphQLParams, opts);
+    return httpFetcher(graphQLParams, fetcherOpts);
   };
 }

packages/graphiql-create-fetcher/src/lib.ts

@@ -1,6 +1,6 @@
 import { DocumentNode, visit } from 'graphql';
 import { meros } from 'meros';
-import { createClient, Client } from 'graphql-ws';
+import { createClient, Client, ClientOptions } from 'graphql-ws';
 import { SubscriptionClient } from 'subscriptions-transport-ws';
 import {
   isAsyncIterable,
@@ -67,7 +67,10 @@ export const createSimpleFetcher = (
   return data.json();
 };
 
-export const createWebsocketsFetcherFromUrl = (url: string) => {
+export const createWebsocketsFetcherFromUrl = (
+  url: string,
+  connectionParams?: ClientOptions['connectionParams'],
+) => {
   let wsClient: Client | null = null;
   let legacyClient: SubscriptionClient | null = null;
   if (url) {
@@ -76,12 +79,13 @@ export const createWebsocketsFetcherFromUrl = (url: string) => {
         // TODO: defaults?
         wsClient = createClient({
           url,
+          connectionParams,
         });
         if (!wsClient) {
-          legacyClient = new SubscriptionClient(url);
+          legacyClient = new SubscriptionClient(url, { connectionParams });
         }
       } catch (err) {
-        legacyClient = new SubscriptionClient(url);
+        legacyClient = new SubscriptionClient(url, { connectionParams });
       }
     } catch (err) {
       console.error(`Error creating websocket client for:\n${url}\n\n${err}`);

packages/graphiql-create-fetcher/src/types.ts

@@ -1,5 +1,6 @@
-import type { Client } from 'graphql-ws';
+import type { Client, ClientOptions } from 'graphql-ws';
 import type { SubscriptionClient } from 'subscriptions-transport-ws';
+import type { Fetcher } from '@graphiql/toolkit';
 
 export type WebsocketsClient = Client | SubscriptionClient;
 
@@ -27,6 +28,10 @@ export interface CreateFetcherOptions {
    * A header you set statically here, it will be overriden by their value.
    */
   headers?: Record<string, string>;
+  /**
+   * Websockets connection params used when you provide subscriptionUrl. graphql-ws `ClientOptions.connectionParams`
+   */
+  wsConnectionParams?: ClientOptions['connectionParams'];
   /**
    * You can disable the usage of the `fetch-multipart-graphql` library
    * entirely, defaulting to a simple fetch POST implementation.
@@ -38,4 +43,9 @@ export interface CreateFetcherOptions {
    * default fetch behavior yet.
    */
   fetch?: typeof fetch;
+  /**
+   * An optional custom fetcher specifically for your schema. For most cases
+   * the `url` and `headers` property should have you covered.
+   */
+  schemaFetcher?: Fetcher;
 }

packages/graphiql-toolkit/src/types.ts

@@ -39,14 +39,16 @@ export type FetcherResultPayload =
   | {
       data: IntrospectionQuery;
       errors?: Array<any>;
-      hasNext?: boolean;
     }
-  | { data?: any; errors?: Array<any>; hasNext?: boolean }
-  // for IncrementalDelivery
+  // normal result payloads
+  | { data?: any; errors?: Array<any> }
+  // for the initial Stream/Defer payload
+  | { data?: any; errors?: Array<any>; hasNext: boolean }
+  // for successive Stream/Defer payloads
   | {
       data?: any;
       errors?: any[];
-      path?: (string | number)[];
+      path: (string | number)[];
       hasNext: boolean;
     };
 

packages/graphiql/README.md

@@ -44,8 +44,16 @@ const mockStreamSuccess = {
   hasNext: false,
 };
 
+const testDeferQuery = /* GraphQL */ `
+  query DeferQuery($delay: Int) {
+    streamable(delay: $delay) @stream(initialCount: 2) {
+      text
+    }
+  }
+`;
+
 describe('IncrementalDelivery support via fetcher', () => {
-  it('Expects slower streams to resolve in several increments', () => {
+  it('Expects slower streams to resolve in several increments, and the payloads to patch properly', () => {
     const delay = 100;
     const timeout = mockStreamSuccess.data.streamable.length * (delay * 1.5);
 

packages/graphiql/cypress/integration/incrementalDelivery.spec.ts

@@ -1068,7 +1068,8 @@ export class GraphiQL extends React.Component<GraphiQLProps, GraphiQLState> {
         );
       }
 
-      const totalResponse: FetcherResultPayload = { data: {} };
+      // when dealing with defer or stream, we need to aggregate results
+      const fullResponse: FetcherResultPayload = { data: {}, hasNext: false };
 
       // _fetchQuery may return a subscription.
       const subscription = await this._fetchQuery(
@@ -1080,36 +1081,36 @@ export class GraphiQL extends React.Component<GraphiQLProps, GraphiQLState> {
         (result: FetcherResult) => {
           if (queryID === this._editorQueryID) {
             if (
-              typeof result === 'object' &&
+              typeof result !== 'string' &&
               result !== null &&
               'hasNext' in result
             ) {
               if (result.errors) {
                 // We dont care about "index" here, just concat.
-                totalResponse.errors = [
-                  ...(totalResponse?.errors || []),
+                fullResponse.errors = [
+                  ...(fullResponse?.errors || []),
                   ...result?.errors,
                 ];
               }
 
-              totalResponse.hasNext = result.hasNext;
+              fullResponse.hasNext = result.hasNext;
 
               if ('path' in result) {
                 if (!('data' in result)) {
                   throw new Error(
                     `Expected part to contain a data property, but got ${result}`,
                   );
                 }
-                dset(totalResponse.data, result.path!.map(String), result.data);
+                dset(fullResponse.data, result.path, result.data);
               } else if ('data' in result) {
                 // If there is no path, we don't know what to do with the payload,
                 // so we just set it.
-                totalResponse.data = result.data;
+                fullResponse.data = result.data;
               }
 
               this.setState({
                 isWaitingForResponse: false,
-                response: GraphiQL.formatResult(totalResponse),
+                response: GraphiQL.formatResult(fullResponse),
               });
             } else {
               this.setState({

packages/graphiql/src/components/GraphiQL.tsx

@@ -137,6 +137,34 @@ const Greeting = new GraphQLObjectType({
   },
 });
 
+const delayArgument = (defaultValue = 400) => ({
+  description:
+    'delay in milleseconds for subsequent results, for demonstration purposes',
+  type: GraphQLInt,
+  defaultValue,
+});
+
+const DeferrableObject = new GraphQLObjectType({
+  name: 'Deferrable',
+  fields: {
+    normalString: {
+      type: GraphQLString,
+      resolve: () => `Nice`,
+    },
+    deferredString: {
+      args: {
+        delay: delayArgument(600),
+      },
+      type: GraphQLString,
+      resolve: async function lazilyReturnValue(_value, args) {
+        const seconds = args.delay / 1000;
+        await sleep(args.delay);
+        return `Oops, this took ${seconds} seconds longer than I thought it would!`;
+      },
+    },
+  },
+});
+
 const sleep = async timeout => new Promise(res => setTimeout(res, timeout));
 
 const TestType = new GraphQLObjectType({
@@ -147,15 +175,14 @@ const TestType = new GraphQLObjectType({
       description: '`test` field from `Test` type.',
       resolve: () => ({}),
     },
+    deferrable: {
+      type: DeferrableObject,
+      resolve: () => ({}),
+    },
     streamable: {
       type: new GraphQLList(Greeting),
       args: {
-        delay: {
-          description:
-            'delay in milleseconds for subsequent results, for demonstration purposes',
-          type: GraphQLInt,
-          defaultValue: 400,
-        },
+        delay: delayArgument(300),
       },
       resolve: async function* sayHiInSomeLanguages(_value, args) {
         let i = 0;