loader: add experimental text import

doc/api/cli.md

@@ -1171,6 +1171,18 @@ passing a second `parentURL` argument for contextual resolution.
 
 Previously gated the entire `import.meta.resolve` feature.
 
+### `--experimental-import-text`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+Enable experimental support for importing modules with
+`with { type: 'text' }`.
+
 ### `--experimental-inspector-network-resource`
 
 <!-- YAML
@@ -3604,6 +3616,7 @@ one is included in the list below.
 * `--experimental-detect-module`
 * `--experimental-eventsource`
 * `--experimental-import-meta-resolve`
+* `--experimental-import-text`
 * `--experimental-json-modules`
 * `--experimental-loader`
 * `--experimental-modules`

doc/api/esm.md

@@ -294,8 +294,10 @@ Node.js only supports the `type` attribute, for which it supports the following
 | Attribute `type` | Needed for       |
 | ---------------- | ---------------- |
 | `'json'`         | [JSON modules][] |
+| `'text'`         | [Text modules][] |
 
 The `type: 'json'` attribute is mandatory when importing JSON modules.
+The `type: 'text'` attribute is mandatory when importing text modules.
 
 ## Built-in modules
 
@@ -709,6 +711,25 @@ exports. A cache entry is created in the CommonJS cache to avoid duplication.
 The same object is returned in CommonJS if the JSON module has already been
 imported from the same path.
 
+<i id="esm_experimental_text_modules"></i>
+
+## Text modules
+
+> Stability: 1.0 - Early development
+
+Text modules are available behind the `--experimental-import-text` flag.
+
+Text files can be referenced by `import`:
+
+```js
+import message from './message.txt' with { type: 'text' };
+```
+
+The `with { type: 'text' }` syntax is mandatory; see [Import Attributes][].
+
+The imported text only exposes a `default` export whose value is the module
+source as a string.
+
 <i id="esm_experimental_wasm_modules"></i>
 
 ## Wasm modules
@@ -1308,6 +1329,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
 [Node.js Module Resolution And Loading Algorithm]: #resolution-algorithm-specification
 [Source Phase Imports]: https://github.com/tc39/proposal-source-phase-imports
 [Terminology]: #terminology
+[Text modules]: #text-modules
 [URL]: https://url.spec.whatwg.org/
 [WebAssembly JS String Builtins Proposal]: https://github.com/WebAssembly/js-string-builtins
 [`"exports"`]: packages.md#exports

doc/node.1

@@ -701,6 +701,10 @@ Enable experimental \fBimport.meta.resolve()\fR parent URL support, which allows
 passing a second \fBparentURL\fR argument for contextual resolution.
 Previously gated the entire \fBimport.meta.resolve\fR feature.
 .
+.It Fl -experimental-import-text
+Enable experimental support for importing modules with
+\fBwith { type: 'text' }\fR.
+.
 .It Fl -experimental-inspector-network-resource
 Enable experimental support for inspector network resources.
 .
@@ -1859,6 +1863,8 @@ one is included in the list below.
 .It
 \fB--experimental-import-meta-resolve\fR
 .It
+\fB--experimental-import-text\fR
+.It
 \fB--experimental-json-modules\fR
 .It
 \fB--experimental-loader\fR

lib/internal/modules/esm/assert.js

@@ -8,6 +8,7 @@ const {
   ObjectValues,
 } = primordials;
 const { validateString } = require('internal/validators');
+const { getOptionValue } = require('internal/options');
 
 const {
   ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE,
@@ -29,8 +30,13 @@ const formatTypeMap = {
   'commonjs': kImplicitTypeAttribute,
   'json': 'json',
   'module': kImplicitTypeAttribute,
+  'text': 'text',
   'wasm': kImplicitTypeAttribute, // It's unclear whether the HTML spec will require an type attribute or not for Wasm; see https://github.com/WebAssembly/esm-integration/issues/42
 };
+// NOTE: Don't add bytes support yet as it requires Uint8Arrays backed by immutable ArrayBuffers,
+// which V8 does not support yet.
+// see: https://github.com/nodejs/node/pull/62300#issuecomment-4079163816
+
 
 /**
  * The HTML spec disallows the default type to be explicitly specified
@@ -42,7 +48,6 @@ const supportedTypeAttributes = ArrayPrototypeFilter(
   ObjectValues(formatTypeMap),
   (type) => type !== kImplicitTypeAttribute);
 
-
 /**
  * Test a module's import attributes.
  * @param {string} url The URL of the imported module, for error reporting.
@@ -62,6 +67,12 @@ function validateAttributes(url, format,
   }
   const validType = formatTypeMap[format];
 
+  if (validType !== undefined &&
+    importAttributes.type === 'text' &&
+    !getOptionValue('--experimental-import-text')) {
+    throw new ERR_IMPORT_ATTRIBUTE_UNSUPPORTED('type', importAttributes.type, url);
+  }
+
   switch (validType) {
     case undefined:
       // Ignore attributes for module formats we don't recognize, to allow new

lib/internal/modules/esm/get_format.js

@@ -47,6 +47,13 @@ function mimeToFormat(mime) {
   ) { return 'module'; }
   if (mime === 'application/json') { return 'json'; }
   if (mime === 'application/wasm') { return 'wasm'; }
+  if (
+    getOptionValue('--experimental-import-text') &&
+    RegExpPrototypeExec(
+      /^\s*text\/plain\s*(;\s*charset=utf-?8\s*)?$/i,
+      mime,
+    ) !== null
+  ) { return 'text'; }
   return null;
 }
 
@@ -236,12 +243,22 @@ function getFileProtocolModuleFormat(url, context = { __proto__: null }, ignoreE
   throw new ERR_UNKNOWN_FILE_EXTENSION(ext, filepath);
 }
 
+// If the caller explicitly requests text format via import attributes, honor it regardless of file extension.
+function isExperimentalTextImport(importAttributes) {
+  return getOptionValue('--experimental-import-text') &&
+    importAttributes?.type === 'text';
+}
+
 /**
  * @param {URL} url
- * @param {{parentURL: string}} context
+ * @param {{parentURL: string, importAttributes?: Record<string, string>}} context
  * @returns {Promise<string> | string | undefined} only works when enabled
  */
 function defaultGetFormatWithoutErrors(url, context) {
+  if (isExperimentalTextImport(context?.importAttributes)) {
+    return 'text';
+  }
+
   const protocol = url.protocol;
   if (!ObjectPrototypeHasOwnProperty(protocolHandlers, protocol)) {
     return null;
@@ -251,10 +268,14 @@ function defaultGetFormatWithoutErrors(url, context) {
 
 /**
  * @param {URL} url
- * @param {{parentURL: string}} context
+ * @param {{parentURL: string, importAttributes?: Record<string, string>}} context
  * @returns {Promise<string> | string | undefined} only works when enabled
  */
 function defaultGetFormat(url, context) {
+  if (isExperimentalTextImport(context?.importAttributes)) {
+    return 'text';
+  }
+
   const protocol = url.protocol;
   if (!ObjectPrototypeHasOwnProperty(protocolHandlers, protocol)) {
     return null;

lib/internal/modules/esm/loader.js

@@ -129,7 +129,7 @@ function getRaceMessage(filename, parentFilename, isForAsyncLoaderHookWorker) {
  */
 
 /**
- * @typedef {'builtin'|'commonjs'|'json'|'module'|'wasm'} ModuleFormat
+ * @typedef {'builtin'|'commonjs'|'json'|'module'|'text'|'wasm'} ModuleFormat
  */
 
 /**

lib/internal/modules/esm/translators.js

@@ -642,3 +642,14 @@ translators.set('module-typescript', function(url, translateContext, parentURL)
   translateContext.source = stripTypeScriptModuleTypes(stringify(source), url);
   return FunctionPrototypeCall(translators.get('module'), this, url, translateContext, parentURL);
 });
+
+// Strategy for loading source as text.
+translators.set('text', function textStrategy(url, translateContext) {
+  emitExperimentalWarning('Text import');
+  let { source } = translateContext;
+  assertBufferSource(source, true, 'load');
+  source = stringify(source);
+  return new ModuleWrap(url, undefined, ['default'], function() {
+    this.setExport('default', source);
+  });
+});

src/node_options.cc

@@ -632,6 +632,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddAlias("--loader", "--experimental-loader");
   AddOption("--experimental-modules", "", NoOp{}, kAllowedInEnvvar);
   AddOption("--experimental-wasm-modules", "", NoOp{}, kAllowedInEnvvar);
+  AddOption("--experimental-import-text",
+            "experimental support for importing source as text with import "
+            "attributes",
+            &EnvironmentOptions::experimental_import_text,
+            kAllowedInEnvvar);
   AddOption("--experimental-import-meta-resolve",
             "experimental ES Module import.meta.resolve() parentURL support",
             &EnvironmentOptions::experimental_import_meta_resolve,

src/node_options.h

@@ -134,6 +134,7 @@ class EnvironmentOptions : public Options {
   std::string localstorage_file;
   bool experimental_global_navigator = true;
   bool experimental_global_web_crypto = true;
+  bool experimental_import_text = false;
   bool experimental_import_meta_resolve = false;
   std::string input_type;  // Value of --input-type
   bool entry_is_url = false;

test/es-module/test-esm-import-attributes-errors.js

@@ -26,6 +26,11 @@ async function test() {
     { code: 'ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE' }
   );
 
+  await assert.rejects(
+    import(jsModuleDataUrl, { with: { type: 'text' } }),
+    { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }
+  );
+
   await assert.rejects(
     import(jsModuleDataUrl, { with: { type: 'json', other: 'unsupported' } }),
     { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }

test/es-module/test-esm-import-attributes-errors.mjs

@@ -21,6 +21,11 @@ await assert.rejects(
   { code: 'ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE' }
 );
 
+await assert.rejects(
+  import(jsModuleDataUrl, { with: { type: 'text' } }),
+  { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }
+);
+
 await assert.rejects(
   import(jsModuleDataUrl, { with: { type: 'json', other: 'unsupported' } }),
   { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }

test/es-module/test-esm-import-attributes-validation-text.js

@@ -0,0 +1,19 @@
+// Flags: --expose-internals --experimental-import-text
+'use strict';
+require('../common');
+
+const assert = require('assert');
+
+const { validateAttributes } = require('internal/modules/esm/assert');
+
+const url = 'test://';
+
+assert.ok(validateAttributes(url, 'text', { type: 'text' }));
+
+assert.throws(() => validateAttributes(url, 'text', {}), {
+  code: 'ERR_IMPORT_ATTRIBUTE_MISSING',
+});
+
+assert.throws(() => validateAttributes(url, 'module', { type: 'text' }), {
+  code: 'ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE',
+});

test/es-module/test-esm-import-text-disabled.mjs

@@ -0,0 +1,12 @@
+import '../common/index.mjs';
+import assert from 'assert';
+
+await assert.rejects(
+  import('../fixtures/file-to-read-without-bom.txt', { with: { type: 'text' } }),
+  { code: 'ERR_UNKNOWN_FILE_EXTENSION' },
+);
+
+await assert.rejects(
+  import('data:text/plain,hello%20world', { with: { type: 'text' } }),
+  { code: 'ERR_UNKNOWN_MODULE_FORMAT' },
+);

test/es-module/test-esm-import-text.mjs

@@ -0,0 +1,51 @@
+// Flags: --experimental-import-text
+import '../common/index.mjs';
+import assert from 'assert';
+
+import staticText from '../fixtures/file-to-read-without-bom.txt' with { type: 'text' };
+import staticTextWithBOM from '../fixtures/file-to-read-with-bom.txt' with { type: 'text' };
+
+const expectedText = 'abc\ndef\nghi\n';
+
+assert.strictEqual(staticText, expectedText);
+assert.strictEqual(staticTextWithBOM, expectedText);
+
+const dynamicText = await import('../fixtures/file-to-read-without-bom.txt', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dynamicText.default, expectedText);
+
+const dataText = await import('data:text/plain,hello%20world', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dataText.default, 'hello world');
+
+const dataJsAsText = await import('data:text/javascript,export{}', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dataJsAsText.default, 'export{}');
+
+const dataInvalidUtf8 = await import('data:text/plain,%66%6f%80%6f', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dataInvalidUtf8.default, 'fo\ufffdo');
+
+const jsAsText = await import('../fixtures/syntax/bad_syntax.js', {
+  with: { type: 'text' },
+});
+assert.match(jsAsText.default, /^var foo bar;/);
+
+const jsonAsText = await import('../fixtures/invalid.json', {
+  with: { type: 'text' },
+});
+assert.match(jsonAsText.default, /"im broken"/);
+
+await assert.rejects(
+  import('data:text/plain,hello%20world'),
+  { code: 'ERR_IMPORT_ATTRIBUTE_MISSING' },
+);
+
+await assert.rejects(
+  import('../fixtures/file-to-read-without-bom.txt'),
+  { code: 'ERR_UNKNOWN_FILE_EXTENSION' },
+);