esm: doc & validate source values for formats

[bmeck]

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

This better specifies how decoding of source values returned from loaders are translated. Some formats expect different types of sources. This also fixes some problems where Buffers were properly decoding due to the custom .toString but typed arrays were not.

We could expand the tests if desired, but I felt just checking Uint8Array was sufficient.

[GeoffreyBooth]

Looks good other than the docs note. Thanks for doing this!

[GeoffreyBooth]

Maybe it's just me, but I read this as "the source value of format", e.g. that 'builtin' should be a string. I think what you mean is the acceptable type of source returned by getSource for this format? So maybe call this "Acceptable Types for getSource Returned source"?

Should we also update the signature in getSource?

@returns{string|buffer}response.source

[bmeck]

Yes, I meant the value from either getSource OR transformSource

[GeoffreyBooth]

Okay, do you mind making that clearer? Maybe “Acceptable Types For source Returned by getSource or transformSource”?

[bmeck]

done, also made sure to actually check both hooks rather than just transformSource

[guybedford]

Nice to see this being locked down well.

[GeoffreyBooth]

Do we need to update the JSDoc function signatures? e.g.

@returns{string|buffer}response.source

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/29959/

[GeoffreyBooth]

@bmeck ☝️ #32202 (comment) do we need to fix this too?

[bmeck]

@GeoffreyBooth We could, but overall the signature isn't trivial and I think Buffer|string is the most likely realistic return value people want to know about. It would be ideal if we had something more sane to explain all the coercions code does in core (like what WebIDL provides), but we don't in core for now :(.

[bmeck]

rebased and looks green locally, will CI then land if green and no comment in next few hours

[bmeck]

rebase had a minor change, in particular I had to update ./test/fixtures/es-module-loaders/transform-source.mjs to handle if it gets a buffer back for a module format.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/30022/

[addaleax]

@bmeck Didn’t look into the other failures but at least the linter is complaining

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/30285/

[bmeck]

Fixed lint, CI errors seem unrelated

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/30813/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/31256/

[targos]

Test error without intl:

assert.js:103
throw new AssertionError(obj);
^
AssertionError [ERR_ASSERTION]: These modules were unexpectedly loaded:
NativeModule string_decoder
at Object.<anonymous> (/home/iojs/build/workspace/node-test-commit-linux-containered/test/parallel/test-bootstrap-modules.js:134:8)
at Module._compile (internal/modules/cjs/loader.js:1176:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1196:10)
at Module.load (internal/modules/cjs/loader.js:1040:32)
at Function.Module._load (internal/modules/cjs/loader.js:929:14)
at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:71:12)
at internal/main/run_main_module.js:17:47 {
generatedMessage: false,
code: 'ERR_ASSERTION',
actual: [Set],
expected: [Set],
operator: 'deepStrictEqual'
}

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/31398/

[DerekNonGeneric]

Although much of this is new material to me, the previous layout didn't really make sense to me. :/

My suggestions are how I've made sense of it, but I could be wrong. I hope we can improve this little area, it's a rather important section for those implementing types on the function boundaries of the custom loader hooks API.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/31445/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/31448/

[himself65]

landed in cd4985c