Naming bikeshed - require(esm) interop flag

[guybedford]

As discussed in today's meeting, we need to come up with a name for the flag that will allow require(esm) to support a custom value for a CJS module.

The pattern is that users can write:

export const __cjsModule = true;
export default module.exports;

where module.exports can be any type of object, which will be returned by require(esm) when it sees this __cjsModule flag, instead of returning the full namespace.

@joyeecheung suggested a good name might be one that describes what it does, eg cjsUnwrapDefault.

It should be unique enough that it will not collide with an existing export name for any ES module in use today.

Opening this thread for further discussion and suggestions, although I'm happy to go with something like @joyeecheung's option here above as well.

[mcollina]

I would still prefix it with __, so __cjsUnwrapDefault would be good for me.

[guybedford]

@mcollina thanks, I do tend to support similar, would you be able to share motivation further here for the prefixing?

[mcollina]

Let users seeing this it's something internal.

[guybedford]

In the case of libraries shipping ES modules that they want to define with non-object values in CJS, the goal is for authors to add this themselves. So perhaps that’s an argument against it then?

…

On Sun, Aug 25, 2024 at 19:55 Matteo Collina ***@***.***> wrote: Let users seeing this it's something internal. — Reply to this email directly, view it on GitHub <#221 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAESFSRKXL3L5VACLLESNIDZTKKJJAVCNFSM6AAAAABMPELMI2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMBZGIYDCMZVGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[joyeecheung]

I am not sure how internal this actually is - it's meant for library authors who want to ship ESM to keep their exports look the same to CJS users. Say for this pretty common pattern on npm:

// package foo is just this file
module.exports = function foo () { ... };

Now the author wants to ship it as ESM, then they change it to

// package foo is just this file
export default function foo() { ... }

Now that works for ESM users, but then for CJS users, it would require code changes for them to use the newer version of the library (shipping ESM-only should better be semver-major regardless, because it makes the exports un-mockable, since ESM exports are immutable - but at the end of the day this is up to the discretion of the library author).

const foo = require('foo');  // This now doesn't work
const foo = require('foo').default;  // It now needs to be like this

So the new flag helps library authors to unwrap their default exports in require(), which means they should write the ESM version as

export default function foo() { ... }
export const whateverThisFlagIsCalled = true;  // This tells Node.js to return namespace.default from require()

Now to their existing CJS users, require('foo') just returns default exports without further unwrapping. This creates a disparity between require() and import() - obviously to support something similar in the latter one needs to convince TC39 for some special syntax, but at least in the meanwhile we have some kind of polyfill to help libraries targeting Node.js to transition. In any case, this is likely to be hand-written by library authors, so it's not very internal IMO. The only internal part is to their ESM consumers, as they will see it via import * as mod from 'foo' or import('foo'), but then it's going to be a well-documented flag, and it may be useful to them if they actually want to test around it, so I am not sure what we get from trying to hide them.

[guybedford]

Okay, agreed that as a user feature and since we have a very unique name, that removing the prefix can be considered. I'm updating the PR to that effect now.

[ljharb]

I dunno, it's still a magic string, and __esModule is already a thing - __something seems like a more consistent and safe choice.

[marco-ippolito]

I dunno, it's still a magic string, and __esModule is already a thing - __something seems like a more consistent and safe choice.

I agree it should start with __ so its pretty obvious its an internal (or meta)

[joyeecheung]

__esModule is a convention used by tools and humans are not supposed to hand-write them. But this flag is meant to be hand-written by human beings.

I don’t feel strong enough to insist on it, anyway. Just be aware this flag isn’t private - it will be documented, and is meant to be hand-written by human beings.

[nicolo-ribaudo]

If this was not on the module namespace object but on a random object, it would probably be a symbol. It's not to hide it, but just to clearly communicate that it's a special value and not just part of the arbitrary keys namespace that random objects can have.

For example, we have Symbol.for('nodejs.util.inspect.custom') and we don't just ready a random utilInspectCustom property on objects, even if that symbol is for hand-written custom inspection implementations that libraries can provide for their objects.

We cannot have symbols on module namespaces, but we should still have some visual marker that says "this property is somewhat different from the other exports".

[joyeecheung]

I wonder if we can do this instead:

function foo() {}

export { foo as "module.exports" };  // Or prefix it with `nodejs`, but "module.exports" feel way nicer
export default foo;

[mcollina]

@joyeecheung love it

[ljharb]

That's already a valid export name, though (as are all strings), so I don't think it avoids the need for a human-visible string indicator that it's internal to node, like __.

[joyeecheung]

These are all valid names, but "module.exports" is probably special and Node.js specific enough (that and string names tend to be rarer than normal names already). Also I think the intention of this is the easiest to guess.