Add String & DocumentTypeDecoration overload

Author: fpapado

package-lock.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.0.0",
     "@octokit/types": "^13.0.0",
     "universal-user-agent": "^7.0.0"

package.json

@@ -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/types.ts

@@ -5,17 +5,36 @@ import type {
   RequestParameters,
 } from "./types.js";
 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,
 ): 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);
+    return graphql<ResponseData>(
+      newRequest,
+      query as DiscardTypeDecoration<typeof query>,
+      options,
+    );
   };
 
   return Object.assign(newApi, {