Refactor DbConnection classes and improve documentation

- Renamed `TakenConnectionState` to `_takenConnectionState` in `DbConnectionProvider<TConnection>` for clarity.
- Updated `QueryResult<TResult>` constructor to initialize `Ordinals` and `Names` properties.
- Reformatted `DbConnectionFactory<TConnection>` for better readability.
- Enhanced documentation in `IExecuteReaderExtensions` for improved clarity.
- Added methods in `CoreExtensions` for efficient handling of `DBNull` values.
- Refactored `DBNullToNullCopy` to utilize new methods for better efficiency.
- Replaced `PoolFromFactory` with `ConnectionFactoryToPoolAdapter` struct in `IDbConnectionFactory<TConnection>`.
- Updated `AsPool` methods to return the new adapter struct for consistency.
- Improved null checking in `AsGeneric` method of `IDbConnectionFactory`.

Author: electricessence

Source/Core/Core/DbConnectionProvider.cs

@@ -9,15 +9,15 @@ internal class DbConnectionProvider<TConnection>(TConnection connection)
 {
 	private TConnection Connection { get; } = connection ?? throw new ArgumentNullException(nameof(connection));
 
-	private ConnectionState? TakenConnectionState;
+	private ConnectionState? _takenConnectionState;
 
 	/// <inheritdoc />
 	public TConnection Take()
 	{
-		if (TakenConnectionState.HasValue)
+		if (_takenConnectionState.HasValue)
 			throw new InvalidOperationException("Concurrent use of a single connection is not supported.");
 
-		TakenConnectionState = Connection.State;
+		_takenConnectionState = Connection.State;
 		return Connection;
 	}
 
@@ -32,10 +32,10 @@ public void Give(IDbConnection connection)
 			throw new ArgumentException("Does not belong to this provider.", nameof(connection));
 		Contract.EndContractBlock();
 
-		if (TakenConnectionState == ConnectionState.Closed)
+		if (_takenConnectionState == ConnectionState.Closed)
 			connection.Close();
 
-		TakenConnectionState = null;
+		_takenConnectionState = null;
 	}
 }
 

Source/Core/Core/QueryResult.cs

@@ -19,6 +19,7 @@ public QueryResult(
 	{
 		if (ordinals.Length != names.Length)
 			throw new ArgumentException("Mismatched array lengths of ordinals and names.");
+
 		Ordinals = ordinals;
 		Names = names;
 		Result = result;

Source/Core/DbConnectionFactory.cs

@@ -43,7 +43,8 @@ public static implicit operator DbConnectionFactory(Func<IDbConnection> factory)
 /// Generic connection factory implementation that accepts a factory function.
 /// </summary>
 /// <typeparam name="TConnection">The connection type.</typeparam>
-public class DbConnectionFactory<TConnection> : DbConnectionFactory, IDbConnectionFactory<TConnection>
+public class DbConnectionFactory<TConnection>
+	: DbConnectionFactory, IDbConnectionFactory<TConnection>
 	where TConnection : IDbConnection
 {
 	readonly Func<TConnection> _factory;

Source/Core/Extensions/IExecuteReader.cs

@@ -165,7 +165,8 @@ public static T First<T>(this IExecuteReader command, Func<IDataRecord, T> trans
 	}
 
 	/// <summary>
-	/// Iterates a IDataReader and returns the first result through a transform function.  Throws if none or more than one entry.
+	/// Iterates a IDataReader and returns the first result through a transform function.
+	/// Throws if none or more than one entry.
 	/// </summary>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="command">The IExecuteReader to iterate.</param>
@@ -183,7 +184,9 @@ public static T Single<T>(this IExecuteReader command, Func<IDataRecord, T> tran
 	}
 
 	/// <summary>
-	/// Iterates an IDataReader and returns the first result through a transform function.  Returns default(T) if none.  Throws if more than one entry.
+	/// Iterates an IDataReader and returns the first result through a transform function.
+	/// Returns default(T) if none.
+	/// Throws if more than one entry.
 	/// </summary>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="command">The IExecuteReader to iterate.</param>

Source/Core/Extensions/_.cs

@@ -26,15 +26,32 @@ internal static IEnumerable<T> Concat<T>(T first, ICollection<T> remaining)
 	internal static object? DBNullValueToNull(object? value)
 		=> value == DBNull.Value ? null : value;
 
+	/// <summary>
+	/// Copies the contents of the <paramref name="values"/> span
+	/// to the <paramref name="target"/> span
+	/// with any <see cref="DBNull"/> values converted to <see langword="null"/>.
+	/// </summary>
+	public static Span<object?> CopyToWithDbNullAsNull(this ReadOnlySpan<object?> values, Span<object?> target)
+	{
+		int len = values.Length;
+		object?[] result = new object?[len];
+		for (int i = 0; i < len; i++)
+			target[i] = DBNullValueToNull(values[i]);
+
+		return result;
+	}
+
+	/// <inheritdoc cref="CopyToWithDbNullAsNull(ReadOnlySpan{object?}, Span{object?})"/>
+	public static Span<object?> CopyToWithDbNullAsNull(this Span<object?> values, Span<object?> target)
+		=> CopyToWithDbNullAsNull((ReadOnlySpan<object?>)values, target);
+
 	/// <summary>
 	/// Any <see cref="DBNull"/> values are yielded as null.
 	/// </summary>
 	/// <param name="values">The source enumerable.</param>
 	public static IEnumerable<object?> DBNullToNull(this IEnumerable<object?> values)
 	{
-		return values is null
-			? throw new ArgumentNullException(nameof(values))
-			: DBNullToNullCore(values);
+		return DBNullToNullCore(values ?? throw new ArgumentNullException(nameof(values)));
 
 		static IEnumerable<object?> DBNullToNullCore(IEnumerable<object?> values)
 		{
@@ -52,10 +69,8 @@ internal static IEnumerable<T> Concat<T>(T first, ICollection<T> remaining)
 		if (values is null) throw new ArgumentNullException(nameof(values));
 		Contract.EndContractBlock();
 
-		int len = values.Length;
-		object?[] result = new object?[len];
-		for (int i = 0; i < len; i++)
-			result[i] = DBNullValueToNull(values[i]);
+		object?[] result = new object?[values.Length];
+		CopyToWithDbNullAsNull(values.AsSpan(), result.AsSpan());
 		return result;
 	}
 
@@ -65,38 +80,21 @@ internal static IEnumerable<T> Concat<T>(T first, ICollection<T> remaining)
 	/// <inheritdoc cref="DBNullToNullCopy(object[])"/>
 	public static object?[] DBNullToNullCopy(this ReadOnlySpan<object?> values)
 	{
-		int len = values.Length;
-		object?[] result = new object?[len];
-		for (int i = 0; i < len; i++)
-			result[i] = DBNullValueToNull(values[i]);
+		object?[] result = new object?[values.Length];
+		DBNullToNullCopy(values, result.AsSpan());
 		return result;
 	}
 
 	/// <inheritdoc cref="DBNullToNullCopy(ReadOnlySpan{object?})"/>
 	public static object?[] DBNullToNullCopy(this Span<object?> values)
-	{
-		int len = values.Length;
-		object?[] result = new object?[len];
-		for (int i = 0; i < len; i++)
-			result[i] = DBNullValueToNull(values[i]);
-		return result;
-	}
+		=> DBNullToNullCopy((ReadOnlySpan<object?>)values);
 
 	/// <summary>
 	/// Replaces any <see cref="DBNull"/> in the <paramref name="values"/> with null;
 	/// </summary>
 	/// <param name="values">The source values.</param>
 	public static Span<object?> ReplaceDBNullWithNull(this Span<object?> values)
-	{
-		int len = values.Length;
-		for (int i = 0; i < len; i++)
-		{
-			ref object? value = ref values[i];
-			if (value == DBNull.Value) value = null;
-		}
-
-		return values;
-	}
+		=> DBNullToNullCopy(values, values);
 
 	/// <inheritdoc cref="ReplaceDBNullWithNull(Span{object?})"/>
 	public static object?[] ReplaceDBNullWithNull(this object?[] values)

Source/Core/IDbConnectionFactory.cs

@@ -27,30 +27,44 @@ public interface IDbConnectionFactory<out TConnection> : IDbConnectionFactory
 /// </summary>
 public static class DbConnectionFactoryExtensions
 {
-	class PoolFromFactory(IDbConnectionFactory connectionFactory) : IDbConnectionPool
+	/// <summary>
+	/// A struct that represents a connection factory that can be used as a pool.
+	/// </summary>
+	public readonly struct ConnectionFactoryToPoolAdapter(Func<IDbConnection> factory) : IDbConnectionPool
 	{
-		private readonly IDbConnectionFactory _connectionFactory
-			= connectionFactory ?? throw new ArgumentNullException(nameof(connectionFactory));
+		/// <summary>
+		/// Constructs a connection factory to pool adapter.
+		/// </summary>
+		public ConnectionFactoryToPoolAdapter(IDbConnectionFactory factory)
+			: this(factory.Create) { }
 
+		/// <inheritdoc />
 		public IDbConnection Take()
-			=> _connectionFactory.Create();
+			=> factory();
 
+		/// <inheritdoc />
 		public void Give(IDbConnection connection)
 			=> connection.Dispose();
 	}
 
-	class PoolFromFactory<TConnection>(IDbConnectionFactory<TConnection> connectionFactory) : IDbConnectionPool<TConnection>
+	/// <inheritdoc cref="ConnectionFactoryToPoolAdapter(Func{IDbConnection})" />/>
+	public readonly struct ConnectionFactoryToPoolAdapter<TConnection>(Func<TConnection> factory) : IDbConnectionPool<TConnection>
 		where TConnection : IDbConnection
 	{
-		private readonly IDbConnectionFactory<TConnection> _connectionFactory
-			= connectionFactory ?? throw new ArgumentNullException(nameof(connectionFactory));
+		/// <summary>
+		/// Constructs a connection factory to pool adapter.
+		/// </summary>
+		public ConnectionFactoryToPoolAdapter(IDbConnectionFactory<TConnection> factory)
+			: this(factory.Create) { }
 
+		/// <inheritdoc />
 		public TConnection Take()
-			=> _connectionFactory.Create();
+			=> factory();
 
 		IDbConnection IDbConnectionPool.Take()
 			=> Take();
 
+		/// <inheritdoc />
 		public void Give(IDbConnection connection)
 			=> connection.Dispose();
 	}
@@ -59,25 +73,30 @@ public void Give(IDbConnection connection)
 	/// Provides a connection pool that simply creates from a connection factory and disposes when returned.
 	/// </summary>
 	/// <param name="connectionFactory">The connection factory to generate connections from.</param>
-	/// <returns></returns>
-	public static IDbConnectionPool AsPool(this IDbConnectionFactory connectionFactory)
-		=> new PoolFromFactory(connectionFactory);
+	/// <returns>An <see cref="ConnectionFactoryToPoolAdapter"/> to handle this factory.</returns>
+	public static ConnectionFactoryToPoolAdapter AsPool(this IDbConnectionFactory connectionFactory)
+		=> new (connectionFactory);
 
 	/// <summary>
 	/// Provides a connection pool that simply creates from a connection factory and disposes when returned.
 	/// </summary>
 	/// <param name="connectionFactory">The connection factory to generate connections from.</param>
-	/// <returns></returns>
-	public static IDbConnectionPool<TConnection> AsPool<TConnection>(this IDbConnectionFactory<TConnection> connectionFactory)
+	/// <returns>An <see cref="ConnectionFactoryToPoolAdapter{TConnection}"/> to handle this factory.</returns>
+	public static ConnectionFactoryToPoolAdapter<TConnection> AsPool<TConnection>(this IDbConnectionFactory<TConnection> connectionFactory)
 		where TConnection : IDbConnection
-		=> new PoolFromFactory<TConnection>(connectionFactory);
+		=> new (connectionFactory);
 
 	/// <summary>
 	/// Coerces a non-generic connection factory to a generic one.
 	/// </summary>
 	/// <param name="connectionFactory">The source connection factory.</param>
 	/// <returns>The generic version of the source factory.</returns>
 	public static IDbConnectionFactory<IDbConnection> AsGeneric(this IDbConnectionFactory connectionFactory)
-		=> (connectionFactory ?? throw new ArgumentNullException(nameof(connectionFactory))) is IDbConnectionFactory<IDbConnection> p ? p
-		: new DbConnectionFactory<IDbConnection>(() => connectionFactory.Create());
+	{
+		if (connectionFactory is null) throw new ArgumentNullException(nameof(connectionFactory));
+		Contract.EndContractBlock();
+
+		return connectionFactory is IDbConnectionFactory<IDbConnection> p ? p
+			: new DbConnectionFactory<IDbConnection>(connectionFactory.Create);
+	}
 }