fix: increase performance of shallow inspection on GQL+EFCore

Author: Spelkington

src/core/Flowthru.Core/Data/Item.cs

@@ -159,6 +159,11 @@ public FlowIO<int> GetCountAsync()
 
   private FlowIO<int> LoadAndCount()
   {
+    // If the adapter can count server-side (e.g. SQL COUNT(*)), use it —
+    // avoids materializing the full dataset just for diagnostic logging.
+    if (_storage is IHasEfficientCount efficient)
+      return efficient.GetCountAsync();
+
     return Load()
       .Map(data =>
       {

src/core/Flowthru.Core/Data/Storage/IHasEfficientCount.cs

@@ -0,0 +1,30 @@
+using Flowthru.Core.Effects;
+
+namespace Flowthru.Core.Data.Storage;
+
+/// <summary>
+/// Optional interface for storage adapters that can return a row count without
+/// materializing the full dataset.
+/// </summary>
+/// <remarks>
+/// <para>
+/// By default, <see cref="Item{T}.GetCountAsync"/> counts by calling <see cref="IStorageAdapter{T}.Load"/>
+/// and enumerating the result. For I/O-bound adapters (databases, APIs) this materializes the
+/// entire dataset just to count rows — wasteful when the count is only needed for diagnostic
+/// logging around step execution.
+/// </para>
+/// <para>
+/// Implement this interface on a storage adapter to provide a cheap server-side count
+/// (e.g. <c>COUNT(*)</c> SQL) that <see cref="Item{T}.GetCountAsync"/> will use instead.
+/// </para>
+/// <para>
+/// Existing adapters that do not implement this interface continue to work without change.
+/// </para>
+/// </remarks>
+public interface IHasEfficientCount
+{
+  /// <summary>
+  /// Returns the number of items in the backing store without materializing them.
+  /// </summary>
+  FlowIO<int> GetCountAsync();
+}

src/extensions/Flowthru.Extensions.EFCore/Data/Storage/DbQueryStorageAdapter.cs

@@ -45,7 +45,7 @@ namespace Flowthru.Core.Data.Storage;
 /// </para>
 /// </remarks>
 /// <typeparam name="T">Entity type. Must be a class registered in the underlying DbContext.</typeparam>
-public sealed class DbQueryStorageAdapter<T> : IStorageAdapter<IEnumerable<T>>
+public sealed class DbQueryStorageAdapter<T> : IStorageAdapter<IEnumerable<T>>, IHasEfficientCount
   where T : class
 {
   private readonly DbQuery<T> _handle;
@@ -122,6 +122,28 @@ public DbQueryStorageAdapter(
   /// <remarks>Returns the deferred query handle — no database I/O.</remarks>
   public FlowIO<IEnumerable<T>> Load() => FlowIO.Lift<IEnumerable<T>>(() => _handle);
 
+  /// <inheritdoc/>
+  /// <remarks>
+  /// Executes <c>SELECT COUNT(*)</c> against the query's predicate — no rows are transferred
+  /// to the application host.
+  /// </remarks>
+  FlowIO<int> IHasEfficientCount.GetCountAsync()
+  {
+    return FlowIO.LiftAsync(async ct =>
+    {
+      var ctx = _handle.OpenContext();
+      try
+      {
+        return await _handle.BuildQuery(ctx).CountAsync(ct);
+      }
+      finally
+      {
+        if (_handle.OwnsContext)
+          await ctx.DisposeAsync();
+      }
+    });
+  }
+
   /// <inheritdoc/>
   /// <remarks>
   /// Fused path when <paramref name="data"/> is a <see cref="DbQuery{T}"/> with a matching scope;

src/extensions/Flowthru.Extensions.EFCore/Data/Storage/EFCoreStorageAdapter.cs

@@ -82,7 +82,7 @@ namespace Flowthru.Core.Data.Storage;
 /// var adapter = new EFCoreStorageAdapter<Company>(dbContext, allowEmptyData: true);
 /// </code>
 /// </example>
-public sealed class EFCoreStorageAdapter<T> : IStorageAdapter<IEnumerable<T>>
+public sealed class EFCoreStorageAdapter<T> : IStorageAdapter<IEnumerable<T>>, IHasEfficientCount
   where T : class
 {
   private readonly DbContext? _injectedContext;
@@ -463,6 +463,24 @@ public static async Task DefaultSave(DbContext context, IEnumerable<T> data, Can
     await context.SaveChangesAsync(ct);
   }
 
+  /// <inheritdoc/>
+  FlowIO<int> IHasEfficientCount.GetCountAsync()
+  {
+    return FlowIO.LiftAsync(async ct =>
+    {
+      var context = GetContext();
+      try
+      {
+        return await context.Set<T>().CountAsync(ct);
+      }
+      finally
+      {
+        if (_ownsContext && context != null)
+          await context.DisposeAsync();
+      }
+    });
+  }
+
   private DbContext GetContext()
   {
     if (_injectedContext != null)

tests/Flowthru.Extensions.EFCore.Tests/DbQueryStorageAdapterTests.cs

@@ -358,6 +358,53 @@ await sourceEntry
     Assert.That(rows.Select(r => r.Name), Is.EquivalentTo(new[] { "Alpha", "Beta" }));
   }
 
+  // ── IHasEfficientCount ──────────────────────────────────────
+
+  [Test]
+  public async Task GetCountAsync_UsesCountStar_NotFullLoad()
+  {
+    var seed = EFCoreItemFactory.Enumerable.EFCore<TestEntity>("seed", _factory);
+    await seed.Save(
+        new[]
+        {
+          new TestEntity { Id = 1, Name = "A" },
+          new TestEntity { Id = 2, Name = "B" },
+          new TestEntity { Id = 3, Name = "C" },
+        }
+      )
+      .Run();
+
+    var entry = EFCoreItemFactory.Query.EFCore<TestEntity>("test", _factory);
+
+    // Should use IHasEfficientCount → SELECT COUNT(*) rather than materializing
+    var count = await entry.GetCountAsync().Run();
+
+    Assert.That(count, Is.EqualTo(3));
+  }
+
+  [Test]
+  public async Task GetCountAsync_WithWhereClause_CountsMatchingRows()
+  {
+    var seed = EFCoreItemFactory.Enumerable.EFCore<TestEntity>("seed", _factory);
+    await seed.Save(Enumerable.Range(1, 10).Select(i => new TestEntity { Id = i, Name = $"E{i}" }))
+      .Run();
+
+    // Load the deferred handle, add a predicate, then count — should not pull all 10 rows
+    var entry = EFCoreItemFactory.Query.EFCore<TestEntity>("test", _factory);
+    IEnumerable<TestEntity> handle = await entry.Load().Run();
+    var filtered = ((DbQuery<TestEntity>)handle).Where(e => e.Id <= 4);
+
+    // Wrap back into an Item so GetCountAsync goes through IHasEfficientCount
+    var filteredEntry = EFCoreItemFactory.Query.EFCore<TestEntity>(
+      "filtered",
+      _factory,
+      queryCustomizer: q => q.Where(e => e.Id <= 4)
+    );
+    var count = await filteredEntry.GetCountAsync().Run();
+
+    Assert.That(count, Is.EqualTo(4));
+  }
+
   // ── Project<TResult> ─────────────────────────────────────────────────────
 
   [Test]

tests/Flowthru.Extensions.EFCore.Tests/EFCoreStorageAdapterTests.cs

@@ -176,4 +176,42 @@ public void ArrayKeyEntity_ThrowsInvalidOperationException_OnConstruction()
         )
     );
   }
+
+  // ── IHasEfficientCount ──────────────────────────────────────────────────
+
+  [Test]
+  public async Task GetCountAsync_UsesCountStar_NotFullLoad()
+  {
+    var testData = new[]
+    {
+      new TestEntity { Id = 1, Name = "Alice" },
+      new TestEntity { Id = 2, Name = "Bob" },
+      new TestEntity { Id = 3, Name = "Carol" },
+    };
+
+    var entry = EFCoreItemFactory.Enumerable.EFCore<TestEntity>(
+      "test",
+      () => new TestDbContext(_options)
+    );
+    await entry.Save(testData).Run();
+
+    // GetCountAsync must hit IHasEfficientCount, not Load()+enumerate
+    var count = await entry.GetCountAsync().Run();
+
+    Assert.That(count, Is.EqualTo(3));
+  }
+
+  [Test]
+  public async Task GetCountAsync_EmptyTable_ReturnsZero()
+  {
+    var entry = EFCoreItemFactory.Enumerable.EFCore<TestEntity>(
+      "test",
+      () => new TestDbContext(_options)
+    );
+
+    // Empty table: Exists() returns false → GetCountAsync() short-circuits to 0
+    var count = await entry.GetCountAsync().Run();
+
+    Assert.That(count, Is.EqualTo(0));
+  }
 }