Support legacy systems importing ESM

[NSeydoux]

Currently, the jose library exports ES modules with an exports map in package.json. This is quite future-proof, and works with up-to-date tools, but a significant part of the JS front-end ecosystem still doesn’t support this, e.g.:

• Webpack 4 (Webpack 5 does),
• Jest
• Parcel
• TypeScript

Therefore, adopting jose for a library (which is our use case) puts some constraints on the dependents of that library. One way to mitigate this, which should be relatively low-cost to jose, would be to add an index file that re-exports all the sub-modules, with a series of exports looking like the following:

export {
    JWTVerifyGetKey,
    jwtVerify
} from "./jwt/verify";
// ...

...and to add the following entry to the package.json file, e.g.:

"module": "./dist/browser/index.js",

Doing this means one could write import { jwtVerify } from 'jose' if they do not/cannot support import { jwtVerify } from 'jose/jwt/verify'. This shouldn’t have any impact on users that support exports map.

Would you have any objections to jose supporting this export mode as well as the current one ? If you’re okay with it, I’m happy to create a PR containing the suggested additions.

[panva]

@NSeydoux it is only a matter of time before the tooling ecosystem catches up with node's import/require algorithm. Conditional and subpath exports are now available and stable in all Node.js versions that are not End-of-Life, that means LTS Maintenance, Active LTS, and Current. As such I do not feel like stepping down from exclusively using this scheme just yet.

FYI I took a stab at a flat index file once or twice already and always dropped the effort for one reason or another. Types not being loaded anymore, adjust type loading mapping, then types didn't work for the actual modules.

If you feel like putting in the time then by all means, but it's not before I see the final impact of that PR that I can say I'd accept it.

[panva]

Oh, one more note. I intentionally do not care for or wish to support Webpack below version 5 because of its horrific polyfill behaviours. Last thing I need is a slew of "issues" about crypto.getCurves() not being a function or similar due to its use of a default crypto polyfill from 2018. I test the supported runtimes extensively. If tooling doesn't wish to play ball with Node.js module resolution algorithm, so be it.

[Vinnl]

I took a stab at this at #202, let me know what you think. I think I'd just keep this as an undocumented option for those who are stuck with tooling that hasn't caught up yet (and don't automatically add their own incomplete polyfills), hopefully there shouldn't be too many issues then.

[panva]

I'm done waiting for these ecosystems to catch up. jose v4.x will be coming out today/tomorrow with only top level named exports that solve all these tools' problems.