esm: update example-loader test fixture & API docs

[DerekNonGeneric]

• Remove importing of URL & process as is unnecessary (they exist in global scope)
• Correct all type annotations (param & returns) to be accurate to both TypeScript & Closure
• Fix bare-import check error message to be accurate and grammatically correct
• Update bare-import check to more closely match language used in error message
• Update command that runs the example to be cross-platform
• Prefer use of captialized {Function} type annotation over {function}
• Update prose regarding the condition in which parentModuleURL is undefined
• Move assignment of parentModuleURL to inside the resolve hook function
• Prefer --experimental-loader to --loader (taken care of in another PR)

Fixes: #29610

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[DerekNonGeneric]

@bmeck, WDYT?

[Trott]

@nodejs/modules-active-members @nodejs/documentation This could use some reviews.

[Trott]

@nodejs/collaborators This could use some reviews.

[DerekNonGeneric]

@Trott, thanks for reaching out to everyone, the topic of type checking .mjs files using TypeScript/Closure compiler-style JSDoc comments seems to be a little more involved than I initially thought. At this point in my continuing research on the topic, I'd like to caution people who are unfamiliar with it and happen to arrive at this PR eager to help. Ensuring that JSDoc type annotations are interoperable between the TypeScript and Closure type systems is not a small feat to accomplish. There are some odd considerations that need to be made, which I intend on addressing. I have a good solution that I hope to demonstrate in an example repo. As such, I recommend holding off on further revision until it's ready.

[DerekNonGeneric]

As promised, I have created the demonstration repo. It would be great if everyone involved could take a brief moment to ensure that the compilers have their options set correctly. This takes place in tasks/typecheck-sources.js. Thanks in advance! The solution proposed in the PR will be kept up to date on the dummy-loader-solution branch for anyone interested in playing with it.

/to @bmeck @guybedford @jkrems @weswigham @devsnek @vsemozhetbyt @BridgeAR

[DerekNonGeneric]

I'd like to bring to the attention of those designing the resolver hook API what is probably the most significant finding of this whole effort: the order of the parameters is not ideal for Closure. As it currently stands, Closure emits the following warning:

WARNING - [JSC_OPTIONAL_ARG_AT_END] optional arguments must be at the end
export async function resolve(specifier, parentModuleURL = undefined, defaultResolver) {
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

0 error(s), 1 warning(s), 83.9% typed

Apparently, Closure wants the optional param to be last. It might be best to change this while we still can if there's no justification for keeping the current order.

[jkrems]

LGTM in general

[DerekNonGeneric]

/to @nodejs/modules-active-members

Other than the merge conflict, is anything blocking this?

[GeoffreyBooth]

We should land this with #30986, which also refactors resolve.

[DerekNonGeneric]

@GeoffreyBooth, how would you recommend we do this? Should I make a PR to your fork?

[GeoffreyBooth]

Cc @bmeck or @guybedford for opinions.

Does this PR have any conflicts with that one? If not yeah, I guess you can PR my branch and then this work becomes part of that PR. Anyone object to this plan?

[DerekNonGeneric]

No word from @bmeck or @guybedford. Is applying types to the code samples still desired?

[GeoffreyBooth]

I think it's desired, can you rebase?

[HarshithaKP]

@DerekNonGeneric, this needs a rebase.

[DerekNonGeneric]

Glad to see there's still interest in this. There are a few reasons why a rebase of this PR hasn't happened yet and some of the discussion about it has happened outside of this thread. Allow me to bring folks up to speed.

1. When this PR was made, there was only one loader sample on the docs page.
2. This code sample was also a test fixture, which made it easy to pull in/import/embed.
3. New hooks have been added to the custom loader API along with several more code samples.
4. These new hook samples do not have corresponding fixtures in the test directory.

I believe @GeoffreyBooth had mentioned that he had the new hook samples as individual files during a sync we had. I'm still unclear whether fixtures can play this dual role as samples or if they should live in a separate directory or even repo. I got a new email address and sent out a hangouts invitation—happy to set up another sync or continue the conversation. Please keep me posted.

[DerekNonGeneric]

/to @HarshithaKP

@DerekNonGeneric, this needs a rebase.

With my previous comment in mind, I've rebased the PR to continue in the spirit of the original PR. This fixture no longer exists as a sample in the docs, so hopes of embedding it as one are probably lost. I was not the one who added the new samples, but I will note that they are neither valid TypeScript Compiler nor Closure Compiler annotations. Fixing all of them in this PR would beyond its scope, though. There are also two larger examples (the https loader and transpiler loader) that need work.

Ideally these samples would live in their own files and be subject to typechecking and linting prior to being embedded into the docs via a templating engine otherwise you inevitably end up providing bad samples to users, which isn't uncommon.

[DerekNonGeneric]

Closing in favor of #32646 as this branch name is no longer relevant.