Made sure that all types are documented and that IJSWrapper types implement IJSCreatable.

Author: KristofferStrube

src/KristofferStrube.Blazor.FileAPI/BaseJSWrapper.cs

@@ -1,32 +1,48 @@
-using Microsoft.JSInterop;
+using KristofferStrube.Blazor.WebIDL;
+using Microsoft.JSInterop;
 
 namespace KristofferStrube.Blazor.FileAPI;
 
-public abstract class BaseJSWrapper : IAsyncDisposable
+/// <summary>
+/// A base class for all wrappers in Blazor.FileAPI.
+/// </summary>
+public abstract class BaseJSWrapper : IJSWrapper
 {
-    public readonly IJSObjectReference JSReference;
+    /// <summary>
+    /// A lazily loaded task that evaluates to a helper module instance from the Blazor.FileAPI library.
+    /// </summary>
     protected readonly Lazy<Task<IJSObjectReference>> helperTask;
-    protected readonly IJSRuntime jSRuntime;
+
+    /// <inheritdoc/>
+    public IJSRuntime JSRuntime { get; }
+    /// <inheritdoc/>
+    public IJSObjectReference JSReference { get; }
+    /// <inheritdoc/>
+    public bool DisposesJSReference { get; }
 
     /// <summary>
     /// Constructs a wrapper instance for an equivalent JS instance.
     /// </summary>
     /// <param name="jSRuntime">An <see cref="IJSRuntime"/> instance.</param>
     /// <param name="jSReference">A JS reference to an existing JS instance that should be wrapped.</param>
-    internal BaseJSWrapper(IJSRuntime jSRuntime, IJSObjectReference jSReference)
+    /// <param name="options">The options for constructing this wrapper.</param>
+    internal BaseJSWrapper(IJSRuntime jSRuntime, IJSObjectReference jSReference, CreationOptions options)
     {
         helperTask = new(jSRuntime.GetHelperAsync);
+        JSRuntime = jSRuntime;
         JSReference = jSReference;
-        this.jSRuntime = jSRuntime;
+        DisposesJSReference = options.DisposesJSReference;
     }
 
+    /// <inheritdoc/>
     public async ValueTask DisposeAsync()
     {
         if (helperTask.IsValueCreated)
         {
             IJSObjectReference module = await helperTask.Value;
             await module.DisposeAsync();
         }
+        await IJSWrapper.DisposeJSReference(this);
         GC.SuppressFinalize(this);
     }
 }

src/KristofferStrube.Blazor.FileAPI/Blob.InProcess.cs

@@ -1,26 +1,34 @@
 using KristofferStrube.Blazor.Streams;
+using KristofferStrube.Blazor.WebIDL;
 using Microsoft.JSInterop;
 
 namespace KristofferStrube.Blazor.FileAPI;
 
 /// <summary>
 /// <see href="https://www.w3.org/TR/FileAPI/#blob-section">Blob browser specs</see>
 /// </summary>
-public class BlobInProcess : Blob
+[IJSWrapperConverter]
+public class BlobInProcess : Blob, IJSInProcessCreatable<BlobInProcess, Blob>
 {
-    public new IJSInProcessObjectReference JSReference;
-    protected readonly IJSInProcessObjectReference inProcessHelper;
+    /// <inheritdoc />
+    public new IJSInProcessObjectReference JSReference { get; }
 
     /// <summary>
-    /// Constructs a wrapper instance for a given JS Instance of a <see cref="Blob"/>.
+    /// A lazily loaded task that evaluates to a helper module instance from the Blazor.FileAPI library.
     /// </summary>
-    /// <param name="jSRuntime">An <see cref="IJSRuntime"/> instance.</param>
-    /// <param name="jSReference">A JS reference to an existing <see cref="Blob"/>.</param>
-    /// <returns>A wrapper instance for a <see cref="Blob"/>.</returns>
+    protected IJSInProcessObjectReference InProcessHelper { get; }
+
+    /// <inheritdoc/>
     public static async Task<BlobInProcess> CreateAsync(IJSRuntime jSRuntime, IJSInProcessObjectReference jSReference)
+    {
+        return await CreateAsync(jSRuntime, jSReference, new());
+    }
+
+    /// <inheritdoc/>
+    public static async Task<BlobInProcess> CreateAsync(IJSRuntime jSRuntime, IJSInProcessObjectReference jSReference, CreationOptions options)
     {
         IJSInProcessObjectReference inProcessHelper = await jSRuntime.GetInProcessHelperAsync();
-        return new BlobInProcess(jSRuntime, inProcessHelper, jSReference);
+        return new BlobInProcess(jSRuntime, inProcessHelper, jSReference, options);
     }
 
     /// <summary>
@@ -41,19 +49,14 @@ public static async Task<BlobInProcess> CreateAsync(IJSRuntime jSRuntime, IJSInP
             })
             .ToArray();
         IJSInProcessObjectReference jSInstance = await inProcessHelper.InvokeAsync<IJSInProcessObjectReference>("constructBlob", jsBlobParts, options);
-        return new BlobInProcess(jSRuntime, inProcessHelper, jSInstance);
+        return new BlobInProcess(jSRuntime, inProcessHelper, jSInstance, new() { DisposesJSReference = true });
     }
 
-    /// <summary>
-    /// Constructs a wrapper instance for a given JS Instance of a <see cref="Blob"/>.
-    /// </summary>
-    /// <param name="jSRuntime">An <see cref="IJSRuntime"/> instance.</param>
-    /// <param name="inProcessHelper">An in process helper instance.</param>
-    /// <param name="jSReference">A JS reference to an existing <see cref="Blob"/>.</param>
-    internal BlobInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProcessHelper, IJSInProcessObjectReference jSReference) : base(jSRuntime, jSReference)
+    /// <inheritdoc cref="CreateAsync(IJSRuntime, IJSInProcessObjectReference, CreationOptions)"/>
+    protected internal BlobInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProcessHelper, IJSInProcessObjectReference jSReference, CreationOptions options) : base(jSRuntime, jSReference, options)
     {
-        this.inProcessHelper = inProcessHelper;
         JSReference = jSReference;
+        InProcessHelper = inProcessHelper;
     }
 
     /// <summary>
@@ -63,20 +66,20 @@ internal BlobInProcess(IJSRuntime jSRuntime, IJSInProcessObjectReference inProce
     public new async Task<ReadableStreamInProcess> StreamAsync()
     {
         IJSInProcessObjectReference jSInstance = JSReference.Invoke<IJSInProcessObjectReference>("stream");
-        return await ReadableStreamInProcess.CreateAsync(jSRuntime, jSInstance);
+        return await ReadableStreamInProcess.CreateAsync(JSRuntime, jSInstance);
     }
 
     /// <summary>
     /// The size of this blob.
     /// </summary>
     /// <returns>A <see langword="ulong"/> representing the size of the blob in bytes.</returns>
-    public ulong Size => inProcessHelper.Invoke<ulong>("getAttribute", JSReference, "size");
+    public ulong Size => InProcessHelper.Invoke<ulong>("getAttribute", JSReference, "size");
 
     /// <summary>
     /// The media type of this blob. This is either a parseable MIME type or an empty string.
     /// </summary>
     /// <returns>The MIME type of this blob.</returns>
-    public string Type => inProcessHelper.Invoke<string>("getAttribute", JSReference, "type");
+    public string Type => InProcessHelper.Invoke<string>("getAttribute", JSReference, "type");
 
     /// <summary>
     /// Gets some range of the content of a <see cref="Blob"/> as a new <see cref="Blob"/>.
@@ -90,6 +93,6 @@ public BlobInProcess Slice(long? start = null, long? end = null, string? content
         start ??= 0;
         end ??= (long)Size;
         IJSInProcessObjectReference jSInstance = JSReference.Invoke<IJSInProcessObjectReference>("slice", start, end, contentType);
-        return new BlobInProcess(jSRuntime, inProcessHelper, jSInstance);
+        return new BlobInProcess(JSRuntime, InProcessHelper, jSInstance, new() { DisposesJSReference = true });
     }
 }

src/KristofferStrube.Blazor.FileAPI/Blob.cs

@@ -1,22 +1,37 @@
 using KristofferStrube.Blazor.Streams;
+using KristofferStrube.Blazor.WebIDL;
 using Microsoft.JSInterop;
 
 namespace KristofferStrube.Blazor.FileAPI;
 
 /// <summary>
 /// <see href="https://www.w3.org/TR/FileAPI/#blob-section">Blob browser specs</see>
 /// </summary>
-public class Blob : BaseJSWrapper
+[IJSWrapperConverter]
+public class Blob : BaseJSWrapper, IJSCreatable<Blob>
 {
+    /// <inheritdoc/>
+    public static async Task<Blob> CreateAsync(IJSRuntime jSRuntime, IJSObjectReference jSReference)
+    {
+        return await CreateAsync(jSRuntime, jSReference, new());
+    }
+
+    /// <inheritdoc/>
+    public static Task<Blob> CreateAsync(IJSRuntime jSRuntime, IJSObjectReference jSReference, CreationOptions options)
+    {
+        return Task.FromResult(new Blob(jSRuntime, jSReference, options));
+    }
+
     /// <summary>
     /// Constructs a wrapper instance for a given JS Instance of a <see cref="Blob"/>.
     /// </summary>
     /// <param name="jSRuntime">An <see cref="IJSRuntime"/> instance.</param>
     /// <param name="jSReference">A JS reference to an existing <see cref="Blob"/>.</param>
     /// <returns>A wrapper instance for a <see cref="Blob"/>.</returns>
+    [Obsolete("This will be removed in the next major release as all creator methods should be asynchronous for uniformity. Use CreateAsync instead.")]
     public static Blob Create(IJSRuntime jSRuntime, IJSObjectReference jSReference)
     {
-        return new Blob(jSRuntime, jSReference);
+        return new Blob(jSRuntime, jSReference, new());
     }
 
     /// <summary>
@@ -37,15 +52,11 @@ public static async Task<Blob> CreateAsync(IJSRuntime jSRuntime, IList<BlobPart>
             })
             .ToArray();
         IJSObjectReference jSInstance = await helper.InvokeAsync<IJSObjectReference>("constructBlob", jsBlobParts, options);
-        return new Blob(jSRuntime, jSInstance);
+        return new Blob(jSRuntime, jSInstance, new() { DisposesJSReference = true });
     }
 
-    /// <summary>
-    /// Constructs a wrapper instance for a given JS Instance of a <see cref="Blob"/>.
-    /// </summary>
-    /// <param name="jSRuntime">An <see cref="IJSRuntime"/> instance.</param>
-    /// <param name="jSReference">A JS reference to an existing <see cref="Blob"/>.</param>
-    internal Blob(IJSRuntime jSRuntime, IJSObjectReference jSReference) : base(jSRuntime, jSReference) { }
+    /// <inheritdoc cref="CreateAsync(IJSRuntime, IJSObjectReference, CreationOptions)"/>
+    protected Blob(IJSRuntime jSRuntime, IJSObjectReference jSReference, CreationOptions options) : base(jSRuntime, jSReference, options) { }
 
     /// <summary>
     /// The size of this blob.
@@ -79,7 +90,7 @@ public async Task<Blob> SliceAsync(long? start = null, long? end = null, string?
         start ??= 0;
         end ??= (long)await GetSizeAsync();
         IJSObjectReference jSInstance = await JSReference.InvokeAsync<IJSObjectReference>("slice", start, end, contentType);
-        return new Blob(jSRuntime, jSInstance);
+        return new Blob(JSRuntime, jSInstance, new() { DisposesJSReference = true });
     }
 
     /// <summary>
@@ -89,7 +100,7 @@ public async Task<Blob> SliceAsync(long? start = null, long? end = null, string?
     public async Task<ReadableStream> StreamAsync()
     {
         IJSObjectReference jSInstance = await JSReference.InvokeAsync<IJSObjectReference>("stream");
-        return await ReadableStream.CreateAsync(jSRuntime, jSInstance);
+        return await ReadableStream.CreateAsync(JSRuntime, jSInstance);
     }
 
     /// <summary>

src/KristofferStrube.Blazor.FileAPI/Converters/DateTimeConverter.cs

@@ -7,11 +7,9 @@ internal class DateTimeConverter : JsonConverter<DateTime>
 {
     public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
     {
-        if (reader.TryGetUInt64(out ulong jsonValue))
-        {
-            return DateTime.UnixEpoch.AddMilliseconds(jsonValue);
-        }
-        throw new JsonException($"string {reader.GetString()} could not be parsed as a long.");
+        return reader.TryGetUInt64(out ulong jsonValue)
+            ? DateTime.UnixEpoch.AddMilliseconds(jsonValue)
+            : throw new JsonException($"string {reader.GetString()} could not be parsed as a long.");
     }
 
     public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)

src/KristofferStrube.Blazor.FileAPI/Converters/EnumDescriptionConverter.cs

@@ -17,7 +17,7 @@ public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerial
 
         foreach (FieldInfo? fi in typeToConvert.GetFields())
         {
-            DescriptionAttribute description = (DescriptionAttribute)fi.GetCustomAttribute(typeof(DescriptionAttribute), false);
+            var description = (DescriptionAttribute)fi.GetCustomAttribute(typeof(DescriptionAttribute), false);
 
             if (description != null)
             {
@@ -34,7 +34,7 @@ public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions
     {
         FieldInfo fi = value.GetType().GetField(value.ToString());
 
-        DescriptionAttribute description = (DescriptionAttribute)fi.GetCustomAttribute(typeof(DescriptionAttribute), false);
+        var description = (DescriptionAttribute)fi.GetCustomAttribute(typeof(DescriptionAttribute), false);
 
         writer.WriteStringValue(description.Description);
     }

src/KristofferStrube.Blazor.FileAPI/Enums/EndingType.cs

@@ -4,13 +4,23 @@
 namespace KristofferStrube.Blazor.FileAPI;
 
 /// <summary>
-/// <see href="https://www.w3.org/TR/FileAPI/#enumdef-endingtype">EndingType browser specs</see>
+/// It controls how line endings are handled in <see cref="string"/> elements within <see cref="BlobPart"/>s
 /// </summary>
+/// <remarks>
+/// <see href="https://www.w3.org/TR/FileAPI/#enumdef-endingtype">EndingType browser specs</see>
+/// </remarks>
 [JsonConverter(typeof(EnumDescriptionConverter<EndingType>))]
 public enum EndingType
 {
+    /// <summary>
+    /// Line endings in <see cref="string"/> elements within <see cref="BlobPart"/>s remain unchanged, with no conversion applied, preserving the original format.
+    /// </summary>
     [Description("transparent")]
     Transparent,
+
+    /// <summary>
+    /// Line endings in <see cref="string"/> elements within <see cref="BlobPart"/>s are converted to the platform's native format (<c>\n</c> or <c>\r\n</c>), ensuring consistency with the system's convention.
+    /// </summary>
     [Description("native")]
     Native,
 }

src/KristofferStrube.Blazor.FileAPI/Extensions/IServiceCollectionExtensions.cs

@@ -3,13 +3,24 @@
 
 namespace KristofferStrube.Blazor.FileAPI;
 
+/// <summary>
+/// Contains extension methods for adding services to a <see cref="IServiceCollection"/>.
+/// </summary>
 public static class IServiceCollectionExtensions
 {
+    /// <summary>
+    /// Adds an <see cref="IURLService"/> to the service collection.
+    /// </summary>
+    /// <param name="serviceCollection">The service collection.</param>
     public static IServiceCollection AddURLService(this IServiceCollection serviceCollection)
     {
         return serviceCollection.AddScoped<IURLService, URLService>();
     }
 
+    /// <summary>
+    /// Adds an <see cref="IURLServiceInProcess"/> to the service collection.
+    /// </summary>
+    /// <param name="serviceCollection">The service collection.</param>
     public static IServiceCollection AddURLServiceInProcess(this IServiceCollection serviceCollection)
     {
         return serviceCollection.AddScoped<IURLServiceInProcess>(sp => new URLServiceInProcess((IJSInProcessRuntime)sp.GetRequiredService<IJSRuntime>()));