Mapping between .Net objects and JSReference should not allow to match objects of different types.

src/NodeApi/Interop/JSRuntimeContext.cs

@@ -35,6 +35,8 @@ public sealed class JSRuntimeContext : IDisposable
     /// </remarks>
     public const string GlobalObjectName = "node_api_dotnet";
 
+    private static IEqualityComparer<object> s_jsTranslationEqualityComparer = Interop.JSTranslationEqualityComparer.Instance;
+
     private readonly napi_env _env;
 
     // Track JS constructors and instance JS wrappers for exported classes, enabling
@@ -73,8 +75,11 @@ public sealed class JSRuntimeContext : IDisposable
     /// a C# object maps to the same JS instance when marshalled multiple times. The
     /// references are weak to allow the JS wrappers to be released; new wrappers are
     /// re-constructed as needed.
+    /// Important! We need to match by reference, otherwise for classes that overrides
+    /// the <see cref="object.Equals(object?)"/> method, JS can receive unpredictable
+    /// object instance.
     /// </remarks>
-    private readonly ConcurrentDictionary<object, JSReference> _objectMap = new();
+    private readonly ConcurrentDictionary<object, JSReference> _objectMap = new(JSTranslationEqualityComparer);
 
     /// <summary>
     /// Maps from exported struct types to (strong references to) JS constructors for classes
@@ -136,6 +141,24 @@ public static explicit operator JSRuntimeContext(napi_env env)
     /// thread.</exception>
     public static JSRuntimeContext Current => JSValueScope.Current.RuntimeContext;
 
+    /// <summary>
+    /// The equality comparer used to translate .NET objects to JS objects.
+    /// </summary>
+    /// <remarks>
+    /// This property allows for altering the behavior of the translation process from .NET objects to JS objects.
+    /// If certain types have equality members that block access to required instances, this property can be assigned
+    /// to a more suitable implementation. See the <see cref="Microsoft.JavaScript.NodeApi.Interop.JSTranslationEqualityComparer"/>
+    /// comparer for more details.
+    /// </remarks>
+    public static IEqualityComparer<object> JSTranslationEqualityComparer
+    {
+        get => s_jsTranslationEqualityComparer;
+        set
+        {
+            s_jsTranslationEqualityComparer = value ?? throw new ArgumentNullException(nameof(value));
+        }
+    }
+
     public JSRuntime Runtime { get; }
 
     public JSSynchronizationContext SynchronizationContext { get; }

src/NodeApi/Interop/JSTranslationEqualityComparer.cs

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Generic;
+
+namespace Microsoft.JavaScript.NodeApi.Interop;
+
+/// <summary>
+/// Default .Net to JS objects translation equality comparer.
+/// </summary>
+public class JSTranslationEqualityComparer : IEqualityComparer<object>
+{
+    /// <summary>
+    /// Single instance of the comparer.
+    /// </summary>
+    public static JSTranslationEqualityComparer Instance { get; } = new ();
+
+    private JSTranslationEqualityComparer()
+    {
+    }
+
+    /// <inheritdoc />
+    public new bool Equals(object? x, object? y)
+    {
+        if (x is null)
+        {
+            return y is null;
+        }
+
+        if (y is null)
+        {
+            return false;
+        }
+
+        // We should deliberately make different types not equal to avoid type definition mismatch.
+        // Object of type B that matched through A.Equal(B) can be accessed in JS through description of type A, which is wrong.
+        if (x.GetType() != y.GetType())
+        {
+            return false;
+        }
+
+        return x.Equals(y);
+    }
+
+    /// <inheritdoc />
+    public int GetHashCode(object? obj)
+    {
+        if (obj is null)
+        {
+            return 0;
+        }
+
+        return obj.GetHashCode();
+    }
+}