Typescript - decodeJwt & jwtVerify (and maybe others) should take in a generic for strongly typed payloads

[MrSimmmons]

Pretty much the title. I have a scenario where I have custom data in the payload of the JWT, and I have to force the type of the output of both of these methods.

My issue, is that I have to disable my linter for that line because the linter doesn't like forcing types (which is generally best practice) and I'm not a huge fan of having to do that because it kind of defeats the purpose of a linter.

// eslint-disable-next-line ...
const payload = jose.decodeJwt(token) as jose.JWTPayload & { foo: string };

So, I'm proposing to add a generic to these methods so linters can be happy

const payload = jose.decodeJwt<{ foo: string }>(token);

[panva]

Rather than relying on generics and blindly trusting what you receive I believe it's far better to have a validation function for the payload that a) validates the payload is actually of your expected type and in doing so b) uses type predicate to allow you continue with your expected type.

interface Foo extends jose.JWTPayload {
  foo: string
}

function isFoo(payload: jose.JWTPayload): payload is Foo {
  return 'foo' in payload && typeof payload.foo === 'string'
}

const { payload } = await jose.jwtVerify(token, key)

if (isFoo(payload)) {
  payload.foo // :tada:
}

[MrSimmmons]

While yes that would work, IMO its not very scaleable as the more custom key / value pairs you add just make the predicate check arbitrarily long. And especially complicated if one of the things that you are passing in the jwt is a nested object.

What about wrapping the provide generic in Partial. That way you can still "force" the user to check for undefined cases if they are required to do so

[panva]

Of course you can also omit the validation in the predicate if you want to blindly trust the shape of the received payload.

[aryzing]

@MrSimmmons you can easily validate with a schema library such as Zod.

[aryzing]

@panva how come decodeJwt doesn't use generics but jwtVerify does?

export declare function jwtVerify<PayloadType = JWTPayload>(jwt: string | Uint8Array, key: KeyLike | Uint8Array, options?: JWTVerifyOptions): Promise<JWTVerifyResult<PayloadType>>;

export declare function decodeJwt(jwt: string): JWTPayload;

[panva]

How come? I just forgot to add it there.

[panva]

https://github.com/panva/jose/releases/tag/v5.1.0