Merge js-string-builtins into wasm-3.0 #1943

eqrion · 2025-06-25T22:17:25Z

There are no substantive open issues on the js-string-builtins repo right now, this has shipped in two browsers now (Chrome and Firefox), and so I'd like to start the process of merging this into the spec. I originally based this off the wasm-3.0 branch, so that's what I'm basing this PR onto.

From my read of the process document, js-string-builtins needs to be phase 5 before merging into the spec repo. So I've filed an agenda item for advancing js-string-builtins to phase 5 here. I think we could start review of this before then to catch any potential issues that may need to be discussed with the WG. If not, I'll just leave this here until after the next WG meeting.

cc' @rossberg @Ms2ger as editors.

* Adopts builtin modules approach * Adds section of polyfilling * Adds section on feature detection * Adds cast/test builtins * Adds future extension ideas for - binding memory - utf8/wtf8 - evolving the type signatures

Update proposal

- Eliminate usage of 'builtin module' in description. This is not essential to the proposal and causes confusion around a similarly named JS proposal, which had different goals. - Clarify some minor points. - Make JS-API changes to WebIDL comprehensive. - Reword feature detection section to actually propose change to WebAssembly.validate method

- Function builtin behaviors is defined using 'create a host function' - Clarify behavior around monkey patching using standard language - Clarify edge cases around nullability - Clarify edge cases around unsigned/signed integers - Restrict 'substring' behavior to normal cases - Use wasm helpers for when wasm instructions are needed

The existing WTF-8 operation in this proposal violated one of the goals of the proposal: "don't create substantial new functionality" by introducing WTF-8 transcoding support to the web platform without prior precedent. The WTF-8 operation is removed because of this. The naming for WTF-16 operations is reworked to refer to 'charCodes' instead as that is what the JS String interface uses. We could support UTF-8 transcoding by referring to the TextEncoder/TextDecoder interfaces, so this commit adds support for that.

Fixes WebAssembly#19.

Fixes WebAssembly#19

Fixes WebAssembly#17.

Explain that users should validate modules that deliberately produce link errors to test for support for particular builtins.

This commit adds a basic suite of tests for the js-string-builtins. This is done by defining a polyfill module matching the overview, and then comparing the host provided builtins against the polyfill on representative inputs.

Fixes WebAssembly#24.

- Syntax highlighting - Added links - Code font - Consistency - Grammer fixes

Needs more detail to properly integrate with GC array ops.

This avoids having to refer to actual Wasm instructions, since after all this is a host function.

Equals specifically allows null inputs. Update the JS API tests and the polyfill to match.

rossberg · 2025-06-26T06:54:02Z

I'll let @Ms2ger review thia, since it only touches the JS specs.

Ms2ger · 2025-06-26T09:48:47Z

Thanks - no obvious issues jump out at me while skimming; I'll try to take a slightly more thorough look by next week.

Should the tests still be marked as tentative?

eqrion · 2025-06-26T14:44:23Z

Good catch, updated.

eqrion · 2025-07-23T21:15:42Z

The WG voted to advance js-string-builtins to phase 5 today, so I don't think we are blocked on that anymore.

tlively · 2025-08-14T18:41:23Z

I opened eqrion#1 to clarify that the function types for each of the builtins must also be in their own rec groups, etc. V8 is currently shipping a bug where we accept any function type that has the correct signature, but we'll try to fix it. It would be good to add tests for this as well.

Ms2ger

Some formatting comments. Thanks!

Ms2ger · 2025-08-21T10:12:56Z

document/js-api/index.bs

+            1. Let |importExternType| be |import|[2]
+            1. Let |stringExternType| be `global const (ref extern)`
+            1. If [=match_externtype=](|stringExternType|, |importExternType|) is false, return false


Ms2ger · 2025-08-21T10:17:39Z

document/js-api/index.bs

@@ -384,53 +398,104 @@ Note:
 </div>

 <div algorithm>
-  The <dfn method for="WebAssembly">validate(|bytes|)</dfn> method, when invoked, performs the following steps:
+  To <dfn>validate builtins and imported string for a WebAssembly module</dfn> from module |module|, enabled builtins |builtinSetNames|, and |importedStringModule|, perform the following steps:


For new algorithms, please follow the formatting of "retrieving a host value", that is, empty line after <div> and before </div>, an empty line between the header and the list, and start on column 0. (I haven't made the spec consistent yet because of diff churn, but I probably should after this batch of proposals.)

Ms2ger · 2025-08-21T10:17:55Z

document/js-api/index.bs

+    1. Let |builtinSetNames| be |options|["builtins"]
+    1. Let |importedStringModule| be |options|["importedStringConstants"]


Ms2ger · 2025-08-21T10:18:11Z

document/js-api/index.bs

+            1. Let |builtinSetNames| be |options|["builtins"]
+            1. Let |importedStringModule| be |options|["importedStringConstants"]


Ms2ger · 2025-08-21T10:19:30Z

document/js-api/index.bs

+<div algorithm>
+To <dfn>instantiate imported strings</dfn> with module |module| and |importedStringModule|, perform the following steps:
+1. Assert: |importedStringModule| is not null.


Ms2ger · 2025-08-21T10:22:11Z

document/js-api/index.bs

+<div algorithm>
+To <dfn>get the builtins for a builtin set</dfn> with |builtinSetName|, perform the following steps:


Suggested change

<div algorithm>

To <dfn>get the builtins for a builtin set</dfn> with |builtinSetName|, perform the following steps:

<div algorithm>

To <dfn>get the builtins for a builtin set</dfn> with |builtinSetName|, perform the following steps:

and below

Ms2ger · 2025-08-21T10:22:49Z

document/js-api/index.bs

+To <dfn>find a builtin</dfn> with |import| and enabled builtins |builtinSetNames|, perform the following steps:
+
+1. Assert: [=validate builtin set names=] |builtinSetNames| is true.
+1. Let |importModuleName| be |import|[0]


Ms2ger · 2025-08-21T10:23:50Z

document/js-api/index.bs

+<div algorithm>
+  To <dfn>create a builtin function</dfn> from type |funcType| and execution steps |steps|, perform the following steps:
+
+    1. Let |stored settings| be the <a spec=HTML>incumbent settings object</a>.


stored settings is unused

Ms2ger · 2025-08-21T10:26:00Z

document/js-api/index.bs

+
+The JS-API defines sets of builtin functions which can be imported through {{WebAssemblyCompileOptions|options}} when compiling a module. WebAssembly builtin functions mirror existing JavaScript builtins, but adapt them to be useable directly as WebAssembly functions with minimal overhead.
+
+All builtin functions are grouped into sets. Every builtin set has a |name| that is used in {{WebAssemblyCompileOptions}}, and a |qualified name| with a `wasm:` prefix that [=read the imports|is used during import lookup=].


name and qualified name should be definitions (with for=builtin-set or similar) and be cross-referenced as such below

Ms2ger · 2025-08-21T10:27:11Z

document/js-api/index.bs

+
+<div algorithm>
+
+The <dfn abstract-op lt="CharCodeAt ">CharCodeAt(|string|, |index|)</dfn> abstract operation, when invoked, performs the following steps:


dtig and others added 30 commits August 9, 2023 15:39

Initial commit

a0c525b

Merge remote-tracking branch 'upstream/main'

bfc3c0b

Initial setup and overview

5b29562

Update proposal

1dea0a3

* Adopts builtin modules approach * Adds section of polyfilling * Adds section on feature detection * Adds cast/test builtins * Adds future extension ideas for - binding memory - utf8/wtf8 - evolving the type signatures

Address review feedback

09444a5

Merge pull request WebAssembly#8 from WebAssembly/refactor

b73eb94

Update proposal

Rename concatenate to concat

969ecee

Review comments

42143e4

Update substring range checking

206a3a0

Fix mutability of array i8

f8138fe

Fixes WebAssembly#19.

Add streaming-related functions

fee87c1

Fixes WebAssembly#19

Clarify behavior of flags and function names

9363099

Fixes WebAssembly#17.

Fix link to type-imports prposal in js-string-builtins/Overview.md

492bbd4

Clarify feature detection scheme

2b24b0d

Explain that users should validate modules that deliberately produce link errors to test for support for particular builtins.

Add test for js-string-builtins

cf796dc

This commit adds a basic suite of tests for the js-string-builtins. This is done by defining a polyfill module matching the overview, and then comparing the host provided builtins against the polyfill on representative inputs.

Fix type signature of 'concat'

8951375

Fixes WebAssembly#24.

Add section on string constants, including Struct.from

2b634f5

Rework to use imported string constants idea

6a7a39b

Fixup typos

f13f076

Add missing start parameter to measureStringAsUTF8 overview

8c65950

Update Overview.md

809dd46

Many small improvements

bb95b01

- Syntax highlighting - Added links - Code font - Consistency - Grammer fixes

Update proposals/js-string-builtins/Overview.md

47b4744

Fix nullability for string constants

33291d7

Expand section on string constants

f7a14c3

Revert unintentional change to builtins field

7530d20

Add note about empty imports object

98953e8

ajklein and others added 21 commits August 21, 2024 08:56

Add basic support for fromCharCodeArray

a402a3a

Needs more detail to properly integrate with GC array ops.

Make fromCharCodeArray slightly less formal

e6462a6

This avoids having to refer to actual Wasm instructions, since after all this is a host function.

Add intoCharCodeArray

86d7160

Add equals and compare

a3c7562

Review fixes for builtin steps

d7765e6

Tweak wording for trapping in builtins

9570169

Fix spec to separate builtin name used for imports and compile options

91115df

Add note about patching the String builtins

1937e00

Add more tests

e1bbe79

Don't validate that every builtin set option is valid

7851a78

Fix null-handling for equals in test and polyfill

ab1be32

Equals specifically allows null inputs. Update the JS API tests and the polyfill to match.

Editorial: replace Type AO with new ECMA-262 type test convention

4553771

actually remove Type

dd601fb

support per-component polyfill fallbacks

6cbeb82

spec rework

df1f6df

typo

9cdd245

Editorial: Align with Web IDL specification

7d0b519

[js-api] Fix incorrect return statement in 'validate builtin set names'

753b7a1

[js-api] Remove copy-pasted if statements

70a3869

Merge remote-tracking branch 'spec/wasm-3.0'

81bfc5f

Revert changes to conf and README to prepare for merging

b0816d4

rossberg requested a review from Ms2ger June 26, 2025 06:54

[tests] Remove tentative from js-string tests

48e869a

Expand JS builtin functypes

aeded79

Ms2ger approved these changes Aug 21, 2025

View reviewed changes

		1. Let \|builtinSetNames\| be \|options\|["builtins"]
		1. Let \|importedStringModule\| be \|options\|["importedStringConstants"]

		<div algorithm>
		To <dfn>get the builtins for a builtin set</dfn> with \|builtinSetName\|, perform the following steps:

	1. Let \|importModuleName\| be \|import\|[0]
	1. Let \|importModuleName\| be \|import\|[0].


		The JS-API defines sets of builtin functions which can be imported through {{WebAssemblyCompileOptions\|options}} when compiling a module. WebAssembly builtin functions mirror existing JavaScript builtins, but adapt them to be useable directly as WebAssembly functions with minimal overhead.

		All builtin functions are grouped into sets. Every builtin set has a \|name\| that is used in {{WebAssemblyCompileOptions}}, and a \|qualified name\| with a `wasm:` prefix that [=read the imports\|is used during import lookup=].


		<div algorithm>

		The <dfn abstract-op lt="CharCodeAt ">CharCodeAt(\|string\|, \|index\|)</dfn> abstract operation, when invoked, performs the following steps:

	The <dfn abstract-op lt="CharCodeAt ">CharCodeAt(\|string\|, \|index\|)</dfn> abstract operation, when invoked, performs the following steps:
	The <dfn abstract-op lt="CharCodeAt">CharCodeAt(\|string\|, \|index\|)</dfn> abstract operation, when invoked, performs the following steps:

Merge js-string-builtins into wasm-3.0 #1943

Are you sure you want to change the base?

Merge js-string-builtins into wasm-3.0 #1943

Uh oh!

Conversation

eqrion commented Jun 25, 2025

Uh oh!

rossberg commented Jun 26, 2025

Uh oh!

Ms2ger commented Jun 26, 2025

Uh oh!

eqrion commented Jun 26, 2025

Uh oh!

eqrion commented Jul 23, 2025

Uh oh!

tlively commented Aug 14, 2025

Uh oh!

Ms2ger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!