Merge pull request #883 from BitGo/DX-704

docs: add comments to unchecked routes

Author: andrew-scott-fischer

packages/typed-express-router/src/types.ts

@@ -123,9 +123,84 @@ export type WrappedRouter<Spec extends ApiSpec> = Omit<
     put: AddRouteHandler<Spec, 'put'>;
     delete: AddRouteHandler<Spec, 'delete'>;
     patch: AddRouteHandler<Spec, 'patch'>;
+    /**
+     * This function will create a GET route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     getUnchecked: AddUncheckedRouteHandler<Spec, 'get'>;
+    /**
+     * This function will create a POST route without validating the request body, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     postUnchecked: AddUncheckedRouteHandler<Spec, 'post'>;
+    /**
+     * This function will create a PUT route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     putUnchecked: AddUncheckedRouteHandler<Spec, 'put'>;
+    /**
+     * This function will create a DELETE route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     deleteUnchecked: AddUncheckedRouteHandler<Spec, 'delete'>;
+    /**
+     * This function will create a PATCH route without validating the request, or encoding the response body.
+     * However, it will still try decode the request and set `req.decoded: Either<DecodedRequest, Error>`. To see the
+     * result of this operation, you can check `req.decoded` in your route handler like this:
+     *
+     * ```typescript
+     * import * as E from 'fp-ts/Either';
+     *
+     * if (E.isLeft(req.decoded)) {
+     *    // input validation failed
+     * } else {
+     *    // input validation succeeded
+     * }
+     * ```
+     */
     patchUnchecked: AddUncheckedRouteHandler<Spec, 'patch'>;
   };

packages/typed-express-router/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.json",
   "include": ["src/**/*", "test/**/*"],
   "compilerOptions": {
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "removeComments": false
   },
   "references": [
     {