Add tests, handle toString() call internally

Author: fpapado

src/with-defaults.ts

@@ -7,17 +7,6 @@ import type {
 import { graphql } from "./graphql.js";
 import type { DocumentTypeDecoration } from "@graphql-typed-document-node/core";
 
-/**
- * Allows discarding the DocumentTypeDecoration information from the external
- * interface, and casting the String part to string. This avoids the external
- * API interface spreading to the internal types, while keeping type-safety for
- * future extensions/changes.
- */
-type DiscardTypeDecoration<T> = T extends String &
-  DocumentTypeDecoration<unknown, unknown>
-  ? string
-  : T;
-
 export function withDefaults(
   request: typeof Request,
   newDefaults: RequestParameters,
@@ -30,11 +19,20 @@ export function withDefaults(
       | RequestParameters,
     options?: RequestParameters,
   ) => {
-    return graphql<ResponseData>(
-      newRequest,
-      query as DiscardTypeDecoration<typeof 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,72 @@ describe("graphql()", () => {
     });
   });
 
+  it("README TypedDocumentString example", () => {
+    const mockData = {
+      repository: {
+        issues: {
+          edges: [
+            {
+              node: {
+                title: "Foo",
+              },
+            },
+            {
+              node: {
+                title: "Bar",
+              },
+            },
+            {
+              node: {
+                title: "Baz",
+              },
+            },
+          ],
+        },
+      },
+    };
+
+    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: fetchMock.sandbox().post(
+          "https://api.github.com/graphql",
+          { data: mockData },
+          {
+            headers: {
+              accept: "application/vnd.github.v3+json",
+              authorization: "token secret123",
+              "user-agent": userAgent,
+            },
+          },
+        ),
+      },
+    }).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 +198,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
+            }
+          }
+        }
+      }
+    }`);
+
+    return graphql(query, {
+      headers: {
+        authorization: `token secret123`,
+      },
+      owner: "octokit",
+      repo: "graphql.js",
+      request: {
+        fetch: fetchMock
+          .sandbox()
+          .post(
+            "https://api.github.com/graphql",
+            (_url, options: OctokitTypes.RequestOptions) => {
+              const body = JSON.parse(options.body);
+              expect(body.query).toEqual(query.toString());
+              expect(body.variables).toStrictEqual({
+                owner: "octokit",
+                repo: "graphql.js",
+              });
+
+              return { data: {} };
+            },
+          ),
+      },
+    });
+  });
+
   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-codegen-types/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/**/*"]
 }