exp and nbf not overridden by expiresIn / notBefore as per docs

[instilled]

Hi, thanks for the great library — it’s been a pleasure to use.

I noticed a mismatch between the documentation and the implementation:

Docs: expiresIn and notBefore override any existing exp / nbf claims.

fast-jwt/README.md

Lines 30 to 32 in ad60c83

	- `expiresIn`: Time span (in milliseconds or text describing time) after which the token expires, added as the `exp` claim in the payload as defined by the [section 4.1.4 of RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4). This will override any existing value in the claim.
	> Eg: `60`, `"2 days"`, `"10h"`, `"7d"`. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default (`"120"` is equal to `"120ms"`).
	For more info look into [@lukeed/ms](https://www.npmjs.com/package/@lukeed/ms).

Code: if exp / nbf is already present in the payload, it is left untouched.

fast-jwt/src/signer.js

Lines 97 to 98 in ad60c83

	exp: payload.exp ? payload.exp : expiresIn ? Math.floor((iat + expiresIn) / 1000) : undefined,
	nbf: payload.nbf ? payload.nbf : notBefore ? Math.floor((iat + notBefore) / 1000) : undefined

This means that expiresIn (and similarly notBefore) do not actually override claims, contrary to what’s documented.

👉 I’d personally prefer the documented behavior (override) if this is an open decision, as it’s the least surprising.

[dosubot]

Hi @instilled! I'm Dosu and I’m helping the fast-jwt team.

You're correct—there is a mismatch between the documentation and the actual implementation. The code preserves any existing exp and nbf claims in the payload, so expiresIn and notBefore do not override them as the docs suggest. This behavior is confirmed in both the implementation and related discussions: if exp or nbf is present in the payload, those values are used; otherwise, the options are applied to set them (source, source).

There’s no recorded rationale or inline comment in the codebase explaining why this choice was made, and no relevant pull requests or documentation updates addressing the discrepancy. The current behavior may be due to legacy compatibility or simply an undocumented decision, but as it stands, the implementation does not match the documented override behavior (source).

If you prefer the documented behavior, it would require a change in the implementation or an update to the documentation for clarity.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}