feat: endpoint response types (#35)

This will allow for typeaheads for RequestInterface (e.g. for octokit.request) like it does for EndpointInterfeace, and sets types for responses

package.json

@@ -30,6 +30,7 @@
   "author": "Gregor Martynus (https://twitter.com/gr2m)",
   "license": "MIT",
   "devDependencies": {
+    "@gimenete/type-writer": "^0.1.5",
     "@octokit/graphql": "^4.2.2",
     "handlebars": "^4.7.6",
     "lodash.set": "^4.3.2",

scripts/update-endpoints/fetch-json.js

@@ -26,6 +26,16 @@ const QUERY = `
         type
         required
       }
+      responses {
+        code
+        description
+        examples {
+          data
+        }
+      }
+      renamed {
+        note
+      }
     }
   }`;
 

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

@@ -1,27 +1,30 @@
 // DO NOT EDIT THIS FILE
 import { RequestHeaders } from "../RequestHeaders";
 import { RequestRequestOptions } from "../RequestRequestOptions";
+import { OctokitResponse } from "../OctokitResponse";
 import { Url } from "../Url";
+type AnyResponse = OctokitResponse<any>;
 
 export interface Endpoints {
   {{#each endpointsByRoute}}
-  "{{@key}}": [{{union this "optionsTypeName"}}, {{union this "requestOptionsTypeName"}}]
+  "{{@key}}": [{{union this "optionsTypeName"}}, {{union this "requestOptionsTypeName"}}, {{union this "responseTypeName"}}]
   {{/each}}
 }
 
 {{#each options}}
-type {{in.name}} = {
-{{#each in.parameters}}
+type {{parameters.name}} = {
+{{#each parameters.parameters}}
   {{&jsdoc}}
   {{{name this}}}: {{{type this}}}
 {{/each}}
 }
-type {{out.name}} = {
-  method: "{{out.method}}",
-  url: "{{out.url}}",
+type {{request.name}} = {
+  method: "{{request.method}}",
+  url: "{{request.url}}",
   headers: RequestHeaders,
   request: RequestRequestOptions
 }
+{{&response}}
 {{/each}}
 
 {{#childParams}}

scripts/update-endpoints/typescript.js

@@ -7,6 +7,7 @@ const { pascalCase } = require("pascal-case");
 const prettier = require("prettier");
 const { stringToJsdocComment } = require("string-to-jsdoc-comment");
 const sortKeys = require("sort-keys");
+const TypeWriter = require("@gimenete/type-writer");
 
 const ENDPOINTS = require("./generated/endpoints.json");
 const ENDPOINTS_PATH = resolve(
@@ -61,6 +62,8 @@ const typeMap = {
 };
 
 for (const endpoint of ENDPOINTS) {
+  if (endpoint.renamed) continue;
+
   const route = `${endpoint.method} ${endpoint.url.replace(
     /\{([^}]+)}/g,
     ":$1"
@@ -71,27 +74,47 @@ for (const endpoint of ENDPOINTS) {
   }
 
   endpointsByRoute[route].push({
-    optionsTypeName:
-      pascalCase(`${endpoint.scope} ${endpoint.id}`) + "Endpoint",
-    requestOptionsTypeName:
-      pascalCase(`${endpoint.scope} ${endpoint.id}`) + "RequestOptions",
+    optionsTypeName: pascalCase(`${endpoint.scope} ${endpoint.id} Endpoint`),
+    requestOptionsTypeName: pascalCase(
+      `${endpoint.scope} ${endpoint.id} RequestOptions`
+    ),
+    responseTypeName: endpointToResponseTypeName(endpoint),
   });
 }
 
 const options = [];
 const childParams = {};
 
 for (const endpoint of ENDPOINTS) {
+  if (endpoint.renamed) continue;
+
+  const typeWriter = new TypeWriter();
   const { method, parameters } = endpoint;
   const url = endpoint.url.replace(/\{([^}]+)}/g, ":$1");
 
-  const optionsTypeName =
-    pascalCase(`${endpoint.scope} ${endpoint.id}`) + "Endpoint";
-  const requestOptionsTypeName =
-    pascalCase(`${endpoint.scope} ${endpoint.id}`) + "RequestOptions";
+  const optionsTypeName = pascalCase(
+    `${endpoint.scope} ${endpoint.id} Endpoint`
+  );
+  const requestOptionsTypeName = pascalCase(
+    `${endpoint.scope} ${endpoint.id} RequestOptions`
+  );
+
+  const responses =
+    endpoint.responses.length && endpoint.responses[0].examples
+      ? endpoint.responses[0].examples.map((example) =>
+          JSON.parse(example.data)
+        )
+      : undefined;
+  if (responses) {
+    typeWriter.add(responses, {
+      rootTypeName: endpointToResponseTypeName(endpoint),
+    });
+
+    typeWriter.generate("typescript");
+  }
 
   options.push({
-    in: {
+    parameters: {
       name: optionsTypeName,
       parameters: parameters
         .map(parameterize)
@@ -133,14 +156,19 @@ for (const endpoint of ENDPOINTS) {
         })
         .filter(Boolean),
     },
-    out: {
+    request: {
       name: requestOptionsTypeName,
       method,
       url,
     },
+    response: responses ? typeWriter.generate("typescript") : "",
   });
+
+  process.stdout.write(".");
 }
 
+console.log("\ndone.");
+
 const result = template({
   endpointsByRoute: sortKeys(endpointsByRoute, { deep: true }),
   options,
@@ -176,3 +204,14 @@ function parameterize(parameter) {
     jsdoc: stringToJsdocComment(parameter.description),
   };
 }
+
+function endpointToResponseTypeName(endpoint) {
+  const hasResponses =
+    endpoint.responses.length && endpoint.responses[0].examples;
+
+  if (hasResponses) {
+    return pascalCase(`${endpoint.scope} ${endpoint.id} ResponseData`);
+  }
+
+  return "any";
+}

src/RequestInterface.ts

@@ -4,6 +4,8 @@ import { OctokitResponse } from "./OctokitResponse";
 import { RequestParameters } from "./RequestParameters";
 import { Route } from "./Route";
 
+import { Endpoints } from "./generated/Endpoints";
+
 export interface RequestInterface {
   /**
    * Sends a request based on endpoint options
@@ -18,9 +20,14 @@ export interface RequestInterface {
    * @param {string} route Request method + URL. Example: `'GET /orgs/:org'`
    * @param {object} [parameters] URL, query or body parameters, as well as `headers`, `mediaType.{format|previews}`, `request`, or `baseUrl`.
    */
-  <T = any>(route: Route, parameters?: RequestParameters): Promise<
-    OctokitResponse<T>
-  >;
+  <R extends Route>(
+    route: keyof Endpoints | R,
+    options?: R extends keyof Endpoints
+      ? Endpoints[R][0] & RequestParameters
+      : RequestParameters
+  ): R extends keyof Endpoints
+    ? Promise<OctokitResponse<Endpoints[R][2]>>
+    : Promise<OctokitResponse<any>>;
 
   /**
    * Returns a new `endpoint` with updated route and parameters