Custom marshal attribute

.vscode/settings.json

@@ -1,4 +1,9 @@
 {
     // Don't show the "Required assets are missing..." dialog on startup. We'll manage tasks.json / launch.json manually.
-    "csharp.suppressBuildAssetsNotification": true
+    "csharp.suppressBuildAssetsNotification": true,
+
+    // We try to limit the length of code lines to 100 columns.
+    "editor.rulers": [
+      100,
+  ]
 }

Runtime/IJSMarshaler.cs

@@ -0,0 +1,14 @@
+
+namespace NodeApi;
+
+/// <summary>
+/// Interface for a custom implementation of marshaling .NET types to and from JavaScript values.
+/// A type that implements this interface can be assigned to
+/// <see cref="JSMarshalAsAttribute.CustomMarshalType" />.
+/// </summary>
+public interface IJSMarshaler<T>
+{
+    JSValue MarshalToJS(T value);
+
+    T MarshalFromJS(JSValue value);
+}

Runtime/JSMarshal.cs

@@ -0,0 +1,49 @@
+
+namespace NodeApi;
+
+/// <summary>
+/// Specifies marshalling behavior for <see cref="JSMarshalAsAttribute" />.
+/// </summary>
+public enum JSMarshal
+{
+    /// <summary>
+    /// Default marshalling behavior.
+    /// </summary>
+    Default,
+
+    /// <summary>
+    /// Marshalling is handled by a custom marshaler type. When this is specified,
+    /// <see cref="JSMarshalAsAttribute.CustomMarshalType" /> must also be set.
+    /// </summary>
+    CustomMarshaler,
+
+    /// <summary>
+    /// A .NET object is marshalled as a JS external value. External values may not
+    /// be accessed by JS, but may be held and passed back to .NET code intact.
+    /// </summary>
+    ExternalObject,
+
+    /// <summary>
+    /// The object is marshalled by value, meaning all public properties are shallow-copied.
+    /// This is the default marshalling behavior for .NET structs.
+    /// </summary>
+    ByValObject,
+
+    /// <summary>
+    /// The object is marshalled by reference, meaning only a proxy to the object is passed.
+    /// This is the default marshalling behavior for .NET classes and interfaces.
+    /// </summary>
+    ByRefObject,
+
+    /// <summary>
+    /// Collection items are copied into a new collection in the target environment.
+    /// This is the default marshalling behavior for .NET arrays.
+    /// </summary>
+    ByValCollection = ByValObject,
+
+    /// <summary>
+    /// The collection is marshalled by reference, meaning only a proxy to the collection is passed.
+    /// This is the default marshalling behavior for .NET generic collections.
+    /// </summary>
+    ByRefCollection = ByRefObject,
+}

Runtime/JSMarshalAsAttribute.cs

@@ -0,0 +1,37 @@
+
+using System;
+
+namespace NodeApi;
+
+/// <summary>
+/// Specifies how .NET types are marshalled to and from JavaScript values.
+/// </summary>
+[AttributeUsage(
+    AttributeTargets.Property |
+    AttributeTargets.Parameter |
+    AttributeTargets.ReturnValue)]
+public sealed class JSMarshalAsAttribute : Attribute
+{
+    /// <summary>
+    /// Specifies how a .NET property, parameter, or return value is marshalled to
+    /// and from a JavaScript value.
+    /// </summary>
+    /// <param name="marshal">One of the available marshaling options.</param>
+    public JSMarshalAsAttribute(JSMarshal marshal)
+    {
+        Value = marshal;
+    }
+
+    /// <summary>
+    /// Gets the marshaling behavior indicated by the attribute.
+    /// </summary>
+    public JSMarshal Value { get; }
+
+    /// <summary>
+    /// When <see cref="Value" /> is <see cref="JSMarshal.CustomMarshaler" />, gets the type
+    /// that handles marshalling. The type must implement <see cref="IJSMarshaler{T}" />,
+    /// where the type argument matches the type being of the property, parameter, or
+    /// return value the <see cref="JSMarshalAsAttribute" /> is applied to.
+    /// </summary>
+    public Type? CustomMarshalType { get; init; }
+}