From b27526daec0e1b368dc309fc0886c296a886ce73 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 --- doc/api/errors.md | 17 ++++- doc/api/esm.md | 36 ++++++--- lib/internal/errors.js | 9 ++- lib/internal/modules/cjs/loader.js | 8 +- lib/internal/modules/esm/assert.js | 56 +++++++------- lib/internal/modules/esm/load.js | 16 +++- lib/internal/modules/esm/loader.js | 73 +++++++++++++------ lib/internal/modules/esm/module_job.js | 10 +-- lib/internal/modules/esm/translators.js | 4 +- 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 | 41 +++++++++-- ...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 - .../assertionless-json-import.mjs | 8 +- .../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 +- 35 files changed, 279 insertions(+), 214 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 diff --git a/doc/api/errors.md b/doc/api/errors.md index 9c88b7d7d4de0f..4e776380beb766 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 8f147b9c2445b2..d9f9ccf8d1ab85 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -15,7 +15,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 @@ -230,7 +230,9 @@ 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 @@ -250,10 +257,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][] | @@ -529,7 +536,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. @@ -732,6 +739,11 @@ prevent unintentional breaks in the chain.