From 15c3b8098acc0661e7e0ae8d1828fd3206d83852 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 14 Oct 2023 05:52:38 +0200 Subject: [PATCH] esm: use import attributes instead of import assertions The old import assertions proposal has been renamed to "import attributes" with the follwing major changes: 1. The keyword is now `with` instead of `assert`. 2. Unknown assertions cause an error rather than being ignored, This commit updates the documentation to encourage folks to use the new syntax, and add aliases for module customization hooks. PR-URL: https://github.com/nodejs/node/pull/50140 Fixes: https://github.com/nodejs/node/issues/50134 Refs: https://github.com/v8/v8/commit/159c82c5e6392e78b9bba7161b1bed6e23758984 Reviewed-By: Geoffrey Booth Reviewed-By: Jacob Smith Reviewed-By: Benjamin Gruenbaum --- .eslintignore | 2 + .eslintrc.js | 7 +- doc/api/errors.md | 17 ++++- doc/api/esm.md | 29 +++++--- doc/api/module.md | 19 +++-- lib/internal/errors.js | 9 ++- lib/internal/modules/cjs/loader.js | 8 +-- lib/internal/modules/esm/assert.js | 54 +++++++------- lib/internal/modules/esm/hooks.js | 54 +++++++++++--- lib/internal/modules/esm/load.js | 16 ++++- lib/internal/modules/esm/loader.js | 70 +++++++++---------- lib/internal/modules/esm/module_job.js | 11 ++- lib/internal/modules/esm/module_map.js | 16 ++--- lib/internal/modules/esm/translators.js | 6 +- lib/internal/modules/esm/utils.js | 6 +- lib/internal/process/execution.js | 4 +- lib/repl.js | 8 +-- src/module_wrap.cc | 44 ++++++------ src/module_wrap.h | 2 +- ...s => test-esm-dynamic-import-attribute.js} | 0 ... => test-esm-dynamic-import-attribute.mjs} | 0 .../es-module/test-esm-import-assertion-2.mjs | 6 -- .../test-esm-import-assertion-validation.js | 45 ------------ .../test-esm-import-assertion-warning.mjs | 43 +++++++++--- ...1.mjs => test-esm-import-attributes-1.mjs} | 0 ...4.mjs => test-esm-import-attributes-2.mjs} | 0 ...3.mjs => test-esm-import-attributes-3.mjs} | 0 ...s => test-esm-import-attributes-errors.js} | 12 ++-- ... => test-esm-import-attributes-errors.mjs} | 10 +-- .../test-esm-import-attributes-validation.js | 45 ++++++++++++ test/es-module/test-esm-json.mjs | 1 - test/es-module/test-esm-virtual-json.mjs | 2 +- .../assertionless-json-import.mjs | 14 ++-- .../builtin-named-exports-loader.mjs | 2 +- .../es-module-loaders/hooks-custom.mjs | 4 +- .../es-module-loaders/hooks-input.mjs | 12 ++-- .../loader-invalid-format.mjs | 2 +- .../es-module-loaders/loader-invalid-url.mjs | 4 +- .../es-module-loaders/loader-with-dep.mjs | 4 +- .../not-found-assert-loader.mjs | 4 +- .../es-module-loaders/string-sources.mjs | 2 +- .../parallel/test-vm-module-dynamic-import.js | 4 +- tools/dep_updaters/update-eslint.sh | 4 +- .../lib/index.js | 19 ----- .../LICENSE | 0 .../lib/index.js | 31 ++++++++ .../package.json | 10 ++- .../data/features/css-display-contents.js | 2 +- .../node_modules/caniuse-lite/package.json | 2 +- .../full-chromium-versions.js | 13 +++- .../full-chromium-versions.json | 2 +- .../electron-to-chromium/full-versions.js | 7 +- .../electron-to-chromium/full-versions.json | 2 +- .../electron-to-chromium/package.json | 2 +- 54 files changed, 401 insertions(+), 291 deletions(-) rename test/es-module/{test-esm-dynamic-import-assertion.js => test-esm-dynamic-import-attribute.js} (100%) rename test/es-module/{test-esm-dynamic-import-assertion.mjs => test-esm-dynamic-import-attribute.mjs} (100%) delete mode 100644 test/es-module/test-esm-import-assertion-2.mjs delete mode 100644 test/es-module/test-esm-import-assertion-validation.js rename test/es-module/{test-esm-import-assertion-1.mjs => test-esm-import-attributes-1.mjs} (100%) rename test/es-module/{test-esm-import-assertion-4.mjs => test-esm-import-attributes-2.mjs} (100%) rename test/es-module/{test-esm-import-assertion-3.mjs => test-esm-import-attributes-3.mjs} (100%) rename test/es-module/{test-esm-import-assertion-errors.js => test-esm-import-attributes-errors.js} (84%) rename test/es-module/{test-esm-import-assertion-errors.mjs => test-esm-import-attributes-errors.mjs} (81%) create mode 100644 test/es-module/test-esm-import-attributes-validation.js delete mode 100644 tools/node_modules/eslint/node_modules/@babel/plugin-syntax-import-assertions/lib/index.js rename tools/node_modules/eslint/node_modules/@babel/{plugin-syntax-import-assertions => plugin-syntax-import-attributes}/LICENSE (100%) create mode 100644 tools/node_modules/eslint/node_modules/@babel/plugin-syntax-import-attributes/lib/index.js rename tools/node_modules/eslint/node_modules/@babel/{plugin-syntax-import-assertions => plugin-syntax-import-attributes}/package.json (66%) diff --git a/.eslintignore b/.eslintignore index 153ac6e24f731e..6f3d86e6bfac8a 100644 --- a/.eslintignore +++ b/.eslintignore @@ -8,5 +8,7 @@ tools/lint-md/lint-md.mjs benchmark/tmp benchmark/fixtures doc/**/*.js +doc/changelogs/CHANGELOG_v1*.md +!doc/changelogs/CHANGELOG_v18.md !doc/api_assets/*.js !.eslintrc.js diff --git a/.eslintrc.js b/.eslintrc.js index 6107469443ab61..9c31bf3da17dbf 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -18,7 +18,7 @@ const hacks = [ 'eslint-plugin-jsdoc', 'eslint-plugin-markdown', '@babel/eslint-parser', - '@babel/plugin-syntax-import-assertions', + '@babel/plugin-syntax-import-attributes', ]; Module._findPath = (request, paths, isMain) => { const r = ModuleFindPath(request, paths, isMain); @@ -44,7 +44,10 @@ module.exports = { parserOptions: { babelOptions: { plugins: [ - Module._findPath('@babel/plugin-syntax-import-assertions'), + [ + Module._findPath('@babel/plugin-syntax-import-attributes'), + { deprecatedAssertSyntax: true }, + ], ], }, requireConfigFile: false, diff --git a/doc/api/errors.md b/doc/api/errors.md index c589fcd375136d..ecfb20864c37d1 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1762,7 +1762,8 @@ added: - v16.14.0 --> -An import assertion has failed, preventing the specified module to be imported. +An import `type` attribute was provided, but the specified module is of a +different type. @@ -1774,7 +1775,7 @@ added: - v16.14.0 --> -An import assertion is missing, preventing the specified module to be imported. +An import attribute is missing, preventing the specified module to be imported. @@ -1786,7 +1787,17 @@ added: - v16.14.0 --> -An import assertion is not supported by this version of Node.js. +An import attribute is not supported by this version of Node.js. + + + +### `ERR_IMPORT_ATTRIBUTE_UNSUPPORTED` + + + +An import attribute is not supported by this version of Node.js. diff --git a/doc/api/esm.md b/doc/api/esm.md index 269888042fc453..88d58735707123 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -18,7 +18,7 @@ changes: - v17.1.0 - v16.14.0 pr-url: https://github.com/nodejs/node/pull/40250 - description: Add support for import assertions. + description: Add experimental support for import assertions. - version: - v17.0.0 - v16.12.0 @@ -234,17 +234,28 @@ absolute URL strings. import fs from 'node:fs/promises'; ``` -## Import assertions + + +## Import attributes -> Stability: 1 - Experimental +> Stability: 1.1 - Active development + +> This feature was previously named "Import assertions", and using the `assert` +> keyword instead of `with`. Because the version of V8 on this release line does +> not support the `with` keyword, you need to keep using `assert` to support +> this version of Node.js. -The [Import Assertions proposal][] adds an inline syntax for module import +The [Import Attributes proposal][] adds an inline syntax for module import statements to pass on more information alongside the module specifier. ```js @@ -254,10 +265,10 @@ const { default: barData } = await import('./bar.json', { assert: { type: 'json' } }); ``` -Node.js supports the following `type` values, for which the assertion is +Node.js supports the following `type` values, for which the attribute is mandatory: -| Assertion `type` | Needed for | +| Attribute `type` | Needed for | | ---------------- | ---------------- | | `'json'` | [JSON modules][] | @@ -547,7 +558,7 @@ JSON files can be referenced by `import`: import packageConfig from './package.json' assert { type: 'json' }; ``` -The `assert { type: 'json' }` syntax is mandatory; see [Import Assertions][]. +The `assert { type: 'json' }` syntax is mandatory; see [Import Attributes][]. The imported JSON only exposes a `default` export. There is no support for named exports. A cache entry is created in the CommonJS cache to avoid duplication. @@ -1076,8 +1087,8 @@ success! [Determining module system]: packages.md#determining-module-system [Dynamic `import()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import [ES Module Integration Proposal for WebAssembly]: https://github.com/webassembly/esm-integration -[Import Assertions]: #import-assertions -[Import Assertions proposal]: https://github.com/tc39/proposal-import-assertions +[Import Attributes]: #import-attributes +[Import Attributes proposal]: https://github.com/tc39/proposal-import-attributes [JSON modules]: #json-modules [Module customization hooks]: module.md#customization-hooks [Node.js Module Resolution And Loading Algorithm]: #resolution-algorithm-specification diff --git a/doc/api/module.md b/doc/api/module.md index c0cbcf68f86fb4..61776aefbebeef 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -456,6 +456,11 @@ register('./path-to-my-hooks.js', {