Skip to content
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
change up symbol usage, use for(;;), add tests
  • Loading branch information
devsnek committed Nov 2, 2017
commit ac2b4a1fb000a1337b96f192406a38632521b12f
16 changes: 7 additions & 9 deletions doc/api/esm.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,13 +86,12 @@ or fragment string differs between `import` statements.
CommonJS modules, when imported, will be handled in one of two ways. By default
they will provide a single `default` export representing the value of
`module.exports` at the time they finish evaluating. However, they may also
provide `@@esModule` or `__esModule` to use named exports, representing each
enumerable key of `module.exports` at the time they finish evaluating.
`@@esModule` is available as `require('module').esModule` and prefered over
`__esModule` In both cases, this should be thought of like a "snapshot" of
the exports at the time of importing; asynchronously modifying `module.exports`
will not affect the values of the exports. Builtin libraries are provided with
named exports as if they were using `@@esModule`.
provide `@@esModuleInterop` or `__esModule` to use named exports, representing
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps clarify exactly what these properties are - "provide a @esModuleInterop or __esModule boolean export indicating that a snapshot should be taken of each enumerable key..."

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good, and is it @@ or @ to doc a symbol, i thought it was two

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah it's still two, that was a typo.

each enumerable key of `module.exports` at the time they finish evaluating.
In both cases, this should be thought of like a "snapshot" of the exports at
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a snapshot of the values, or just a snapshot of the names?

The latter is necessary, but the former may not be.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought just saying exports was ok since its both the names and the values

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right - I’m saying that there’s no need for the values to be snapshotted; just the names.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

technically it isn't a snapshot, it's just a useful term to describe how it becomes static when assigned in reflection with es imports.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It’s pretty important to be precise here :-) i think “a snapshot of the names of the exports”, and indicating that if the values are updated, the resulting imports will update as well (a requirement for APM-like use cases, i understand)

the time of importing; asynchronously modifying `module.exports` will not
affect the values of the exports. Builtin libraries are provided with named
exports as if they were using `@@esModuleInterop`.

```js
import { readFile } from 'fs';
Expand All @@ -110,9 +109,8 @@ readFile('./foo.txt', (err, body) => {
import { part } from './other.js';

// other.js
import { esModule } from 'module';
exports.part = () => {};
exports[esModule] = true;
exports[Symbol.for('esModuleInterop')] = true;
```

## Loader hooks
Expand Down
11 changes: 6 additions & 5 deletions lib/internal/loader/ModuleRequest.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ const search = require('internal/loader/search');
const asyncReadFile = require('util').promisify(require('fs').readFile);
const debug = require('util').debuglog('esm');

const esModuleSymbol = exports.esModuleSymbol = Symbol('esModule');
const esModuleInterop = Symbol.for('esModuleInterop');

const realpathCache = new Map();

Expand All @@ -42,12 +42,12 @@ loaders.set('cjs', async (url) => {
const CJSModule = require('module');
const pathname = internalURLModule.getPathFromURL(new URL(url));
const exports = CJSModule._load(pathname);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This changes CJS to always evaluate prior to linking ESM which reorders imports in odd ways

const es = Boolean(exports[esModuleSymbol] || exports.__esModule);
const es = Boolean(exports[esModuleInterop] || exports.__esModule);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if it might be useful to allow [esModuleInterop]: false to cancel out __esModule when that isn't wanted?

const keys = es ? Object.keys(exports) : ['default'];
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would Object.getOwnPropertyNames(exports) make more sense?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i chose to use Object.keys so that it only exports enumerable properties. (it says so in the esm doc)

return createDynamicModule(keys, url, (reflect) => {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like createDynamicModule would throw if one of the exports was named executor because there would be duplicated exports? Seems like ideally it would generate an executor name that wouldn't conflict, or at least make it less likely to conflict.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It maps names to safeguard against this already:

${ArrayJoin(ArrayMap(names, (name) => `export let $${name};`), '\n')}

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah so it does, my mistake. Missed the $ on there.

if (es) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is branching like this faster? Otherwise seems like the else branch does exactly what the if branch does, just more generally.

Copy link
Member Author

@devsnek devsnek Nov 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i don't understand what you mean, those two blocks do different things

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sign, nevermind, just another case of misreading.

for (const key of keys)
reflect.exports[key].set(exports[key]);
for (let i = 0; i < keys.length; i++)
reflect.exports[keys[i]].set(exports[keys[i]]);
} else {
reflect.exports.default.set(exports);
}
Expand All @@ -62,7 +62,8 @@ loaders.set('builtin', async (url) => {
const keys = Object.keys(exports);
return createDynamicModule(['default', ...keys], url, (reflect) => {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not documented that builtin modules still have a default export.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps for these native module keys we should add a filter - Object.keys(exports).filter(name => name.startsWith('_') === false)? This would avoid private keys such as import { _makeLong } from 'path' being on the public API that will end up in the list for type hinting systems such as TypeScript.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please do not; _ may be used to convey hopeful privacy, but it’s always fully public.

reflect.exports.default.set(exports);
for (const key of keys) reflect.exports[key].set(exports[key]);
for (let i = 0; i < keys.length; i++)
reflect.exports[keys[i]].set(exports[keys[i]]);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the worries with doing this for native modules was that any updates to native module exports won't be seen. Specifically I think this was an issue when considering APM use cases that monkey patch any native internals.

That said, if such issues do come up, setter detection on native modules could possibly be configured to update named exports.

});
});

Expand Down
2 changes: 0 additions & 2 deletions lib/module.js
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ const errors = require('internal/errors');
const Loader = require('internal/loader/Loader');
const ModuleJob = require('internal/loader/ModuleJob');
const { createDynamicModule } = require('internal/loader/ModuleWrap');
const { esModuleSymbol } = require('internal/loader/ModuleRequest');
let ESMLoader;

function stat(filename) {
Expand Down Expand Up @@ -80,7 +79,6 @@ Module._pathCache = Object.create(null);
Module._extensions = Object.create(null);
var modulePaths = [];
Module.globalPaths = [];
Module.esModule = esModuleSymbol;

Module.wrap = function(script) {
return Module.wrapper[0] + script + Module.wrapper[1];
Expand Down
9 changes: 9 additions & 0 deletions test/es-module/test-esm-cjs-esmodule.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
// Flags: --experimental-modules
/* eslint-disable required-modules */

import assert from 'assert';
import eightyfour, { named as fourtytwo } from
'../fixtures/es-module-loaders/babel-to-esm.js';

assert.strictEqual(eightyfour, 84);
assert.strictEqual(fourtytwo, 42);
15 changes: 15 additions & 0 deletions test/fixtures/es-module-loaders/babel-to-esm.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
"use strict";

/*
created by babel with es2015 preset
```
export const named = 42;
export default 84;
```
*/

Object.defineProperty(exports, "__esModule", {
value: true
});
var named = exports.named = 42;
exports.default = 84;
4 changes: 1 addition & 3 deletions test/fixtures/es-module-loaders/cjs-to-es-namespace.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
const { esModule } = require('module');

exports.named = true;
exports.default = 1;

exports[esModule] = true;
exports[Symbol.for('esModuleInterop')] = true;
4 changes: 1 addition & 3 deletions test/fixtures/es-module-loaders/reserved-keywords.js
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
const { esModule } = require('module');

module.exports = {
enum: 'enum',
class: 'class',
delete: 'delete',
[esModule]: true,
[Symbol.for('esModuleInterop')]: true,
Copy link
Member

@jdalton jdalton Nov 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Babel folks: Any opinions on the symbol name esModuleInterop?
@hzoo @danez @loganfsmyth

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there's no need to force camelCase. ES Module Interop would work too.

Copy link
Member Author

@devsnek devsnek Nov 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

most symbols i see throughout the js world use camelCase or PascalCase, and __esModule is still supported (as it says in the docs)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Variable names do; Symbols haven't been around long enough to have an established convention around that. The string in Symbol() and Symbol.for() is a description - there's zero reason it needs to be limited to being an identifier.

Copy link
Member

@jdalton jdalton Nov 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not see the camel case debate coming... was thinking more along the lines of whether it should be Symbol.for('esModule') (so just remove the double underbar), but sure. I also wanted to pull Babel folks into this thread since it's super relevant to them.

Node is currently a bit all over the place with its symbol labels. Examples:

Symbol('util.promisify.custom')
Symbol('customPromisifyArgs')

I'm curious if Babel is transitioning to a symbol key as well and if they already have a name.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely appreciate the ping. I personally don't see that it'd be feasible for us to use a Symbol because the code could be running on a platform that doesn't support Symbols, assuming I'm following all this properly, but it probably does make sense to use a Symbol in the long run for loaders, assuming Symbol support is known to exist.

};