More granular JSExceptions for JSInterop

[KristofferStrube]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

The invocation can fail for multiple reasons when using JSInterop to call JavaScript functions from Blazor. Currently, the erroring case is handled on the JS side, where a boolean indicating whether the invocation was successful together with the error message, and the stack (stack trace) is returned to the C# side as we can see here and the formatting function here. On the C# side a JSException is constructed containing the message and nothing else. But what we are missing is the type of error. An error can basically be one of these types with the APIs available in the browser:

• EvalError
• RangeError
• ReferenceError
• SyntaxError
• TypeError
• URIError

Apart from these, we also have some standard exceptions called the DOMExceptions. There are many different kinds of DOMExceptions as well that are defined in the WebIDL standard specifications. They differ only by having different names and then of cause by being used in different scenarios.

Many JS methods can throw different error types depending on how the invocation failed. As developers, we would like to know why an invocation failed, but we only have the JSException with a raw string message in it. People have employed different methods to parse the string to recover the original reason that the invocation failed. But nowhere in the message is the actual name of the error, as we don't capture that when formatting the error. Instead, people try to find consistent parts of the error message and check if the error contains this subpart to identify the type. An example could be to check if the phrase "is aborted" is in the message to identify it as an AbortError DOMException.

Describe the solution you'd like

I would like it if Blazor would send back the name attribute that is defined on all error types so that developers can check for this property to identify the reason why an invocation failed without doing any guesswork.

Additionally, it would be awesome if there were exception types for all standard JS error names so that developers could catch specific reasons for failure like this:

try
{
    var result = await JSRuntime.InvokeAsync<string>("navigator.clipboard.readText");
}
catch (NotAllowedJSException exception)
{
    Logger.LogWarning(exception, "The user has not given permission to read the clipboard.");
}
catch (NotFoundJSException exception)
{
    Logger.LogWarning(exception, "There wasn't text in the clipboard.");
}
catch (JSException exception)
{
    Logger.LogError(exception, $"An JS error with name '{exception.Name}' happened.");
}
catch (Exception exception)
{
    Logger.LogError(exception, $"Some other unexpected error happened '{exception.GetType().Name}': \"{exception.Message}\"");
}

Additional context

I previously made the following article that also repeats some of my above points but with more details:
https://kristoffer-strube.dk/post/typed-exceptions-for-jsinterop-in-blazor/

In the article I also started on this library which is a workaround to get typed exception types: https://github.com/KristofferStrube/Blazor.WebIDL

[javiercn]

@KristofferStrube thanks for contacting us.

You seem to have done a lot of work on this already, while we need to look in more detail. Would you be open to contribute this to the framework?

[KristofferStrube]

@javiercn yes, very much.

Thanks for contacting us.

We're moving this issue to the .NET 9 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[javiercn]

@KristofferStrube great.

Could you make a concrete proposal? In general, as long as we are able to establish a mapping between the types in JS and the Types in .NET (that doesn't involve parsing error messages) I think we will be ok with it.

[KristofferStrube]

Yes. I will get on that.

[KristofferStrube]

First, I would like to extend the existing JSException class with the following property. The property is optional, as it will only be set if the invocation was due to an erroneous JS invocation.

/// <summary>
/// Represents errors that occur during an interop call from .NET to JavaScript.
/// </summary>
public class JSException : Exception
{
+    /// <summary>
+    /// The name of the error that occurred.
+    /// </summary>
+    public string? Name { get; }

+    /// <summary>
+    /// Constructs an instance of <see cref="JSException"/>.
+    /// </summary>
+    /// <param name="message">The exception message.</param>
+    /// <param name="name">The name of the error that occurred.</param>
+    public JSException(string message, string name) : base(message)
+    {
+        Name = name;
+    }

    /// <summary>
    /// Constructs an instance of <see cref="JSException"/>.
    /// </summary>
    /// <param name="message">The exception message.</param>
    public JSException(string message) : base(message)
    {
    }

    /// <summary>
    /// Constructs an instance of <see cref="JSException"/>.
    /// </summary>
    /// <param name="message">The exception message.</param>
    /// <param name="innerException">The inner exception.</param>
    public JSException(string message, Exception innerException) : base(message, innerException)
    {
    }
}

New types

Next, we want to add these types that extend JSException.

/// <summary>
/// Indicates a value that is not in the set or range of allowable values.
/// </summary>
public class RangeErrorJSException : JSException
{
    /// <summary>
    /// The name of the JS error.
    /// </summary>
    public const string JSErrorName = "RangeError";

    /// <inheritdoc/>
    public RangeErrorJSException(string message) : base(message, JSErrorName) { }
}

/// <summary>
/// Indicate that an invalid reference has been detected.
/// </summary>
public class ReferenceErrorJSException : JSException
{
    /// <summary>
    /// The name of the JS error.
    /// </summary>
    public const string JSErrorName = "ReferenceError";

    /// <inheritdoc/>
    public ReferenceErrorJSException(string message) : base(message, JSErrorName) { }
}

/// <summary>
/// Indicates that a parsing error has occurred.
/// </summary>
public class SyntaxErrorJSException : JSException
{
    /// <summary>
    /// The name of the JS error.
    /// </summary>
    public const string JSErrorName = "SyntaxError";

    /// <inheritdoc/>
    public SyntaxErrorJSException(string message) : base(message, JSErrorName) { }
}

/// <summary>
/// TypeError is used to indicate an unsuccessful operation when none of the other <see cref="JSException"/> types are an appropriate indication of the failure cause.
/// </summary>
public class TypeErrorJSException : JSException
{
    /// <summary>
    /// The name of the JS error.
    /// </summary>
    public const string JSErrorName = "TypeError";

    /// <inheritdoc/>
    public TypeErrorJSException(string message) : base(message, JSErrorName) { }
}

/// <summary>
/// Indicates that one of the global URI handling functions was used in a way that is incompatible with its definition.
/// </summary>
public class URIErrorJSException : JSException
{
    /// <summary>
    /// The name of the JS error.
    /// </summary>
    public const string JSErrorName = "URIError";

    /// <inheritdoc/>
    public URIErrorJSException(string message) : base(message, JSErrorName) { }
}

Next, we want equivalent types for the JS DOMExceptions. First, we define a type for all the different DOMExceptions:

/// <summary>
/// Indicates that an abnormal event happened during a JS invocation.
/// </summary>
public class DOMJSException : JSException
{
    /// <inheritdoc/>
    protected DOMJSException(string message, string name) : base(message, name) { }
}

Next, we want to add types for all the different standard DOMException names as defined in this list.

This is 1 example of one of these:

/// <summary>
/// The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.
/// </summary>
public class NotAllowedErrorJSException : DOMJSException
{
    /// <summary>
    /// The name of the JS error.
    /// </summary>
    public const string JSErrorName = "NotAllowedError";

    /// <inheritdoc/>
    public NotAllowedErrorJSException(string message) : base(message, JSErrorName) { }
}

Changes to error formatting

We start by making a change to the formatError method in Microsoft.JSInterop.ts. We handle the SyntaxError DOMException uniquely as the specification has a naming collision for these types making the indistinguishable.
comment from the spec: To help disambiguate this further, always favor the "SyntaxError" DOMException notation over just using SyntaxError to refer to the DOMException.

  function formatError(error: Error | string): string {
      if (error instanceof Error) {
-          return `${error.message}\n${error.stack}`;
+          let name = error.name;
+          if (error instanceof DOMException && name == "SyntaxError") {
+               name = "SyntaxErrorDOMException";
+          };
+          return `name:${name}\n${error.message}\n${error.stack}`;
      }

      return error ? error.toString() : "null";
  }

I don't really like this approach as it uses a custom format, but it makes it very easy to check if the error string starts with on the .NET side, like:

    internal bool EndInvokeJS(long taskId, bool succeeded, ref Utf8JsonReader jsonReader)
    {
        if (!_pendingTasks.TryRemove(taskId, out var tcs))
        {
            // We should simply return if we can't find an id for the invocation.
            // This likely means that the method that initiated the call defined a timeout and stopped waiting.
            return false;
        }

        CleanupTasksAndRegistrations(taskId);

        try
        {
            if (succeeded)
            {
                var resultType = TaskGenericsUtil.GetTaskCompletionSourceResultType(tcs);

                var result = JsonSerializer.Deserialize(ref jsonReader, resultType, JsonSerializerOptions);
                ByteArraysToBeRevived.Clear();
                TaskGenericsUtil.SetTaskCompletionSourceResult(tcs, result);
            }
            else
            {
                var exceptionText = jsonReader.GetString() ?? string.Empty;
-                TaskGenericsUtil.SetTaskCompletionSourceException(tcs, new JSException(exceptionText));
+                JSException jsException;
+                if (exceptionText.StartsWith("name"))
+                {
+                    int firstLineBreak = text.IndexOf('\n', StringComparison.Ordinal);
+                    string name = exceptionText[5..firstLineBreak];
+                    string messageAndStrackTrace = exceptionText[firstLineBreak+1..];
+                    jsException = switch (name)
+                    {
+                        RangeErrorJSException.JSErrorName => new RangeErrorJSException(messageAndStrackTrace),
+                        ReferenceErrorJSException.JSErrorName => new ReferenceErrorJSException(messageAndStrackTrace),
+                        SyntaxErrorJSException.JSErrorName => new SyntaxErrorJSException(messageAndStrackTrace),
+                        TypeErrorJSException.JSErrorName => new TypeErrorJSException(messageAndStrackTrace),
+                        URIErrorJSException.JSErrorName => new URIErrorJSException(messageAndStrackTrace),
+                        NotAllowedErrorJSException.JSErrorName => new NotAllowedErrorJSException(messageAndStrackTrace),
+                        ... // All other DOMExceptions types we have added will be added here.
+                        _ => new JSException(messageAndStrackTrace, name),
+                    }
+                }
+                else
+                {
+                    jsException = new JSException(exceptionText);
+                }
+                TaskGenericsUtil.SetTaskCompletionSourceException(tcs, jsException);
            }

            return true;
        }
        catch (Exception exception)
        {
            var message = $"An exception occurred executing JS interop: {exception.Message}. See InnerException for more details.";
            TaskGenericsUtil.SetTaskCompletionSourceException(tcs, new JSException(message, exception));
            return false;
        }
    }

As we can see above, it is rather easy to parse the new error format. But it would probably be more beautiful if we returned a JSON formatted object instead with message, name, and stack properties. But this is a bigger change to the overall format of the existing error format.

Conclusion

This will make it very clear why an error occurred. I'm open to any feedback, especially on naming and comments.

[KristofferStrube]

Hey @javiercn just wanted to point to the above proposal if you hadn't seen it.