feat: handle status codes or response keys in express-wrapper

Author: bitgopatmcl

package-lock.json

@@ -4,102 +4,25 @@
  */
 
 import express from 'express';
-import * as PathReporter from 'io-ts/lib/PathReporter';
 
-import { ApiSpec, HttpRoute, RequestType, ResponseType } from '@api-ts/io-ts-http';
+import { ApiSpec, HttpRoute } from '@api-ts/io-ts-http';
 
 import { apiTsPathToExpress } from './path';
-
-export type Function<R extends HttpRoute> = (
-  input: RequestType<R>,
-) => ResponseType<R> | Promise<ResponseType<R>>;
-export type RouteStack<R extends HttpRoute> = [
-  ...express.RequestHandler[],
-  Function<R>,
-];
-
-/**
- * Dynamically assign a function name to avoid anonymous functions in stack traces
- * https://stackoverflow.com/a/69465672
- */
-const createNamedFunction = <F extends (...args: any) => void>(
-  name: string,
-  fn: F,
-): F => Object.defineProperty(fn, 'name', { value: name });
-
-const decodeRequestAndEncodeResponse = <Route extends HttpRoute>(
-  apiName: string,
-  httpRoute: Route,
-  handler: Function<Route>,
-): express.RequestHandler => {
-  return createNamedFunction(
-    'decodeRequestAndEncodeResponse' + httpRoute.method + apiName,
-    async (req, res) => {
-      const maybeRequest = httpRoute.request.decode(req);
-      if (maybeRequest._tag === 'Left') {
-        console.log('Request failed to decode');
-        const validationErrors = PathReporter.failure(maybeRequest.left);
-        const validationErrorMessage = validationErrors.join('\n');
-        res.writeHead(400, { 'Content-Type': 'application/json' });
-        res.write(JSON.stringify({ error: validationErrorMessage }));
-        res.end();
-        return;
-      }
-
-      let rawResponse: ResponseType<Route> | undefined;
-      try {
-        rawResponse = await handler(maybeRequest.right);
-      } catch (err) {
-        console.warn('Error in route handler:', err);
-        res.statusCode = 500;
-        res.end();
-        return;
-      }
-
-      for (const [statusCodeStr, responseCodec] of Object.entries(httpRoute.response)) {
-        const statusCode = Number(statusCodeStr);
-        if (!Number.isInteger(statusCode) || rawResponse.type !== statusCode) {
-          continue;
-        }
-
-        // We expect that some route implementations may "beat the type
-        // system away with a stick" and return some unexpected values
-        // that fail to encode, so we catch errors here just in case
-        let response: unknown;
-        try {
-          response = responseCodec.encode(rawResponse.payload);
-        } catch (err) {
-          console.warn(
-            "Unable to encode route's return value, did you return the expected type?",
-            err,
-          );
-          res.statusCode = 500;
-          res.end();
-          return;
-        }
-        res.writeHead(statusCode, {
-          'Content-Type': 'application/json',
-        });
-        res.write(JSON.stringify(response));
-        res.end();
-        return;
-      }
-
-      // If we got here then we got an unexpected response
-      res.status(500);
-      res.end();
-    },
-  );
-};
+import {
+  decodeRequestAndEncodeResponse,
+  getMiddleware,
+  getServiceFunction,
+  RouteHandler,
+} from './request';
 
 const isHttpVerb = (verb: string): verb is 'get' | 'put' | 'post' | 'delete' =>
-  ({ get: 1, put: 1, post: 1, delete: 1 }.hasOwnProperty(verb));
+  verb === 'get' || verb === 'put' || verb === 'post' || verb === 'delete';
 
 export function createServer<Spec extends ApiSpec>(
   spec: Spec,
   configureExpressApplication: (app: express.Application) => {
     [ApiName in keyof Spec]: {
-      [Method in keyof Spec[ApiName]]: RouteStack<Spec[ApiName][Method]>;
+      [Method in keyof Spec[ApiName]]: RouteHandler<Spec[ApiName][Method]>;
     };
   },
 ) {
@@ -114,14 +37,13 @@ export function createServer<Spec extends ApiSpec>(
         continue;
       }
       const httpRoute: HttpRoute = resource[method]!;
-      const stack = routes[apiName]![method]!;
-      // Note: `stack` is guaranteed to be non-empty thanks to our function's type signature
-      const handler = decodeRequestAndEncodeResponse(
+      const routeHandler = routes[apiName]![method]!;
+      const expressRouteHandler = decodeRequestAndEncodeResponse(
         apiName,
-        httpRoute,
-        stack[stack.length - 1] as Function<HttpRoute>,
+        httpRoute as any, // TODO: wat
+        getServiceFunction(routeHandler),
       );
-      const handlers = [...stack.slice(0, stack.length - 1), handler];
+      const handlers = [...getMiddleware(routeHandler), expressRouteHandler];
 
       const expressPath = apiTsPathToExpress(httpRoute.path);
       router[method](expressPath, handlers);

packages/express-wrapper/src/index.ts

@@ -0,0 +1,103 @@
+/**
+ * express-wrapper
+ * A simple, type-safe web server
+ */
+
+import express from 'express';
+import * as t from 'io-ts';
+import * as PathReporter from 'io-ts/lib/PathReporter';
+
+import {
+  HttpRoute,
+  HttpToKeyStatus,
+  KeyToHttpStatus,
+  RequestType,
+  ResponseType,
+} from '@api-ts/io-ts-http';
+
+type NumericOrKeyedResponseType<R extends HttpRoute> =
+  | ResponseType<R>
+  | {
+      [S in keyof R['response']]: S extends keyof HttpToKeyStatus
+        ? {
+            type: HttpToKeyStatus[S];
+            payload: t.TypeOf<R['response'][S]>;
+          }
+        : never;
+    }[keyof R['response']];
+
+export type ServiceFunction<R extends HttpRoute> = (
+  input: RequestType<R>,
+) => NumericOrKeyedResponseType<R> | Promise<NumericOrKeyedResponseType<R>>;
+
+export type RouteHandler<R extends HttpRoute> =
+  | ServiceFunction<R>
+  | { middleware: express.RequestHandler[]; handler: ServiceFunction<R> };
+
+export const getServiceFunction = <R extends HttpRoute>(
+  routeHandler: RouteHandler<R>,
+): ServiceFunction<R> =>
+  'handler' in routeHandler ? routeHandler.handler : routeHandler;
+
+export const getMiddleware = <R extends HttpRoute>(
+  routeHandler: RouteHandler<R>,
+): express.RequestHandler[] =>
+  'middleware' in routeHandler ? routeHandler.middleware : [];
+
+/**
+ * Dynamically assign a function name to avoid anonymous functions in stack traces
+ * https://stackoverflow.com/a/69465672
+ */
+const createNamedFunction = <F extends (...args: any) => void>(
+  name: string,
+  fn: F,
+): F => Object.defineProperty(fn, 'name', { value: name });
+
+export const decodeRequestAndEncodeResponse = <Route extends HttpRoute>(
+  apiName: string,
+  httpRoute: Route,
+  handler: ServiceFunction<Route>,
+): express.RequestHandler => {
+  return createNamedFunction(
+    'decodeRequestAndEncodeResponse' + httpRoute.method + apiName,
+    async (req, res) => {
+      const maybeRequest = httpRoute.request.decode(req);
+      if (maybeRequest._tag === 'Left') {
+        console.log('Request failed to decode');
+        const validationErrors = PathReporter.failure(maybeRequest.left);
+        const validationErrorMessage = validationErrors.join('\n');
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.write(JSON.stringify({ error: validationErrorMessage }));
+        res.end();
+        return;
+      }
+
+      let rawResponse: NumericOrKeyedResponseType<Route> | undefined;
+      try {
+        rawResponse = await handler(maybeRequest.right);
+      } catch (err) {
+        console.warn('Error in route handler:', err);
+        res.status(500).end();
+        return;
+      }
+
+      const { type, payload } = rawResponse;
+      const status = typeof type === 'number' ? type : (KeyToHttpStatus as any)[type];
+      if (status === undefined) {
+        console.warn('Unknown status code returned');
+        res.status(500).end();
+        return;
+      }
+      const responseCodec = httpRoute.response[status];
+      if (responseCodec === undefined || !responseCodec.is(payload)) {
+        console.warn(
+          "Unable to encode route's return value, did you return the expected type?",
+        );
+        res.status(500).end();
+        return;
+      }
+
+      res.status(status).json(responseCodec.encode(payload)).end();
+    },
+  );
+};

packages/express-wrapper/src/request.ts

@@ -99,7 +99,7 @@ const CreateHelloWorld = async (parameters: {
 
 const GetHelloWorld = async (params: { id: string }) =>
   ({
-    type: 200,
+    type: 'ok',
     payload: params,
   } as const);
 
@@ -110,8 +110,8 @@ test('should offer a delightful developer experience', async (t) => {
     app.use(appMiddleware);
     return {
       'hello.world': {
-        put: [routeMiddleware, CreateHelloWorld],
-        get: [GetHelloWorld],
+        put: { middleware: [routeMiddleware], handler: CreateHelloWorld },
+        get: GetHelloWorld,
       },
     };
   });
@@ -139,8 +139,8 @@ test('should handle io-ts-http formatted path parameters', async (t) => {
     app.use(appMiddleware);
     return {
       'hello.world': {
-        put: [routeMiddleware, CreateHelloWorld],
-        get: [GetHelloWorld],
+        put: { middleware: [routeMiddleware], handler: CreateHelloWorld },
+        get: GetHelloWorld,
       },
     };
   });
@@ -163,8 +163,8 @@ test('should invoke app-level middleware', async (t) => {
     app.use(appMiddleware);
     return {
       'hello.world': {
-        put: [CreateHelloWorld],
-        get: [GetHelloWorld],
+        put: CreateHelloWorld,
+        get: GetHelloWorld,
       },
     };
   });
@@ -186,8 +186,8 @@ test('should invoke route-level middleware', async (t) => {
     app.use(express.json());
     return {
       'hello.world': {
-        put: [routeMiddleware, CreateHelloWorld],
-        get: [GetHelloWorld],
+        put: { middleware: [routeMiddleware], handler: CreateHelloWorld },
+        get: GetHelloWorld,
       },
     };
   });
@@ -209,8 +209,8 @@ test('should infer status code from response type', async (t) => {
     app.use(express.json());
     return {
       'hello.world': {
-        put: [CreateHelloWorld],
-        get: [GetHelloWorld],
+        put: CreateHelloWorld,
+        get: GetHelloWorld,
       },
     };
   });
@@ -232,8 +232,8 @@ test('should return a 400 when request fails to decode', async (t) => {
     app.use(express.json());
     return {
       'hello.world': {
-        put: [CreateHelloWorld],
-        get: [GetHelloWorld],
+        put: CreateHelloWorld,
+        get: GetHelloWorld,
       },
     };
   });

packages/express-wrapper/test/server.test.ts

@@ -21,7 +21,7 @@ httpRoute({
     },
   }),
   response: {
-    ok: t.string,
+    200: t.string,
   },
 });
 ```
@@ -38,7 +38,7 @@ httpRoute({
     },
   }),
   response: {
-    ok: t.string,
+    200: t.string,
   },
 });
 ```
@@ -64,7 +64,7 @@ const Route = httpRoute({
     },
   }),
   response: {
-    ok: t.string,
+    200: t.string,
   },
 });
 
@@ -86,22 +86,22 @@ const response: string = await routeApiClient({ id: 1337 });
 ### `response`
 
 Declares the potential responses that a route may return along with the codec associated
-to each response. The possible response keys can be found in the `io-ts-response`
-package. Incoming responses are assumed to be JSON.
+to each response. Response keys correspond to HTTP status codes. Incoming responses are
+assumed to be JSON.
 
 ```typescript
 const Route = httpRoute({
   path: '/example',
   method: 'GET',
   request: httpRequest({}),
   response: {
-    ok: t.type({
+    200: t.type({
       foo: t.string,
     }),
-    notFound: t.type({
+    404: t.type({
       message: t.string,
     }),
-    invalidRequest: t.type({
+    400: t.type({
       message: t.string,
     }),
   },
@@ -154,7 +154,7 @@ const StringBodyRoute = httpRoute({
     }),
   ]),
   response: {
-    ok: t.string,
+    200: t.string,
   },
 });
 
@@ -191,7 +191,7 @@ const UnionRoute = httpRoute({
     }),
   ]),
   response: {
-    ok: string,
+    200: string,
   },
 });