feat: make YdbList struct-only builder for List<Struct<...>>; remove plain mode

Author: LiamHamsters

src/Ydb.Sdk/src/Ado/BulkUpsert/BulkUpsertImporter.cs

@@ -31,51 +31,58 @@ internal BulkUpsertImporter(
         _cancellationToken = cancellationToken;
     }
 
-    /// <summary>Adds one line to the current BulkUpsert batch.</summary>
-    /// <param name="values">Column values are in array order <c>columns</c>.</param>
-    /// <remarks>Types: <see cref="YdbValue"/> / <see cref="YdbParameter"/> / <see cref="YdbList"/> — as is; others are displayed.</remarks>
-    /// <example><code>// columns: ["Id","Name"]
+    /// <summary>
+    /// Add a single row to the current BulkUpsert batch.
+    /// </summary>
+    /// <param name="values">Column values in the same order as the configured <c>columns</c>.</param>
+    /// <remarks>
+    /// Supported element types: <see cref="YdbValue"/>, <see cref="YdbParameter"/>, <see cref="YdbList"/> (as-is);
+    /// other CLR values are converted via <see cref="YdbParameter"/>.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // columns: ["Id", "Name"]
     /// await importer.AddRowAsync(1, "Alice");
-    /// </code></example>
-    /// <exception cref="ArgumentException">The number of values is not equal to the number of columns.</exception>
-    /// <exception cref="InvalidOperationException">The value cannot be compared with the YDB type.</exception>
+    /// </code>
+    /// </example>
+    /// <exception cref="ArgumentException">When the number of values doesn't equal the number of columns.</exception>
+    /// <exception cref="InvalidOperationException">When a value cannot be mapped to a YDB type.</exception>
     public async ValueTask AddRowAsync(params object[] values)
     {
         if (values.Length != _columns.Count)
-            throw new ArgumentException("Values count must match columns count", nameof(values));
+            throw new ArgumentException("Values count must match columns count.", nameof(values));
 
         var ydbValues = values.Select(v => v switch
-            {
-                YdbValue ydbValue => ydbValue.GetProto(),
-                YdbParameter param => param.TypedValue,
-                YdbList list => list.ToTypedValue(),
-                _ => new YdbParameter { Value = v }.TypedValue
-            }
-        ).ToArray();
+        {
+            YdbValue ydbValue  => ydbValue.GetProto(),
+            YdbParameter param => param.TypedValue,
+            YdbList list       => list.ToTypedValue(),
+            _                  => new YdbParameter { Value = v }.TypedValue
+        }).ToArray();
 
         var protoStruct = new Ydb.Value();
-        foreach (var value in ydbValues) protoStruct.Items.Add(value.Value);
+        foreach (var value in ydbValues)
+            protoStruct.Items.Add(value.Value);
 
         var rowSize = protoStruct.CalculateSize();
 
         if (_currentBytes + rowSize > _maxBatchByteSize && _rows.Count > 0)
-        {
             await FlushAsync();
-        }
 
         _rows.Add(protoStruct);
         _currentBytes += rowSize;
 
         _structType ??= new StructType
-            { Members = { _columns.Select((col, i) => new StructMember { Name = col, Type = ydbValues[i].Type }) } };
+        {
+            Members = { _columns.Select((col, i) => new StructMember { Name = col, Type = ydbValues[i].Type }) }
+        };
     }
-    
+
     /// <summary>
-    /// Adds a set of strings in the form <see cref="YdbList"/>.
+    /// Add multiple rows from a single <see cref="YdbList"/> parameter.
     /// </summary>
     /// <remarks>
-    /// The expected value is of the type <c>List&lt;Struct&lt;...&gt;&gt;</c>. Names and order of fields <c>Struct</c>
-    /// they must exactly match the array <c>columns</c> passed when creating the importer..
+    /// Expects <c>List&lt;Struct&lt;...&gt;&gt;</c>; struct member names and order must exactly match the configured <c>columns</c>.
     /// Example: <c>columns=["Id","Name"]</c> → <c>List&lt;Struct&lt;Id:Int64, Name:Utf8&gt;&gt;</c>.
     /// </remarks>
     public async ValueTask AddListAsync(YdbList list)
@@ -120,9 +127,14 @@ public async ValueTask AddListAsync(YdbList list)
         }
     }
 
+    /// <summary>
+    /// Flush the current batch via BulkUpsert. No-op if the batch is empty.
+    /// </summary>
     public async ValueTask FlushAsync()
     {
-        if (_rows.Count == 0) return;
+        if (_rows.Count == 0)
+            return;
+
         if (_structType == null)
             throw new InvalidOperationException("structType is undefined");
 

src/Ydb.Sdk/src/Ado/BulkUpsert/IBulkUpsertImporter.cs

@@ -4,18 +4,16 @@ namespace Ydb.Sdk.Ado.BulkUpsert;
 
 public interface IBulkUpsertImporter
 {
-    /// <summary>Adds one line to the batch.</summary>
-    /// <param name="row">The column values are in order <c>columns</c>.</param>
+    /// <summary>Add a single row to the batch. Values must match the importer column order.</summary>
+    /// <param name="row">Column values in the same order as the configured <c>columns</c>.</param>
     ValueTask AddRowAsync(params object[] row);
-    
+
     /// <summary>
-    /// Adds multiple lines with a single parameter <see cref="YdbList"/>.
+    /// Add many rows from <see cref="YdbList"/> (shape: <c>List&lt;Struct&lt;...&gt;&gt;</c>).
+    /// Struct member names and order must exactly match the configured <c>columns</c>.
     /// </summary>
-    /// <remarks>
-    /// Expected <c>List&lt;Struct&lt;...&gt;&gt;</c>, where the names and order of the fields are the same as <c>columns</c>.
-    /// Form Example: <c>List&lt;Struct&lt;Id:Int64, Name:Utf8&gt;&gt;</c>.
-    /// </remarks>
     ValueTask AddListAsync(YdbList list);
 
+    /// <summary>Flush the current batch via BulkUpsert (no-op if empty).</summary>
     ValueTask FlushAsync();
 }

src/Ydb.Sdk/src/Ado/YdbParameter.cs

@@ -37,7 +37,9 @@ public sealed class YdbParameter : DbParameter
 
     private string _parameterName = string.Empty;
 
-    public YdbParameter() { }
+    public YdbParameter()
+    {
+    }
 
     public YdbParameter(string parameterName, object value)
     {
@@ -122,14 +124,10 @@ internal TypedValue TypedValue
             var value = Value;
 
             if (value is YdbValue ydbValue)
-            {
                 return ydbValue.GetProto();
-            }
 
             if (value == null || value == DBNull.Value)
-            {
                 return NullTypedValue();
-            }
 
             return YdbDbType switch
             {
@@ -147,13 +145,13 @@ internal TypedValue TypedValue
                 YdbDbType.Double => MakeDouble(value),
                 YdbDbType.Decimal when value is decimal decimalValue => Decimal(decimalValue),
                 YdbDbType.Bytes => MakeBytes(value),
-                YdbDbType.Json when value is string stringValue => stringValue.Json(),
-                YdbDbType.JsonDocument when value is string stringValue => stringValue.JsonDocument(),
+                YdbDbType.Json when value is string sJson => sJson.Json(),
+                YdbDbType.JsonDocument when value is string sJsonDoc => sJsonDoc.JsonDocument(),
                 YdbDbType.Uuid when value is Guid guidValue => guidValue.Uuid(),
                 YdbDbType.Date => MakeDate(value),
-                YdbDbType.DateTime when value is DateTime dateTimeValue => dateTimeValue.Datetime(),
+                YdbDbType.DateTime when value is DateTime dt => dt.Datetime(),
                 YdbDbType.Timestamp => MakeTimestamp(value),
-                YdbDbType.Interval when value is TimeSpan timeSpanValue => timeSpanValue.Interval(),
+                YdbDbType.Interval when value is TimeSpan ts => ts.Interval(),
                 YdbDbType.Unspecified => Cast(value),
                 _ => throw ValueTypeNotSupportedException
             };
@@ -277,9 +275,7 @@ private TypedValue Decimal(decimal value) =>
     private TypedValue NullTypedValue()
     {
         if (YdbNullByDbType.TryGetValue(YdbDbType, out var value))
-        {
             return value;
-        }
 
         if (YdbDbType == YdbDbType.Decimal)
         {
@@ -289,8 +285,7 @@ private TypedValue NullTypedValue()
         }
 
         throw new InvalidOperationException(
-            "Writing value of 'null' is not supported without explicit mapping to the YdbDbType"
-        );
+            "Writing value of 'null' is not supported without explicit mapping to the YdbDbType");
     }
 
     private InvalidOperationException ValueTypeNotSupportedException =>