Should decoding the header be a seperate function?

[jonkoops]

I was thinking, since we're changing the public API for v4 anyways, would it perhaps make more sense to have a separate function to decode the header? If would make our types less complex, as the decode function would no longer have a polymorphic return type.

For example, the following code:

import { jwtDecode } from "jwt-decode";

const token = "eyJ0eXAiO.../// jwt token";
const payload = jwtDecode(token);
const header = jwtDecode(token, { header: true });

Would become:

import { decodePayload, decodeHeader } from "jwt-decode";

const token = "eyJ0eXAiO.../// jwt token";
const payload = decodePayload(token);
const header = decodeHeader(token);

This would also allow further expansion quite easily, for example if we wanted to add support to read the signature:

import { decodePayload, decodeHeader, decodeSignature } from "jwt-decode";

const token = "eyJ0eXAiO.../// jwt token";
const payload = decodePayload(token);
const header = decodeHeader(token);
const signature = decodeSignature(token);

Or perhaps we could even add a convenience method to do all of the above all at once:

import { decodeToken } from "jwt-decode";

const token = "eyJ0eXAiO.../// jwt token";
const { header,  payload, signature } = decodeToken(token);

[frederikprijck]

On one hand, I can definetly see the benefit. On the other hand, it has always worked like this and the intention of this new major version was not to reinvent the library, but merely modernize things abit in terms of setup, drop polyfills and ESM/CJS. Even more so, the intention was not to change the public API, but we eventually did for the sake of ESM/CJS.

Personally, I like what you propose over what we currently have. However, no one has ever asked for anything like that so I am more keen to keeping things as is. On top of that, even though the difference is minimal, it's slightly easier to migrate if we keep it as is.

[jonkoops]

If the issue is the cost of migration we could opt to keep the jwtDecode() function, but simply alias it to decodePayload() or decodeHeader() based on the options passed into it. Naturally, it should be a deprecated feature that will be removed in the future, but it could allow for easier migration.

But quite honestly, the migration would be extremely small considering the API surface.

[jonkoops]

@frederikprijck now that the major has landed, perhaps we want to revisit this? I'd be up for adding some convenience methods for decodePayload() and decodeHeader().

[frederikprijck]

Having discussed this internally with the team, we believe we want to leave the API as is. The current codebase is only a couple of lines and exports a single function and we would like to keep it like that to leave the public API as stable as possible.

We understand adding these two functions wouldn't break anything, but we also feel like it's not something we want to add at the moment, especially given the little value it adds compared to the documentation/blogposts/stack overflow being out there about jwt-decode.

[jonkoops]

Got it, then let's consider this resolved 👍