Explainer by kriskowal · Pull Request #1 · endojs/proposal-import-hook

kriskowal · 2025-07-17T20:18:46Z

This migrates and updates the explainer for what was Compartments Layer 0: Module and ModuleSource. The new proposal drops the parts of Source Phase Imports and ESM Phase Imports that have already progressed to Stage 2.7 and consolidates the Module and ModuleInstance, with an additional design rationale section explaining why I am personally favoring that direction.

github-actions · 2025-07-17T20:20:32Z

The rendered spec for this PR is available at https://endojs.github.io/proposal-import-hook/pr/1.

erights · 2025-07-17T22:32:33Z

The rendered spec for this PR is available at https://endojs.github.io/proposal-import-hook/pr/1.

That gives me a 404

erights · 2025-07-17T22:30:44Z

CONTRIBUTING.md

+# template-for-proposals
+
+A repository template for ECMAScript proposals.


Is this guide to contributing a proposal mistakenly copied from the template?

Rather than delete it, I moved it out of the way.

did you? forgot to push?

totally fine to delete it too, the content's visible on the template and in the history :-p

erights · 2025-07-17T22:37:12Z

README.md

+> The handler is necessary for capturing a base specifier for resolving a
+> relative import specifier, and allows 262 to avoid unnecssary specificity
+> about resolution algorithms.


Why quoted? What is it quoting? (Likewise for other uses of > )

It’s parenthetical commentary.

erights · 2025-07-17T22:39:02Z

README.md

+  importHook?: ImportHook,
+  importMetaHook?: ImportMetaHook,
+  // ...
+  [name: string | symbol | number]: unknown,


Would not actually be part of a TypeScript type for typing what this proposal proposes, yes?

This is intended to communicate that the handler may have other, unspecified properties that are communicated as normal through to the receivers of the hooks.

erights · 2025-07-17T22:52:09Z

README.md

+> For consideration: for a dynamic import, we may or may not pass the given
+> import attributes object through to import hooks, and we may or may not
+> assert or otherwise adjust the key order to be canonicalized.
+> The canonical order is important for the implementation to form a
+> deterministic cache key from arbitrary attributes but an import hook should
+> not be sensitive to that order.


This sounds like a crazy degree of non-determinism to allow an implementation. Can we pin this down in the obvious way?

We have that option, yes. I wrote it both ways, so it’s a good point to raise in an issue for discussion.

erights · 2025-07-17T22:56:23Z

README.md

+
+> The Module Harmony group elected to avoid deferring the import meta hook
+> to the first evaluation of an `import.meta` expression, but leaves the option
+> open for a host hook, just not a user code hook.


Breaking host virtualizability? This seems bad.

Hosts do not currently do anything with the privilege of deferring creation of import.meta that is observably different than populating import.meta before execution, except that they are able to avoid the allocation and population of the import.meta in cases where import.meta is uttered in the source but never executed.

erights · 2025-07-17T23:09:45Z

README.md

+for the corresponding module namespace.
+In that process, the implementation will call `importHook` for each module
+imported statically and dynamically in that module, giving it the module
+specifier string an canonicalized import attributes.


erights · 2025-07-17T23:51:07Z

README.md

+## New Global
+
+This import hooks proposal creates a foundation for a [`new Global`
+proposal](proposal-new-global), which in turn provides a sufficient foundation


The rendered link is broken

Suggested change

proposal](proposal-new-global), which in turn provides a sufficient foundation

proposal](https://github.com/endojs/proposal-new-global/), which in turn provides a sufficient foundation

until it moves to a better place?

The errors is using parens rather than brackets.

erights · 2025-07-17T23:52:29Z

README.md

+
+This import hooks proposal creates a foundation for a [`new Global`
+proposal](proposal-new-global), which in turn provides a sufficient foundation
+to implement [`Compartment` proposal](proposal-compartments) and


Suggested change

to implement [`Compartment` proposal](proposal-compartments) and

to implement [`Compartment` proposal](https://github.com/tc39/proposal-compartments) and

erights · 2025-07-17T23:54:54Z

README.md

+We expect a future proposal to introduce `import.now` or `import.sync` as a
+mechanism for synchronously growing the module graph and executing a module.
+If so, `ModuleSource` handlers would need a corresponding synchronous import
+hook that may not return a promise.


Suggested change

hook that may not return a promise.

hook that must not return a promise.

?

erights · 2025-07-17T23:56:34Z

README.md

+going async there has no implications whatsoever.
+In prior iterations of this, the user was responsible for loop thru the
+dependencies, and prepare the instance before kicking the next phase, that's
+not longer the case here, where the level of control on the different phases is


Suggested change

not longer the case here, where the level of control on the different phases is

no longer the case here, where the level of control on the different phases is

erights · 2025-07-17T23:57:24Z

README.md

+
+Since the `importHook` is only triggered via the kicker (`import(instance)`),
+going async there has no implications whatsoever.
+In prior iterations of this, the user was responsible for loop thru the


Suggested change

In prior iterations of this, the user was responsible for loop thru the

In prior iterations of this, the user was responsible for looping thru the

erights · 2025-07-17T23:57:58Z

README.md

+Since the `importHook` is only triggered via the kicker (`import(instance)`),
+going async there has no implications whatsoever.
+In prior iterations of this, the user was responsible for loop thru the
+dependencies, and prepare the instance before kicking the next phase, that's


Suggested change

dependencies, and prepare the instance before kicking the next phase, that's

dependencies, and preparing the instance before kicking the next phase. That's

erights · 2025-07-17T23:58:35Z

README.md

+
+### Can cycles be represented?
+
+Yes, `importHook` can return a `Module` that was either `import()` already or


Suggested change

Yes, `importHook` can return a `Module` that was either `import()` already or

Yes, `importHook` can return a `Module` that was either `import()`ed already or

erights

Approving because, even without my suggestions, it is more than good enough to point to from the draft agenda before deadline. All suggestions can be addressed after.

README is now CONTRIBUTING

7485b7f

kriskowal requested a review from erights July 17, 2025 21:23

erights reviewed Jul 17, 2025

View reviewed changes

erights approved these changes Jul 18, 2025

View reviewed changes

Migrate and update explainer from Compartments layer 0

667d375

kriskowal force-pushed the explainer branch from d36af41 to 667d375 Compare July 18, 2025 01:47

kriskowal merged commit 1fac314 into main Jul 18, 2025
1 check passed

kriskowal deleted the explainer branch July 18, 2025 01:47

		# template-for-proposals

		A repository template for ECMAScript proposals.

	proposal](proposal-new-global), which in turn provides a sufficient foundation
	proposal](https://github.com/endojs/proposal-new-global/), which in turn provides a sufficient foundation

	to implement [`Compartment` proposal](proposal-compartments) and
	to implement [`Compartment` proposal](https://github.com/tc39/proposal-compartments) and

	hook that may not return a promise.
	hook that must not return a promise.

	not longer the case here, where the level of control on the different phases is
	no longer the case here, where the level of control on the different phases is

	In prior iterations of this, the user was responsible for loop thru the
	In prior iterations of this, the user was responsible for looping thru the

	dependencies, and prepare the instance before kicking the next phase, that's
	dependencies, and preparing the instance before kicking the next phase. That's


		### Can cycles be represented?

		Yes, `importHook` can return a `Module` that was either `import()` already or

Conversation

kriskowal commented Jul 17, 2025

Uh oh!

github-actions bot commented Jul 17, 2025

Uh oh!

erights commented Jul 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erights left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants