feat: support TypedDocumentString as query argument

README.md

@@ -260,6 +260,46 @@ Additionally, `GraphQlQueryResponseData` has been exposed to users:
 import type { GraphQlQueryResponseData } from "@octokit/graphql";
 ```
 
+### Usage with graphql-codegen
+
+If your query is represented as a `String & DocumentTypeDecoration`, for example as [`TypedDocumentString` from graphql-codegen and its client preset](https://the-guild.dev/graphql/codegen/docs/guides/vanilla-typescript), then you can get type-safety for the query's parameters and return values.
+
+Assuming you have configured graphql-codegen, with [GitHub's GraphQL schema](https://docs.github.com/en/graphql/overview/public-schema), and an output under `./graphql`:
+
+```tsx
+import * as octokit from "@octokit/graphql";
+
+// The graphql query factory from graphql-codegen's output
+import { graphql } from "./graphql/graphql.js";
+
+const result = await octokit.graphql(
+  graphql`
+    query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
+      repository(owner: $owner, name: $repo) {
+        issues(last: $num) {
+          edges {
+            node {
+              title
+            }
+          }
+        }
+      }
+    }
+  `,
+  {
+    owner: "octokit",
+    repo: "graphql.js",
+    headers: {
+      authorization: `token secret123`,
+    },
+  },
+  // ^ parameters are required; owner and repo are type-checked
+);
+
+type Return = typeof result;
+//   ^? { repository: {issues: {edges: Array<{node: {title: string}>}} }
+```
+
 ## Errors
 
 In case of a GraphQL error, `error.message` is set to a combined message describing all errors returned by the endpoint.

package.json

@@ -24,6 +24,7 @@
   "author": "Gregor Martynus (https://github.com/gr2m)",
   "license": "MIT",
   "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
     "@octokit/request": "^9.1.4",
     "@octokit/types": "^13.6.2",
     "universal-user-agent": "^7.0.0"

src/types.ts

@@ -4,6 +4,8 @@ import type {
   EndpointInterface,
 } from "@octokit/types";
 
+import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
+
 import type { graphql } from "./graphql.js";
 
 export type GraphQlEndpointOptions = EndpointOptions & {
@@ -33,6 +35,25 @@ export interface graphql {
     parameters?: RequestParameters,
   ): GraphQlResponse<ResponseData>;
 
+  /**
+   * Sends a GraphQL query request based on endpoint options. The query parameters are type-checked
+   *
+   * @param {String & DocumentTypeDecoration<ResponseData, QueryVariables>} query GraphQL query. Example: `'query { viewer { login } }'`.
+   * @param {object} [parameters] URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
+   */
+  <ResponseData, QueryVariables>(
+    query: String & DocumentTypeDecoration<ResponseData, QueryVariables>,
+    /**
+     * The tuple in rest parameters allows makes RequestParameters conditionally
+     * optional , if the query does not require any variables.
+     *
+     * @see https://github.com/Microsoft/TypeScript/pull/24897#:~:text=not%20otherwise%20observable).-,Optional%20elements%20in%20tuple%20types,-Tuple%20types%20now
+     */
+    ...[parameters]: QueryVariables extends Record<string, never>
+      ? [RequestParameters?]
+      : [QueryVariables & RequestParameters]
+  ): GraphQlResponse<ResponseData>;
+
   /**
    * Returns a new `endpoint` with updated route and parameters
    */

src/with-defaults.ts

@@ -5,17 +5,34 @@ import type {
   RequestParameters,
 } from "./types.js";
 import { graphql } from "./graphql.js";
+import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
 
 export function withDefaults(
   request: typeof Request,
   newDefaults: RequestParameters,
 ): ApiInterface {
   const newRequest = request.defaults(newDefaults);
   const newApi = <ResponseData>(
-    query: Query | RequestParameters,
+    query:
+      | Query
+      | (String & DocumentTypeDecoration<unknown, unknown>)
+      | RequestParameters,
     options?: RequestParameters,
   ) => {
-    return graphql<ResponseData>(newRequest, query, options);
+    const innerQuery =
+      typeof query === "string"
+        ? query
+        : // Allows casting String & DocumentTypeDecoration<unknown, unknown> to
+          // string. This could be replaced with an instanceof check if we had
+          // access to a shared TypedDocumentString. Alternatively, we could use
+          // string & TypedDocumentDecoration<unknown, unknown> as the external
+          // interface, and push `.toString()` onto the caller, which might not
+          // be the worst idea.
+          String.prototype.isPrototypeOf(query)
+          ? query.toString()
+          : (query as RequestParameters);
+
+    return graphql<ResponseData>(newRequest, innerQuery, options);
   };
 
   return Object.assign(newApi, {

test/graphql.test.ts

@@ -5,9 +5,25 @@ import { getUserAgent } from "universal-user-agent";
 import { graphql } from "../src";
 import { VERSION } from "../src/version";
 import type { RequestParameters } from "../src/types";
+import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
 
 const userAgent = `octokit-graphql.js/${VERSION} ${getUserAgent()}`;
 
+class TypedDocumentString<TResult, TVariables>
+  extends String
+  implements DocumentTypeDecoration<TResult, TVariables>
+{
+  __apiType?: DocumentTypeDecoration<TResult, TVariables>["__apiType"];
+
+  constructor(private value: string) {
+    super(value);
+  }
+
+  toString(): string & DocumentTypeDecoration<TResult, TVariables> {
+    return this.value;
+  }
+}
+
 describe("graphql()", () => {
   it("is a function", () => {
     expect(graphql).toBeInstanceOf(Function);
@@ -77,6 +93,74 @@ describe("graphql()", () => {
     });
   });
 
+  it("README TypedDocumentString example", () => {
+    const mockData = {
+      repository: {
+        issues: {
+          edges: [
+            {
+              node: {
+                title: "Foo",
+              },
+            },
+            {
+              node: {
+                title: "Bar",
+              },
+            },
+            {
+              node: {
+                title: "Baz",
+              },
+            },
+          ],
+        },
+      },
+    };
+
+    const mock = fetchMock.createInstance().post(
+      "https://api.github.com/graphql",
+      { data: mockData },
+      {
+        headers: {
+          accept: "application/vnd.github.v3+json",
+          authorization: "token secret123",
+          "user-agent": userAgent,
+        },
+      },
+    );
+
+    const RepositoryDocument = new TypedDocumentString<
+      {
+        repository: { issues: { edges: Array<{ node: { title: string } }> } };
+      },
+      Record<string, never>
+    >(/* GraphQL */ `
+      {
+        repository(owner: "octokit", name: "graphql.js") {
+          issues(last: 3) {
+            edges {
+              node {
+                title
+              }
+            }
+          }
+        }
+      }
+    `);
+
+    return graphql(RepositoryDocument, {
+      headers: {
+        authorization: `token secret123`,
+      },
+      request: {
+        fetch: mock.fetchHandler,
+      },
+    }).then((result) => {
+      expect(JSON.stringify(result)).toStrictEqual(JSON.stringify(mockData));
+    });
+  });
+
   it("Variables", () => {
     const query = `query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
       repository(owner:$owner, name:$repo) {
@@ -116,6 +200,54 @@ describe("graphql()", () => {
     });
   });
 
+  it("Variables with TypedDocumentString", () => {
+    const query = new TypedDocumentString<
+      {
+        repository: { issues: { edges: Array<{ node: { title: string } }> } };
+      },
+      {
+        owner: string;
+        repo: string;
+        num?: number;
+      }
+    >(`query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
+      repository(owner:$owner, name:$repo) {
+        issues(last:$num) {
+          edges {
+            node {
+              title
+            }
+          }
+        }
+      }
+    }`);
+
+    const mock = fetchMock
+      .createInstance()
+      .post("https://api.github.com/graphql", (callHistory) => {
+        //@ts-ignore mock.fetchHandler is not typed
+        const body = JSON.parse(mock.callHistory.calls()[0].options.body);
+        expect(body.query).toEqual(query.toString());
+        expect(body.variables).toStrictEqual({
+          owner: "octokit",
+          repo: "graphql.js",
+        });
+
+        return { data: {} };
+      });
+
+    return graphql(query, {
+      headers: {
+        authorization: `token secret123`,
+      },
+      owner: "octokit",
+      repo: "graphql.js",
+      request: {
+        fetch: mock.fetchHandler,
+      },
+    });
+  });
+
   it("Pass headers together with variables as 2nd argument", () => {
     const query = `query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
       repository(owner:$owner, name:$repo) {

test/tsconfig.test.json

@@ -3,7 +3,14 @@
   "compilerOptions": {
     "emitDeclarationOnly": false,
     "noEmit": true,
-    "allowImportingTsExtensions": true
+    "allowImportingTsExtensions": true,
+    // TODO: This setting is not compatible with the default definition of
+    // DocumentTypeDecoration from '@graphql-typed-document-node/core'. That
+    // definition includes `{__apiType?: ...}` as an optional, so assigning it
+    // to an explicit `undefined` is impossible under
+    // exactOptionalPropertyTypes. We only need to work around this in tests,
+    // since that is where we use concrete examples of DocumentTypeDecoration.
+    "exactOptionalPropertyTypes": false
   },
   "include": ["src/**/*"]
 }