Aligned DataLoader options behavior. (#8044)

.vscode/tasks.json

@@ -17,12 +17,19 @@
       }
     },
     {
-      "label": "Build src/All.sln",
+      "type": "dotnet",
+      "task": "build",
+      "group": "build",
+      "problemMatcher": [],
+      "label": "dotnet: build"
+    },
+    {
+      "label": "Build src/All.slnx",
       "command": "dotnet",
       "type": "shell",
       "args": [
         "build",
-        "src/All.sln",
+        "src/All.slnx",
         "/property:GenerateFullPaths=true",
         "/consoleloggerparameters:NoSummary"
       ],
@@ -49,12 +56,12 @@
       "problemMatcher": "$msCompile"
     },
     {
-      "label": "Test src/All.sln",
+      "label": "Test src/All.slnx",
       "command": "dotnet",
       "type": "shell",
       "args": [
         "test",
-        "src/All.sln",
+        "src/All.slnx",
         "--verbosity q",
         "/property:GenerateFullPaths=true",
         "/consoleloggerparameters:NoSummary"
@@ -64,6 +71,6 @@
         "reveal": "silent"
       },
       "problemMatcher": "$msCompile"
-    },
+    }
   ]
 }

src/GreenDonut/src/GreenDonut/BatchDataLoader.cs

@@ -28,10 +28,6 @@ protected BatchDataLoader(
         DataLoaderOptions options)
         : base(batchScheduler, options)
     {
-        if (options is null)
-        {
-            throw new ArgumentNullException(nameof(options));
-        }
     }
 
     /// <inheritdoc />

src/GreenDonut/src/GreenDonut/BranchedDataLoader.cs

@@ -0,0 +1,42 @@
+namespace GreenDonut;
+
+/// <summary>
+/// This class represents a branched <see cref="IDataLoader{TKey, TValue}"/>.
+/// </summary>
+/// <typeparam name="TKey">
+/// The type of the key.
+/// </typeparam>
+/// <typeparam name="TValue">
+/// The type of the value.
+/// </typeparam>
+public class BranchedDataLoader<TKey, TValue>
+    : DataLoaderBase<TKey, TValue>
+    where TKey : notnull
+{
+    private readonly DataLoaderBase<TKey, TValue> _root;
+
+    public BranchedDataLoader(
+        DataLoaderBase<TKey, TValue> root,
+        string key)
+        : base(root.BatchScheduler, root.Options)
+    {
+        _root = root;
+        CacheKeyType = $"{root.CacheKeyType}:{key}";
+        ContextData = root.ContextData;
+    }
+
+    public IDataLoader<TKey, TValue> Root => _root;
+
+    protected internal override string CacheKeyType { get; }
+
+    protected sealed override bool AllowCachePropagation => false;
+
+    protected override bool AllowBranching => true;
+
+    protected internal override ValueTask FetchAsync(
+        IReadOnlyList<TKey> keys,
+        Memory<Result<TValue?>> results,
+        DataLoaderFetchContext<TValue> context,
+        CancellationToken cancellationToken)
+        => _root.FetchAsync(keys, results, context, cancellationToken);
+}

src/GreenDonut/src/GreenDonut/DataLoaderBase.cs

@@ -46,9 +46,11 @@ public abstract partial class DataLoaderBase<TKey, TValue>
     /// <exception cref="ArgumentNullException">
     /// Throws if <paramref name="options"/> is <c>null</c>.
     /// </exception>
-    protected DataLoaderBase(IBatchScheduler batchScheduler, DataLoaderOptions? options = null)
+    protected DataLoaderBase(IBatchScheduler batchScheduler, DataLoaderOptions options)
     {
-        options ??= new DataLoaderOptions();
+        ArgumentNullException.ThrowIfNull(batchScheduler);
+        ArgumentNullException.ThrowIfNull(options);
+
         _diagnosticEvents = options.DiagnosticEvents ?? Default;
         Cache = options.Cache;
         _batchScheduler = batchScheduler;
@@ -226,7 +228,7 @@ void Initialize()
                 ct);
         }
     }
-    
+
     /// <inheritdoc />
     public void SetCacheEntry(TKey key, Task<TValue?> value)
     {

src/GreenDonut/src/GreenDonut/GroupedDataLoader.cs

@@ -25,7 +25,7 @@ public abstract class GroupedDataLoader<TKey, TValue>
     /// </exception>
     protected GroupedDataLoader(
         IBatchScheduler batchScheduler,
-        DataLoaderOptions? options = null)
+        DataLoaderOptions options)
         : base(batchScheduler, options)
     { }
 
@@ -92,7 +92,7 @@ public abstract class StatefulGroupedDataLoader<TKey, TValue>
     /// </exception>
     protected StatefulGroupedDataLoader(
         IBatchScheduler batchScheduler,
-        DataLoaderOptions? options = null)
+        DataLoaderOptions options)
         : base(batchScheduler, options)
     { }
 

src/GreenDonut/test/GreenDonut.Tests/DataLoader.cs

@@ -3,7 +3,7 @@ namespace GreenDonut;
 public class DataLoader<TKey, TValue>(
     FetchDataDelegate<TKey, TValue> fetch,
     IBatchScheduler batchScheduler,
-    DataLoaderOptions? options = null)
+    DataLoaderOptions options)
     : DataLoaderBase<TKey, TValue>(batchScheduler, options)
     where TKey : notnull
 {

src/GreenDonut/test/GreenDonut.Tests/DataLoaderExtensionsTests.cs

@@ -1,5 +1,7 @@
 // ReSharper disable InconsistentNaming
 
+using System.Reflection.Metadata;
+
 namespace GreenDonut;
 
 public class DataLoaderExtensionsTests
@@ -24,7 +26,7 @@ public void SetCacheEntryKeyNull()
         // arrange
         var fetch = TestHelpers.CreateFetch<string, string>();
         var batchScheduler = new ManualBatchScheduler();
-        var loader = new DataLoader<string, string>(fetch, batchScheduler);
+        var loader = new DataLoader<string, string>(fetch, batchScheduler, new DataLoaderOptions());
         var value = "Bar";
 
         // act
@@ -40,7 +42,7 @@ public void SetCacheEntryNoException()
         // arrange
         var fetch = TestHelpers.CreateFetch<string, string>();
         var batchScheduler = new ManualBatchScheduler();
-        var loader = new DataLoader<string, string>(fetch, batchScheduler);
+        var loader = new DataLoader<string, string>(fetch, batchScheduler, new DataLoaderOptions());
         var key = "Foo";
 
         // act
@@ -149,7 +151,7 @@ public void IDataLoaderSetCacheEntryNoException()
         // arrange
         var fetch = TestHelpers.CreateFetch<string, string>();
         var batchScheduler = new ManualBatchScheduler();
-        IDataLoader loader = new DataLoader<string, string>(fetch, batchScheduler);
+        IDataLoader loader = new DataLoader<string, string>(fetch, batchScheduler, new DataLoaderOptions());
         object key = "Foo";
 
         // act

src/GreenDonut/test/GreenDonut.Tests/DataLoaderStateTests.cs

@@ -6,7 +6,7 @@ public static class DataLoaderStateTests
     public static async Task SetStateInferredKey()
     {
         // arrange
-        var loader = new DummyDataLoader(typeof(string).FullName!);
+        var loader = new DummyDataLoader(typeof(string).FullName!, new DataLoaderOptions());
 
         // act
         await loader.SetState("abc").LoadAsync("def");
@@ -19,7 +19,7 @@ public static async Task SetStateInferredKey()
     public static async Task SetStateExplicitKey()
     {
         // arrange
-        var loader = new DummyDataLoader("abc");
+        var loader = new DummyDataLoader("abc", new DataLoaderOptions());
 
         // act
         await loader.SetState("abc", "def").LoadAsync("ghi");
@@ -32,7 +32,7 @@ public static async Task SetStateExplicitKey()
     public static async Task TrySetStateInferredKey()
     {
         // arrange
-        var loader = new DummyDataLoader(typeof(string).FullName!);
+        var loader = new DummyDataLoader(typeof(string).FullName!, new DataLoaderOptions());
 
         // act
         await loader.SetState("abc").TrySetState("xyz").LoadAsync("def");
@@ -45,7 +45,7 @@ public static async Task TrySetStateInferredKey()
     public static async Task TrySetStateExplicitKey()
     {
         // arrange
-        var loader = new DummyDataLoader("abc");
+        var loader = new DummyDataLoader("abc", new DataLoaderOptions());
 
         // act
         await loader.SetState("abc", "def").TrySetState("abc", "xyz").LoadAsync("def");
@@ -58,7 +58,7 @@ public static async Task TrySetStateExplicitKey()
     public static async Task AddStateEnumerableInferredKey()
     {
         // arrange
-        var loader = new DummyDataLoader(typeof(string).FullName!);
+        var loader = new DummyDataLoader(typeof(string).FullName!, new DataLoaderOptions());
 
         // act
         await loader.AddStateEnumerable("abc").AddStateEnumerable("xyz").LoadAsync("def");
@@ -74,7 +74,7 @@ public static async Task AddStateEnumerableInferredKey()
     public static async Task AddStateEnumerableExplicitKey()
     {
         // arrange
-        var loader = new DummyDataLoader("abc");
+        var loader = new DummyDataLoader("abc", new DataLoaderOptions());
 
         // act
         await loader.AddStateEnumerable("abc", "def").AddStateEnumerable("abc", "xyz").LoadAsync("def");
@@ -86,7 +86,7 @@ public static async Task AddStateEnumerableExplicitKey()
             item => Assert.Equal("xyz", item));
     }
 
-    public class DummyDataLoader(string expectedKey, DataLoaderOptions? options = null)
+    public class DummyDataLoader(string expectedKey, DataLoaderOptions options)
         : DataLoaderBase<string, string>(AutoBatchScheduler.Default, options)
     {
         public object? State { get; set; }

src/GreenDonut/test/GreenDonut.Tests/DependencyInjection/DataLoaderServiceCollectionExtensionsTests.cs

@@ -17,7 +17,10 @@ public void ImplFactoryIsCalledWhenServiceIsResolved()
             .AddDataLoader(sp =>
             {
                 factoryCalled = true;
-                return new DataLoader<string, string>(fetch, sp.GetRequiredService<IBatchScheduler>());
+                return new DataLoader<string, string>(
+                    fetch,
+                    sp.GetRequiredService<IBatchScheduler>(),
+                    sp.GetRequiredService<DataLoaderOptions>());
             });
         var scope = services.BuildServiceProvider().CreateScope();
 
@@ -40,7 +43,10 @@ public void InterfaceImplFactoryIsCalledWhenServiceIsResolved()
             .AddDataLoader<IDataLoader<string, string>, DataLoader<string, string>>(sp =>
             {
                 factoryCalled = true;
-                return new DataLoader<string, string>(fetch, sp.GetRequiredService<IBatchScheduler>());
+                return new DataLoader<string, string>(
+                    fetch,
+                    sp.GetRequiredService<IBatchScheduler>(),
+                    sp.GetRequiredService<DataLoaderOptions>());
             });
         var scope = services.BuildServiceProvider().CreateScope();
 

src/HotChocolate/Core/test/Execution.Tests/Integration/DataLoader/UseDataLoaderTests.cs

@@ -256,7 +256,7 @@ public class TestGroupedLoader : GroupedDataLoader<int, Foo>
     {
         public TestGroupedLoader(
             IBatchScheduler batchScheduler,
-            DataLoaderOptions? options = null)
+            DataLoaderOptions options)
             : base(batchScheduler, options)
         {
         }

website/src/docs/hotchocolate/v15/migrating/migrate-from-14-to-15.md

@@ -50,8 +50,74 @@ Please ensure that your clients are sending date/time strings in the correct for
 - `DateOnly` is now bound to `LocalDateType` instead of `DateType`.
 - `TimeOnly` is now bound to `LocalTimeType` instead of `TimeSpanType`.
 
+## DataLoaderOptions are now required
+
+Starting with Hot Chocolate 15, the `DataLoaderOptions` must be passed down to the DataLoaderBase constructor.
+
+```csharp
+public class ProductByIdDataLoader : BatchDataLoader<int, Product>
+{
+    private readonly IServiceProvider _services;
+
+    public ProductDataLoader1(
+        IBatchScheduler batchScheduler,
+        DataLoaderOptions options) // the options are now required ...
+        : base(batchScheduler, options)
+    {
+    }
+}
+```
+
+## DataLoader Dependency Injection
+
+DataLoader must not be manually registered with the dependency injection and must use the extension methods provided by GreenDonut.
+
+```csharp
+services.AddDataLoader<ProductByIdDataLoader>();
+services.AddDataLoader<IProductByIdDataLoader, ProductByIdDataLoader>();
+services.AddDataLoader<IProductByIdDataLoader>(sp => ....);
+```
+
+We recommend to use the source-generated DataLoaders and let the source generator write the registration code for you.
+
+> If you register DataLoader manually they will be stuck in the auto-dispatch mode, which basically means that they will no longer batch.
+
+DataLoader are available as scoped services and can be injected like any other scoped service.
+
+```csharp
+public class ProductService(IProductByIdDataLoader productByIdData)
+{
+    public async Task<Product> GetProductById(int id)
+    {
+        return await productByIdDataLoader.LoadAsync(id);
+    }
+}
+```
+
 # Deprecations
 
+## GroupDataLoader
+
+We no longer recommend using the `GroupDataLoader`, as the same functionality can be achieved with a BatchDataLoader, which provides greater flexibility in determining the type of list returned.
+
+Use the following patter to replace the `GroupDataLoader`:
+
+```csharp
+internal static class ProductDataLoader
+{
+    [DataLoader]
+    public static async Task<Dictionary<int, Product[]>> GetProductsByBrandIdAsync(
+        IReadOnlyList<int> brandIds,
+        CatalogContext context,
+        CancellationToken cancellationToken)
+        => await context.Products
+            .Where(t => brandIds.Contains(t.BrandId))
+            .GroupBy(t => t.BrandId)
+            .Select(t => new { t.Key, Items = t.OrderBy(p => p.Name).ToArray() })
+            .ToDictionaryAsync(t => t.Key, t => t.Items, cancellationToken);
+}
+```
+
 ## AdHoc DataLoader
 
 The ad-hoc DataLoader methods on IResolverContext have been deprecated.