feat: improve declaration of response types

This changes the way that `HttpResponse` is declared. The language
server now offers actual helpful autocomplete suggestions, and type
inferencing behaves correctly as far as I can tell.

Author: bitgopatmcl

packages/io-ts-http/src/httpResponse.ts

@@ -3,14 +3,18 @@ import * as t from 'io-ts';
 import { Status } from '@api-ts/response';
 
 export type HttpResponse = {
-  [K: string]: t.Mixed;
+  [K in Status]?: t.Mixed;
 };
 
-type KnownResponses<Response extends HttpResponse> = {
-  [K in Status]: K extends keyof Response ? K : never;
-}[Status];
+export type KnownResponses<Response extends HttpResponse> = {
+  [K in keyof Response]: K extends Status
+    ? undefined extends Response[K]
+      ? never
+      : K
+    : never;
+}[keyof Response];
 
-export const HttpResponseCodes: { [K in Status]: number } = {
+export const HttpResponseCodes = {
   ok: 200,
   invalidRequest: 400,
   unauthenticated: 401,
@@ -19,7 +23,23 @@ export const HttpResponseCodes: { [K in Status]: number } = {
   rateLimitExceeded: 429,
   internalError: 500,
   serviceUnavailable: 503,
-};
+} as const;
+
+export type HttpResponseCodes = typeof HttpResponseCodes;
+
+// Create a type-level assertion that the HttpResponseCodes map contains every key
+// in the Status union of string literals, and no unexpected keys. Violations of
+// this assertion will cause compile-time errors.
+//
+// Thanks to https://stackoverflow.com/a/67027737
+type ShapeOf<T> = Record<keyof T, any>;
+type AssertKeysEqual<X extends ShapeOf<Y>, Y extends ShapeOf<X>> = never;
+type _AssertHttpStatusCodeIsDefinedForAllResponses = AssertKeysEqual<
+  { [K in Status]: number },
+  HttpResponseCodes
+>;
 
-export type KnownHttpStatusCodes<Response extends HttpResponse> =
-  typeof HttpResponseCodes[KnownResponses<Response>];
+export type ResponseTypeForStatus<
+  Response extends HttpResponse,
+  S extends keyof Response,
+> = Response[S] extends t.Mixed ? t.TypeOf<Response[S]> : never;

packages/io-ts-http/src/httpRoute.ts

@@ -1,7 +1,7 @@
 import * as t from 'io-ts';
 
-import { HttpResponse } from './httpResponse';
-import { HttpRequestCodec } from './httpRequest';
+import { HttpResponse, KnownResponses } from './httpResponse';
+import { httpRequest, HttpRequestCodec } from './httpRequest';
 import { Status } from '@api-ts/response';
 
 export type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
@@ -13,15 +13,17 @@ export type HttpRoute = {
   readonly response: HttpResponse;
 };
 
+type ResponseItem<Status, Codec extends t.Mixed | undefined> = Codec extends t.Mixed
+  ? {
+      type: Status;
+      payload: t.TypeOf<Codec>;
+    }
+  : never;
+
 export type RequestType<T extends HttpRoute> = t.TypeOf<T['request']>;
 export type ResponseType<T extends HttpRoute> = {
-  [K in Status]: K extends keyof T['response']
-    ? {
-        type: K;
-        payload: t.TypeOf<T['response'][K]>;
-      }
-    : never;
-}[Status];
+  [K in KnownResponses<T['response']>]: ResponseItem<K, T['response'][K]>;
+}[KnownResponses<T['response']>];
 
 export type ApiSpec = {
   [Key: string]: {

packages/superagent-wrapper/src/request.ts

@@ -5,15 +5,16 @@ import type { Response, SuperAgent, SuperAgentRequest } from 'superagent';
 import type { SuperTest } from 'supertest';
 import { URL } from 'url';
 import { pipe } from 'fp-ts/function';
+import { Status } from '@api-ts/response';
 
 type SuccessfulResponses<Route extends h.HttpRoute> = {
-  [Status in h.KnownHttpStatusCodes<Route['response']>]: {
-    status: Status;
+  [R in h.KnownResponses<Route['response']>]: {
+    status: h.HttpResponseCodes[R];
     error?: undefined;
-    body: t.TypeOf<Route['response'][Status]>;
+    body: h.ResponseTypeForStatus<Route['response'], R>;
     original: Response;
   };
-}[h.KnownHttpStatusCodes<Route['response']>];
+}[h.KnownResponses<Route['response']>];
 
 type DecodedResponse<Route extends h.HttpRoute> =
   | SuccessfulResponses<Route>
@@ -28,17 +29,16 @@ const decodedResponse = <Route extends h.HttpRoute>(res: DecodedResponse<Route>)
 
 type ExpectedDecodedResponse<
   Route extends h.HttpRoute,
-  Status extends h.KnownHttpStatusCodes<Route['response']>,
-> = {
-  body: t.TypeOf<Route['response'][Status]>;
-  original: Response;
-};
+  StatusCode extends h.HttpResponseCodes[h.KnownResponses<Route['response']>],
+> = DecodedResponse<Route> & { status: StatusCode };
 
 type PatchedRequest<Req extends SuperAgentRequest, Route extends h.HttpRoute> = Req & {
   decode: () => Promise<DecodedResponse<Route>>;
-  decodeExpecting: <Status extends h.KnownHttpStatusCodes<Route['response']>>(
-    status: Status,
-  ) => Promise<ExpectedDecodedResponse<Route, Status>>;
+  decodeExpecting: <
+    StatusCode extends h.HttpResponseCodes[h.KnownResponses<Route['response']>],
+  >(
+    status: StatusCode,
+  ) => Promise<ExpectedDecodedResponse<Route, StatusCode>>;
 };
 
 type SuperagentMethod = 'get' | 'post' | 'put' | 'delete';
@@ -84,6 +84,13 @@ export const supertestRequestFactory =
     return supertest[method](path);
   };
 
+const hasCodecForStatus = <S extends Status>(
+  responses: h.HttpResponse,
+  status: S,
+): responses is { [K in S]: t.Mixed } => {
+  return status in responses && responses[status] !== undefined;
+};
+
 const patchRequest = <Req extends SuperAgentRequest, Route extends h.HttpRoute>(
   route: Route,
   req: Req,
@@ -94,11 +101,11 @@ const patchRequest = <Req extends SuperAgentRequest, Route extends h.HttpRoute>(
     req.then((res) => {
       const { body, status: statusCode } = res;
 
-      let status: string | undefined;
+      let status: Status | undefined;
       // DISCUSS: Should we have this as a preprocessed const in io-ts-http?
       for (const [name, code] of Object.entries(h.HttpResponseCodes)) {
         if (statusCode === code) {
-          status = name;
+          status = name as Status;
           break;
         }
       }
@@ -111,7 +118,7 @@ const patchRequest = <Req extends SuperAgentRequest, Route extends h.HttpRoute>(
         });
       }
 
-      if (route.response[status] === undefined) {
+      if (!hasCodecForStatus(route.response, status)) {
         return decodedResponse({
           // DISCUSS: what's this non-standard HTTP status code?
           status: 'decodeError',
@@ -124,10 +131,12 @@ const patchRequest = <Req extends SuperAgentRequest, Route extends h.HttpRoute>(
         route.response[status].decode(res.body),
         E.map((body) =>
           decodedResponse<Route>({
-            status: statusCode,
+            status: statusCode as h.HttpResponseCodes[h.KnownResponses<
+              Route['response']
+            >],
             body,
             original: res,
-          }),
+          } as SuccessfulResponses<Route>),
         ),
         E.getOrElse((error) =>
           // DISCUSS: what's this non-standard HTTP status code?
@@ -142,19 +151,16 @@ const patchRequest = <Req extends SuperAgentRequest, Route extends h.HttpRoute>(
     });
 
   patchedReq.decodeExpecting = <
-    Status extends h.KnownHttpStatusCodes<Route['response']>,
+    StatusCode extends h.HttpResponseCodes[h.KnownResponses<Route['response']>],
   >(
-    status: Status,
+    status: StatusCode,
   ) =>
     patchedReq.decode().then((res) => {
       if (res.status !== status) {
         const error = res.error ?? `Unexpected status code ${res.status}`;
         throw new Error(JSON.stringify(error));
       } else {
-        return {
-          body: res.body,
-          original: res.original,
-        };
+        return res as ExpectedDecodedResponse<Route, StatusCode>;
       }
     });
   return patchedReq;