Skip to content

update param of BinaryenRefNull to take BinaryenHeapType - #8981

Open
chharvey wants to merge 3 commits into
WebAssembly:mainfrom
chharvey:feat/ref-null-heaptype
Open

update param of BinaryenRefNull to take BinaryenHeapType#8981
chharvey wants to merge 3 commits into
WebAssembly:mainfrom
chharvey:feat/ref-null-heaptype

Conversation

@chharvey

@chharvey chharvey commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

According to the WASM spec, the (ref.null <ht>) instruction takes a heap type as an argument, not a reference type. This PR updates BinaryenRefNull to align with that.

The parameter is changed from a BinaryenType to a BinaryenHeapType and removes the nullable assertion. This puts the onus on the caller to make sure they are passing in a correct type.

This is a breaking change and would require callers to be more careful about their arguments, but it provides for a more spec-aligned and predictable API.

Problem Statement

As an example of a problem it solves: say you’re using GC and you define your own custom heap type (example in JS):

(type $NumberUnion (struct
	(field $tag   i8)
	(field $int   i64)
	(field $float f64)
))
const tb = new binaryen.TypeBuilder();
tb.setStructType(0, [
	{type: binaryen.i32, packedType: "i8"},
	{type: binaryen.i64, packedType: "notPacked"},
	{type: binaryen.f64, packedType: "notPacked"},
]);
const heaptypes = tb.buildAndDispose();
const ht_NumberUnion = heaptypes[0];

and then you want to create a null-ref expression (ref.null $NumberUnion) in your module code:

const mod = new binaryen.Module();
mod.ref.null(ht_NumberUnion); // error: `BinaryenRefNull` currently only accepts ref types

To fix, you have to create your own nullable ref type first:

mod.ref.null(binaryen.getTypeFromHeapType(ht_NumberUnion, true));

With this PR’s proposed change, you can now just call BinaryenRefNull passing in your heap type.

@chharvey
chharvey requested a review from a team as a code owner August 8, 2026 08:18
@chharvey
chharvey requested review from tlively and removed request for a team August 8, 2026 08:18
@chharvey
chharvey marked this pull request as draft August 8, 2026 08:34
@chharvey
chharvey marked this pull request as ready for review August 8, 2026 14:00
function initializeConstants() {

// Types
[ ['none', 'None'],

@chharvey chharvey Aug 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This 'none' (BinaryenTypeNone()) refers to the type with stack effect [t*] -> []. It is not the WASM heap type none (BinaryenHeapTypeNone()), nor the WASM ref type (ref null none) (BinaryenTypeNullref()).

We should probably document this somewhere or change it to a less conflicting name like 'void'.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant