module: add isPreloading indicator

[jasnell]

Adds a module.isPreloading property that is true only during the
preload (-r) phase of Node.js bootstrap. This provides modules an
easy, non-hacky way of knowing if they are being loaded during preload.

For example, sample.js:

console.log(module.isPreloading);

$ node -r sample.js -pe ""
true
undefined

$ node sample.js
false

Signed-off-by: James M Snell jasnell@gmail.com

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

[nodejs-github-bot]

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

[ShogunPanda]

Maybe it might be a little out of context for a single PR, but would it be possible to also add isMain or isEntrypoint (or whatever name you see fit) to also clearly state which was the main script launched with node?

[jasnell]

@ShogunPanda ... There's already require.main that can be used to easily make that determination. Not sure adding an additional property helps.

[jasnell]

Landed in 8ff2501

[Trott]

@nodejs/modules-active-members If there are any concerns about this, including whether isPreloading is the right name or whether module is the right place to put this property, let's tag this appropriately so it doesn't go out in a release before those things are hashed out. It seems good/correct to me, but I'll certainly defer to the experts on this.

[bmeck]

I've often thought we might instead want to use conditions to allow this, i don't know where to put a property like this PR does on an ESM thing (JS or WASM).

[ljharb]

Is this something that can be polyfilled, since it won’t be backportable earlier than node 14?

[jkrems]

Is this an attribute of the execution phase more so than of the current file? If so, could it be something imported, e.g. from module or process? That should work for both ESM and CJS.

[ljharb]

Or even simpler, a global that only exists during this phase.

[jasnell]

I've often thought we might instead want to use conditions to allow this, i don't know where to put a property like this PR does on an ESM thing (JS or WASM).

Unless we had preloads figured out for ESM, it doesn't really matter. If preloads did support it, a property in import.meta would make sense.

Is this something that can be polyfilled, since it won’t be backportable earlier than node 14?

Why wouldn't it be backportable earlier than 14? And no, it can't be polyfilled.

Is this an attribute of the execution phase more so than of the current file? If so, could it be something imported, e.g. from module or process? That should work for both ESM and CJS.

It's an attribute of the execution phase that is not relevant to ESM because preloads do not support ESM.

[ljharb]

@jasnell i was under the impression that v12.20 was the last expected minor in v12 before it goes into maintenance.

Preloads will one day support ESM, so it seems prudent to aim for a mechanism that's the same in both CJS and ESM.

[jasnell]

import { isPreloading } from 'module' 

... Should work easily enough if preloads ever actually support ESM?

There may be process reasons why it's not backported but there's no technical reason why it can't be backported. It can't be polyfilled tho.

[ljharb]

What's the advantage to making it importable when it's global state? Global state is usually accessed via "a global".

[jasnell]

I haven't made it importable. I'm just saying that it could be if necessary. The pattern I suggested is consistent with what we've done elsewhere also (see import { isMainThread } from 'worker_threads' for instance. If preloads ever actually do support ESM, the currently already landed mechanism would work consistently for both CJS and ESM. Unless someone can articulate why it wouldn't work for ESM, I'm having a hard time understanding why we're having this discussion after it's already landed.

[ljharb]

We're having the discussion after it landed because a modules feature landed without anyone on the modules github team being pinged, as is customary for any feature that has a stakeholder github team.

I think you're right that it would work fine for ESM - I'm mainly just asking why "a global" wasn't considered, given that it's global state.

[jasnell]

I'm mainly just asking why "a global" wasn't considered

I'm still confused. It was considered.

For instance...

$ node -pe "module.isPreloading" 

Feels pretty global. We even list module as a global (even if it only appears as such and isn't really one).

We do have a tradition of treating new globals as semver-major, which I wanted to avoid here. Dropping this off the existing pseudo-global module made the most sense to keep is semver-minor (and therefore backportable) and easily adaptable to ESM should that hypothetical future ever happen.

And as for pinging the modules team, I had (apparently incorrectly) assumed that the CODEOWNERS file would cover notifying the modules team of changes in the 'internal/modules/cjs/* subfolder but I guess the existing rules didn't work as they were supposed to? May be good for someone to look into that.

[ljharb]

Thanks, that answers my question (and I'm convinced; new globals are indeed semver-major, and module is indeed effectively a CJS global, and import 'module' in ESM is totally reasonable).

fwiw, i'm not implying a mistake was made or anything intentional was done or that a revert would be reasonable, it's just that the post-merge ping is the reason it's being discussed now :-) thanks for bearing with me.

[guybedford]

We should ideally make sure that the live binding for import { isPreloading } from 'module' works here. See the implementation of syncESMBuiltinExports for how to do this.

[jkrems]

Alternatively, getProcessReadyState() which would remove the need for the live binding. But either would work. :)