Merge pull request #27 from Open-NET-Libraries/feature/10.1-phase5

10.1.0: release finalization + optimizations

Author: electricessence

README.md

@@ -147,3 +147,22 @@ public static bool TryTransaction()
 - .NET 9.0 added to targets to ensure potential compilation and performance improvements are available.
 - Impelmented some .NET 8 and 9 specific features.
 - Significant cleanup and simplifcation where possible.
+
+## 10.1.0 Release Notes
+
+A modernization and allocation-reduction pass. **Source-compatible with 10.0** — existing code recompiles cleanly.
+
+- **Target frameworks:** `net10.0` is now the primary/modern target. `netstandard2.0` and `netstandard2.1` are retained as shimmed legacy paths (net8/net9 consumers use the `netstandard2.1` build); `Open.Database.Extensions.MSSqlClient` also targets `net472`. The explicit `net8.0`/`net9.0` targets were dropped.
+- **Fewer allocations on the hot paths:** case-insensitive column-to-property matching now uses `StringComparer.OrdinalIgnoreCase` (and `FrozenDictionary` on `net10.0`) instead of allocating an upper-cased string per column; assorted per-query LINQ and dead code removed.
+- **Ergonomic field-mapping overrides:** `Results<T>`, `ResultsAsync<T>`, `To<T>`, etc. now accept target-typed `new(...)` and collection expressions:
+
+  ```cs
+  cmd.Results<Person>(new("FirstName", "first_name"), new("LastName", "last_name"));
+  cmd.Results<Person>([new("FirstName", "first_name"), new("LastName", "last_name")]);
+  ```
+
+- **Modernized `params`:** ordinal helpers (`Retrieve`, `AsEnumerable`, …) accept `params IEnumerable<int>`/`params IEnumerable<string>` — any enumerable, not just arrays.
+- **Read-only inputs:** several read-only `IList<T>` parameters were widened to `IReadOnlyList<T>` (`GetValuesFromOrdinals`, `EnumerateValuesFromOrdinals`, `ToDictionary`). Arrays, `List<T>`, `ImmutableArray<T>`, etc. all still bind. *(A custom type implementing only `IList<T>` — and not also `IReadOnlyList<T>` — would need to recompile; no BCL collection is affected.)*
+- **Lower per-query overhead:** `Transformer<T>` caches its per-type reflection once instead of rebuilding it on every query; buffered/data-table paths pre-size collections and avoid redundant `Select` iterators.
+- Fixed a wasted-allocation / incorrect-return bug in `CopyToDBNullAsNull`.
+- Public API surface is now tracked with `Microsoft.CodeAnalysis.PublicApiAnalyzers`, and unit-test coverage was substantially expanded.

Source/Core/Core/Transformer.cs

@@ -27,21 +27,28 @@ public class Transformer<T>
 	/// <summary>
 	/// The type of <typeparamref name="T"/>.
 	/// </summary>
-	public Type Type { get; }
+	public Type Type => typeof(T);
 
-	private readonly PropertyInfo[] _properties;
+	// Reflection is invariant per T; a static on this generic type is per-T and initialized once
+	// (thread-safe), so GetProperties() and the name->PropertyInfo map aren't rebuilt per query.
+	// Built once, read on every query (property lookups + Keys) -> frozen on the modern target.
+	[SuppressMessage("Roslynator", "RCS1158:Static member in generic type should use a type parameter.", Justification = "Per-T reflection cache is intentional.")]
+#if NET10_0_OR_GREATER
+	static readonly FrozenDictionary<string, PropertyInfo> PropertiesByName
+		= typeof(T).GetProperties().ToFrozenDictionary(p => p.Name);
+#else
+	static readonly Dictionary<string, PropertyInfo> PropertiesByName
+		= typeof(T).GetProperties().ToDictionary(p => p.Name);
+#endif
 
 	// Allow mapping key = object property, value = column name.
 	readonly Dictionary<string, string> _propertyMap;
 
 	// Column-name -> property lookup, matched case-insensitively (OrdinalIgnoreCase) so no
-	// upper-cased key strings are allocated. Built once and never mutated after construction,
-	// so it is frozen on the modern target for faster reads.
-#if NET10_0_OR_GREATER
-	readonly FrozenDictionary<string, PropertyInfo> _columnToPropertyMap;
-#else
+	// upper-cased key strings are allocated. This map is per-query (a fresh Transformer is built
+	// per operation) and read only a handful of times, so a plain Dictionary is correct here —
+	// freezing a short-lived map costs more to build than the few lookups would ever recover.
 	readonly Dictionary<string, PropertyInfo> _columnToPropertyMap;
-#endif
 
 	/// <summary>
 	/// The property names.
@@ -58,31 +65,25 @@ public class Transformer<T>
 	/// </summary>
 	protected internal Transformer(IEnumerable<(string Field, string? Column)>? overrides = null)
 	{
-		Type = typeof(T);
-		_properties = Type.GetProperties();
-		_propertyMap = _properties.Select(p => p.Name).ToDictionary(n => n);
-
-		Dictionary<string, PropertyInfo> pm = _properties.ToDictionary(p => p.Name);
+		// Per-instance copy of the default (property-name -> same column-name) map, sized exactly,
+		// so the optional overrides can mutate it without touching the shared reflection cache.
+		_propertyMap = new Dictionary<string, string>(PropertiesByName.Count);
+		foreach (string name in PropertiesByName.Keys)
+			_propertyMap[name] = name;
 
 		if (overrides != null)
 		{
 			foreach ((string Field, string? Column) in overrides)
 			{
-				string? cn = Column;
-				if (cn == null) _propertyMap.Remove(Field); // Null values indicate a desire to 'ignore' a field.
-				else _propertyMap[Field] = cn;
+				if (Column == null) _propertyMap.Remove(Field); // Null column indicates 'ignore this field'.
+				else _propertyMap[Field] = Column;
 			}
 		}
 
-		// Project column-name -> property straight into the target map with a case-insensitive
-		// comparer: no upper-cased key strings, and no intermediate Dictionary on the frozen path.
-#if NET10_0_OR_GREATER
-		_columnToPropertyMap = _propertyMap.ToFrozenDictionary(
-			kvp => kvp.Value, kvp => pm[kvp.Key], StringComparer.OrdinalIgnoreCase);
-#else
+		// Project column-name -> property directly with a case-insensitive comparer (no upper-cased
+		// key strings). A plain Dictionary — this map lives only for the duration of one query.
 		_columnToPropertyMap = _propertyMap.ToDictionary(
-			kvp => kvp.Value, kvp => pm[kvp.Key], StringComparer.OrdinalIgnoreCase);
-#endif
+			kvp => kvp.Value, kvp => PropertiesByName[kvp.Key], StringComparer.OrdinalIgnoreCase);
 	}
 
 	/// <summary>
@@ -207,6 +208,24 @@ public IEnumerable<T> AsDequeueingEnumerable(QueryResult<Queue<object[]>> result
 		});
 	}
 
+	// Splits the matched (Name, Ordinal) columns into an ordinal array (which hits the IList<int>
+	// fast path in the reader enumeration) and an exactly-sized immutable name array, in one pass —
+	// avoiding two lazy Select iterators and a growing ImmutableArray builder per query.
+	static (int[] Ordinals, ImmutableArray<string> Names) SplitColumns((string Name, int Ordinal)[] columns)
+	{
+		int n = columns.Length;
+		var ordinals = new int[n];
+		var names = ImmutableArray.CreateBuilder<string>(n);
+		names.Count = n;
+		for (int i = 0; i < n; i++)
+		{
+			ordinals[i] = columns[i].Ordinal;
+			names[i] = columns[i].Name;
+		}
+
+		return (ordinals, names.MoveToImmutable());
+	}
+
 	/// <inheritdoc cref="ResultsBuffered(IDataReader, bool)"/>
 	internal IEnumerable<T> Results(IDataReader reader)
 	{
@@ -215,11 +234,12 @@ internal IEnumerable<T> Results(IDataReader reader)
 
 		// Ignore missing columns.
 		(string Name, int Ordinal)[] columns = reader.GetMatchingOrdinals(_propertyMap.Values, true);
-		var processor = new Processor(this, columns.Select(m => m.Name).ToImmutableArray());
+		(int[] ordinals, ImmutableArray<string> names) = SplitColumns(columns);
+		var processor = new Processor(this, names);
 		Func<object?[], T> transform = processor.Transform;
 
 		return reader
-			.AsEnumerable(columns.Select(m => m.Ordinal), LocalPool)
+			.AsEnumerable(ordinals, LocalPool)
 			.Select(a =>
 			{
 				try
@@ -250,6 +270,9 @@ internal IEnumerable<T> ResultsBuffered(IDataReader reader, bool readStarted)
 		// Ignore missing columns.
 		(string Name, int Ordinal)[] columns = reader.GetMatchingOrdinals(_propertyMap.Values, true);
 
+		// NOTE: pass the lazy projections straight through — RetrieveInternal materializes the
+		// ordinals into an ImmutableArray that QueryResult then reuses zero-copy (Immute fast path);
+		// pre-materializing here would add a redundant array.
 		return AsDequeueingEnumerable(
 			CoreExtensions.RetrieveInternal(
 				LocalPool,
@@ -275,9 +298,10 @@ async IAsyncEnumerable<T> ResultsAsyncCore(DbDataReader reader, [EnumeratorCance
 		{
 			// Ignore missing columns.
 			(string Name, int Ordinal)[] columns = reader.GetMatchingOrdinals(_propertyMap.Values, true);
-			var processor = new Processor(this, columns.Select(m => m.Name).ToImmutableArray());
+			(int[] ordinals, ImmutableArray<string> names) = SplitColumns(columns);
+			var processor = new Processor(this, names);
 
-			await foreach (object[] a in reader.AsAsyncEnumerable(columns.Select(m => m.Ordinal), LocalPool, cancellationToken))
+			await foreach (object[] a in reader.AsAsyncEnumerable(ordinals, LocalPool, cancellationToken))
 			{
 				try
 				{
@@ -303,17 +327,30 @@ public IEnumerable<T> Results(DataTable table, bool clearTable)
 		if (table is null) throw new ArgumentNullException(nameof(table));
 		Contract.EndContractBlock();
 
-		int columnCount = table.Columns.Count;
-		IEnumerable<DataColumn> columns = table.Columns.AsEnumerable();
-		var results = new QueryResult<Queue<object[]>>(
-			columns.Select(c => c.Ordinal),
-			columns.Select(c => c.ColumnName),
-			new Queue<object[]>(table.Rows.AsEnumerable().Select(r =>
-			{
-				object[] a = LocalPool.Rent(columnCount);
-				for (int i = 0; i < columnCount; i++) a[i] = r[i];
-				return a;
-			})));
+		DataColumnCollection cols = table.Columns;
+		int columnCount = cols.Count;
+
+		// Ordinals + names in a single pass (no double Select iterators).
+		var ordinals = new int[columnCount];
+		var names = new string[columnCount];
+		for (int i = 0; i < columnCount; i++)
+		{
+			DataColumn c = cols[i];
+			ordinals[i] = c.Ordinal;
+			names[i] = c.ColumnName;
+		}
+
+		// The row count is known, so pre-size the queue and fill it directly.
+		DataRowCollection rows = table.Rows;
+		var buffer = new Queue<object[]>(rows.Count);
+		foreach (DataRow r in rows)
+		{
+			object[] a = LocalPool.Rent(columnCount);
+			for (int i = 0; i < columnCount; i++) a[i] = r[i];
+			buffer.Enqueue(a);
+		}
+
+		var results = new QueryResult<Queue<object[]>>(ordinals, names, buffer);
 
 		if (clearTable) table.Rows.Clear();
 		return AsDequeueingEnumerable(results, LocalPool);

Source/Core/Extensions/DataRecord.cs

@@ -214,15 +214,15 @@ static IEnumerable<object> EnumerateValuesFromOrdinalsCore(IDataRecord record, I
 	}
 
 	/// <inheritdoc cref="EnumerateValuesFromOrdinals(IDataRecord, IEnumerable{int})"/>
-	public static IEnumerable<object> EnumerateValuesFromOrdinals(this IDataRecord record, IList<int> ordinals)
+	public static IEnumerable<object> EnumerateValuesFromOrdinals(this IDataRecord record, IReadOnlyList<int> ordinals)
 	{
 		return record is null
 			? throw new ArgumentNullException(nameof(record))
 			: ordinals is null
 			? throw new ArgumentNullException(nameof(ordinals))
 			: EnumerateValuesFromOrdinalsCore(record, ordinals);
 
-		static IEnumerable<object> EnumerateValuesFromOrdinalsCore(IDataRecord record, IList<int> ordinals)
+		static IEnumerable<object> EnumerateValuesFromOrdinalsCore(IDataRecord record, IReadOnlyList<int> ordinals)
 		{
 			// Avoid creating an another enumerator if possible.
 			int count = ordinals.Count;
@@ -267,7 +267,7 @@ public static Span<object> GetValuesFromOrdinals(this IDataRecord record, ReadOn
 
 	/// <returns>The provided list, updated with values matching the ordinal positions requested.</returns>
 	/// <inheritdoc cref="GetValuesFromOrdinals(IDataRecord, ReadOnlySpan{int}, Span{object})"/>
-	public static TList GetValuesFromOrdinals<TList>(this IDataRecord record, IList<int> ordinals, TList values)
+	public static TList GetValuesFromOrdinals<TList>(this IDataRecord record, IReadOnlyList<int> ordinals, TList values)
 		where TList : IList<object>
 	{
 		if (record is null) throw new ArgumentNullException(nameof(record));
@@ -282,7 +282,7 @@ public static TList GetValuesFromOrdinals<TList>(this IDataRecord record, IList<
 
 	/// <returns>An array of values matching the ordinal positions requested.</returns>
 	/// <inheritdoc cref="GetValuesFromOrdinals(IDataRecord, ReadOnlySpan{int}, Span{object})"/>
-	public static object[] GetValuesFromOrdinals(this IDataRecord record, IList<int> ordinals)
+	public static object[] GetValuesFromOrdinals(this IDataRecord record, IReadOnlyList<int> ordinals)
 	{
 		if (record is null) throw new ArgumentNullException(nameof(record));
 		if (ordinals is null) throw new ArgumentNullException(nameof(ordinals));
@@ -418,7 +418,7 @@ public static string[] GetDataTypeNames(this IDataRecord record)
 	/// <param name="record">The <see cref="IDataRecord"/> to extract values from.</param>
 	/// <param name="ordinalMapping">The column ids and resultant names to query.</param>
 	/// <returns>The resultant Dictionary of values.</returns>
-	public static Dictionary<string, object?> ToDictionary(this IDataRecord record, IList<(string Name, int Ordinal)> ordinalMapping)
+	public static Dictionary<string, object?> ToDictionary(this IDataRecord record, IReadOnlyList<(string Name, int Ordinal)> ordinalMapping)
 	{
 		if (record is null) throw new ArgumentNullException(nameof(record));
 		if (ordinalMapping is null) throw new ArgumentNullException(nameof(ordinalMapping));
@@ -484,7 +484,7 @@ public static string[] GetDataTypeNames(this IDataRecord record)
 	/// <param name="record">The <see cref="IDataRecord"/> to extract values from.</param>
 	/// <param name="columnNames">The column names to query.</param>
 	/// <returns>The resultant Dictionary of values.</returns>
-	public static Dictionary<string, object?> ToDictionary(this IDataRecord record, IList<string> columnNames)
+	public static Dictionary<string, object?> ToDictionary(this IDataRecord record, IReadOnlyList<string> columnNames)
 	{
 		if (record is null) throw new ArgumentNullException(nameof(record));
 		if (columnNames is null) throw new ArgumentNullException(nameof(columnNames));

Source/Core/Extensions/Retrieve.cs

@@ -34,10 +34,19 @@ public static QueryResultQueue<object[]> Retrieve(this IDataReader reader)
 	{
 		ImmutableArray<string> names = reader.GetNames();
 		return new QueryResultQueue<object[]>(
-			Enumerable.Range(0, names.Length), names,
+			IdentityOrdinals(names.Length), names,
 			reader.AsEnumerable());
 	}
 
+	// Builds [0, 1, ... n-1] directly as an ImmutableArray (exact capacity, and reused zero-copy by
+	// QueryResult) instead of an Enumerable.Range that a growing ToImmutableArray would then copy.
+	static ImmutableArray<int> IdentityOrdinals(int count)
+	{
+		var b = ImmutableArray.CreateBuilder<int>(count);
+		for (int i = 0; i < count; i++) b.Add(i);
+		return b.MoveToImmutable();
+	}
+
 	/// <summary>
 	/// Iterates all records within the current result set using an <see cref="IDataReader"/> and returns the desired results.
 	/// </summary>
@@ -131,7 +140,7 @@ public static async ValueTask<QueryResultQueue<object[]>> RetrieveAsync(this DbD
 		if (!useReadAsync) cancellationToken.ThrowIfCancellationRequested();
 
 		return new QueryResultQueue<object[]>(
-			Enumerable.Range(0, names.Length),
+			IdentityOrdinals(names.Length),
 			names,
 			buffer);
 	}

Source/Core/Extensions/_.cs

@@ -187,6 +187,7 @@ static IEnumerable<DataRow> AsEnumerableCore(DataRowCollection rows)
 		.Results(table, clearSourceTable);
 
 	/// <inheritdoc cref="To{T}(DataTable, IEnumerable{KeyValuePair{string, string?}}?, bool)"/>
+	[System.Runtime.CompilerServices.OverloadResolutionPriority(1)]
 	public static IEnumerable<T> To<T>(this DataTable table, params IEnumerable<(string Field, string? Column)> fieldMappingOverrides) where T : new()
 		=> Transformer<T>
 		.Create(fieldMappingOverrides)