Question about marshalling of certain types

[luaneko]

Hello! I am thinking of using ClearScript in one of my projects, and I have a few questions about how certain types are marshalled to and from Javascript. I couldn't find the answers in the tutorial or FAQ, so I apologize if they had already been answered elsewhere.

byte[], Memory<byte> and alike

Are these buffer-like objects converted to Uint8Array, or are they exposed as they are?

var buffer = new byte[] { 0, 1, 2, 3 };
engine.Script.buffer = buffer;
engine.Script.bufferAsMemory = (Memory<byte>)buffer;

const x = buffer
const y = bufferAsMemory

x // is this UInt8Array?
y // what is this?

Unsafe types like pointers

A few host methods I'm exposing to the script are unsafe and contain pointer parameters (int*). How are they marshalled?

Enums

I have this enum and method exposed to the script:

public enum MyEnum {
  Value = 1
}

public static class MyClass {
  public static void Method(MyEnum value) { }
}

engine.AddHostType("MyEnum", typeof(MyEnum));
engine.AddHostType("MyClass", typeof(MyClass));

Will the enum be automatically marshalled when referring to it by name, value or reference?

// are any of these possible?
MyClass.Method("Value")
MyClass.Method(1)
MyClass.Method(MyEnum.Value)

ref structs like Span<byte>

These things inherently can't exist on the heap, but all Javascript objects must exist on the heap. How are they handled?

Multidimensional arrays like int[,]

Javascript doesn't have multidimensional arrays. Are they marshalled as jagged arrays number[][]?

[ClearScriptLib]

Hello @phosphene47,

Thanks for your question!

ClearScript generally prefers not to convert between host and script data types, especially if the conversion is lossy, unless the lack of this conversion makes using ClearScript exceptionally painful.

To that end, it provides automatic conversion of fundamental data types only – numbers, strings, Booleans, etc. – and optional automatic conversion of nontrivial but commonly used data types such as date-times and tasks/promises. Everything else is marshaled by proxy; that is, the recipient gets a local object that represents something on the other side of the host-script boundary. The proxy holds a strong reference and provides access to its remote target.

For proxy marshaling to work, the target must be capable of durable reference. For .NET that means it must be on the managed heap – either a reference object or a boxed value. That rules out pointers and ref structs.

Everything else you asked about – simple arrays, multidimensional arrays, conventional structs, and enums – are all marshaled by proxy without conversion. Enums and some other immutable values are also canonicalized, meaning that script code receives a consistent reference for each distinct value, enabling meaningful by-reference comparison.

Good luck!

[luaneko]

Thank you for your answer! It cleared most of my doubts about the library :)