rc.4: deprecate the members that have a better route ([Obsolete] warnings)

Source/Core/Core/Transformer.cs

@@ -13,6 +13,8 @@ namespace Open.Database.Extensions.Core;
 /// <typeparam name="T">The type of the model to create from the data.</typeparam>
 public class Transformer<T>
 {
+	const string ResultsObsolete = "Use table.CreateDataReader().Map(map).ToList() instead, where map is the RowMap<T> you gave Transformer<T>.Create. It returns a List<T>, not a lazy enumerable, and has no clearTable argument: clear the table yourself after reading it. Removed in 12.";
+
 	/// <summary>
 	/// Maximum number of arrays to hold in the local array pool per bucket.
 	/// May also define how many records are pre buffered before transforming.
@@ -162,11 +164,14 @@ static IEnumerable<T> Drain(Queue<object[]> queue, Func<object?[], T> map, Array
 	}
 
 	/// <summary>
+	/// Obsolete: use table.CreateDataReader().Map(map).ToList().
 	/// Processes the data from the data table into a queue. Then dequeues the results and transforms each one by one during enumeration.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <param name="table">The data to process.</param>
 	/// <param name="clearTable">If true, will clear the table after buffering the data.</param>
 	/// <returns>A dequeuing enumerable of the transformed results.</returns>
+	[Obsolete(ResultsObsolete)]
 	public IEnumerable<T> Results(DataTable table, bool clearTable)
 	{
 		if (table is null) throw new ArgumentNullException(nameof(table));

Source/Core/ExpressiveCommandBase.cs

@@ -17,12 +17,15 @@ public abstract partial class ExpressiveCommandBase<TConnection, TCommand, TRead
 		where TDbType : struct
 		where TThis : ExpressiveCommandBase<TConnection, TCommand, TReader, TDbType, TThis>
 {
+	const string ConcatObsolete = "Not part of the command API: use remaining is null ? [first] : remaining.Prepend(first) (Prepend alone throws on null). Removed in 12.";
+
 	/// <summary>
 	/// Utility for simplifying param concatenation.
 	/// </summary>
 	/// <typeparam name="T">The type of the enumerable.</typeparam>
 	/// <param name="first">The first value.</param>
 	/// <param name="remaining">The remaining values.</param>
+	[Obsolete(ConcatObsolete)]
 	protected static IEnumerable<T> Concat<T>(T first, ICollection<T> remaining)
 		=> CoreExtensions.Concat(first, remaining);
 

Source/Core/Extensions/Command._.cs

@@ -6,6 +6,8 @@ namespace Open.Database.Extensions;
 /// </summary>
 public static partial class CommandExtensions
 {
+	const string ToListAsyncObsolete = "Use await command.Map(transform).ToListAsync(cancellationToken) instead. Map also reads the later result sets, so a failure in one is thrown; add .SingleResult() to read only the first, as this method does. Map executes asynchronously and then reads the rows with Read(), as useReadAsync: false did. It has no CommandBehavior argument: if you passed one, use await command.ExecuteReaderAsync(r => r.Map(transform).ToList(), behavior | CommandBehavior.SingleResult, cancellationToken). Removed in 12.";
+
 	#region Connection.EnsureOpen Shortcuts.
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	private static ConnectionState EnsureOpen(this IDbCommand command)
@@ -162,15 +164,18 @@ public static ValueTask<List<T>> ToListAsync<T>(this DbCommand command,
 		=> ToListAsync(command, behavior, transform, cancellationToken);
 
 	/// <summary>
+	/// Obsolete: use await command.Map(transform).ToListAsync(cancellationToken).
 	/// Asynchronously iterates all records using an <see cref="IDataReader"/> and returns the desired results as a list.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="command">The <see cref="DbCommand"/> to generate a reader from.</param>
 	/// <param name="behavior">The behavior to use with the data reader.</param>
 	/// <param name="transform">The transform function to process each <see cref="IDataRecord"/>.</param>
 	/// <param name="useReadAsync">If true (default) will iterate the results using .ReadAsync() otherwise will only Execute the reader asynchronously and then use .Read() to iterate the results but still allowing cancellation.</param>
 	/// <param name="cancellationToken">The cancellation token.</param>
 	/// <returns>A task containing a list of all results.</returns>
+	[Obsolete(ToListAsyncObsolete)]
 	public static async ValueTask<List<T>> ToListAsync<T>(this DbCommand command,
 		CommandBehavior behavior,
 		Func<IDataRecord, T> transform,
@@ -187,26 +192,31 @@ public static async ValueTask<List<T>> ToListAsync<T>(this DbCommand command,
 #endif
 		using DbDataReader reader = await command.OpenAndExecuteReaderAsync(behavior, cancellationToken).ConfigureAwait(false);
 
-		if (useReadAsync) return await reader.ToListAsync(transform, cancellationToken).ConfigureAwait(false);
+		if (useReadAsync) return await DataReaderExtensions.ToListAsyncCore(reader, transform, cancellationToken).ConfigureAwait(false);
 
-		var r = reader.ToList(transform, cancellationToken);
-		return r;
+		return reader.Select(transform, cancellationToken).ToList();
 	}
 
 	/// <inheritdoc cref="ToListAsync{T}(DbCommand, CommandBehavior, Func{IDataRecord, T}, bool, CancellationToken)"/>
+	[Obsolete(ToListAsyncObsolete)]
 	public static ValueTask<List<T>> ToListAsync<T>(this DbCommand command,
 		CommandBehavior behavior,
 		Func<IDataRecord, T> transform,
 		CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // One obsolete overload forwards to another.
 		=> ToListAsync(command, behavior, transform, true, cancellationToken);
+#pragma warning restore CS0618
 
 	/// <inheritdoc cref="ToListAsync{T}(DbCommand, CommandBehavior, Func{IDataRecord, T}, bool, CancellationToken)"/>
+	[Obsolete(ToListAsyncObsolete)]
 	public static ValueTask<List<T>> ToListAsync<T>(this DbCommand command,
 		Func<IDataRecord, T> transform,
 		CommandBehavior behavior = CommandBehavior.Default,
 		bool useReadAsync = true,
 		CancellationToken cancellationToken = default)
+#pragma warning disable CS0618 // One obsolete overload forwards to another.
 		=> ToListAsync(command, behavior, transform, useReadAsync, cancellationToken);
+#pragma warning restore CS0618
 
 	/// <summary>
 	/// Iterates all records using an <see cref="IDataReader"/> and returns the desired results as an array.

Source/Core/Extensions/DataReader.cs

@@ -11,6 +11,11 @@ namespace Open.Database.Extensions;
 #pragma warning restore IDE0079 // Remove unnecessary suppression
 public static class DataReaderExtensions
 {
+	const string ReaderToListObsolete = "Use reader.Map(transform).ToList() instead. It reads the current result set, as this method does, and takes no CancellationToken: if you passed one, use reader.Select(transform, cancellationToken).ToList(). Removed in 12.";
+	const string ReaderToArrayObsolete = "Use reader.Map(transform).ToArray() instead. It reads the current result set, as this method does. Removed in 12.";
+	const string ReaderToImmutableArrayObsolete = "Use reader.Map(transform).ToImmutableArray() instead. It reads the current result set, as this method does. Removed in 12.";
+	const string ReaderToListAsyncObsolete = "Use await reader.Map(transform).ToListAsync(cancellationToken) instead. It reads the current result set, as this method does, but with Read() where this method used ReadAsync. Removed in 12.";
+
 	/// <summary>
 	/// Iterates all records from an <see cref="IDataReader"/>.
 	/// </summary>
@@ -663,27 +668,37 @@ public static IAsyncEnumerable<T> SelectAsync<T>(this IDataReader reader,
 		=> SelectAsync(reader, transform, false, cancellationToken);
 
 	/// <summary>
+	/// Obsolete: use reader.Map(transform).ToList().
 	/// Shortcut for .Iterate(transform).ToList();
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="reader">The IDataReader to iterate.</param>
 	/// <param name="transform">The transform function to process each <see cref="IDataRecord"/>.</param>
 	/// <param name="cancellationToken">Optional cancellation token.</param>
 	/// <returns>A list of the transformed results.</returns>
+	[Obsolete(ReaderToListObsolete)]
 	public static List<T> ToList<T>(this IDataReader reader,
 		Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)
 		=> reader.Select(transform, cancellationToken).ToList();
 
 	/// <summary>
+	/// Obsolete: use await reader.Map(transform).ToListAsync(cancellationToken).
 	/// Asynchronously iterates all records using the data reader and returns the desired results as a list.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="reader">The SqlDataReader to read from.</param>
 	/// <param name="transform">The transform function to process each <see cref="IDataRecord"/>.</param>
 	/// <param name="cancellationToken">Optional cancellation token.</param>
 	/// <returns>A task containing a list of all results.</returns>
-	public static async ValueTask<List<T>> ToListAsync<T>(this DbDataReader reader,
+	[Obsolete(ReaderToListAsyncObsolete)]
+	public static ValueTask<List<T>> ToListAsync<T>(this DbDataReader reader,
 		Func<IDataRecord, T> transform, CancellationToken cancellationToken = default)
+		=> ToListAsyncCore(reader, transform, cancellationToken);
+
+	internal static async ValueTask<List<T>> ToListAsyncCore<T>(DbDataReader reader,
+		Func<IDataRecord, T> transform, CancellationToken cancellationToken)
 	{
 		if (reader is null) throw new ArgumentNullException(nameof(reader));
 		if (transform is null) throw new ArgumentNullException(nameof(transform));
@@ -708,22 +723,28 @@ public static async ValueTask<List<T>> ToListAsync<T>(this DbDataReader reader,
 	}
 
 	/// <summary>
+	/// Obsolete: use reader.Map(transform).ToArray().
 	/// Shortcut for .Select(transform).ToArray();
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="reader">The IDataReader to iterate.</param>
 	/// <param name="transform">The transform function to process each <see cref="IDataRecord"/>.</param>
 	/// <returns>An array of the transformed results.</returns>
+	[Obsolete(ReaderToArrayObsolete)]
 	public static T[] ToArray<T>(this IDataReader reader, Func<IDataRecord, T> transform)
 		=> reader.Select(transform).ToArray();
 
 	/// <summary>
+	/// Obsolete: use reader.Map(transform).ToImmutableArray().
 	/// Shortcut for .Select(transform).ToImmutableArray();
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The return type of the transform function.</typeparam>
 	/// <param name="reader">The IDataReader to iterate.</param>
 	/// <param name="transform">The transform function to process each <see cref="IDataRecord"/>.</param>
 	/// <returns>An immutable array of the transformed results.</returns>
+	[Obsolete(ReaderToImmutableArrayObsolete)]
 	public static ImmutableArray<T> ToImmutableArray<T>(this IDataReader reader, Func<IDataRecord, T> transform)
 		=> reader.Select(transform).ToImmutableArray();
 

Source/Core/Extensions/IExecuteReader.cs

@@ -13,6 +13,10 @@ public static class IExecuteReaderExtensions
 	const string TakeObsolete = "Use .Map(selector).Take(count).ToList() instead. " + LaterSets + " Take(0) now runs the command; this method did not. Removed in 12.";
 	const string SkipObsolete = "Use .Map(selector).Skip(count).ToList() instead. " + LaterSets + " " + SkipDifference + " Removed in 12.";
 	const string SkipThenTakeObsolete = "Use .Map(selector).Skip(skip).Take(take).ToList() instead. " + LaterSets + " " + SkipDifference + " Take(0) now runs the command; this method did not. Removed in 12.";
+	const string ToListObsolete = "Use .Map(transform).ToList() instead. " + LaterSets + " Map has no CommandBehavior argument: if you passed one, use cmd.ExecuteReader(r => r.Map(transform).ToList(), behavior | CommandBehavior.SingleResult). Removed in 12.";
+	const string ToArrayObsolete = "Use .Map(transform).ToArray() instead. " + LaterSets + " Map has no CommandBehavior argument: if you passed one, use cmd.ExecuteReader(r => r.Map(transform).ToArray(), behavior | CommandBehavior.SingleResult). Removed in 12.";
+	const string ToImmutableArrayObsolete = "Use .Map(transform).ToImmutableArray() instead. " + LaterSets + " Map has no CommandBehavior argument: if you passed one, use cmd.ExecuteReader(r => r.Map(transform).ToImmutableArray(), behavior | CommandBehavior.SingleResult). Removed in 12.";
+	const string IterateReaderObsolete = "Use .Map(transform).Read(selector) instead. " + LaterSets + " Map has no CommandBehavior argument: if you passed one, use cmd.ExecuteReader(r => selector(r.Select(transform)), behavior | CommandBehavior.SingleResult). Removed in 12.";
 
 	/// <summary>
 	/// Iterates a reader on a command with a handler function.
@@ -194,15 +198,18 @@ await reader
 	}
 
 	/// <summary>
+	/// Obsolete: use .Map(transform).Read(selector).
 	/// Executes a reader on a command with a transform function.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="TEntity">The return type of the transform function applied to each record.</typeparam>
 	/// <typeparam name="TResult">The type returned by the selector.</typeparam>
 	/// <param name="command">The IExecuteReader to iterate.</param>
 	/// <param name="transform">The transform function for each IDataRecord.</param>
 	/// <param name="selector">Provides an IEnumerable&lt;TEntity&gt; to select individual results by.</param>
 	/// <param name="behavior">The behavior to use with the data reader.</param>
 	/// <returns>The result of the transform.</returns>
+	[Obsolete(IterateReaderObsolete)]
 	public static TResult IterateReader<TEntity, TResult>(
 		this IExecuteReader command,
 		Func<IDataRecord, TEntity> transform,
@@ -342,7 +349,7 @@ public static List<T> Skip<T>(this IExecuteReader command, int count, Func<IData
 
 		return command.ExecuteReader(
 			reader => count == 0
-				? reader.ToList(transform)
+				? reader.Select(transform).ToList()
 				: reader.Select(transform).Skip(count).ToList(),
 			CommandBehavior.SingleResult);
 	}
@@ -375,13 +382,16 @@ public static List<T> SkipThenTake<T>(this IExecuteReader command, int skip, int
 	}
 
 	/// <summary>
+	/// Obsolete: use .Map(transform).ToList().
 	/// Converts all IDataRecords into a list using a transform function.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The expected return type.</typeparam>
 	/// <param name="command">The IExecuteReader to iterate.</param>
 	/// <param name="transform">The transform function.</param>
 	/// <param name="behavior">The command behavior for once the command the reader is complete.</param>
 	/// <returns>The list of transformed records.</returns>
+	[Obsolete(ToListObsolete)]
 	public static List<T> ToList<T>(this IExecuteReader command, Func<IDataRecord, T> transform, CommandBehavior behavior = CommandBehavior.Default)
 	{
 		if (command is null) throw new ArgumentNullException(nameof(command));
@@ -394,13 +404,16 @@ public static List<T> ToList<T>(this IExecuteReader command, Func<IDataRecord, T
 	}
 
 	/// <summary>
+	/// Obsolete: use .Map(transform).ToArray().
 	/// Converts all IDataRecords into an array using a transform function.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The expected return type.</typeparam>
 	/// <param name="command">The IExecuteReader to iterate.</param>
 	/// <param name="transform">The transform function.</param>
 	/// <param name="behavior">The command behavior for once the command the reader is complete.</param>
 	/// <returns>The array of transformed records.</returns>
+	[Obsolete(ToArrayObsolete)]
 	public static T[] ToArray<T>(this IExecuteReader command, Func<IDataRecord, T> transform, CommandBehavior behavior = CommandBehavior.Default)
 	{
 		if (command is null) throw new ArgumentNullException(nameof(command));
@@ -413,13 +426,16 @@ public static T[] ToArray<T>(this IExecuteReader command, Func<IDataRecord, T> t
 	}
 
 	/// <summary>
+	/// Obsolete: use .Map(transform).ToImmutableArray().
 	/// Converts all IDataRecords into an immutable array using a transform function.
 	/// </summary>
+	/// <remarks>Obsolete in 11.0, removed in 12. See <see href="https://open-net-libraries.github.io/Open.Database.Extensions/articles/whats-new-11.html#deprecated-in-110">Deprecated in 11.0</see> for the difference and a before/after example.</remarks>
 	/// <typeparam name="T">The expected return type.</typeparam>
 	/// <param name="command">The IExecuteReader to iterate.</param>
 	/// <param name="transform">The transform function.</param>
 	/// <param name="behavior">The command behavior for once the command the reader is complete.</param>
 	/// <returns>The array of transformed records.</returns>
+	[Obsolete(ToImmutableArrayObsolete)]
 	public static ImmutableArray<T> ToImmutableArray<T>(this IExecuteReader command, Func<IDataRecord, T> transform, CommandBehavior behavior = CommandBehavior.Default)
 	{
 		if (command is null) throw new ArgumentNullException(nameof(command));