feat: add support for typed methods

This adds support for typed methods, by generating endpoint and method types. This is largely taken from scripts in "@octokit/plugin-rest-endpoint-methods".

As "@octokit/types" does not support GHEC types, we cannot import endpoint types directly. Instead, we generate them for this package from "@octokit/openapi-types-ghec".

package.json

@@ -15,7 +15,9 @@
     "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --coverage",
     "update-endpoints": "npm-run-all update-endpoints:*",
     "update-endpoints:fetch-json": "node scripts/update-endpoints/fetch-json",
-    "update-endpoints:code": "node scripts/update-endpoints/code"
+    "update-endpoints:code": "node scripts/update-endpoints/code",
+    "update-endpoints:typescript": "node scripts/update-endpoints/typescript",
+    "update-endpoints:types": "node scripts/update-endpoints/types"
   },
   "repository": "github:octokit/plugin-enterprise-cloud.js",
   "keywords": [
@@ -29,7 +31,8 @@
   "author": "Gregor Martynus (https://github.com/gr2m)",
   "license": "MIT",
   "dependencies": {
-    "@octokit/types": "^13.0.0"
+    "@octokit/types": "^13.0.0",
+    "@octokit/openapi-types-ghec": "^22.2.0"
   },
   "peerDependencies": {
     "@octokit/core": ">=6"
@@ -46,11 +49,13 @@
     "github-openapi-graphql-query": "^4.0.0",
     "glob": "^11.0.0",
     "jest": "^29.0.0",
+    "lodash.camelcase": "^4.3.0",
     "npm-run-all2": "^6.0.0",
     "prettier": "3.3.2",
     "semantic-release": "^24.0.0",
     "semantic-release-plugin-update-version-in-files": "^1.0.0",
     "sort-keys": "^5.0.0",
+    "string-to-jsdoc-comment": "^1.0.0",
     "ts-jest": "^29.0.0",
     "typescript": "^5.0.0"
   },

scripts/update-endpoints/templates/endpoints.ts.template

@@ -0,0 +1,117 @@
+// DO NOT EDIT THIS FILE
+import type { paths } from "@octokit/openapi-types-ghec";
+import type { OctokitResponse, RequestHeaders, RequestRequestOptions } from "@octokit/types";
+
+/**
+ * @license (MIT OR CC0-1.0)
+ * @source https://github.com/sindresorhus/type-fest/blob/570e27f8fdaee37ef5d5e0fbf241e0212ff8fc1a/source/simplify.d.ts
+ */
+export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
+
+// https://stackoverflow.com/a/50375286/206879
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I
+) => void
+  ? I
+  : never;
+
+type ExtractParameters<T> = "parameters" extends keyof T
+  ? UnionToIntersection<
+      {
+        // query parameter might be optional
+        // https://github.com/octokit/types.ts/pull/555#issuecomment-1585105522
+        [K in keyof T["parameters"]]-?: T["parameters"][K];
+      }[keyof T["parameters"]]
+    >
+  : {};
+type ExtractRequestBody<T> = "requestBody" extends keyof T
+  ? "content" extends keyof T["requestBody"]
+    ? "application/json" extends keyof T["requestBody"]["content"]
+      ? T["requestBody"]["content"]["application/json"]
+      : {
+          data: {
+            [K in keyof T["requestBody"]["content"]]: T["requestBody"]["content"][K];
+          }[keyof T["requestBody"]["content"]];
+        }
+    : "application/json" extends keyof T["requestBody"]
+    ? T["requestBody"]["application/json"]
+    : {
+        data: {
+          [K in keyof T["requestBody"]]: T["requestBody"][K];
+        }[keyof T["requestBody"]];
+      }
+  : {};
+type ToOctokitParameters<T> = ExtractParameters<T> & ExtractRequestBody<Required<T>>;
+
+type Operation<Url extends keyof paths, Method extends keyof paths[Url]> = {
+  parameters: Simplify<ToOctokitParameters<paths[Url][Method]>>;
+  request: Method extends ReadOnlyMethods
+    ? {
+        method: Method extends string ? Uppercase<Method> : never;
+        url: Url;
+        headers: RequestHeaders;
+        request: RequestRequestOptions;
+      }
+    : {
+        method: Method extends string ? Uppercase<Method> : never;
+        url: Url;
+        headers: RequestHeaders;
+        request: RequestRequestOptions;
+        data: ExtractRequestBody<paths[Url][Method]>;
+      };
+  response: ExtractOctokitResponse<paths[Url][Method]>;
+};
+
+type ReadOnlyMethods = "get" | "head";
+type SuccessStatuses = 200 | 201 | 202 | 204 | 205;
+type RedirectStatuses = 301 | 302;
+type EmptyResponseStatuses = 201 | 204 | 205;
+type KnownJsonResponseTypes =
+  | "application/json"
+  | "application/octocat-stream" // GET /octocat
+  | "application/scim+json"
+  | "text/html"
+  | "text/plain"; // GET /zen
+
+type SuccessResponseDataType<Responses> = {
+  [K in SuccessStatuses & keyof Responses]: GetContentKeyIfPresent<
+    Responses[K]
+  > extends never
+    ? never
+    : OctokitResponse<GetContentKeyIfPresent<Responses[K]>, K>;
+}[SuccessStatuses & keyof Responses];
+type RedirectResponseDataType<Responses> = {
+  [K in RedirectStatuses & keyof Responses]: OctokitResponse<unknown, K>;
+}[RedirectStatuses & keyof Responses];
+type EmptyResponseDataType<Responses> = {
+  [K in EmptyResponseStatuses & keyof Responses]: OctokitResponse<never, K>;
+}[EmptyResponseStatuses & keyof Responses];
+
+type GetContentKeyIfPresent<T> = "content" extends keyof T
+  ? DataType<T["content"]>
+  : DataType<T>;
+type DataType<T> = {
+  [K in KnownJsonResponseTypes & keyof T]: T[K];
+}[KnownJsonResponseTypes & keyof T];
+type ExtractOctokitResponse<R> = "responses" extends keyof R
+  ? SuccessResponseDataType<R["responses"]> extends never
+    ? RedirectResponseDataType<R["responses"]> extends never
+      ? EmptyResponseDataType<R["responses"]>
+      : RedirectResponseDataType<R["responses"]>
+    : SuccessResponseDataType<R["responses"]>
+  : unknown;
+
+export interface Endpoints {
+  {{#each endpointsByRoute}}
+  /**
+   * @see {{documentationUrl}}
+   {{#deprecated}}
+   * @deprecated {{{.}}}
+   {{/deprecated}}
+   */
+  "{{@key}}": Operation<
+    "{{url}}",
+    "{{method}}"
+  >,
+  {{/each}}
+}

scripts/update-endpoints/types.js

@@ -0,0 +1,160 @@
+import { writeFileSync, readFileSync } from "node:fs";
+import { join as pathJoin } from "node:path";
+
+import camelCase from "lodash.camelcase";
+import { format } from "prettier";
+import { stringToJsdocComment } from "string-to-jsdoc-comment";
+import sortKeys from "sort-keys";
+
+const ENDPOINTS = JSON.parse(readFileSync(new URL("./generated/endpoints.json", import.meta.url), "utf-8"));
+import { isDeprecated } from "./util.js";
+
+generateTypes();
+
+async function generateTypes() {
+  const ROUTES = await getRoutes();
+
+  const namespaces = Object.keys(ROUTES).reduce((namespaces, namespace) => {
+    const methods = Object.keys(ROUTES[namespace]).reduce((methods, methodName) => {
+      const entry = ROUTES[namespace][methodName];
+
+      const description = [entry.description, entry.deprecated && `@deprecated ${entry.deprecated}`].filter(Boolean).join("\n");
+
+      return methods.concat({
+        name: methodName,
+        route: `${entry.method} ${entry.url}`,
+        hasRequiredPreviews: entry.hasRequiredPreviews,
+        jsdoc: stringToJsdocComment(description),
+      });
+    }, []);
+
+    return namespaces.concat({
+      namespace: camelCase(namespace),
+      methods,
+    });
+  }, []);
+
+  const RestEndpointMethodParameterAndResponseTypes = [];
+  for (const namespace of namespaces) {
+    const namespaceMethods = [];
+    for (const method of namespace.methods) {
+      namespaceMethods.push(
+        `${method.name}: {
+          parameters: RequestParameters & Endpoints["${method.route}"]["parameters"],
+          response: Endpoints["${method.route}"]["response"]
+        }`
+      );
+    }
+
+    RestEndpointMethodParameterAndResponseTypes.push(`${namespace.namespace}: {
+      ${namespaceMethods.join("\n")}
+    }`);
+  }
+
+  const RestEndpointMethodNamespaceTypes = [];
+  for (const namespace of namespaces) {
+    const namespaceMethods = [];
+    for (const method of namespace.methods) {
+      namespaceMethods.push(
+        [
+          method.jsdoc,
+          `${method.name}: {
+          (params?: RestEndpointMethodTypes["${namespace.namespace}"]["${method.name}"]["parameters"]): Promise<RestEndpointMethodTypes["${namespace.namespace}"]["${method.name}"]["response"]>
+          defaults: RequestInterface["defaults"];
+          endpoint: EndpointInterface<{ url: string }>;
+        }`,
+        ].join("\n")
+      );
+    }
+
+    RestEndpointMethodNamespaceTypes.push(`${namespace.namespace}: {
+      ${namespaceMethods.join("\n")}
+    }`);
+  }
+
+  const methodTypesSource = await format(
+    [
+      `import type { EndpointInterface, RequestInterface } from "@octokit/types";`,
+      `import type { RestEndpointMethodTypes } from "./parameters-and-response-types.js";`,
+      "",
+      `export type RestEndpointMethods = {
+        ${RestEndpointMethodNamespaceTypes.join("\n")}
+      }`,
+    ].join("\n"),
+    {
+      parser: "typescript",
+    }
+  );
+  const parametersAndResponsesTypes = await format(
+    [
+      `import type { RequestParameters } from "@octokit/types";`,
+      `import type { Endpoints } from "./endpoints-types.js";`,
+      "",
+      `export type RestEndpointMethodTypes = {
+        ${RestEndpointMethodParameterAndResponseTypes.join("\n")}
+      }`,
+    ].join("\n"),
+    {
+      parser: "typescript",
+    }
+  );
+
+  const methodTypesFilePath = pathJoin(process.cwd(), "src", "generated", "method-types.ts");
+
+  writeFileSync(methodTypesFilePath, methodTypesSource, "utf8");
+  console.log(`Types written to ${methodTypesFilePath}`);
+
+  const parametersAndResponseFilePath = pathJoin(process.cwd(), "src", "generated", "parameters-and-response-types.ts");
+
+  writeFileSync(parametersAndResponseFilePath, parametersAndResponsesTypes, "utf8");
+  console.log(`Types written to ${parametersAndResponseFilePath}`);
+}
+
+async function getRoutes() {
+  const newRoutes = {};
+
+  ENDPOINTS.forEach((endpoint) => {
+    if (isDeprecated(endpoint)) return;
+
+    const scope = endpoint.scope;
+
+    if (!newRoutes[scope]) {
+      newRoutes[scope] = {};
+    }
+
+    const idName = endpoint.id;
+    const url = endpoint.url
+      .toLowerCase()
+      // stecial case for "Upload a release asset": remove ":origin" prefix
+      .replace(/^:origin/, "");
+
+    // new route
+    newRoutes[scope][idName] = {
+      method: endpoint.method,
+      url,
+      description: endpoint.description,
+      hasRequiredPreviews: !!endpoint.previews.length,
+      deprecated: newRoutes[scope][idName] ? newRoutes[scope][idName].deprecated : undefined,
+    };
+
+    if (endpoint.renamed) {
+      const { before, after } = endpoint.renamed;
+      if (!newRoutes[before.scope]) {
+        newRoutes[before.scope] = {};
+      }
+
+      if (!newRoutes[before.scope][before.id]) {
+        newRoutes[before.scope][before.id] = newRoutes[scope][idName];
+      }
+
+      newRoutes[before.scope][before.id].deprecated =
+        `octokit.rest.${before.scope}.${before.id}() has been renamed to octokit.rest.${after.scope}.${after.id}() (${endpoint.renamed.date})`;
+    }
+
+    if (endpoint.isDeprecated) {
+      newRoutes[scope][idName].deprecated = `octokit.rest.${scope}.${idName}() is deprecated, see ${endpoint.documentationUrl}`;
+    }
+  });
+
+  return sortKeys(newRoutes, { deep: true });
+}