Improve documentation

[rpivo]

I'm trying to understand what this proposal does, and have been looking at this document: https://tc39.es/dynamic-import-host-adjustment/.

It appears that the linked document is a stage 0 draft, while this proposal is currently at stage 2. Does any additional documentation for this proposal exist somewhere?

It would be great if the details of this specification could be fleshed out a little more on GitHub. I'm happy to help with this effort if notes are provided somewhere, or if details can be relayed in a call or something.

Thanks!

[ljharb]

I assume the spec hasn't changed, just the stage number has.

[rpivo]

Thanks for the clarification, @ljharb.

For my own understanding, I typed out the below description. If this is not correct at all, please let me know (or feel free to edit). 😬

---

The Dynamic Import Host Adjustment proposal would help prevent DOM XSS (cross-site scripting) from occurring while using dynamic import statements.

This proposal would update the dynamic import specification to be able to ingest an object containing a toString() method that stringifies the import. If a Trusted Types policy exists for this string, then the dynamic import resolves, and the module will successfully be imported.

const m = import({
  toString() {
    return './foo';
  },
};

m.then(
  (contents) => { console.log('module resolved', contents); },
  () => { console.log('module rejected'); }
);

[koto]

Hey Ryan,

The idea is that the stringification happens in the host, and the (non-stringified) specifier gets passed to the host, which returns a string (or rejects the import). The integration mechanism for the hosts is indeed Trusted Types. Specifically, the specifiers would be passed to Get Trusted Types compliant string which asserts that the object itself is already a TrustedScriptURL or that a default policy agrees to create one from the passed string.

We were trying to avoid referring to Trusted Types directly in the proposal, but if you think this makes the proposal goal easier to ingest, let's do it.

[rpivo]

@koto thanks -- that makes sense. There seems to be a lot of Trusted Types documentation, which is linked in the readme -- maybe there doesn't need to be any more description of trusted types here.

I think it might help if there's a quick example in the readme showing a dynamic import trying to import something, with success and failure scenarios.