esm: js-string Wasm builtins in ESM Integration

PR-URL: nodejs#59020
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>

Author: guybedford

doc/api/esm.md

@@ -663,6 +663,74 @@ node --experimental-wasm-modules index.mjs
 
 would provide the exports interface for the instantiation of `module.wasm`.
 
+### JavaScript String Builtins
+
+<!-- YAML
+added: REPLACEME
+-->
+
+When importing WebAssembly modules, the
+[WebAssembly JS String Builtins Proposal][] is automatically enabled through the
+ESM Integration. This allows WebAssembly modules to directly use efficient
+compile-time string builtins from the `wasm:js-string` namespace.
+
+For example, the following Wasm module exports a string `getLength` function using
+the `wasm:js-string` `length` builtin:
+
+```text
+(module
+  ;; Compile-time import of the string length builtin.
+  (import "wasm:js-string" "length" (func $string_length (param externref) (result i32)))
+
+  ;; Define getLength, taking a JS value parameter assumed to be a string,
+  ;; calling string length on it and returning the result.
+  (func $getLength (param $str externref) (result i32)
+    local.get $str
+    call $string_length
+  )
+
+  ;; Export the getLength function.
+  (export "getLength" (func $get_length))
+)
+```
+
+```js
+import { getLength } from './string-len.wasm';
+getLength('foo'); // Returns 3.
+```
+
+Wasm builtins are compile-time imports that are linked during module compilation
+rather than during instantiation. They do not behave like normal module graph
+imports and they cannot be inspected via `WebAssembly.Module.imports(mod)`
+or virtualized unless recompiling the module using the direct
+`WebAssembly.compile` API with string builtins disabled.
+
+Importing a module in the source phase before it has been instantiated will also
+use the compile-time builtins automatically:
+
+```js
+import source mod from './string-len.wasm';
+const { exports: { getLength } } = await WebAssembly.instantiate(mod, {});
+getLength('foo'); // Also returns 3.
+```
+
+### Reserved Wasm Namespaces
+
+<!-- YAML
+added: REPLACEME
+-->
+
+When importing WebAssembly modules through the ESM Integration, they cannot use
+import module names or import/export names that start with reserved prefixes:
+
+* `wasm-js:` - reserved in all module import names, module names and export
+  names.
+* `wasm:` - reserved in module import names and export names (imported module
+  names are allowed in order to support future builtin polyfills).
+
+Importing a module using the above reserved names will throw a
+`WebAssembly.LinkError`.
+
 <i id="esm_experimental_top_level_await"></i>
 
 ## Top-level `await`
@@ -1101,6 +1169,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
 [Node.js Module Resolution And Loading Algorithm]: #resolution-algorithm-specification
 [Terminology]: #terminology
 [URL]: https://url.spec.whatwg.org/
+[WebAssembly JS String Builtins Proposal]: https://github.com/WebAssembly/js-string-builtins
 [`"exports"`]: packages.md#exports
 [`"type"`]: packages.md#type
 [`--experimental-default-type`]: cli.md#--experimental-default-typetype

lib/internal/modules/esm/translators.js

@@ -2,6 +2,7 @@
 
 const {
   ArrayPrototypePush,
+  BigInt,
   Boolean,
   FunctionPrototypeCall,
   JSONParse,
@@ -12,13 +13,17 @@ const {
   SafeMap,
   SafeSet,
   SafeWeakMap,
+  StringFromCharCode,
+  StringFromCodePoint,
   StringPrototypeIncludes,
   StringPrototypeReplaceAll,
   StringPrototypeSlice,
   StringPrototypeStartsWith,
   globalThis: { WebAssembly },
 } = primordials;
 
+const { Buffer: { from: BufferFrom } } = require('buffer');
+
 const {
   compileFunctionForCJSLoader,
 } = internalBinding('contextify');
@@ -455,6 +460,17 @@ translators.set('wasm', async function(url, source) {
     if (impt.kind === 'global') {
       ArrayPrototypePush(wasmGlobalImports, impt);
     }
+    // Prefix reservations per https://webassembly.github.io/esm-integration/js-api/index.html#parse-a-webassembly-module.
+    if (impt.module.startsWith('wasm-js:')) {
+      throw new WebAssembly.LinkError(`Invalid Wasm import "${impt.module}" in ${url}`);
+    }
+    // wasm:js-string polyfill is being applied
+    if (impt.module === 'wasm:js-string') {
+      continue;
+    }
+    if (impt.name.startsWith('wasm:') || impt.name.startsWith('wasm-js:')) {
+      throw new WebAssembly.LinkError(`Invalid Wasm import name "${impt.module}" in ${url}`);
+    }
     importsList.add(impt.module);
   }
 
@@ -464,6 +480,9 @@ translators.set('wasm', async function(url, source) {
     if (expt.kind === 'global') {
       wasmGlobalExports.add(expt.name);
     }
+    if (expt.name.startsWith('wasm:') || expt.name.startsWith('wasm-js:')) {
+      throw new WebAssembly.LinkError(`Invalid Wasm export name "${expt.name}" in ${url}`);
+    }
     exportsList.add(expt.name);
   }
 
@@ -486,9 +505,14 @@ translators.set('wasm', async function(url, source) {
         reflect.imports[impt] = wrappedModule;
       }
     }
+
     // In cycles importing unexecuted Wasm, wasmInstance will be undefined, which will fail during
     // instantiation, since all bindings will be in the Temporal Deadzone (TDZ).
-    const { exports } = new WebAssembly.Instance(compiled, reflect.imports);
+    const { exports } = new WebAssembly.Instance(compiled, {
+      ...reflect.imports,
+      // Provide a polyfill for js string builtins
+      'wasm:js-string': wasmJSStringBuiltinsPolyfill,
+    });
     wasmInstances.set(module.getNamespace(), exports);
     for (const expt of exportsList) {
       let val = exports[expt];
@@ -524,3 +548,147 @@ translators.set('module-typescript', function(url, source) {
   debug(`Translating TypeScript ${url}`);
   return FunctionPrototypeCall(translators.get('module'), this, url, code, false);
 });
+
+// Helper binary:
+// (module
+//   (type $array_i16 (array (mut i16)))
+//   (func $createArrayMutI16 (param $size i32) (result anyref)
+//     (local.get $size)
+//     (array.new_default $array_i16)
+//   )
+//   (func $arrayLength (param $arr arrayref) (result i32)
+//     (local.get $arr)
+//     (array.len)
+//   )
+//   (func $arraySet (param $arr (ref null $array_i16)) (param $index i32) (param $value i32)
+//     (local.get $arr)
+//     (local.get $index)
+//     (local.get $value)
+//     (array.set $array_i16)
+//   )
+//   (func $arrayGet (param $arr (ref null $array_i16)) (param $index i32) (result i32)
+//     (local.get $arr)
+//     (local.get $index)
+//     (array.get_u $array_i16)
+//   )
+//   (export "createArrayMutI16" (func $createArrayMutI16))
+//   (export "arrayLength" (func $arrayLength))
+//   (export "arraySet" (func $arraySet))
+//   (export "arrayGet" (func $arrayGet))
+// )
+let helperExports;
+function loadHelperBinary() {
+  if (!helperExports) {
+    const module = new WebAssembly.Module(BufferFrom('AGFzbQEAAAABHAVedwFgAX8BbmABagF/YANjAH9/AGACYwB/AX8DBQQBAgMEBz' +
+      'kEEWNyZWF0ZUFycmF5TXV0STE2AAALYXJyYXlMZW5ndGgAAQhhcnJheVNldAACCGFycmF5R2V0AAMKJgQHACAA+wcACwYAIAD7DwsLACAAIAE' +
+      'gAvsOAAsJACAAIAH7DQALAH8EbmFtZQE1BAARY3JlYXRlQXJyYXlNdXRJMTYBC2FycmF5TGVuZ3RoAghhcnJheVNldAMIYXJyYXlHZXQCMwQA' +
+      'AQAEc2l6ZQEBAANhcnICAwADYXJyAQVpbmRleAIFdmFsdWUDAgADYXJyAQVpbmRleAQMAQAJYXJyYXlfaTE2', 'base64'));
+    ({ exports: helperExports } = new WebAssembly.Instance(module));
+  }
+}
+
+function throwIfNotString(a) {
+  if (typeof a !== 'string') {
+    throw new WebAssembly.RuntimeError();
+  }
+}
+
+const wasmJSStringBuiltinsPolyfill = {
+  test: (string) => {
+    if (string === null || typeof string !== 'string') {
+      return 0;
+    }
+    return 1;
+  },
+  cast: (string) => {
+    throwIfNotString(string);
+    return string;
+  },
+  fromCharCodeArray: (array, arrayStart, arrayCount) => {
+    loadHelperBinary();
+    arrayStart >>>= 0;
+    arrayCount >>>= 0;
+    const length = helperExports.arrayLength(array);
+    if (BigInt(arrayStart) + BigInt(arrayCount) > BigInt(length)) {
+      throw new WebAssembly.RuntimeError();
+    }
+    let result = '';
+    for (let i = arrayStart; i < arrayStart + arrayCount; i++) {
+      result += StringFromCharCode(helperExports.arrayGet(array, i));
+    }
+    return result;
+  },
+  intoCharCodeArray: (string, arr, arrayStart) => {
+    loadHelperBinary();
+    arrayStart >>>= 0;
+    throwIfNotString(string);
+    const arrLength = helperExports.arrayLength(arr);
+    const stringLength = string.length;
+    if (BigInt(arrayStart) + BigInt(stringLength) > BigInt(arrLength)) {
+      throw new WebAssembly.RuntimeError();
+    }
+    for (let i = 0; i < stringLength; i++) {
+      helperExports.arraySet(arr, arrayStart + i, string[i].charCodeAt(0));
+    }
+    return stringLength;
+  },
+  fromCharCode: (charCode) => {
+    charCode >>>= 0;
+    return StringFromCharCode(charCode);
+  },
+  fromCodePoint: (codePoint) => {
+    codePoint >>>= 0;
+    return StringFromCodePoint(codePoint);
+  },
+  charCodeAt: (string, stringIndex) => {
+    stringIndex >>>= 0;
+    throwIfNotString(string);
+    if (stringIndex >= string.length) {
+      throw new WebAssembly.RuntimeError();
+    }
+    return string.charCodeAt(stringIndex);
+  },
+  codePointAt: (string, stringIndex) => {
+    stringIndex >>>= 0;
+    throwIfNotString(string);
+    if (stringIndex >= string.length) {
+      throw new WebAssembly.RuntimeError();
+    }
+    return string.codePointAt(stringIndex);
+  },
+  length: (string) => {
+    throwIfNotString(string);
+    return string.length;
+  },
+  concat: (stringA, stringB) => {
+    throwIfNotString(stringA);
+    throwIfNotString(stringB);
+    return stringA + stringB;
+  },
+  substring: (string, startIndex, endIndex) => {
+    startIndex >>>= 0;
+    endIndex >>>= 0;
+    throwIfNotString(string);
+    if (startIndex > string.length || endIndex > string.length || endIndex < startIndex) {
+      return '';
+    }
+    return string.substring(startIndex, endIndex);
+  },
+  equals: (stringA, stringB) => {
+    if (stringA !== null) {
+      throwIfNotString(stringA);
+    }
+    if (stringB !== null) {
+      throwIfNotString(stringB);
+    }
+    return stringA === stringB;
+  },
+  compare: (stringA, stringB) => {
+    throwIfNotString(stringA);
+    throwIfNotString(stringB);
+    if (stringA < stringB) {
+      return -1;
+    }
+    return stringA === stringB ? 0 : 1;
+  },
+};

test/es-module/test-esm-wasm.mjs

@@ -410,4 +410,95 @@ describe('ESM: WASM modules', { concurrency: !process.env.TEST_PARALLEL }, () =>
     strictEqual(stdout, '');
     notStrictEqual(code, 0);
   });
+
+  it('should reject wasm: import names', async () => {
+    const { code, stderr, stdout } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--experimental-wasm-modules',
+      '--input-type=module',
+      '--eval',
+      `import(${JSON.stringify(fixtures.fileURL('es-modules/invalid-import-name.wasm'))})`,
+    ]);
+
+    match(stderr, /Invalid Wasm import name/);
+    strictEqual(stdout, '');
+    notStrictEqual(code, 0);
+  });
+
+  it('should reject wasm-js: import names', async () => {
+    const { code, stderr, stdout } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--experimental-wasm-modules',
+      '--input-type=module',
+      '--eval',
+      `import(${JSON.stringify(fixtures.fileURL('es-modules/invalid-import-name-wasm-js.wasm'))})`,
+    ]);
+
+    match(stderr, /Invalid Wasm import name/);
+    strictEqual(stdout, '');
+    notStrictEqual(code, 0);
+  });
+
+  it('should reject wasm-js: import module names', async () => {
+    const { code, stderr, stdout } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--experimental-wasm-modules',
+      '--input-type=module',
+      '--eval',
+      `import(${JSON.stringify(fixtures.fileURL('es-modules/invalid-import-module.wasm'))})`,
+    ]);
+
+    match(stderr, /Invalid Wasm import/);
+    strictEqual(stdout, '');
+    notStrictEqual(code, 0);
+  });
+
+  it('should reject wasm: export names', async () => {
+    const { code, stderr, stdout } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--experimental-wasm-modules',
+      '--input-type=module',
+      '--eval',
+      `import(${JSON.stringify(fixtures.fileURL('es-modules/invalid-export-name.wasm'))})`,
+    ]);
+
+    match(stderr, /Invalid Wasm export/);
+    strictEqual(stdout, '');
+    notStrictEqual(code, 0);
+  });
+
+  it('should reject wasm-js: export names', async () => {
+    const { code, stderr, stdout } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--experimental-wasm-modules',
+      '--input-type=module',
+      '--eval',
+      `import(${JSON.stringify(fixtures.fileURL('es-modules/invalid-export-name-wasm-js.wasm'))})`,
+    ]);
+
+    match(stderr, /Invalid Wasm export/);
+    strictEqual(stdout, '');
+    notStrictEqual(code, 0);
+  });
+
+  it('should support js-string builtins', async () => {
+    const { code, stderr, stdout } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--experimental-wasm-modules',
+      '--input-type=module',
+      '--eval',
+      [
+        'import { strictEqual } from "node:assert";',
+        `import * as wasmExports from ${JSON.stringify(fixtures.fileURL('es-modules/js-string-builtins.wasm'))};`,
+        'strictEqual(wasmExports.getLength("hello"), 5);',
+        'strictEqual(wasmExports.concatStrings("hello", " world"), "hello world");',
+        'strictEqual(wasmExports.compareStrings("test", "test"), 1);',
+        'strictEqual(wasmExports.compareStrings("test", "different"), 0);',
+      ].join('\n'),
+    ]);
+
+    strictEqual(stderr, '');
+    strictEqual(stdout, '');
+    strictEqual(code, 0);
+  });
 });