From de169def56f98f4237741aa6755d0c5e248bd561 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=C2=A0F=2E=20Romaniello?= <jfromaniello@gmail.com>
Date: Fri, 6 May 2022 12:06:58 -0300
Subject: [PATCH] deprecate ExpressJwtRequest in favor of Request with optional
 auth, closes #284

---
 README.md    | 27 +++------------------
 src/index.ts | 67 +++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 67 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index f7a43fb2..f02f4cee 100644
--- a/README.md
+++ b/README.md
@@ -244,34 +244,13 @@ To get the full types of the parameters object install also `@types/jsonwebtoken
 An `ExpressJwtRequest` type is provided which extends `express.Request` with the `auth` property.
 
 ```typescript
-import { expressjwt, ExpressJwtRequest } from "express-jwt";
+import { expressjwt, Request as JWTRequest } from "express-jwt";
 
 app.get(
   "/protected",
   expressjwt({ secret: "shhhhhhared-secret", algorithms: ["HS256"] }),
-  function (req: ExpressJwtRequest, res: express.Response) {
-    if (!req.auth.admin) return res.sendStatus(401);
-    res.sendStatus(200);
-  }
-);
-```
-
-If you use `credentialsRequired: false` then use `ExpressJwtRequestUnrequired`. This type defines `req.auth` as optional, example:
-
-```typescript
-import { expressjwt, ExpressJwtRequest } from "express-jwt";
-
-app.get(
-  "/protected",
-  expressjwt({
-    secret: "shhhhhhared-secret",
-    algorithms: ["HS256"],
-    credentialsRequired: false,
-  }),
-  function (req: ExpressJwtRequestUnrequired, res: express.Response) {
-    if (!req.auth?.admin) {
-      return res.sendStatus(401);
-    }
+  function (req: JWTRequest, res: express.Response) {
+    if (!req.auth?.admin) return res.sendStatus(401);
     res.sendStatus(200);
   }
 );
diff --git a/src/index.ts b/src/index.ts
index ee4472fc..9db3c5b8 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,33 +3,94 @@ import * as express from 'express';
 import expressUnless from 'express-unless';
 import { UnauthorizedError } from './errors/UnauthorizedError';
 
+/**
+ * A function that defines how to retrieve the verification key given the express request and the JWT.
+ */
 export type GetVerificationKey = (req: express.Request, token: jwt.Jwt | undefined) => jwt.Secret | Promise<jwt.Secret>;
 
-//deprecates key callback types for backward compatibility with v6
+/**
+ * @deprecated use GetVerificationKey
+ */
 export type SecretCallback = GetVerificationKey;
+
+/**
+ * @deprecated use GetVerificationKey
+ */
 export type SecretCallbackLong = GetVerificationKey;
-//
 
+/**
+ * A function to check if a token is revoked
+ */
 export type IsRevoked = (req: express.Request, token: jwt.Jwt | undefined) => boolean | Promise<boolean>;
+
+/**
+ * A function to customize how a token is retrieved from the express request.
+ */
 export type TokenGetter = (req: express.Request) => string | Promise<string> | undefined;
 
 type Params = {
+  /**
+   * The Key or a function to retrieve the key used to verify the JWT.
+   */
   secret: jwt.Secret | GetVerificationKey,
+
+  /**
+   * Defines how to retrieves the token from the request object.
+   */
   getToken?: TokenGetter,
+
+  /**
+   * Defines how to verify if a token is revoked.
+   */
   isRevoked?: IsRevoked,
+
+  /**
+   * If sets to true, continue to the next middleware when the
+   * request doesn't include a token without failing.
+   *
+   * @default true
+   */
   credentialsRequired?: boolean,
+
+  /**
+   * Allows to customize the name of the property in the request object
+   * where the decoded payload is set.
+   * @default 'auth'
+   */
   requestProperty?: string,
+
+  /**
+   * List of JWT algorithms allowed.
+   */
   algorithms: jwt.Algorithm[];
 } & jwt.VerifyOptions;
 
 export { UnauthorizedError } from './errors/UnauthorizedError';
 
+/**
+ * @deprecated this breaks tsc when using strict: true
+ */
 export type ExpressJwtRequest<T = jwt.JwtPayload> =
   express.Request & { auth: T }
 
+/**
+ * @deprecated use Request<T>
+ */
 export type ExpressJwtRequestUnrequired<T = jwt.JwtPayload> =
   express.Request & { auth?: T }
 
+/**
+ * The Express Request including the "auth" property with the decoded JWT payload.
+ */
+export type Request<T = jwt.JwtPayload> =
+  express.Request & { auth?: T };
+
+/**
+ * Returns an express middleware to verify JWTs.
+ *
+ * @param options {Params}
+ * @returns
+ */
 export const expressjwt = (options: Params) => {
   if (!options?.secret) throw new RangeError('express-jwt: `secret` is a required option');
   if (!options.algorithms) throw new RangeError('express-jwt: `algorithms` is a required option');
@@ -108,7 +169,7 @@ export const expressjwt = (options: Params) => {
         throw new UnauthorizedError('revoked_token', { message: 'The token has been revoked.' });
       }
 
-      const request = req as ExpressJwtRequest<jwt.JwtPayload | string>;
+      const request = req as Request<jwt.JwtPayload | string>;
       request[requestProperty] = decodedToken.payload;
       next();
     } catch (err) {