feat: add FillDataTableAsync() for responsive streaming into DataGridView

Batches rows (default 500) with BeginLoadData/EndLoadData per batch
and awaits Task.Yield() between batches so the UI message pump stays
responsive — form stays clickable while large result sets stream in.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: vkuttyp

src/SqlDotnetty.Core/ISqlDatabase.cs

@@ -132,17 +132,6 @@ public static class SqlRowExtensions
     /// <paramref name="table"/>. Columns are added to the table automatically on the first call
     /// if the table has no columns yet.
     /// </summary>
-    /// <example>
-    /// <code>
-    /// var dt = new DataTable("Orders");
-    /// await foreach (var row in conn.QueryStreamAsync("SELECT * FROM Orders"))
-    /// {
-    ///     row.AddToDataTable(dt);
-    ///     // update UI incrementally here
-    /// }
-    /// dataGridView1.DataSource = dt;
-    /// </code>
-    /// </example>
     public static System.Data.DataRow AddToDataTable(this SqlRow row, System.Data.DataTable table)
     {
         if (table.Columns.Count == 0)
@@ -161,17 +150,7 @@ public static System.Data.DataRow AddToDataTable(this SqlRow row, System.Data.Da
     /// <summary>
     /// Converts this <see cref="SqlRow"/> to a standalone <see cref="System.Data.DataRow"/>
     /// belonging to a new <see cref="System.Data.DataTable"/> (not yet added to any table).
-    /// Useful when you need the <c>DataRow</c> without a pre-existing <c>DataTable</c>.
     /// </summary>
-    /// <example>
-    /// <code>
-    /// await foreach (var row in conn.QueryStreamAsync("SELECT * FROM Orders"))
-    /// {
-    ///     var dataRow = row.ToDataRow();
-    ///     // dataRow.Table holds the schema, dataRow[0] etc. hold CLR values
-    /// }
-    /// </code>
-    /// </example>
     public static System.Data.DataRow ToDataRow(this SqlRow row)
     {
         var dt = new System.Data.DataTable();
@@ -184,4 +163,74 @@ public static System.Data.DataRow ToDataRow(this SqlRow row)
         dt.Rows.Add(dataRow);
         return dataRow;
     }
+
+    /// <summary>
+    /// Streams <paramref name="rows"/> into <paramref name="table"/> in batches, suspending
+    /// DataTable notifications per batch so the UI message pump stays responsive.
+    /// Bind <paramref name="table"/> to your DataGridView <em>before</em> calling this method —
+    /// the grid will refresh after each batch rather than after every individual row.
+    /// </summary>
+    /// <param name="rows">The async row stream from <c>QueryStreamAsync</c>.</param>
+    /// <param name="table">A DataTable already bound to a DataGridView (or similar).</param>
+    /// <param name="batchSize">Rows to accumulate before flushing to the DataTable. Default 500.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <example>
+    /// <code>
+    /// var dt = new DataTable();
+    /// dataGridView1.DataSource = dt;          // bind upfront
+    ///
+    /// await conn.QueryStreamAsync("SELECT * FROM BigTable")
+    ///           .FillDataTableAsync(dt);       // rows appear in batches of 500
+    /// </code>
+    /// </example>
+    public static async Task FillDataTableAsync(
+        this IAsyncEnumerable<SqlRow> rows,
+        System.Data.DataTable table,
+        int batchSize = 500,
+        CancellationToken ct = default)
+    {
+        var batch = new List<SqlRow>(batchSize);
+
+        await foreach (var row in rows.WithCancellation(ct).ConfigureAwait(false))
+        {
+            // Ensure columns exist from the very first row
+            if (table.Columns.Count == 0)
+            {
+                foreach (var col in row.Columns)
+                    table.Columns.Add(col.Name, typeof(object));
+            }
+
+            batch.Add(row);
+
+            if (batch.Count >= batchSize)
+            {
+                FlushBatch(table, batch);
+                batch.Clear();
+                // Yield to the UI thread so the message pump can process redraws/clicks
+                await Task.Yield();
+            }
+        }
+
+        if (batch.Count > 0)
+            FlushBatch(table, batch);
+    }
+
+    private static void FlushBatch(System.Data.DataTable table, List<SqlRow> batch)
+    {
+        table.BeginLoadData(); // suspend DataGridView notifications and index rebuilds
+        try
+        {
+            foreach (var row in batch)
+            {
+                var dataRow = table.NewRow();
+                for (int i = 0; i < row.ColumnCount; i++)
+                    dataRow[i] = row[i].ToClrObject();
+                table.Rows.Add(dataRow);
+            }
+        }
+        finally
+        {
+            table.EndLoadData(); // one bulk notification → one DataGridView refresh
+        }
+    }
 }