ESM Hooks: nextResolve & nextLoad can return promises which is not reflected in documentation

[koshic]

Affected URL(s)

https://nodejs.org/dist/latest-v20.x/docs/api/esm.html#hooks

Description of the problem

But in the reality nextResolve (and nextLoad) can return Promises, which is highly confusing: as an example, try...catch around 'return nextResolve(...)' will never catch the error if nextResolve returns rejected Promise. The same thing with access to nextResolve(...) result properties.

In both cases await keyword is mandatory to get predictable results.

[aduh95]

Would you like to send a PR?

[koshic]

Would you like to send a PR?

Sorry, I don't have enough time 😒

[GeoffreyBooth]

Our linter complains if we do return await, because it’s unnecessary, so you might see code like return nextResolve(...). But I think our examples always await the next* call when we’re using the returned value.

@koshic What changes in the docs would make things more obvious to you? Would the changes discussed in #49265 (comment) have been sufficient?

[koshic]

Our linter complains if we do return await, because it’s unnecessary...

Small off topic: do you mean https://eslint.org/docs/latest/rules/no-return-await? 'This rule was deprecated in ESLint v8.46.0 with no replacement' (c)

@koshic What changes in the docs would make things more obvious to you? Would the changes discussed in #49265 (comment) have been sufficient?

Looks better than existing docs due to 'async'. My issue is a bit late, thx! )