feat(graphiql-toolkit)!: accept HeadersInit

.changeset/early-pears-remember.md

@@ -0,0 +1,12 @@
+---
+'@graphiql/toolkit': minor
+'@graphiql/react': patch
+---
+
+`graphiql-toolkit` now accepts `HeadersInit` input.
+
+`graphiql-react` has internal type changes to support this.
+
+BREAKING CHANGE:
+
+Because `graphiql-toolkit` functions now accept HeadersInit where previously a partially wider type of `Record<string, unknown>` was accepted, there is a technical backwards incompatibility. This new stricter type could for example cause your project to fail type checking after this upgrade. At runtime, nothing should change since if you weren't already using `string` typed value headers already then they were being coerced implicitly. In practice, this should only serve to marginally improve your code with trivial effort.

packages/graphiql-react/src/execution.tsx

@@ -147,7 +147,7 @@ export function ExecutionContextProvider({
     }
 
     const headersString = headerEditor?.getValue();
-    let headers: Record<string, unknown> | undefined;
+    let headers: Record<string, string> | undefined;
     try {
       headers = tryParseJsonObject({
         json: headersString,

packages/graphiql-react/src/schema.tsx

@@ -391,7 +391,7 @@ function useIntrospectionQuery({
 }
 
 function parseHeaderString(headersString?: string) {
-  let headers: Record<string, unknown> | null = null;
+  let headers: Record<string, string> | null = null;
   let isValidJSON = true;
 
   try {

packages/graphiql-toolkit/package.json

@@ -23,7 +23,7 @@
     "dev": "tsup --watch",
     "prebuild": "yarn types:check",
     "types:check": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest"
   },
   "dependencies": {
     "@n1ru4l/push-pull-async-iterable-iterator": "^3.1.0",

packages/graphiql-toolkit/src/create-fetcher/__tests__/_helpers.ts

@@ -0,0 +1,36 @@
+/* eslint-disable */
+
+import { Mock, it as itBase } from 'vitest';
+
+export const test = itBase.extend<{
+  fetch: Mock<typeof fetch>;
+  graphqlWs: {
+    createClient: Mock<
+      (parameters: { connectionParams: Record<string, string> }) => any
+    >;
+  };
+}>({
+  // @ts-expect-error fixme
+  fetch: async ({}, use) => {
+    const originalFetch = globalThis.fetch;
+    const mock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response(JSON.stringify({ data: {} })));
+    globalThis.fetch = mock;
+    await use(fetch);
+    globalThis.fetch = originalFetch;
+  },
+  graphqlWs: async ({}, use) => {
+    const graphqlWsExports = {
+      createClient: vi.fn(() => {
+        return {
+          subscribe: vi.fn(),
+        };
+      }),
+    };
+    vi.doMock('graphql-ws', () => {
+      return graphqlWsExports;
+    });
+    await use(graphqlWsExports);
+  },
+});

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

@@ -0,0 +1,77 @@
+/* eslint-disable */
+
+import { parse } from 'graphql';
+import { createGraphiQLFetcher } from '../createFetcher';
+import { test } from './_helpers';
+
+interface TestCase {
+  constructor: HeadersInit;
+  send: HeadersInit;
+  expected: Record<string, string>;
+}
+
+const H = Headers;
+const cases: TestCase[] = [
+  // --- levels merge
+  { constructor: { a:'1' }      , send: { b:'2' }      , expected: { a:'1', b:'2' } },
+  { constructor: [['a','1']]    , send: [['b','2']]    , expected: { a:'1', b:'2' } },
+  { constructor: new H({a:'1'}) , send: new H({b:'2'}) , expected: { a:'1', b:'2' } },
+  // --- send level takes precedence
+  { constructor: { a:'1' }      , send: { a:'2' }      , expected: { a:'2' } },
+  { constructor: [['a','1']]    , send: [['a','2']]    , expected: { a:'2' } },
+  { constructor: new H({a:'1'}) , send: new H({a:'2'}) , expected: { a:'2' } },
+]; // prettier-ignore
+
+describe('accepts HeadersInit on constructor and send levels, send taking precedence', () => {
+  test.for(cases)('%j', async (_case, { fetch }) => {
+    const fetcher = createGraphiQLFetcher({
+      url: 'https://foobar',
+      enableIncrementalDelivery: false,
+      headers: _case.constructor,
+    });
+    await fetcher({ query: '' }, { headers: _case.send });
+    // @ts-expect-error
+    const requestHeaders = Object.fromEntries(new Headers(fetch.mock.calls[0]?.[1]?.headers ?? {}).entries()); // prettier-ignore
+    expect(fetch).toBeCalledTimes(1);
+    expect(requestHeaders).toMatchObject(_case.expected);
+  });
+
+  test.for(cases)('incremental delivery: %j', async (_case, { fetch }) => {
+    const fetcher = createGraphiQLFetcher({
+      url: 'https://foobar',
+      enableIncrementalDelivery: true,
+      headers: _case.constructor,
+    });
+    const result = await fetcher({ query: '' }, { headers: _case.send });
+    // TODO: Improve types to indicate that result is AsyncIterable when enableIncrementalDelivery is true
+    await drainAsyncIterable(result as AsyncIterable<any>);
+    // @ts-expect-error
+    const requestHeaders = Object.fromEntries(new Headers(fetch.mock.calls[0]?.[1]?.headers ?? {}).entries()); // prettier-ignore
+    expect(fetch).toBeCalledTimes(1);
+    expect(requestHeaders).toMatchObject(_case.expected);
+  });
+
+  test.for(cases)('subscription: %j', async (_case, { graphqlWs }) => {
+    const fetcher = createGraphiQLFetcher({
+      url: 'https://foobar',
+      headers: _case.constructor,
+      subscriptionUrl: 'wss://foobar',
+    });
+    await fetcher({ query: '', operationName:'foo' }, { headers: _case.send, documentAST: parse('subscription foo { bar }') }); // prettier-ignore
+    const connectionParams = graphqlWs.createClient.mock.calls[0]?.[0]?.connectionParams ?? {}; // prettier-ignore
+    expect(graphqlWs.createClient).toBeCalledTimes(1);
+    expect(connectionParams).toMatchObject(_case.expected);
+  });
+});
+
+// -------------------------------------------------------------------------------------------------
+// Helpers
+// -------------------------------------------------------------------------------------------------
+
+const drainAsyncIterable = async (iterable: AsyncIterable<any>) => {
+  const result: any[] = [];
+  for await (const item of iterable) {
+    result.push(item);
+  }
+  return result;
+};

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

@@ -13,11 +13,11 @@ import {
  * - optionally supports graphql-ws or `
  */
 export function createGraphiQLFetcher(options: CreateFetcherOptions): Fetcher {
-  const httpFetch =
-    options.fetch || (typeof window !== 'undefined' && window.fetch);
+  const httpFetch = options.fetch ?? globalThis.fetch;
   if (!httpFetch) {
     throw new Error('No valid fetcher implementation available');
   }
+
   options.enableIncrementalDelivery =
     options.enableIncrementalDelivery !== false;
   // simpler fetcher for schema requests
@@ -29,6 +29,7 @@ export function createGraphiQLFetcher(options: CreateFetcherOptions): Fetcher {
 
   return async (graphQLParams, fetcherOpts) => {
     if (graphQLParams.operationName === 'IntrospectionQuery') {
+      // todo test this
       return (options.schemaFetcher || simpleFetcher)(
         graphQLParams,
         fetcherOpts,

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

@@ -1,3 +1,9 @@
+// todo
+// Current TS Config target does not support `Headers.entries()` method.
+// However it is reported as "widely available" and so should be fine to use.
+// @see https://developer.mozilla.org/en-US/docs/Web/API/Headers/entries
+// Several places we currently use ts-expect-error to allow this.
+
 import { DocumentNode, visit } from 'graphql';
 import { meros } from 'meros';
 import type {
@@ -57,14 +63,17 @@ export const isSubscriptionWithName = (
 export const createSimpleFetcher =
   (options: CreateFetcherOptions, httpFetch: typeof fetch): Fetcher =>
   async (graphQLParams: FetcherParams, fetcherOpts?: FetcherOpts) => {
+    const headers = new Headers({
+      'content-type': 'application/json',
+      // @ts-expect-error: todo enable ES target that has entries on headers
+      ...Object.fromEntries(new Headers(options.headers ?? {}).entries()),
+      // @ts-expect-error: todo enable ES target that has entries on headers
+      ...Object.fromEntries(new Headers(fetcherOpts?.headers ?? {}).entries()),
+    });
     const data = await httpFetch(options.url, {
       method: 'POST',
       body: JSON.stringify(graphQLParams),
-      headers: {
-        'content-type': 'application/json',
-        ...options.headers,
-        ...fetcherOpts?.headers,
-      },
+      headers,
     });
     return data.json();
   };
@@ -141,17 +150,18 @@ export const createMultipartFetcher = (
   httpFetch: typeof fetch,
 ): Fetcher =>
   async function* (graphQLParams: FetcherParams, fetcherOpts?: FetcherOpts) {
+    const headers = new Headers({
+      'content-type': 'application/json',
+      accept: 'application/json, multipart/mixed',
+      // @ts-expect-error: todo enable ES target that has entries on headers
+      ...Object.fromEntries(new Headers(options.headers ?? {}).entries()),
+      // @ts-expect-error: todo enable ES target that has entries on headers
+      ...Object.fromEntries(new Headers(fetcherOpts?.headers ?? {}).entries()),
+    });
     const response = await httpFetch(options.url, {
       method: 'POST',
       body: JSON.stringify(graphQLParams),
-      headers: {
-        'content-type': 'application/json',
-        accept: 'application/json, multipart/mixed',
-        ...options.headers,
-        // allow user-defined headers to override
-        // the static provided headers
-        ...fetcherOpts?.headers,
-      },
+      headers,
     }).then(r =>
       meros<Extract<ExecutionResultPayload, { hasNext: boolean }>>(r, {
         multiple: true,
@@ -187,9 +197,15 @@ export async function getWsFetcher(
     return createWebsocketsFetcherFromClient(options.wsClient);
   }
   if (options.subscriptionUrl) {
+    const headers = {
+      // @ts-expect-error: todo enable ES target that has entries on headers
+      ...Object.fromEntries(new Headers(options?.headers ?? {}).entries()),
+      // @ts-expect-error: todo enable ES target that has entries on headers
+      ...Object.fromEntries(new Headers(fetcherOpts?.headers ?? {}).entries()),
+    };
     return createWebsocketsFetcherFromUrl(options.subscriptionUrl, {
       ...options.wsConnectionParams,
-      ...fetcherOpts?.headers,
+      ...headers,
     });
   }
   const legacyWebsocketsClient = options.legacyClient || options.legacyWsClient;

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

@@ -31,7 +31,7 @@ export type FetcherParams = {
 };
 
 export type FetcherOpts = {
-  headers?: { [key: string]: any };
+  headers?: HeadersInit;
   documentAST?: DocumentNode;
 };
 
@@ -104,7 +104,7 @@ export interface CreateFetcherOptions {
    * If you enable the headers editor and the user provides
    * A header you set statically here, it will be overridden by their value.
    */
-  headers?: Record<string, string>;
+  headers?: HeadersInit;
   /**
    * Websockets connection params used when you provide subscriptionUrl. graphql-ws `ClientOptions.connectionParams`
    */